Dialogs API Specification


1 Overview

Dialogs are UI elements used by GUI applications.

Dialog terminology
Dialog terminology

As shown in Figure 1, a dialog consists of a title, zero or more pages consisting of a sequence of lines, and a row of one or more softkeys (CBA).

The lines can only be arranged vertically, allowing for simpler programming, a small application footprint, and a high likelihood of dialogs that are easy for novice users to use. Each line consists of a label and a control for displaying and entering data. The controls are: a choice list, a set of option buttons, a check box, and input fields. Most dialogs have one page of controls.

Multi-page tabs only appear in multi-page dialogs. They are used to access separate dialog pages. When a lot of controls are put together on a single dialog, a multi-page dialog (or occasionally a scrolling dialog) is invariably used to fit all the controls neatly on devices' small screens. There is a difference between multi-page tabs with dialog architecture and multi-views with view architecture. In views, the view state and data need to be saved between the switch, and each view can be activated from outside by a view-switch mechanism, whereas in multi-page dialogs data is saved when the dialog is closed (after memory footprint) and it is not possible to reach individual dialog tabs from outside the dialog.

For typical dialog uses, S60 provides a large collection of ready-made dialog classes.

See S60 3.1 Queries API Specification for more information.

used by components which have no UI context (for example, engine components). See S60 3.1 Notifiers API Specification for more information.

to the user. See S60 3.1 Notes API Specification for more information.

settings). See S60 3.1 Form API Specification for more information. This document describes how to implement and use dialogs.

For further information see API documentation for CEikDialog in Symbian OS 9.1 API Reference Guide for more information.

API categorypublic
API typec++
Existed sinceLegacy S60 0.9
API librarieseikdlg.lib

1.1 Description

Dialogs API allows creating and using application-specific dialogs.

Dialogs use the dialog resource, defined in the application resource file (RSS). The runtime representations of dialogs are instances of the CEikDialog and CAknDialog classes, or any custom class deriving from the above. Derivation is used to add custom functionality, controls or behavior to standard dialogs.

1.2 Changes

Dialogs API is an SDK API and was first published in S60 release 0.9.

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

1.3 Use Cases

  • Defining the resource
  • Defining the dialog resource
  • Defining the dialog line resource
  • Defining the softkeys
  • Defining single-page dialog resource
  • Defining multi-page dialog resource
  • Creating and launching dialog
  • Creating dialog without menu
  • Creating dialog with menu
  • Launching the dialog
  • Accessing control in dialog
  • Implementing custom dialog
  • Providing the factory function
  • Initializing controls
  • Checking the exit condition
  • Adding custom control to dialog
  • Handling commands
  • Handling key events

1.4 Class Structure

Summary of API classes and header files
CEikDialog /epoc32/include/mw/eikdialg.h

Many methods of CEikDialog can be overridden to provide custom behavior. If standard behavior and built-in components are sufficient, CEikDialog or CAknDialog can be used directly.

CAknDialog adds Options menu handling to CEikDialog .

Dialogs API
Dialogs API

2 Using The API

Two steps are necessary to use dialogs:

application resource file.

be used. Custom dialogs can also be developed by deriving from these base classes. Most methods of dialogs base classes are virtual.

Optionally, individual dialog lines and controls can be accessed and manipulated. This enables modifying the dialog contents runtime.

2.1 Defining the resource

2.1.1 Defining the dialog resource

A DIALOG resource encapsulates the structure of a dialog. The developers need to define a dialog using the DIALOG resource. Its STRUCT is defined in the eikon.rh file with the following members:

    LONG flags=0;
    LTEXT title="";
    LLINK pages=0;
    LLINK buttons=0;
    STRUCT items();
    LLINK form=0;
Dialog resource structure
Member Description
LONG flags = 0; Optional bitmask of flags governing attributes of the dialog. Defaults

to 0.

