Notifiers API
Changes in Notifiers API documentation
PurposeNotifiers API includes a number of global notes and global queries that
are used by applications and engine components to display notes or query the
user for information globally on top of other applications. Using the notes is suggested if the client does not have its own UI context
(an instance of
CCoeEnv ). Such clients are usually engine
components that do not have an UI environment at all. It is important to note that they are shown on top of all applications,
thus they should be used sparingly.
Classification and release informationNotifiers 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.
Related APIs
API descriptionGlobal notes and queries are able to be driven from applications or engines
without access to any other UI components or UI environments. They hide the
RNotifier API
and provide helper classes on top of that. Global notes provide a simple notification UI with optional soft keys,
graphic, animation and tones. They display textual information in a given
format. The format or rather the note type is defined by
TAknGlobalNoteType .
The notes are provided by one class, namely CAknGlobalNote . One interesting aspect of the global notes is that each note is identified
by a
TInt ID, and the client can refer to a note with the
help of such an ID. Global queries provide a slightly more complex UI. For example, in case
CAknGlobalMsgQuery is
located beside the text, a header text and image can also be specified. The
following global queries exist:
-
The confirmation query
(CAknGlobalConfirmationQuery) .
-
The list query
(CAknGlobalListQuery) .
-
The message query
(CAknGlobalMsgQuery) .
-
The list message query
CAknGlobalListMsgQuery ).(
-
The progress dialog
(CAknGlobalProgressDialog) , which
is a global query in a way.
The displaying order of the global notes and queries (in case of components
that have no time-out) is LIFO (last in, first out). The global notes and queries interact correctly with the key lock mechanism,
and hide themselves from the display automatically when a call is active.
They reappear once a call has been disconnected. All global notes and queries
can be canceled (simultaneously in case several notifiers exist) by pressing
the End key while a call is not active. Note that task switching (using the
Applications key) is not possible when a global note or query is visible. Global notes and queries support skins. For more information on skins,
refer to Skins API Specification
[1].
Use casesThe 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 structureGenerally 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.
Related APIs
Related APIs
(CAknGlobalConfirmationQuery) (CAknGlobalListQuery) (CAknGlobalMsgQuery) (CAknGlobalProgressDialog) CAknGlobalListMsgQuery CAknGlobalMsgQuery CAknGlobalNote RNotifier TAknGlobalNoteType TInt
Using the Notifiers API
Showing global notesAll 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:
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.
Related APIs
CAknGlobalNote EAknGlobalConfirmationNote EAknGlobalErrorNote EAknGlobalInformationNote EAknGlobalTextNote EAknGlobalWaitNote EAknGlobalWarningNote ShowNoteL() TAknGlobalNoteType TRequestStatus
Getting global notes responsesIt 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; }
Related APIs
CGlobalObserver ShowNoteL() TRequestStatus
Canceling global notesA 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
Setting the note text processingIt is possible to enable or disable all text processing done by the dialog.
This can be done with the
SetTextProcessing() method of CAknGlobalNote .
Related APIs
CAknGlobalNote SetTextProcessing()
Setting the note softkeysAny kind of a softkey (pair) can be added to the note before showing it
with the
SetSoftkeys() method: note->SetSoftkeys(R_AVKON_SOFTKEYS_CLOSE); note->ShowNoteL(EAknGlobalWaitNote, KWaitingText);
Related APIs
Setting the note graphicA graphic and the corresponding mask can be set to global notes with the
SetGraphic() method
of CAknGlobalNote . 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); }
Related APIs
CAknGlobalNote SetGraphic()
Setting the note animationAnimation can be set to global notes with the
SetAnimation() method
of CAknGlobalNote . It requires a BMPANIM_DATA resource
structure.
Related APIs
BMPANIM_DATA CAknGlobalNote SetAnimation()
Setting the note toneA tone can be set to notes as well with the
SetTone() method
of CAknGlobalNote .
Related APIs
Showing global queriesGlobal queries are provided by several classes, such as:
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.
Showing a confirmation queryThe following example illustrates the creation of a global confirmation
query, and also how it is shown to the user. 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); }
Showing a list queryA global list query displays a list. When the user selects a list item,
the completed request status passed to the
ShowListQueryL() of CAknGlobalListQuery holds
the non-negative index (starting from zero) of the selected item or a Symbian
platform error code if the query was rejected or canceled. 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); }
In the previous example
R_GLOBAL_LIST_ARRAY is an ARRAY resource
structure. CAknGlobalListQuery is allowed to hold only simple
list items (no tabulators are allowed in the items). For more information
on lists, see Lists API Specification [2]. The following extract gives an example of the array resource structure: RESOURCE ARRAY r_global_list_array { items = { LBUF {txt = "Switch off";}, LBUF {txt = "General";}, LBUF {txt = "Silent";}, LBUF {txt = "Meeting";}, LBUF {txt = "Flight";} }; }
Note that it is possible to set a heading for the list query with the
SetHeadingL() method.
Related APIs
ARRAY CAknGlobalListQuery R_GLOBAL_LIST_ARRAY SetHeadingL() ShowListQueryL()
Showing a message queryGlobal message queries enable specifying a query header text, a separate
query message below the header, softkeys, and a header image and a tone. The following example illustrates the construction and displaying of a
message query: 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); }
Showing a list message queryA global list message query displays a list with message. When the user
selects a list item and chooses the accepting softkey, the completed request
status passed to
CAknGlobalListMsgQuery ’s ShowListMsgQueryL() holds
the non-negative index (starting from zero) of the selected item. If the user
selects the canceling softkey, the index contains the softkey ID, which is
either a negative value or a positive value starting from 3000. The default
accepting and canceling softkeys are OK and Cancel, but those can be defined
by the user. 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); }
Defining the list array resource for global list message query is identical
to the global list query. For details, refer to
Showing a list query.
Related APIs
CAknGlobalListMsgQuery ShowListMsgQueryL()
Showing and updating a progress dialogThe global progress dialog displays a message to the user together with
a progress bar. The dialog is implemented in the class
CAknGlobalProgressDialog and
can be shown with the ShowProgressDialogL() method. This
method displays a null progress, so the progress bar stands on 0%. To update
progress info, the UpdateProgressDialog() method must be
called specifying the current and final value. The following example shows a progress dialog and uses a periodic timer
object (
CPeriodic ) that updates the progress bar: 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(); } }
Related APIs
CAknGlobalProgressDialog CPeriodic ShowProgressDialogL() UpdateProgressDialog()
Related APIs
CAknGlobalConfirmationQuery CAknGlobalListMsgQuery CAknGlobalListQuery CAknGlobalMsgQuery CAknGlobalProgressDialog Show…() TRequestStatus
Updating a confirmation or message queryOnly 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.
Related APIs
UpdateConfirmationQuery() UpdateMsgQuery()
Manipulating the selection in a list or list message queryThe 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.
Related APIs
MoveSelectionDown() MoveSelectionUp() SelectItem()
Canceling global queriesGlobal 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 .
Related APIs
CancelConfirmationQuery() CancelListMsgQuery() CancelListQuery() CancelMsgQuery() CancelProgressDialog() KErrCancel TRequestStatus
Enhancing global queriesThere 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);
Related APIs
SetIconL() SetImageL() ShowProgressDialogL()
Error handlingNotifiers 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 overheadThe 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.
Related APIs
Limitations of the APIThere are no limitations to the API.
Extensions to the APIThere are no extensions to the API.
GlossaryThere is no glossary.
Abbreviations
Notifiers API abbreviations
API |
Application Programming Interface |
ID
|
Identifier
|
OS
|
Operating System
|
References
[1] S60 Skins API Specification Document |
|
[2] S60 Lists API Specification Document
|
|
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|