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.
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 OS 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;
}
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.
It is possible to enable or disable all text processing done by the dialog.
This can be done with the SetTextProcessing() method of CAknGlobalNote.
Any 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);
A 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);
}
Animation can be set to global notes with the SetAnimation() method
of CAknGlobalNote. It requires a BMPANIM_DATA resource
structure.
A tone can be set to notes as well with the SetTone() method
of CAknGlobalNote.
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.
The 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);
}
A 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
OS 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.
Global 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);
}
A 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.
The 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();
}
}
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.
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.
Global queries can be canceled from the client code:
CancelConfirmationQuery().CancelListQuery().CancelMsgQuery().CancelListMsgQuery().CancelProgressDialog().When a query is canceled with one of the methods above, the corresponding
observer’s request status (TRequestStatus) is completed with KErrCancel.
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);
Notifiers API uses the standard Symbian OS 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 OS platform application.
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.
There are no limitations to the API.
There are no extensions to the API.