Purpose

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

Constraints

This API is valid for all platforms running on Symbian OS v9.5 or later.

Classification and release information

This API was first published in S60 release 5.2. This document is valid from S60 release 5.2 onwards.

Emulator support

This API is supported in the WINS/WINSCW emulator environment, with the following exception:

  • Tactile feedback is not supported.

API description

Applications 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 cases

The following use cases illustrate the typical use of the Discreet Pop-up API:

  • Launching a local pop-up

    • Launching a local pop-up with parameters

    • Launching a local pop-up using resource structure

  • Launching a global pop-up

    • Launching a global pop-up with parameters

    • Launching a global pop-up using resource structure

  • Defining discreet pop-up flags

API class structure

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

The Discreet pop-up API class structure


The Discreet pop-up API class structure

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
  • CAknDiscreetPopup
  • MEikCommandObserver
Related APIs
  • CAknDiscreetPopup::ShowGlobalPopupL()
  • CAknDiscreetPopup::ShowLocalPopupL()

Using the Discreet pop-up API

Launching a local pop-up

A 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 parameters

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

  • By providing a pointer to a constructed CGulIcon instance (ownership of the icon will transfer to CAknDiscreetPopup).

  • By providing the bitmap information.

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
  • CAknDiscreetPopup
  • CGulIcon
  • KAknsIIDN
  • KCommandId
  • MEikCommandObserver
  • ProcessCommandL
  • titleText

Launching a local pop-up using resource structure

A 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_POPUP
  • KCommandId
  • MEikCommandObserver
  • ProcessCommandL
  • titleText
Related APIs
  • CAknDiscreetPopup
  • CAknDiscreetPopup::ShowLocalPopupL()

Launching a global pop-up

A 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 parameters

A 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
  • KAknsIIDN
  • KDiscreetPopupExampleUid
  • KDiscreetPopupViewUid
  • titleText

Launching a global pop-up using resource structure

Launching 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
  • KCommandId
  • MEikCommandObserver
  • ProcessCommandL
Related APIs
  • CAknDiscreetPopup
  • CAknDiscreetPopup::ShowGlobalPopupL()

Defining discreet pop-up flags

The 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
  • KAknDiscreetPopupConfirmationT
  • KAknDiscreetPopupConfirmationTone
  • KAknDiscreetPopupDurationLong
  • KAknDiscreetPopupErrorT
  • KAknDiscreetPopupErrorTone
  • KAknDiscreetPopupWarningT
  • KAknDiscreetPopupWarningTone
  • avkon.hrh

Memory overhead

Memory consumption depends on the number of discreet pop-ups co-existing.

Extensions to the API

There is no explicit support for extensions to the Discreet Pop-up API.

Limitations of the API

Control Environment (ConE) is required for using local pop-ups.