Symbian dialog box Summary: Standard dialog box

Series60 provides a comprehensive set of dialog box classes and base classes. You can use these classes to create custom dialogs, as well as develop forms, notices, and queries) and List dialog.

All dialogs have some basic attributes. First, the dialog box is a control with a window. All the dialog box classes are ultimately derived from ccoecontrol. The dialog box is managed by a dialog box framework, including layout, drawing, and interaction between the user and the dialog box in the widget. In typical cases, most complex dialogs are fully defined in a resource file. After dynamic instantiation, the dialog box framework loads the definition from the resource file to complete the creation of the dialog box. The layout and positioning of all elements in the dialog box are usually automatic, and you can also intervene in it.

The dialog box of series60 is modal and non-wait by default. The modal/non-modal dialog box does not need to be described. The non-Wait dialog box allows the application to continue processing in the background. The wait dialog box prevents the application from performing any further processing before the dialog box is closed.

Cakndialog is the base class of most series60 dialogs. The usage of the dialog box is roughly divided into the following steps: 1. Define resources. 2. Compile the dialog box class. 3. Save and verify the dialog box data. 4. dynamically initialize the standard dialog box. 5. Build and execute dialog box.

As described below:

1. Define Resources

Use Dialog to define resources. The resource specifies the layout of the dialog box. In the resource, define the number of lines in the dialog box, the controls used, whether the dialog box is modal, and the soft keys used. The following is a simple example:

Resource dialog r_simpledlg_dialog
{
Flags = eeikdialogflagnodrag |
Eeikdialogflagnotitlebar |
Eeikdialogflagfillappclientrect |
Eeikdialogflagcbabuttons |
Eeikdialogflagmodeless;
Buttons = r_avkon_softkeys_options_back;
Items =
{
Dlg_line
{
Id = esimpledlgcidgamename;
Type = eeikctlabel;
Control = label
{
TXT = game_name_text;
};
}
};
}

Flags describes the properties of the dialog box. For the attribute values, see <uikon. HRH>

# Define eeikdialogflagwait
# Define eeikdialogflag1_yesc
# Define eeikdialogflagbuttonsbelow
# Define eeikdialogflagbuttonsright
# Define eeikdialogflagnouserexit
# Define eeikdialogflagmodeless
# Define eeikdialogflagnotitlebar
# Define eeikdialogflagallkeystobuttons
# Define eeikdialogflagfillscreen
# Define eeikdialogflagnodrag
# Define eeikdialogflagdensepacking
# Define eeikdialogflagnobackup
# Define eeikdialogflagfillappclientrect
# Define eeikdialogflagcbabuttons
# Define eeikdialogflagnoborder
# Define eeikdialogflagnoshadow

