Contents

• Purpose
  • Constraints
  • Classification and release information
  • Emulator support
• API description
  • Use cases
  • API class structure
• Using the Notifiers API
  • Showing global notes
  • Getting global notes responses
  • Canceling global notes
  • Enhancing global notes
    • Setting the note text processing
    • Setting the note softkeys
    • Setting the note graphic
    • Setting the note animation
    • Setting the note tone
  • Showing global queries
    • Showing a confirmation query
    • Showing a list query
    • Showing a message query
    • Showing a list message query
    • Showing and updating a progress dialog
  • Updating a confirmation or message query
  • Manipulating the selection in a list or list message query
  • Canceling global queries
  • Enhancing global queries
  • Error handling
  • Memory overhead
  • Limitations of the API
  • Extensions to the API
• Glossary
  • Abbreviations
• References

Constraints

.

Classification and release information

Notifiers API is an SDK API and a part of S60 3rd Edition. This document is valid from S60 3rd Edition, Feature Pack 2 onwards.

Emulator support

This API is fully supported in the WINS/WINSCW emulator environment.

Use cases

The main use cases of Notifiers API are:

• Showing global notes.

• Getting global note responses.

• Canceling global notes.

• Enhancing global notes.

  • Setting the note text processing.

  • Setting the note soft keys.

  • Setting the note graphic.

  • Setting the note animation.

  • Setting the note tone.

• Showing global queries.

  • Showing a confirmation query.

  • Showing a list query.

  • Showing a message query.

  • Showing a list message query.

  • Showing and updating a progress dialog.

• Updating a confirmation or message query.

• Manipulating the selection in a list or list message query.

• Canceling global queries.

• Enhancing global queries.

API class structure

Generally all the classes use the Symbian platform Notifier framework, which is a client-server framework to show notes and queries globally. This functionality is provided by the RNotifier , to which all classes connect.

The figure below shows the UML diagram of a global note which is a part of the Notifiers API.

The figure below and the figures after that show the UML diagrams of the different global queries, including the global progress dialog.

The global list query requires a descriptor array of the list items.

The global list message query requires a descriptor array of the list items.

• RNotifier

Showing global notes

All the following use cases use the ShowNoteL() method of the CAknGlobalNote class without TRequestStatus . It means that the client is not notified when any action has been taken by the user. In cases where there are no soft keys defined for the note, it is not reasonable to wait for some kind of response in TRequestStatus .

An information note can be shown with the type EAknGlobalInformationNote .

             
              CAknGlobalNote* note = CAknGlobalNote::NewLC();
              

              _LIT(KInfoText, "Information");
              

              note->ShowNoteL(EAknGlobalInformationNote, KInfoText);
              

              CleanupStack::PopAndDestroy(note);
             
            

The following global note types are also supported:

• EAknGlobalWarningNote .

• EAknGlobalConfirmationNote .

• EAknGlobalErrorNote .

• EAknGlobalWaitNote .

• EAknGlobalTextNote .

TAknGlobalNoteType defines more global note types, but the other notes are not recommended for use.

All the listed notes have a short time-out - the note is dismissed by the system automatically if there is no softkey defined for the note. However, in case of wait notes this is not true because the note displays the Cancel softkey by default and remains on the screen with a progress bar until the user or the client code cancels it.

The text note is a simplified note by default without any predefined graphics in it. Of course, as with other notes, enhancements (softkeys, a graphic, an animation, a tone) can be added to it.

The note remains on the screen even if it has just been deleted. This means that deleting the actual note object does not dismiss the note itself. If the note must be dismissed, it must be canceled by the client code (or the user). This is discussed in Section Canceling global notes .

• CAknGlobalNote
• EAknGlobalConfirmationNote
• EAknGlobalErrorNote
• EAknGlobalInformationNote
• EAknGlobalTextNote
• EAknGlobalWaitNote
• EAknGlobalWarningNote
• ShowNoteL()
• TAknGlobalNoteType
• TRequestStatus

Getting global notes responses

It is possible to observe the outcome of a global note. It requires a TRequestStatus to be passed to ShowNoteL() as a parameter. The completed status holds the ID of the pressed softkey or a Symbian platform error code.