LTEXT title = ""; The title of the dialog, displayed at the top. Not really used in the

S60 platform because most of the dialogs are full screen dialogs. — The status pane would give information related to the dialog content.

LLINK pages = 0; A resource defining the pages in a multi-page dialog. Do not specify

this if you only want a single-page dialog.

LLINK buttons = 0; A resource defining the buttons to use in the dialog. The default is

no buttons.

STRUCT Items(); A comma-separated list of dialog lines.
LLINK form = 0; A reference to the FORM structure used in single-page forms. Can be

used to specify the style of the form. Supported from S60 release 2.6 onwards. Forms are documented in S60 3.1 Form API Specification. Dialog flags

The dialog types are defined by the flags parameter in the DIALOG structure. These are defined in the eikon.hrh and avkon.hrh files. The basic dialog flags are defined by EEikDialogFlagXxx in the eikon.hrh file, but some of them are not used anymore in the S60 UI.

Note: Symbian OS versions older than v9.1 (S60 releases 1.x and 2.x) specify the dialog flags in the uikon.hrh file.

Typical dialogs specify EEikDialogFlagWait ; other flags control keypad input flow, whether there is a title, and several others, as shown in Table 2.

Dialog resource flags
Flag Description
EEikDialogFlagWait CEikDialog::ExecuteLD() does not return until the

dialog is dismissed.

EEikDialogFlagModeless The dialog does not grab the pointer, and it is not added to the control

stack (so it cannot receive key presses).

EEikDialogFlagNoTitleBar The dialog has no title bar. Default in S60 devices.
EEikDialogFlagAllKeysToButtons This flag must be set for dialogs that use unmodified keys (that is,

keys which are not used in combination with Shift, Ctrl, or Fn). For example, it would typically be set for a dialog that contains "Yes" and "No" buttons, which are activated by an unmodified "Y" or "N" key press.

EEikDialogFlagFillScreen The dialog is sized to fill the screen.
EEikDialogFlagFillAppClientRect The dialog is sized to fill the client rectangle.
EEikDialogFlagCbaButtons The dialog has CBA buttons.
EEikDialogFlagDensePacking Spacing around dialog components is minimized.
EEikDialogFlagNoBackup Do not use a backup window to minimize redrawing. By default, dialogs

use screen backup to minimize redrawing. For more information, see RWindowBase::EnableBackup() .

EEikDialogFlagNotifyEsc The dialog framework calls CEikDialog::OkToExitL() when

the Cancel button is activated (or its hotkey, Esc, is pressed).

EEikDialogFlagNoUserExit The user cannot dismiss the dialog. This is often used for progress


EEikDialogFlagNoBorder No border is drawn for this dialog, TGulBorder::ENone
EEikDialogFlagNoShadow Disable the dialog's shadow, CEikonEnv::AddWindowShadow() .
EEikDialogFlagNoBackgroundFade Related to the internal method DoFadeBehindPopup() .
EEikDialogFlagDontEatUpDownEvents Used by EAknDialogMarkableList . DialogPageSelector forwards

up/down events to its PageContainer .

EAknDialogGenericFullScreen (binary or) into a single

flag. ( EEikDialogFlagNoDrag | EEikDialogFlagNoTitleBar | EEikDialogFlagFillAppClientRect | EEikDialogFlagCbaButtons | EEikDialogFlagWait )

EAknDialogFlagNotConstructed CAknDialog::SetEmphasis() called by the framework

returns immediately, when that dialog is not constructed.

EAknDialogFlagDialogDeleted CAknDialog::SetEmphasis() called by the framework

returns immediately, when that dialog is deleted already.

Note that for compatibility reasons some flags have been maintained in the S60 platform, but none of these are in use anymore in the S60 platform. These removed flags are listed in Table 3.

Removed dialog resource flags
Flag Description
EEikDialogFlagButtonsBelow The dialog's button panel is positioned below the dialog lines.
EEikDialogFlagButtonsRight Not in the S60 platform. The dialog's button panel is positioned to

