Chapter 1

Simply put, the dialog has a title, standard OK and Cancel buttons, some flags, and some
items. In keeping with guidelines for positioning buttons, the Cancel/OK buttons are
indicated by the resource name R_EIK_BUTTONS_CANCEL_OK.
Almost all dialogs should be coded with the line flags = EEikDialogFlagWait, which
makes the dialog modal.
Note
Regrettably, this is not the default. The default behavior is that your
application can continue executing while the dialog is displayed. This isn't
quite the same as a nonmodal dialog. Nonwaiting dialogs are typically used
for activities like progress monitoring, in which the application is busy while
the dialog is being displayed. Because the application is busy, it doesn't
accept user input, so a nonwaiting dialog is effectively modal.
The body of the dialog is a vertical list of controls, each of which has
� a caption or prompt, such as Text;
� an ID, such as EExampleControlIdText;
� a type, such as EEikCtEdwin, which may have some initialization data of a format
corresponding to the type, such as EDWIN { width= 25; maxlength = 256; }.
Don't use too many controls. As far as C++ is concerned, there is no limit, but in UIQ, for
example, more than eight won't fit nicely onto a screen only 320 pixels high. If you code too
many controls, the dialog becomes scrollable, and the user will have to scroll it to see all the
controls. The dialog begins to overwhelm users with too much choice, making it hard to use.
In some UIs, having too many controls will cause the dialog to overflow the screen, making it
effectively unusable.
The prompt serves to identify its purpose to the user, while the ID identifies the control to the
programmer. Later, we'll see that control IDs are used by C++ programs to specify the
controls whose values they want to set or read. Like command IDs, control IDs are defined
in the application's .hrh file, so they can be accessed both by resource file definitions and
C++ programs.
One of the controls used here, EEikCtEdwin, is an edit window; the EDWIN resource
STRUCT is required to initialize such a control. In this example, I specify the size of the
control (25 characters) that affects the dialog layout, and the maximum length of the data
(256 characters).
10.2.2 Dialog Code
The base class for all dialogs is CEikDialog. Any dialog you write in your application will
derive from CEikDialog, and it will typically implement at least two member functions – one
for initializing the dialog and one for processing the OK key (or the DONE key that is often
used in UIQ).
'Read-only' dialogs, for displaying application data, need only implement the initialization
function. Ultra-trivial dialogs, initialized entirely from resource files, needn't even implement
the initialization function. More complex dialogs can implement many functions besides the
two shown below: we'll return to this later on. All CEikDialog virtual functions have a donothing
default implementation: you only override them if necessary.
The following code extract shows the declaration of CExampleWrite-FileDialog,from
streams.cpp:
Note
That's right: streams.cpp, not streams.h. I've treated dialogs as being