The following example defines an observer active object ( CGlobalObserver ) which prints the content of the completed TRequestStatus to the screen.

             
              class CGlobalObserver : public CActive
              

                  {
              

                  public:
              

                      CGlobalObserver(CEikonEnv* aEnv);
              

                      virtual ~CGlobalObserver();
              

                      void Start();
              

                  protected: // from CActive
              

                      void RunL() ;
              

                      void DoCancel();
              

                  private: // data
              

                      CEikonEnv* iEnv;
              

                  };
              

              

              CGlobalObserver:: CGlobalObserver(CEikonEnv* aEnv) 
              

                  : CActive(0), iEnv(aEnv)
              

                  {
              

                  CActiveScheduler::Add(this);
              

                  }
              

              

              CGlobalObserver::~CGlobalObserver()
              

                  {
              

                  Cancel();
              

                  }
              

              

              void CGlobalObserver::RunL() 
              

                  {
              

                  TBuf<120> msg = _L("Received: ");
              

                  msg.AppendNum(iStatus.Int());
              

                  iEnv->InfoMsg(msg);
              

                  }
              

              

              void CGlobalObserver::DoCancel()
              

                  {
              

                  }
              

              

              void CGlobalObserver::Start()
              

                  {
              

                  SetActive();
              

                  }
              

              

              void CMyClient::ShowGlobaNoteL()
              

                  {
              

                  _LIT(KInformationText, "Information");
              

                  delete iNote; 
              

                  iNote = NULL;
              

                  iNote = CAknGlobalNote::NewL();
              

                  delete iObserver;
              

                  iObserver = NULL;
              

                  iObserver = new (ELeave) CGlobalObserver(iEikonEnv);
              

                  iNote->SetSoftkeys(R_AVKON_SOFTKEYS_ANSWER_EXIT);
              

                  iObserver->iStatus = KRequestPending;
              

                  iObserver->Start();
              

                  iNote->ShowNoteL(
              

                      iObserver->iStatus, 
              

                      EAknGlobalInformationNote, 
              

                      KInformationText);
              

                  }
              

              

              void CMyClient::~CMyClient()
              

                  {
              

                  delete iNote; 
              

                  delete iObserver;
              

                  }
             
            

• CGlobalObserver
• ShowNoteL()
• TRequestStatus

Canceling global notes

A note can be canceled with its ID. The following example shows how this is done:

             
              void CMyClient::ShowBusyNoteL()
              

                  {
              

                  CAknGlobalNote* note = CAknGlobalNote::NewLC();
              

                  _LIT(KWaitingText, "Busy");
              

                  TInt id = note->ShowNoteL(EAknGlobalWaitNote, KWaitingText);
              

                  User::After(5000000);
              

                  note->CancelNoteL(id);
              

                  CleanupStack::PopAndDestroy(note);
              

                  }
             
            

The canceling note object does not have to be the same object that showed the note.

Enhancing global notes

              
               note->SetSoftkeys(R_AVKON_SOFTKEYS_CLOSE);
               

               note->ShowNoteL(EAknGlobalWaitNote, KWaitingText);
              
             

              
               void CMyClient::TestNoteGraphicL()
               

                   {
               

                   _LIT(KGraphicText, "New Graphic");
               

                   CAknGlobalNote* note = CAknGlobalNote::NewL();
               

                   CleanupStack::PushL(note);
               

                   note->SetGraphic(
               

                       EMbmAvkonQgn_note_alarm_misc, 
               

                       EMbmAvkonQgn_note_alarm_misc_mask);
               

                   note->ShowNoteL(EAknGlobalInformationNote, KGraphicText);
               

                   CleanupStack::PopAndDestroy(note);
               

                   }
              
             

Showing global queries

Global queries are provided by several classes, such as:

• CAknGlobalConfirmationQuery .

• CAknGlobalListQuery .

• CAknGlobalMsgQuery .

• CAknGlobalListMsgQuery .

• CAknGlobalProgressDialog .