the right of the dialog lines, with the buttons arranged vertically.

EEikDialogFlagNoDrag Removed because no pointing device is defined in the current S60 UI

versions. The dialog cannot be moved around the screen by dragging it with the pointing device.

EEikDialogFlagNoTitleBar The dialog has no title bar.

2.1.2 Defining the dialog line resource

The dialog line structure contained in dialogs is defined in the eikon.rh file.

    WORD type;
    LTEXT prompt;
    WORD id=0;
    LONG itemflags=0;
    STRUCT control;
    LTEXT trailer="";
    LTEXT bmpfile = "" ;
    WORD bmpid = 0xffff ;
    WORD bmpmask ;
    LTEXT tooltip = "" ;
Dialog line resource struct
Member Description
WORD type; The control factory identifier for a control. This may be a custom

control, or one of the stock control classes. The dialog object must be able to understand the value of this WORD — unrecognized controls cause the dialog to panic. Stock controls are identified by EEikCt... and EAknCt... values (defined in eikon.hrh and avkon.hrh, respectively). Dialogs using custom controls must use custom type value and override the virtual CEikDialog::CreateCustomControlL() function to create the custom control.

LTEXT prompt; The text that appears in front of the control in this dialog line.
WORD id = 0; The control ID. This can be used in the C++ source to refer to the

control in this dialog line. The ID must be defined in a HRH file. Default value: 0

LONG itemflags = 0; Item flags. Default value: 0 — no flags set.
STRUCT control; Resource defining this control. This is the resource for a custom control

or one of the stock control classes. Target type: Varies according to the value of the type member.

LTEXT trailer = ""; The text that appears after the control in this dialog line. Default

value: No trailer text.

LTEXT bmpfile = "" ; Specifies the bitmap file name.
WORD bmpid = 0xffff ; Icon image ID, which is the enumeration of an icon image. Supported

from S60 release 2.6 onwards. Default value: 0xffff

WORD bmpmask ; Specifies the icon mask ID. Supported from S60 release 2.6 onwards.
LTEXT tooltip = "" ; Help text for the form line. Supported from S60 release 2.6 onwards. Dialog line flags

Dialog items can have their own flags, as specified in Table 5.

Dialog item flags
Flag Description
EEikDlgItemCtlGetsWidthFirst If there is insufficient space on the dialog, the item has priority

for using the available width.

EEikDlgItemCtlMinHeightOrLess Item height does not expand to fill the available space.
EEikDlgItemCtlMinWidthOrLess Item width does not expand to fill the available space.
EEikDlgItemCtlSharesWidth If there is insufficient space for the item, the item is scaled to

get an equal share of the available space.

EEikDlgItemIndirect Specifies that the line is specified indirectly through an LLINK.
EEikDlgItemLatent The item is initially invisible, and requires a call from the client

to make it visible.

EEikDlgItemLglf A latent group line ( EEikDlgItemLatent ) follows.
EEikDlgItemNoBorder No border is drawn for this item, TGulBorder::ENone .
EEikDlgItemNonFocusing The item does not take keyboard focus.
EEikDlgItemSeparatorAfter A separator is drawn after this line.
EEikDlgItemSeparatorMask Provides a mask for DLG_LINE flags ( EEikDlgItemNoSeparator , EEikDlgItemSeparatorAfter ).
EEikDlgItemTakesEnterKey Item responds to the Enter key.
EEikDlgItemOfferAllHotKeys The item should be offered all hot key events.
EEikDlgItemTrailerAfterEar The item specifies some text in a trailer field to place after the

input area ear.

The flags listed in Table 6 exist only for compatibility reasons.

Dialog item flags not in use
Flag Description
EEikDlgItemAsLabel Treat the line as a label (does not respond to input).
EEikDlgItemColumnEnd Not used.
EEikDlgItemCtlGetsWidthFirst If there is insufficient space on the dialog, the item has priority

