All the following use-cases use the ShowNoteL() method
of the CAknGlobalNote class without a 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 a TRequestStatus.
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 others are not suggested to be used.
All the listed notes have a short timeout - the note is dismissed by the system automatically, if there is no soft key defined for them, but in case of the wait note, that is not true because the note displays a ‘Cancel’ soft key 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 graphic in it. Of course, as in case of other notes, enhancements (soft keys, graphic, animation, tone) can be added to it.
Even if a note is shown and right after it’s deleted, the note remains on the screen: i.e. deleting the actual note object does not dismiss the note itself! If the note must be dismissed, it must be cancelled by the client code (or of course by the user). This is discussed in Canceling global notes.
It is possible to observe the outcome of a global note. It requires a TRequestStatus to
be passed to ShowNoteL() as parameter. The completed status
holds the ID of the soft key pressed 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 = 0;
iNote = CAknGlobalNote::NewL();
delete iObserver;
iObserver = 0;
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 cancelled with its ID. The following example shows this:
void CMyClient::ShowBusyNoteL()
{
CAknGlobalNote* note = CAknGlobalNote::NewLC();
TInt id = note->ShowNoteL(EAknGlobalWaitNote, _L("Busy"));
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 CAknGlobalNote‘s SetTextProcessing() method.
Any kind of soft key (pair) can be added to the note before showing it
with SetSoftkeys() method:
iNote->SetSoftkeys(R_AVKON_SOFTKEYS_CLOSE); iNote->ShowNoteL(EAknGlobalWaitNote, KWaitingText);
A graphic and the corresponding mask can be set to global notes with CAknGlobalNote‘s SetGraphic() method.
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 CAknGlobalNote‘s SetAnimation() method.
It requires a BMPANIM_DATA resource structure.
A tone can be set also to notes with CAknGlobalNote‘s SetTone() method.
Global queries are provided by several classes, like:
CAknGlobalConfirmationQueryCAknGlobalListQueryCAknGlobalMsgQueryCAknGlobalProgressDialog.
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…() method expect a TRequestStatus.
This status holds the user response. It will be described in more details
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 CAknGlobalListQuery’s ShowListQueryL() holds
the non-negative index (starting from zero) of the selected item or a Symbian
OS error code, if the query was rejected or cancelled.
void CMyClient::ShowGlobalListQueryL()
{
delete iGlobalListQuery;
iGlobalListQuery = NULL;
iGlobalListQuery = CAknGlobalListQuery::NewL();
CDesCArray* textArray = iCoeEnv->ReadDesCArrayResourceL(
R_GLOBAL_LIST_ARRAY );
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). About lists refer to
Lists API Specification.
The following extract gives an example for 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 heading to the list query with the SetHeadingL() method!
Global message queries enable specifying a query header text, a separate query message below the header, soft keys, header image and 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);
}
The global progress dialog displays a message to the user together with
a progress bar. The dialog is implemented in 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, UpdateProgressDialog() method must be called
specifying the current and the 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));
}
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 soft keys of the global confirmation query can be changed while
the query is being displayed. This can be achieved with the UpdateConfirmationQuery() method.
The selection (the highlight) can be moved in a list 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 get the position of the currently selected item. However, the highlighted
list item can be selected from client code with the SelectItem() method.
Like in case of global confirmation query, the message query’s soft keys
can only be updated while the query is being displayed. It can be achieved
with CAknGlobalMsgQuery’s UpdateMsgQuery() method.
Global queries can be cancelled from the client code:
CancelConfirmationQuery(),
CancelListQuery(),
CancelMsgQuery(),
CancelProgressDialog().
When a query is cancelled, the corresponding observer’s request status
(TRequestStatus) is completed with EEikBidCancel.
There is only a limited way to enhance global queries. Such enhancements are adding animation, image or tone to a confirmation query or adding image or 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);
Global progress dialogs can also be enhanced with image, icon and a text
appearing beside the icon. The following example 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 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, a confirmation
query, a list query, a message query or a progress dialog. In case of list
query 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, initializes
and displays it in its UI context on top of all applications.
None.
None.