S60 Discreet Pop-up API
Changes in the S60 Discreet Pop-up API documentation
| Version |
Date |
Status |
Description |
|
1.0
|
24.02.2010
|
Approved
|
|
PurposeThe purpose of the Discreet Pop-up component is to display notifications
without blocking the ongoing task flows in the user interface (UI). This means
that the underlying application can handle pointer events outside the pop-up
area even while the pop-up is being displayed. An action can be defined for
the pop-up that is activated when the user taps the pop-up. Discreet pop-ups can be displayed in touch and non-touch devices. For non-touch
devices, the touch functionality of the component is disabled. Discreet pop-up appears on the top of the display. The graphical outlook
of the pop-up varies depending on whether the pop-up contains interaction
or just a plain notification. When the pop-up contains interaction, it is
visually indicated by underlined text.
ConstraintsThis API is valid for all platforms running on Symbian OS v9.5 or later.
Classification and release informationThis API was first published in S60 release 5.2. This document is valid
from S60 release 5.2 onwards.
Emulator supportThis API is supported in the WINS/WINSCW emulator environment, with the
following exception:
API descriptionApplications can use discreet pop-ups for notifying the user in different
situations without blocking other ongoing tasks in the device UI. A pop-up
can be launched with a static call and it disappears after a certain time-out
interval (if the user does not tap the pop-up). Applications can define an
action for the pop-up that is executed when the pop-up is tapped. Tapping
also closes the pop-up. The two types of discreet pop-ups that can be used based on the purpose
of the use are as follows:
-
Global discreet pop-ups - They are displayed regardless of the
active application, i.e. they are always displayed on the top of the active
application, irrespective of any active application. They are launched with CAknDiscreetPopup::ShowGlobalPopupL().
-
Local discreet pop-ups - They are displayed only if the application
displaying the note is running on the foreground. They are launched with CAknDiscreetPopup::ShowLocalPopupL().
Note: A new discreet pop-up always overrides old pop-ups, except
that a local pop-up can never override global pop-ups. A discreet pop-up is temporary in nature and is displayed only for certain
duration (if an action is not taken). While the discreet pop-up is displayed,
the user can navigate through the applications normally. If the user exits
the application that has a local discreet pop-up currently displayed, the
pop-up is closed with the application. The pop-up visibility duration can be either short or long. Short duration
is used in scenarios where the user can expect a note to appear (for example,
confirmations) and when the nature of the message is positive (for example,
the attempted operation was successful). Long duration is used when the note
may appear spontaneously without any user action, or if the message content
is not what the user likely expected (for example, an error). The graphical outlook of a pop-up is simple. The pop-up launcher can define
the maximum of two lines of text and an icon for the pop-up. In addition,
a sound (confirmation, warning or error) can be played when the pop-up is
shown.
Use casesThe following use cases illustrate the typical use of the Discreet Pop-up
API:
API class structureUsing the Discreet pop-up API is simple for client applications. An instance
of
CAknDiscreetPopup needs not to be created; only a static
call is required to display the pop-up. The UI framework handles the creation
and destruction of the CAknDiscreetPopup instances. If the client application needs to receive notifications when the pop-up
is tapped, the pop-up can be provided with a pointer to the
MEikCommandObserver interface
implementing the class instance. The pop-up informs about taps through the MEikCommandObserver interface. Example of a pop-up observer: #include <eikcmobs.h> ... // Pop-up command ID const TInt KPopupCommandId( 1 ); ... class CPopupObserver : public CBase, public MEikCommandObserver { public: ... private: ... // from base class MEikCommandObserver /** * From MEikCommandObserver. * Processes user commands. * * @param ID of the command to respond to. */ void ProcessCommandL( TInt aCommandId ); ... };
Implementation: void CPopupObserver::ProcessCommandL( TInt aCommandId ) { if( aCommandId == KPopupCommandId ) { // Pop-up was tapped - do something } }
Related APIs
CAknDiscreetPopupMEikCommandObserver
Related APIs
CAknDiscreetPopup::ShowGlobalPopupL()CAknDiscreetPopup::ShowLocalPopupL()
Using the Discreet pop-up API
Launching a local pop-upA local pop-up is launched with a static call to
CAknDiscreetPopup::ShowLocalPopupL().
The client does not need to create an instance of CAknDiscreetPopup.
The UI framework handles the creation and destruction of local pop-ups automatically.
Pop-ups can be launched successively through the static call, irrespective
of the previous pop-up(s) being visible. In such scenario, the newly launched
pop-up overrides the old pop-up. After launching the pop-up, it cannot be
cancelled or hidden. The pop-up remains visible until the pop-up time-out
interval, unless the user taps the pop-up.
Launching a local pop-up with parametersA local pop-up can be launched with dynamically constructed parameters.
The pop-up launcher can define ten parameters, out of which only the
titleText parameter
is mandatory. In the absence of body text and title text not fitting to a
row, title text is wrapped to two rows. However, if body text is provided,
both title and body texts are always displayed regardless of their length. The pop-up icon can be provided in two ways: Bitmap information consists of the skin ID, bitmap file path, bitmap ID
and bitmap mask ID parameters. The skin ID can be defined as
KAknsIIDN,
if it is not applicable for a particular icon. In the following example code, the pop-up launcher has implemented the
MEikCommandObserver interface.
Hence, when the pop-up is tapped, its ProcessCommandL method
is called with the KCommandId parameter. #include <akndiscreetpopup.h> #include <avkon.mbg> #include <stringloader.h>… // Command ID const TInt KCommandId( 1 ); // Load strings from resources HBufC* titleText = StringLoader::LoadLC( R_DISCREET_POPUP_FIRST_ROW ); HBufC* bodyText = StringLoader::LoadLC( R_DISCREET_POPUP_SECOND_ROW ); CAknDiscreetPopup::ShowLocalPopupL( *titleText, // first text row *bodyText, // second text row NULL, // no "ready made" icon KAknsIIDQgnNoteInfo, // icon skin ID KAvkonBitmapFile, // bitmap file path EMbmAvkonQgn_note_info, // bitmap ID EMbmAvkonQgn_note_info_mask, // mask ID 0, // flags KCommandId, // command ID this ); // command observer
CleanupStack::PopAndDestroy( bodyText ); CleanupStack::PopAndDestroy( titleText );
Related APIs
CAknDiscreetPopupCGulIconKAknsIIDNKCommandIdMEikCommandObserverProcessCommandLtitleText
Launching a local pop-up using resource structureA local pop-up can also be launched using resource structure (
AVKON_DISCREET_POPUP)
defined in the application resources. Like when launching the pop-up with
dynamically constructed parameters, the only mandatory input is titleText.
In the absence of body text and title text not fitting to a row, title text
is wrapped to two rows. However, if the body text is provided, both title
and body texts are always displayed regardless of their length. Icon information can be provided by defining the bitmap file, bitmap ID,
bitmap mask ID and skin ID. The following example code illustrates how to launch a local pop-up using
resource structure: #include <aknsconstants.hrh> #include <avkon.mbg> #include <avkon.hrh> #include <avkon.rh>…
// ---------------------------------------------------------------------- // // r_discreet_popup_error // Discreet pop-up resource definition // // ---------------------------------------------------------------------- // RESOURCE AVKON_DISCREET_POPUP r_discreet_popup_error { flags = KAknDiscreetPopupErrorT | KAknDiscreetPopupDurationLong; // flags titleTxt = qtn_first_error_text; // first text line bodyTxt = qtn_second_error_text; // second text line bmpFile = AVKON_BITMAP_FILE; // icon bitmap file bmpId = EMbmAvkonQgn_note_error; // icon bitmap ID bmpMask = EMbmAvkonQgn_note_error_mask; // icon bitmap mask ID majorSkinId = EAknsMajorGeneric; // icon major skin ID minorSkinId = EAknsMinorQgnNoteError; // icon minor skin ID }
The pop-up is launched with the resource ID. Additionally, a command ID
and a pointer to command observer can be provided as parameters to enable
the event handling of the pop-up tapping. In the following example code, the pop-up launcher has implemented the
MEikCommandObserver interface.
Hence, when the pop-up is tapped, the ProcessCommandL method
is called with the KCommandId parameter. #include <akndiscreetpopup.h>… const TInt KCommandId( 1 ); CAknDiscreetPopup::ShowLocalPopupL( R_DISCREET_POPUP_ERROR, // resource id KCommandId, // command id this ); // command observer
Related APIs
AVKON_DISCREET_POPUPKCommandIdMEikCommandObserverProcessCommandLtitleText
Related APIs
CAknDiscreetPopupCAknDiscreetPopup::ShowLocalPopupL()
Launching a global pop-upA global pop-up is launched with a static call to
CAknDiscreetPopup::ShowGlobalPopupL().
The client does not need to create an instance of CAknDiscreetPopup.
The UI framework handles the creation and destruction of global pop-ups automatically.
Pop-ups can be launched successively through the static call, irrespective
of the previous pop-ups being visible. In such scenario, the newly launched
pop-up overrides the old pop-up. After launching the pop-up, it cannot be
cancelled or hidden. The pop-up remains visible until the pop-up time-out
interval, unless the user taps the pop-up.
Launching a global pop-up with parametersA global pop-up can be launched with dynamically constructed parameters.
The pop-up launcher can define eleven parameters, out of which only the
titleText parameter
is mandatory. In the absence of body text and title text not fitting to a
row, title text is wrapped to two rows. However, if the body text is provided,
both title and body texts are always displayed regardless of their length.
The pop-up icon can be provided by giving the bitmap information. Bitmap
information consists of the skin ID, bitmap file path, bitmap ID and bitmap
mask ID parameters.
Note: The skin ID can be defined as KAknsIIDN,
if it is not applicable for a particular icon. Like with the local pop-ups, a command observer (and command ID), that
get notified when the pop-up is tapped, can also be defined for global pop-ups.
Additionally, an application UID and a view UID can also be defined for a
global pop-up that is launched when the pop-up is tapped. The following example code illustrates how to launch a global discreet
pop-up with two rows of text. When the pop-up is tapped, an application with
KDiscreetPopupExampleUid is
launched and its view with the ID KDiscreetPopupViewUid is
activated. #include <akndiscreetpopup.h> #include <stringloader.h>… const TUid KDiscreetPopupExampleUid = { 0xABCDEF12 }; const TUid KDiscreetPopupViewUid = { 0x1 };
// Load strings from resources HBufC* titleText = StringLoader::LoadLC( R_DISCREET_POPUP_FIRST_ROW ); HBufC* bodyText = StringLoader::LoadLC( R_DISCREET_POPUP_SECOND_ROW ); CAknDiscreetPopup::ShowGlobalPopupL( *titleText, // first text row *bodyText, // second text row KAknsIIDN, // icon skin ID KNullDesC, // bitmap file path -1, // bitmap ID -1, // mask ID 0, // flags 0, // command ID NULL, // command observer KDiscreetPopupExampleUid, // application to be launched KDiscreetPopupViewUid ); // view to be activated CleanupStack::PopAndDestroy( bodyText ); CleanupStack::PopAndDestroy( titleText );
Related APIs
KAknsIIDNKDiscreetPopupExampleUidKDiscreetPopupViewUidtitleText
Launching a global pop-up using resource structureLaunching a global pop-up using resource structure is possible in the same
way as launching a local pop-up. The pop-up is defined in the resource file
and the resource ID is used when launching the pop-up. The following example code illustrates how to launch a global pop-up using
resource structure: #include <aknsconstants.hrh> #include <avkon.mbg> #include <avkon.hrh> #include <avkon.rh>… // ---------------------------------------------------------------------- // // r_discreet_popup_warning // Discreet popup resource definition // // ---------------------------------------------------------------------- // RESOURCE AVKON_DISCREET_POPUP r_discreet_popup_warning { flags = KAknDiscreetPopupWarningT | KAknDiscreetPopupDurationLong; // flags titleTxt = qtn_first_warning_text; // first text line bodyTxt = qtn_second_warning_text; // second text line bmpFile = AVKON_BITMAP_FILE; // icon bitmap file bmpId = EMbmAvkonQgn_note_warning; // icon bitmap ID bmpMask = EMbmAvkonQgn_note_warning_mask; // icon bitmap mask ID majorSkinId = EAknsMajorGeneric; // icon major skin ID minorSkinId = EAknsMinorQgnNoteWarning; // icon minor skin ID }
The pop-up is launched with the resource ID. Also, the path to the resource
file must be provided when launching a global pop-up. Additionally, a command
ID and a pointer to command observer (as well as an application UID and a
view UID) can be provided as parameters to enable the event handling of the
pop-up tapping. In the following example code, the pop-up launcher has implemented the
MEikCommandObserver interface.
Hence, when the pop-up is tapped, the ProcessCommandL method
is called with the KCommandId parameter. If application and
view UIDs are also provided, the application with the specified UID is launched
and the command is handled. #include<akndiscreetpopup.h>… _LIT( KResourceFile, "\\resource\\apps\\appresource.rsc" ); const TInt KCommandId( 1 ); CAknDiscreetPopup::ShowGlobalPopupL( R_DISCREET_POPUP_WARNING, // resource ID KResourceFile, // resource file KCommandId, // command ID this ); // command observer
Related APIs
KCommandIdMEikCommandObserverProcessCommandL
Related APIs
CAknDiscreetPopupCAknDiscreetPopup::ShowGlobalPopupL()
Defining discreet pop-up flagsThe following flags can be defined using the Discreet Pop-up API:
-
KAknDiscreetPopupDurationLong - Sets the pop-up duration
to long (default is short).
-
KAknDiscreetPopupConfirmationTone - Pop-up plays the
confirmation tone when it is displayed.
-
KAknDiscreetPopupWarningTone - Pop-up plays the warning
tone when it is displayed.
-
KAknDiscreetPopupErrorTone - Pop-up plays the error tone
when it is displayed.
The flags are defined in the
avkon.hrh header file. Flag
values can be combined freely.
Note: A pop-up can have only one of the tone flags (KAknDiscreetPopupConfirmationT, KAknDiscreetPopupWarningT, and KAknDiscreetPopupErrorT) set.
Related APIs
KAknDiscreetPopupConfirmationTKAknDiscreetPopupConfirmationToneKAknDiscreetPopupDurationLongKAknDiscreetPopupErrorTKAknDiscreetPopupErrorToneKAknDiscreetPopupWarningTKAknDiscreetPopupWarningToneavkon.hrh
Memory overheadMemory consumption depends on the number of discreet pop-ups co-existing.
Extensions to the APIThere is no explicit support for extensions to the Discreet Pop-up API.
Limitations of the APIControl Environment (ConE) is required for using local pop-ups.
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|