for using the available width.

EEikDlgItemCtlMinSizeOrLess Item height does not expand to fill the available space.
EEikDlgItemNoSeparator No separator is drawn between this line and the next.

2.1.3 Defining the softkeys

The softkeys in dialogs (buttons field of the DIALOG resource) are defined by a CBA resource. Avkon provides predefined softkeys. The list of predefined softkeys ( R_AVKON_SOFTKEYS_XXX ) is in the avkon.rsg file. If these predefined softkeys do not suffice, a new CBA resource can be defined. Refer to S60 3.1 Buttons API Specification for details.

2.1.4 Defining single-page dialog resource

The dialog resource is defined in the application resource file (RSS file). The following code describes a single-page dialog resource called r_demo_singlepage_dialog .

RESOURCE DIALOG r_demo_singlepage_dialog
    flags = EEikDialogFlagNoDrag | EEikDialogFlagFillAppClientRect |
            EEikDialogFlagCbaButtons | EEikDialogFlagWait;
    items =
            type = EEikCtNumberEditor;
            prompt = "Number1:";
            id = ESinglePageDlgC1Id;
            control = NUMBER_EDITOR { min=0; max=999; };
            trailer = "cm";
            type = EEikCtNumberEditor;
            prompt = "Number2:";
            id = EsinglePageDlgC2Id;
            control = NUMBER_EDITOR { min=0; max=999; };
            trailer = "cm";

2.1.5 Defining multi-page dialog resource

Multi-page dialogs also use the DIALOG resource, but there are some differences compared to single-page dialogs. Multi-page dialogs define a list of pages instead of items in single-page dialogs. The softkeys defined in the resource are generic to the entire dialog - not to each page.

Below is an example of a multi-page dialog and its resource definition.

Multi-page dialog
Multi-page dialog

This dialog has multiple pages.

In the main resource, the only different thing compared to the single-page resource is that the multi-page resource definition includes a pages field with the name of another resource.

RESOURCE DIALOG r_multipage_form
    flags = EEikDialogFlagNoDrag | EEikDialogFlagFillAppClientRect |
            EEikDialogFlagNoTitleBar | EEikDialogFlagNoBorder |
    pages = r_multipage_form_pages;

The pages resource ( r_multipage_form_pages ) is an array resource that consists of PAGE items that contain the text on the tab and lines defined in other resources.

RESOURCE ARRAY r_multipage_form_pages
    items =
            id = EAknExFormPageCtrlIdPage01;
            text = qtn_multipage_form_label_page1;
            form = r_multipage_form_text_field_form;
            id = EAknExFormPageCtrlIdPage02;
            text = qtn_multipage_form_label_page2;
            form = r_aknexform_text_number_field_form;

Every page resource is an array resource that consists of DLG_LINE items. The following shows the resource definition for the first page:

RESOURCE FORM r_multipage_form_text_field_form
    flags = EEikFormUseDoubleSpacedFormat;
    items =
            type = EEikCtEdwin;
            prompt = qtn_multipage_form_label_edwin;
            id = EAknExFormDlgCtrlIdEdwin11;
            itemflags = EEikDlgItemTakesEnterKey |
            control = EDWIN
                flags = EEikEdwinNoHorizScrolling |
                width = AKNEXFORM_EDWIN_WIDTH;
                lines = AKNEXFORM_EDWIN_LINES;
                maxlength = EAknExFormEdwinMaxLength;
                // added to limit expanding in forms.
                // If you want full screen use 5 here
                max_view_height_in_lines = 5;
                // if you have the line above, you must have this.
                // It's calculable from LAF
                base_line_delta = 21;
            tooltip = qtn_multipage_hint_text_edwin;

2.2 Creating and launching dialog