The query objects must exist until the user or the client code dismisses the query because they were designed to process user input. This is why all the Show…() methods expect a TRequestStatus . This status holds the user response. This is described in more detail below.

              
               void CMyClient::ShowGlobaConfirmationQueryL()
               

                   {
               

                   _LIT(KConfirmationText, "Please confirm!");
               

                   delete iGlobalConfirmationQuery;
               

                   iGlobalConfirmationQuery = 0;
               

                   iGlobalConfirmationQuery = CAknGlobalConfirmationQuery::NewL();
               

               

                   delete iConfirmationObserver;
               

                   iConfirmationObserver = 0;
               

                   iConfirmationObserver = new (ELeave) CGlobalObserver(iEikonEnv);
               

                   iConfirmationObserver->iStatus = KRequestPending;
               

                   iConfirmationObserver->Start();
               

               

                   iGlobalConfirmationQuery->ShowConfirmationQueryL(
               

                        iConfirmationObserver->iStatus,
               

                        KConfirmationText,
               

                        R_AVKON_SOFTKEYS_CLOSE);
               

                   }
              
             

              
               void CMyClient::ShowGlobalListQueryL()
               

                   {
               

                   delete iGlobalListQuery;
               

                   iGlobalListQuery = NULL;
               

                   iGlobalListQuery = CAknGlobalListQuery::NewL();
               

               

                   CDesCArray* textArray = iCoeEnv->ReadDesCArrayResourceL(
               

                       R_GLOBAL_LIST_ARRAY);
               

                   CleanupStack::PushL(textArray);
               

               

                   delete iListObserver;
               

                   iListObserver = 0;
               

                   iListObserver = new (ELeave) CGlobalObserver(iEikonEnv);
               

                   iListObserver->iStatus = KRequestPending;
               

                   iListObserver->Start();
               

               

                   iGlobalListQuery->ShowListQueryL(textArray, iListObserver->iStatus);
               

                   CleanupStack::PopAndDestroy(textArray);
               

                   }
              
             

              
               RESOURCE ARRAY r_global_list_array
               

                   {
               

                   items =
               

                       {
               

                       LBUF {txt = "Switch off";},
               

                       LBUF {txt = "General";},
               

                       LBUF {txt = "Silent";},
               

                       LBUF {txt = "Meeting";},
               

                       LBUF {txt = "Flight";}
               

                       };
               

                   }
              
             

              
               void CMyClient::ShowGlobalMsgQueryL()
               

                   {
               

                   _LIT(KHeaderText, "Header text"); 
               

                   _LIT(KMsgText, "Hello, I'm a global message query as you can see.");
               

                   delete iGlobalMsgQuery;
               

                   iGlobalMsgQuery = NULL;
               

                   iGlobalMsgQuery = CAknGlobalMsgQuery::NewL();
               

               

                   delete iMsgObserver;
               

                   iMsgObserver = 0;
               

                   iMsgObserver = new (ELeave) CGlobalObserver(iEikonEnv);
               

                   iMsgObserver->iStatus = KRequestPending;
               

                   iMsgObserver->Start();
               

               

                   iGlobalMsgQuery->ShowMsgQueryL(
               

                       iMsgObserver->iStatus,
               

                       KMsgText,
               

                       R_AVKON_SOFTKEYS_ANSWER_EXIT,
               

                       KHeaderText,
               

                       KNullDesC);
               

                   }
              
             

              
               void CMyClient::ShowGlobalListMsgQueryL()
               

                   {
               

                   _LIT(KHeaderText, "Header text");
               

                   _LIT(KMsgText, "Hello, I am a global list message query as you can see.");
               

                   delete iGlobalListMsgQuery;
               

                   iGlobalListMsgQuery = NULL;
               

                   iGlobalListMsgQuery = CAknGlobalListMsgQuery::NewL();
               

               

                   CDesCArray* textArray = iCoeEnv->ReadDesCArrayResourceL(
               

                       R_GLOBAL_LIST_ARRAY);
               

                   CleanupStack::PushL(textArray);
               

               

                   delete iListMsgObserver;
               

                   iListMsgObserver = 0;
               

                   iListMsgObserver = new (ELeave) CGlobalObserver(iEikonEnv);
               

                   iListMsgObserver->iStatus = KRequestPending;
               

                   iListMsgObserver->Start();
               

                   TInt index = 0;
               

               

                   iGlobalListMsgQuery->ShowListMsgQueryL(
               

                       textArray, 
               

                       iListMsgObserver->iStatus,
               

                       KHeaderText,
               

                       KMsgText);
               

                   CleanupStack::PopAndDestroy(textArray);
               

                   }
              
             

              
               const TInt KFinalValue = 50;
               

               

               void CMyClient::ShowGlobalProgressDialogL()
               

                   {
               

                   _LIT(KMsgText, "Hello, I'm a global progress dialog.");
               

                   delete iGlobalProgressDialog;
               

                   iGlobalProgressDialog = 0;
               

                   iGlobalProgressDialog = CAknGlobalProgressDialog::NewL();
               

               

                   delete iProgressObserver;
               

                   iProgressObserver = 0;
               

                   iProgressObserver = new (ELeave) CGlobalObserver(iEikonEnv);
               

                   iProgressObserver->iStatus = KRequestPending;
               

                   iProgressObserver->Start();
               

               

                   iCurrentValue = 0;
               

                   iGlobalProgressDialog->ShowProgressDialogL(
               

                       iProgressObserver->iStatus,
               

                       KMsgText,
               

                       R_AVKON_SOFTKEYS_CANCEL);
               

               

                   StartTimerL(10000, 10000);
               

                   }
               

               

               void CMyClient::StartTimerL(TInt aStart, TInt aInterval)
               

                   {
               

                   delete iTimer;
               

                   iTimer = 0;
               

                   iTimer = CPeriodic::NewL(EPriorityLow);
               

                   iTimer->Start(aStart, aInterval, TCallBack(TimerCallback, this));
               

                   }
               

               

               // Declare this method as static.
               

               TInt CMyClient::TimerCallback(TAny* aThis)
               

                   {
               

                   static_cast<CMyClient*>(aThis)->GlobalNoteProcessTimerEvent();
               

                   return 0;
               

                   }
               

               

               void CMyClient::GlobalNoteProcessTimerEvent()
               

                   {
               

                   if (!iGlobalProgressDialog)
               

                       {
               

                       return;
               

                       }
               

                   iCurrentValue++;
               

                   if (iCurrentValue <= KFinalValue)
               

                       {
               

                       iGlobalProgressDialog->UpdateProgressDialog(iCurrentValue, KFinalValue);
               

                       }
               

                   else
               

                       {
               

                       iGlobalProgressDialog->ProcessFinished();
               

                       iTimer->Cancel();
               

                       }
               

                   }
              
             