It is a good habit to define a standard dialog box as a waiting dialog box. The standard dialog box should be defined as non-waiting only when appropriate (for example, in the main application window.

Buttons specifies the software to use. For the values, see
# Define r_avkon_softkeys_empty
# Define r_avkon_softkeys_empty_with_ids
# Define r_avkon_softkeys_ OK _empty
# Define r_avkon_softkeys_select_cancel
# Define r_avkon_softkeys_ OK _cancel
# Define r_avkon_softkeys_ OK _details
# Define r_avkon_softkeys_call_cancel
# Define r_avkon_softkeys_options_back
# Define r_avkon_softkeys_options_done
# Define r_avkon_softkeys_options_cancel
# Define r_avkon_softkeys_options_exit
# Define r_avkon_softkeys_ OK _back
# Define r_avkon_softkeys_cancel
# Define r_avkon_softkeys_back
# Define r_avkon_softkeys_close
# Define r_avkon_softkeys_done_back
# Define r_avkon_softkeys_done_cancel
# Define r_avkon_softkeys_select_back
# Define r_avkon_softkeys_mark_back
# Define r_avkon_softkeys_unmark_back
# Define r_avkon_softkeys_yes_no
# Define r_avkon_softkeys_unlock_empty
# Define r_avkon_softkeys_save_back
# Define r_avkon_softkeys_show_cancel
# Define r_avkon_softkeys_show_exit
# Define r_avkon_softkeys_answer_exit
# Define r_avkon_softkeys_exit
# Define r_avkon_softkeys_read_exit
# Define r_avkon_softkeys_listen_exit
# Define r_avkon_softkeys_search_back
# Define r_avkon_softkeys_again_quit
# Define r_avkon_softkeys_quit
# Define r_avkon_softkeys_insert_back

The most important component is the items component, which defines the actual content contained in the dialog box. Define a dlg_line for each control that you want to include in the dialog box. specify at least the following fields in each dlg_line:

* ID: use this value in the application to reference this dialog box line. It must be enumerated in the. HRH file of the application.
* Type: Type of the control contained in the dialog box (defined in avkon. HRH or uikon. HRH ).
* Control: controls used in this dialog box.

In addition, you can specify an itemflags field in the dlg_line resource and use this field to determine the row behavior of the dialog box. For example, the pop-up field text control can use itemflags to indicate that a pop-up window should be opened when the "select" Key is pressed, for example, eeikdlgitemtakesenterkey | eeikdlgitemofferallhotkeys. You can find the itemflags value in uikon. HRH. The most common is the eeikdlgitemseparatorbefore flag, which is used to insert a horizontal "separator" line before the dialog box line.

2. Compile the dialog box class

Next, you need to write a class that can build and execute this dialog box, initialize the control data, process the data received from the control, and decide how to close the dialog box.

A static method is usually provided for executing the dialog box. This method encapsulates the first-stage constructor and executeld ()-functions used to load, display, and destroy the dialog box. Generally, this static method is named rundlgld () and passed to the tbool returned by executeld.

The following is an example:

# Include <akndialog. h> // cakndialog
Class csimpledlgplayernamedialog: Public cakndialog
{
Public: // static construction and execution
Static tbool rundlgld (TDES & aplayername );
Protected: // from cakndialog
Tbool oktoexitl (tint abuttonid );
Protected: // from ceikdialog
Void prelayoutdyninitl ();
PRIVATE: // Constructor
Csimpledlgplayernamedialog (TDES & aplayername): iplayername (aplayername ){};
PRIVATE: // data
TDES & iplayername;
};

Implementation of rundlgld:

Tbool csimpledlgplayernamedialog: rundlgld (TDES & aplayername)
{
Csimpledlgplayernamedialog * playernamedialog = new (eleave) csimpledlgplayernamedialog (aplayername );
Return playernamedialog-> executeld (r_simpledlg_player_name_dialog );
}

Because the dialog box is modal and waiting, you do not need to make it member data. This dialog box will delete itself at the end of executeld.

Why didn't I push it into the clear stack after new? Because executeld () has the ownership of the change dialog box, this method encapsulates the call for the other two methods: preparelc () and runld (). Preparelc () puts the pointer of the dialog box into the clear stack, and then creates the dialog box. Runld () will display the dialog box and pop it up from the clear stack. However, if you need to call any code that may cause abnormal exit before calling executeld (), you should put it in the clearing stack and bring it up before calling executeld.

However, if the dialog box is not waiting, it will be returned directly from executeld () without being deleted.

3. Save and verify the dialog box data

To enable the dialog box to update application data, you need to provide reference to the data. Data verification and update usually occur in the oktoexitl () method. Except for "cancel", the Framework calls this function when any soft key is pressed (by setting the flags in the dialog box, to include eeikdialogflag1_yesc, you can force the framework to call oktoexitl () when it is "canceled ()). If you allow the dialog box to exit, oktoexitl () must return etrue. If you do not allow the exit, efalse is returned. The following is an example:

Tbool csimpledlgplayernamedialog: oktoexitl (tint abuttonid)
{
If (abuttonid = eaknsoftkeyok)
{
Ceikedwin * Editor = static_cast <ceikedwin *> (controlornull (esimpledlgcidplayernameeditor ));
If (editor)
{
Editor-> gettext (iplayername );
}
}
Return etrue;
}

By calling ceikdialog: controlornull () and passing in the ID of the dialog box row, you can get the handle of a specific control. If the ID is valid, a ccoecontrol pointer is returned, and then null is returned. If the ID is invalid and needs to exit, you can use ceikdialog: control (). If the ID is invalid, this method will produce an error.

4. Dynamic Standard initialization dialog box

The items in the Dynamic Setting dialog box are executed in the prelayoutdyninitl () method. The dialog box Framework calls this method before executing the dialog box.

Void csimpledlgplayernamedialog: prelayoutdyninitl ()
{
Ceiklabel * label = static_cast <ceiklabel *> (controlornull (esimpledlgcidplayername ));
If (Label)
{
Hbufc * labeltext = stringloader: loadlc (r_enter_name_text );
Label-> settextl (* labeltext );
Cleanupstack: popanddestroy (labeltext );
}
}

If necessary, you can rewrite another method postlayoutdyninitl () to change the layout and size of controls in the dialog box, or start a timer before the display dialog box.

5. Build and execute dialog box

The rundlgld () method encapsulates the creation and execution of the dialog box.

Switch (acommand)
{
Case esimpledlgw.newgame:
{
If (csimpledlgplayernamedialog: rundlgld (iplayername ))
{
Startnewgamel ();
}
Break;
}
//...
}

By checking the return values of executeld () or rundlgld (), you can know how the dialog box is closed. If efalse is returned, "cancel", "back", or "no" is pressed when the dialog box is closed. Otherwise, etrue is returned.