The following table shows the sequence of method calls used to create, initialize and run dialogs, see sub-chapters for examples. Only the most significant methods are shown. CMyDialog is included to represent the methods typically provided by CAknDialog or CEikDialog -derived classes.

Creating and launching dialogs
CEikDialog CAknDialog CMyDialog
1 new NewL RunDlgLD
2 ConstructL
3 PrepareLC ExecuteLD
4 RunLD

2.2.1 Creating dialog without menu

The following example code creates a standard CEikDialog .

CEikDialog* dlg = new (ELeave) CEikDialog();

2.2.2 Creating dialog with menu

The following example code creates a standard CAknDialog and constructs it with the specified menu resource ( RESOURCE MENU_BAR):

CAknDialog* dlg = new (ELeave) CAknDialog();
CleanupStack::PushL( dlg );
dlg->ConstructL( R_DEMO_MENU );
CleanupStack::Pop( dlg );

2.2.3 Launching the dialog

The following code snippet launches the dialog using the specified resource ( RESOURCE DIALOG):


Alternatively, PrepareLC() and RunLD() can be called:

dlg->PrepareLC( R_DEMO_SINGLEPAGE_DIALOG );  // pushes dlg on the cleanup stack
// Dynamic initialization of dialog, e.g. adding / removing dialog lines.
// The dialog is on the stack. Mind the cleanup stack balance.
dlg->RunLD(); // pops, runs and deletes the dialog

Derived classes may provide other factory functions ( NewL() , RunDlgLD() ) for convenience.

2.3 Implementing custom dialog

Below is an example custom dialog:

class CMyDialog: public CAknDialog
public:     // construction
    static TInt RunDlgLD( TInt aResouceId );
private:    // construction
    virtual ~CMyDialog();
private:    // from CAknDialog
    void PreLayoutDynInitL(); // initialize controls
    TBool OkToExitL( TInt aButtonId ); // exit condition
    SEikControlInfo CreateCustomControlL( TInt aControlType );
    void ProcessCommandL( TInt aCommandId );
    TKeyResponse OfferKeyEventL
        ( const TKeyEvent& aKeyEvent, TEventCode aType );

2.3.1 Providing the factory function

If there is a derived class from CAknDialog, a static function RunDlgLD() may be implemented. In this function instantiate an instance of the dialog and launch it with the appropriate resource. ExecuteLD has the "LD" postfix. "L" means that this function may leave and "D" means it destructs itself. The dialog should not be placed on the cleanup stack when ExecuteLD() is called. ExecuteLD() guarantees that if it leaves, the dialog will be deleted.

TInt CMyDialog::RunDlgLD()
    CMyDialog* dlg = new (ELeave) CMyDialog();
    return dlg->ExecuteLD( R_DEMO_SINGLEPAGE_DIALOG );

2.3.2 Initializing controls

PreLayoutDynInitL() is called by the dialog framework before the dialog is sized and laid out. It may be overloaded to initialize the control values that should influence sizing and layout. The default implementation is empty.

The following example code initializes the values of the two number editors:

void CMyDialog::PreLayoutDynInitL()
    // Get the Number1 editor control.
    CEikNumberEditor* editor1 =
        (CEikNumberEditor*) Control( ESinglePageDlgC1Id );
    // Set the value to the Number1 editor.
    editor1->SetNumber( 100 );
    // Get the Number2 editor control.
    CEikNumberEditor* editor2 =
        (CEikNumberEditor*) Control( ESinglePageDlgC2Id );
    // Set the value to the Number2 editor.
    editor2->SetNumber( 200 );

2.3.3 Checking exit condition

The following example code checks the validity of the values in the two editor controls, if the dialog is accepted. If the values are not valid, the dialog cannot be dismissed. OkToExitL() can be the place to handle button presses and commands.