• CAknGlobalConfirmationQuery
• CAknGlobalListMsgQuery
• CAknGlobalListQuery
• CAknGlobalMsgQuery
• CAknGlobalProgressDialog
• Show…()
• TRequestStatus

Updating a confirmation or message query

Only the softkeys of the global confirmation or message query can be changed while the query is being displayed. This can be achieved with the UpdateConfirmationQuery() and UpdateMsgQuery() methods.

• UpdateConfirmationQuery()
• UpdateMsgQuery()

Manipulating the selection in a list or list message query

The selection (the highlight) can be moved in a list or list message query while it is being displayed with the MoveSelectionUp() and MoveSelectionDown() methods. The list API does not allow moving the selection to a particular position or getting the position of the currently selected item. However, the highlighted list item can be selected from the client code with the SelectItem() method.

• MoveSelectionDown()
• MoveSelectionUp()
• SelectItem()

Canceling global queries

Global queries can be canceled from the client code:

• A confirmation query can be canceled with CancelConfirmationQuery() .

• A list query can be canceled with CancelListQuery() .

• A message query can be canceled with CancelMsgQuery() .

• A list message query can be canceled with CancelListMsgQuery() .

• A progress dialog can be canceled with CancelProgressDialog() .

When a query is canceled with one of the methods above, the corresponding observer’s request status ( TRequestStatus ) is completed with KErrCancel .

• CancelConfirmationQuery()
• CancelListMsgQuery()
• CancelListQuery()
• CancelMsgQuery()
• CancelProgressDialog()
• KErrCancel
• TRequestStatus

Enhancing global queries

There is only a limited way to enhance global queries. Such enhancements are adding an animation, image or a tone to a confirmation query or adding an image or a tone (or both) to a message query.

The following example replaces the default image of the confirmation query:

             
                  iGlobalConfirmationQuery->ShowConfirmationQueryL(
              

                      iConfirmationObserver->iStatus,
              

                      KConfirmationText,
              

                      0,
              

                      0,
              

                      AknIconUtils::AvkonIconFileName(),
              

                      EMbmAvkonQgn_note_call,
              

                      EMbmAvkonQgn_note_call_mask);
             
            

The following example replaces the image with an animation:

             
                  iGlobalConfirmationQuery->ShowConfirmationQueryL(
              

                      iConfirmationObserver->iStatus,
              

                      KConfirmationText,
              

                      R_AVKON_SOFTKEYS_CLOSE,
              

                      R_QGN_NOTE_ERROR_ANIM);
             
            

The global progress dialogs can also be enhanced with an image, icon and a text appearing beside the icon. The example below illustrates this. SetImageL() and SetIconL() methods must be called before showing the dialog with ShowProgressDialogL() .

             
                  iGlobalProgressDialog->SetImageL(
              

                      AknIconUtils::AvkonIconFileName(), 
              

                      EMbmAvkonQgn_note_voice,
              

                      EMbmAvkonQgn_note_voice_mask);
              

              

                  iGlobalProgressDialog->SetIconL(
              

                      _L("1234567890"), 
              

                      AknIconUtils::AvkonIconFileName(),
              

                      EMbmAvkonQgn_prop_nrtyp_home,
              

                      EMbmAvkonQgn_prop_nrtyp_home_mask);
             
            

• SetIconL()
• SetImageL()
• ShowProgressDialogL()

Error handling

Notifiers API uses the standard Symbian platform error reporting mechanism. Leaves and system wide error codes as function return values are used if the error is recoverable. A client application can handle these errors similarly as a normal Symbian platform application.

Memory overhead

The RAM usage depends on the Notifier component used: a note, confirmation query, list query, message query, list message query or progress dialog. In case of the list and list message queries the memory usage is bigger compared to other notes and queries due to the array of list items. In any case, the classes communicate with the notifier server through the RNotifier API. This communication requires serializing the parameters and sending the serialized data through a client-server session. Then the server instantiates the necessary UI component and initializes and displays it in its UI context on top of all applications.

• RNotifier

Limitations of the API

There are no limitations to the API.

Extensions to the API

There are no extensions to the API.

Abbreviations

Notifiers API abbreviations