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:

              
               STRUCT DIALOG
               

                   {
               

                   LONG flags=0;
               

                   LTEXT title="";
               

                   LLINK pages=0;
               

                   LLINK buttons=0;
               

                   STRUCT items[];
               

                   LLINK form=0;
               

                   }
              
             

Dialog resource structure

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 on Symbian 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. Forms are documented in Form API Specification .

• DIALOG
• STRUCT

Defining the dialog line resource

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

              
               STRUCT DLG_LINE
               

                   {
               

                   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. Default value: 0xffff
WORD bmpmask ;	Specifies the icon mask ID.
LTEXT tooltip = "" ;	Help text for the form line.

• CEikDialog::CreateCustomControlL()
• EAknCt...
• EEikCt...

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 Buttons API Specification for details.

• DIALOG
• R_AVKON_SOFTKEYS_XXX

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;
               

                   buttons = R_AVKON_SOFTKEYS_OK_CANCEL;
               

                   items =
               

                       {
               

                       DLG_LINE
               

                           {
               

                           type = EEikCtNumberEditor; 
               

                           prompt = "Number1:";
               

                           id = ESinglePageDlgC1Id;
               

                           control = NUMBER_EDITOR { min=0; max=999; };
               

                           trailer = "cm";
               

                           },
               

                       DLG_LINE
               

                           {
               

                           type = EEikCtNumberEditor; 
               

                           prompt = "Number2:";
               

                           id = EsinglePageDlgC2Id;
               

                           control = NUMBER_EDITOR { min=0; max=999; };
               

                           trailer = "cm";
               

                           }
               

                       };
               

                   }
              
             

• r_demo_singlepage_dialog

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.

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 |
               

                           EEikDialogFlagCbaButtons;
               

                   buttons = R_AVKON_SOFTKEYS_OPTIONS_BACK;
               

                   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 =
               

                       {
               

                       PAGE
               

                           {
               

                           id = EAknExFormPageCtrlIdPage01;
               

                           text = qtn_multipage_form_label_page1;
               

                           form = r_multipage_form_text_field_form;
               

                           },
               

                       PAGE
               

                           {
               

                           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 =
               

                       {
               

                       DLG_LINE
               

                           {
               

                           type = EEikCtEdwin;
               

                           prompt = qtn_multipage_form_label_edwin;
               

                           id = EAknExFormDlgCtrlIdEdwin11;
               

                           itemflags = EEikDlgItemTakesEnterKey | 
               

                                       EEikDlgItemOfferAllHotKeys;
               

                           control = EDWIN
               

                               {
               

                               flags = EEikEdwinNoHorizScrolling | 
               

                                       EEikEdwinResizable;
               

                               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;
               

                           },
               

                       };
               

                   }
              
             

• DIALOG
• DLG_LINE
• PAGE
• r_multipage_form_pages

Creating dialog without menu

The following example code creates a standard CEikDialog .

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

• CEikDialog

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

• CAknDialog

Launching the dialog

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

              
               dlg->ExecuteLD( R_DEMO_SINGLEPAGE_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.

• NewL()
• PrepareLC()
• RunDlgLD()
• RunLD()

             
              class CMyDialog: public CAknDialog
              

                  {
              

              public:     // construction
              

                  static TInt RunDlgLD( TInt aResouceId );
              

              private:    // construction
              

                  CMyDialog();
              

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

                  };
             
            

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

                   }
              
             

• CAknDialog,
• ExecuteLD
• ExecuteLD()
• RunDlgLD()

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

                   }
              
             

• PreLayoutDynInitL()

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;
               

                   }
              
             

• OkToExitL()

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:

              
               DLG_LINE
               

                   {
               

                   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;
               

                           break;
               

               

                       default:
               

                           break;
               

                       }
               

                   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 Core UI API Specification .

• CAknDialog
• CCoeControl
• ConstructFromResourceL()
• CreateCustomControlL()
• DLG_LINE
• Draw()
• MinimumSize()
• SizeChanged()

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

                           break;
               

                           }
               

               

                       case EAknCmdExit:
               

                       case EEikCmdExit:
               

                           {
               

                           ((CAknAppUi*)iEikonEnv->EikAppUi())->RunAppShutter();
               

                           break;
               

                           }
               

               

                       default:
               

                           {
               

                           CAknDialog::ProcessCommandL( aCommandId );
               

                           }
               

                       }
               

                   }
              
             

• OkToExitL()
• ProcessCommandL()
• TryExitL()

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;
               

                       }
               

                   else
               

                       {
               

                       result = CAknDialog::OfferKeyEventL( aKeyEvent, aType );
               

                       }
               

                   return result;
               

                   }