TBool CMyDialog::OkToExitL( TInt aButtonId )
    if ( EAknSoftkeyOk == aButtonId )
        // Dialog accepted, check the exit condition.
        // Get the Number1 editor control.
        CEikNumberEditor* editor1 =
            (CEikNumberEditor*) Control( ESingleDlgId );
        // Get the Number2 editor control.
        CEikNumberEditor* editor2 =
            (CEikNumberEditor*) Control( ESingleDlg2Id );
        // Check the validity of the values in the two editors.
        if ( editor1->Number() > editor2->Number() )
            // Exit condition failed.
            CAknErrorNote* note = new (ELeave) CAknErrorNote;
            note->ExecuteLD( _L("Number1 should be less than number2") );
            return EFalse;
    return ETrue;

2.3.4 Adding custom control to dialog

Controls in the dialog lines are created by the dialog framework. Creation is based on the control type, specified in the DLG_LINE resource. Built-in control types are recognized by the framework. Custom controls types must be recognized, and the appropriate custom control created in the CAknDialog -derived custom dialog class.

The following resource snippet defines a custom control type:

    type = EMyControl;
    id = EMyControlId;
    control = .....

The framework calls CreateCustomControlL() to create the custom control. CreateCustomControlL() should only create, but not construct the created control.

SEikControlInfo CMyDialog::CreateCustomControlL( TInt aControlType )
    SEikControlInfo controlInfo;
    ontrolInfo.iControl = NULL;
    controlInfo.iTrailerTextId = 0;
    controlInfo.iFlags = 0;
    switch ( aControlType )
        case EMyControl:
            controlInfo.iControl = new (ELeave) CMyControl;
    return controlInfo;

The framework constructs the created control by calling ConstructFromResourceL() .

void CMyControl::ConstructFromResourceL( TResourceReader& aReader )
    // Construct the custom control from its resource.

The custom control also needs a few other methods so it can be laid out and drawn. For example, custom controls usually implement MinimumSize() , SizeChanged() and Draw() methods. Details of creating a CCoeControl -based custom control can be found in document S60 3.1 Core UI API Specification.

2.3.5 Handling command

In the example below, ProcessCommandL() responds to custom and system commands.

For the custom command, TryExitL() is used which results in a call to OkToExitL() .

void CMyDialog::ProcessCommandL( TInt aCommandId )
    switch( aCommandId )
        case EMyCommand:
            TryExitL( aCommandId ); // to OkToExitL()
        case EAknCmdExit:
        case EEikCmdExit:
            CAknDialog::ProcessCommandL( aCommandId );

2.3.6 Handling key events

In the example below, a short press of the Selection key invokes a command.

TKeyResponse CMyDialog::OfferKeyEventL
( const TKeyEvent& aKeyEvent, TEventCode aType )
    TKeyResponse result = EKeyWasNotConsumed;
    if (
        ( aKeyEvent.iCode == EKeyOK || aKeyEvent.iCode == EKeyEnter ) &&
        ( !(aKeyEvent.iModifiers & EModifierShift) )
        // Short press of selection key.
        ProcessCommandL( EMyCommand );
        result = EKeyWasConsumed;
        result = CAknDialog::OfferKeyEventL( aKeyEvent, aType );
    return result;

2.4 Error handling

Dialogs API uses standard Symbian OS error reporting mechanism and standard error codes.

2.5 Memory and Performance Considerations

Memory consumption of dialogs depends on the contained controls.

3 Glossary

3.1 Abbreviations

Dialogs API abbreviations
API Application Programming Interface
CBA Command Button Area
GUI Graphical User Interface
OS Operating System
SDK Software Development Kit

3.2 Definitions

Dialogs API definitions
Softkey A command button mapped to a hard key on the device.

4 References

Dialogs API references
S60 3.1 Queries API Specification
S60 3.1 Notifiers API Specification
S60 3.1 Notes API Specification
S60 3.1 Form API Specification
Symbian OS 9.1 API Reference Guide
S60 3.1 Buttons API Specification
S60 3.1 Core UI API Specification