Notifiers API Specification

Contents

1 Overview

Notifiers 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.


API categorypublic
API typec++
Existed sinceLegacy S60 0.9
API librariesaknnotify.lib
Location/sf/mw/classicui/classicui_pub/notifiers_api
Buildfiles/sf/mw/classicui/classicui_pub/notifiers_api/group/bld.inf


1.1 Description

Global 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:

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 [Notifiers_API_Specification.topic5 (1)].

1.1.1 Emulator support

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

1.2 Changes

Notifiers API is an SDK API and a part of S60 Third Edition. This document is valid from S60 release 3.2 onwards.

There are no constraints.

1.3 Use Cases

The main use cases of Notifiers API are:

1.4 Class Structure

Summary of API classes and header files
ClassesFiles
CAknGlobalConfirmationQuery /epoc32/include/mw/AknGlobalConfirmationQuery.h CAknGlobalListMsgQuery /epoc32/include/mw/AknGlobalListMsgQuery.h CAknGlobalListQuery /epoc32/include/mw/AknGlobalListQuery.h CAknGlobalMsgQuery /epoc32/include/mw/AknGlobalMsgQuery.h CAknGlobalNote /epoc32/include/mw/AknGlobalNote.h CAknGlobalProgressDialog /epoc32/include/mw/AknGlobalProgressDialog.h CAknNotifyBase /epoc32/include/mw/AknNotify.h CAknPopupNotify /epoc32/include/mw/AknPopupNotify.h MAknUINotifierBase /epoc32/include/mw/AknNotifyStd.h RNotifier2 /epoc32/include/mw/AknNotify.h

Generally all the classes use the Symbian OS 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.

UML diagram of the global note
UML diagram of the global note

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

UML diagram of the global confirmation query
UML diagram of the global confirmation query

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

UML diagram of the global list query
UML diagram of the global list query
UML diagram of the global message query
UML diagram of the global message query

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

The UML diagram of the global list message query
The UML diagram of the global list message query
UML diagram of the global progress dialog
UML diagram of the global progress dialog

2 Using The API

2.1 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:

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 [Notifiers_API_Specification.topic3.3 Canceling global notes].

2.2 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 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;
    }

2.3 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.

2.4 Enhancing global notes

2.4.1 Setting the note text processing

It is possible to enable or disable all text processing done by the dialog. This can be done with the SetTextProcessing() method of CAknGlobalNote .

2.4.2 Setting the note softkeys

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);

2.4.3 Setting the note graphic

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);
    }

2.4.4 Setting the note animation

Animation can be set to global notes with the SetAnimation() method of CAknGlobalNote . It requires a BMPANIM_DATA resource structure.

2.4.5 Setting the note tone

A tone can be set to notes as well with the SetTone() method of CAknGlobalNote .

2.5 Showing global queries

Global 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.

2.5.1 Showing a confirmation query

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);
    }

2.5.2 Showing a list query

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 [Notifiers_API_Specification.topic5 (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.

2.5.3 Showing a message query

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);
    }

2.5.4 Showing a list message query

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 [Notifiers_API_Specification.topic3.5.2 Showing a list query].

2.5.5 Showing and updating a progress dialog

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();
        }
    }

2.6 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.

2.7 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.

2.8 Canceling global queries

Global queries can be canceled from the client code:

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

2.9 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);

2.10 Error handling

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.

2.11 Memory and Performance Considerations

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.

2.12 Extensions to the API

There are no extensions to the API.

2.13 Limitations of the API

There are no limitations to the API.

3 Glossary

There is no glossary.

3.1 Abbreviations

Notifiers API abbreviations
API Application Programming Interface
ID Identifier
OS Operating System

4 References

(1) S60 Skins API Specification Document
(2) S60 Lists API Specification Document