QDialogs

Found in: Examples\UIQ\QDialogs

QDialogs should not be looked upon as an ordinary application; its purpose is instead to present the different dialog types that are found in UIQ 3. This application should be used as a guide when you want to create a dialog in your own application. You will see the system dialogs that are provided in UIQ 3 and learn how to create your own dialogs. The dialog classes have been changed in UIQ 3.0; the previous CEikDialog class has been deprecated and is replaced by CQikSimpleDialog and CQikViewDialog.

The application contains three parts: system dialogs, simple dialogs and View-dialogs. Demonstrations of each type of dialog are available in the application, grouped by type in cascading menus.

The UI configuration that is used by the phone determines the look-and-feel of the application. The Dialogs example supports the reference UI Configurations that are supported in the UIQ 3 SDK. For development purposes, the UIQ Environment Configuration Tool, UiqEnv, allows you to change the UI Configuration in the emulator in order to develop and test the application with varying phone styles.

For an introduction to dialog handling in UIQ 3 see New UIQ View-dialogs in the Programmer's Guide and How-To Guides for dialogs.

These examples show the different system dialogs in UIQ 3 and describe how they are used. The system dialogs use the old-style dialog, which uses the CEikDialog class. This class is deprecated, which means the old-dialog style should not be used in dialogs in new applications.

The project demonstrates the usage of the following system dialogs:

• Information message,

• Information dialog,

• Query dialog,

• Zoom dialog,

• Save-changes dialog,

• Rename file or folder dialog,

• Copy files and folders dialog,

• Move files and folders dialog,

• Select file dialog,

• Select folder dialog,

• SendAs dialog,

• Notifier message,

• Notifier dialog.

The simple dialog is a simplified version of the old-style dialog. The simple dialog does not, for example, enable multiple pages using tabs. A simple dialog fits on the screen without scrolling, has no tabs and should only contain one input control. But there can be exceptions where it is more appropriate to have more than one input control in a simple dialog as you can see in the user password example.

There are four simple-dialog examples that highlight different use cases.

• Simple text dialog

  This shows how you make a simple text dialog by using data from a resource file. The dialog contains only plain text in the form of a label. This is to illustrate how you create your own dialogs that are as simple as possible.

• Progress dialog

  Here is a simple dialog that presents the use of the progress bar in dialogs. The dialog has a timer that generates each new tick in the progress bar. When the progress bar is finished, the dialog will be closed. The user can choose to close the dialog before it has finished by.

• Animation dialog

  This is a simple dialog that presents the use of animation in dialogs. The dialog closes automatically after 10 seconds unless the user chooses to close it earlier. During the time the dialog is up and running the animation will be played in a never-ending loop.

• User/password dialog

  Here is a simple dialog that is used as a user password dialog that presents a CEikEdwin text editor and a secret editor for username and password fields. It shows how the login command will not be available until a username has been typed. This dialog contradicts the simple dialog guideline of having only one input control. This is to illustrate that in some cases it is applicable to have more than one input control in a simple dialog. But, as you shall see, this as an exception and should be avoided as much as possible.

The View-dialog, which inherits from the view class, is in many ways like a view. For example, a View-dialog uses building blocks for the layout of UI controls. It is intended for advanced dialogs that require scrolling or use tabs. This is the primary dialog to use when several input controls are needed.

There are three View-dialog examples that highlight different use cases.

• Edit alarm dialog

  This demonstrates a View-dialog that is used to set alarm messages. The dialog consists of a time editor to set when the alarm is to be triggered, a sound selector to set the alarm sound and a CEikEdwin text editor in which an alarm message can be written.

  To add alarms to the alarm server queue you need to have write access to user data. This is gained by adding the WriteUserData capability in the .mmp file.

• Multi-page View-dialog

  This dialog shows you how to use the scrollbar and pages in a View-dialog. The dialog itself is a kind of dummy dialog that simply displays the very same label on each page.

• List box View-dialogs

  Here is a View-dialog that demonstrates how you use the list box in a dialog. This dialog is a kind of dummy dialog, just like the multi-page View-dialog. The focus here is on how to create a dialog with a list box and how to use it, not on the content inside the list box.

You need to build the QDialogs project from the beginning because the animation image needs to be exported to the correct location.

First, run bldmake from the projects group directory where the bld.inf file is located:

> bldmake bldfiles

This creates a batch file, called abld.bat, which you use in the next step. To build the project, you call abld build which will build the project for all default targets in both release and debug variants. To build for a particular target and variant, use abld build target-name variant, for example,

> abld build winscw udeb

builds the project for the debug variant of WINSCW only. To run it, choose Dialogs from the Launcher.

CDilaogsApplication is the entry point to the application. The application class defines the properties of the application, such as its UID and caption, and creates a new document.

CDialogsDocument represents the document in the Dialogs application.

CDialogsAppUi represents the application UI in the Dialogs application. It is responsible for creating the view.

CDialogsView is a view that contains commands to launch the different dialogs example. The commands are divided in three cascading menus: system dialogs, simple dialogs and View-dialogs. Command handling for the different dialog types is separated from each other to bring clarity to the differences between the dialog types. This view is responsible for creating the different command handlers and distributing the responsibility for the commands between these handlers.

CDialogsSystemDialogHandler takes care of all system-dialog specific commands for CDialogsView and shows how they can be launched.

CDialogsSimpleDialogHandler takes care of all simple-dialog specific commands for CDialogsView and shows how they can be launched.

CDialogsViewDialogHandler This class takes care of all View-dialog specific commands for CDialogsView and shows how they can be launched.

CDialogsNotifier is a notifier wrapper that allows either an infoprint, which is a single line message, or a simple-dialog box to be displayed on the screen.

CDialogsAnimationDialog presents a label with an animation. This class holds a timer object that notifies when the dialog is to be closed.

CDialogsProgressDialog presents a label with a progress bar. This class holds a timer object that notifies each time the progress bar is to be incremented. When the progress bar is completed, the dialog will be closed.

CDialogsUserPasswordDialog presents a user password dialog that contains a CEikEdwin text editor and a secret editor.

CDialogsEditAlarmDialog presents the alarm dialog that is used to set alarm messages. The dialog consists of a time editor to set when the alarm is to be triggered, a sound selector to set the alarm sound and a CEikEdwin text editor into which an alarm message can be written.

CDialogsMultiPageDialog presents a View-dialog that shows how to create and use a dialog with pages and a scrollbar.

CDialogsListBoxDialog presents a View-dialog that shows how to create and use a list box inside a dialog.