mainpage.dox

国内著名嵌入式培训机构内部资料,内含一些实例代码,包括技术专题书籍

/*! \mainpage Query Example
 *
 * \ref Intro_sec
 * \n\ref UI_sec
 * \n\ref Design_sec
 *
 * <HR>
 *
 * \section Intro_sec 1. About this Example
 *
 * This tutorial explains how to use a query control. A query control displays a
 * dialog for interaction between the user and application. There are two types
 * of query control. One is the query dialog, and the other is the global list
 * query.
 *
 * A query dialog is only displayed within an application, while a global list
 * query is displayed on top even when another application moves to the
 * foreground.
 *
 * The query example application demonstrates the following functions:
 *
 * Query dialog:
 *
 * - Selecting <B>Yes</B>/<B>No</B>
 * - Selecting <B>OK</B>/<B>Cancel</B>
 * - Inputting data (text, number, date, time, duration, secret)
 * - Selecting a list item
 * - Selecting multiple list items
 *
 * Global list query:
 *
 * - Selecting a list item
 *
 * The following are examples of how queries are used:
 *
 * - Confirmation of operation
 * - Informing the user of mandatory input data
 *
 * \subsection Sub11 1.1 APIs demonstrated
 *
 * The following UML diagram shows key classes of the query example application.
 * CAknxxxQueryDialogs are described in more detail in section 2.
 *
 * \image html IMAGE_QUERY001.GIF
 *
 * <HR>
 *
 * \subsection Sub12 1.2 Prerequisites
 *
 * The AknExQuery example application shows how to use query control classes.
 * The following are very important to understand:
 *
 * - Classes that are related to the query
 * - Resource definition
 * - Implementing query-related classes and handling functions in them
 *
 * <HR>
 *
 * \section UI_sec 2. User Interface
 *
 * This section explains how the queries are displayed to the user and explains
 * how to operate them.
 *
 * \subsection Sub21 2.1 Initial view
 *
 * When the example application launches, the following screen in is displayed
 * first.
 *
 * \image html IMAGE_QUERY002.GIF
 *
 * \subsection Sub22 2.2 Text input
 *
 * Press the right soft key (<B>Next</B>) in the initial view, and the dialog
 * below opens. In this dialog, the user can input text. Press the <B>Ok</B> or
 * <B>Cancel</B> key, and the dialog closes.
 *
 * \image html IMAGE_QUERY003.GIF
 *
 * When the dialog closes, press the right soft key (<B>Next</B>) to open the
 * next dialog in the example application. To close this dialog, press the
 * \b Ok or \b Cancel key. When the user presses the \b Ok key, user input data
 * is displayed.
 *
 * \image html IMAGE_QUERY006.GIF
 *
 * When the dialog closes, press the right soft key (<B>Next</B>) to open the
 * next dialog. To close this dialog, press the \b Ok or \b Cancel key. When the
 * user presses the \b Ok key, user input data is displayed.
 *
 * \image html IMAGE_QUERY008.GIF
 *
 * \subsection Sub23 2.3 Selecting Yes/No
 *
 * The next dialog illustrates Yes/No selection (see the figure below). To open
 * it, press the right soft key (<B>Next</B>) after the previous dialog (see the
 * Text input figure) closes. To close this dialog, press the \b Yes or \b No
 * key.
 *
 * \image html IMAGE_QUERY010.GIF
 *
 * \subsection Sub24 2.4 Selecting OK/Cancel
 *
 * The next dialog illustrates OK/Cancel selection (see the figure below). To
 * open this dialog, press the right soft key (<B>Next</B>) after the previous
 * dialog (see the Selecting Yes/No figure) closes. To close this dialog, press
 * the \b Ok or \b Cancel key.
 *
 * \image html IMAGE_QUERY011.GIF
 *
 * \subsection Sub25 2.5 Multiple line input
 *
 * To open the multiple line input dialog (left screen in the figure below),
 * press the right soft key (<B>Next</B>) after the previous dialog closes. This
 * dialog illustrates multiple line data input (Date and Duration input). To
 * close this dialog, press \b Ok or the \b Cancel key. The example application
 * proceeds to the next step (middle screen in the figure below). In this
 * dialog, the user can select "Date and Duration" or "Time and Duration". To
 * open the next dialog (right screen in the figure below), press the select
 * key.
 *
 * This dialog shows Time and Duration input.
 *
 * \image html IMAGE_QUERY018.GIF
 *
 * \subsection Sub26 2.6 Selecting a list item
 *
 * The next step shows selection from a list. After all dialogs in the Multiple
 * line input figure are closed, press the right soft key (<B>Next</B>). A
 * dialog that demonstrates selection from a list opens. To close this dialog,
 * press the \b Ok or \b Cancel key.
 *
 * \image html IMAGE_QUERY021.GIF
 *
 * To open the next dialog, press the right soft key (<B>Next</B>). This dialog
 * demonstrates another type of list item selection. To close this dialog, press
 * the \b Ok or \b Cancel key.
 *
 * \image html IMAGE_QUERY022.GIF
 *
 * \subsection Sub27 2.7 Selecting multiple list items
 *
 * While the previous dialog illustrates single item selection, the next dialog
 * illustrates multiple item selection. To select a check box, move the cursor
 * to the required line and press the select key. The user can select more than
 * one item (right screen in figure below). To close this dialog, press the
 * \b Ok or \b Cancel key.
 *
 * \image html IMAGE_QUERY023.GIF
 *
 * \subsection Sub28 2.8 Global list query
 *
 * When multiple selection is finished, press the right soft key (<B>Next</B>)
 * to display a global list query (left screen in the figure below). A global
 * list query is always displayed on top, even when another application moves to
 * the foreground (middle screen in the figure below). Press \b Ok or \b Cancel
 * to display the index number of the selected item in the list (right screen in
 * the figure below). To close the dialog, press \b Ok.
 *
 * \image html IMAGE_QUERY026.GIF
 *
 * \subsection Sub29 2.9 Options menu
 *
 * The user can select a desired dialog directly by selecting Options when no
 * dialogs are shown. The menu below is displayed when \b Options is selected.
 *
 * \image html IMAGE_QUERY029.GIF
 *
 *
 * \section Design_sec 3. Design and implementation
 *
 * \subsection Sub31 3.1 Resource definition
 *
 * The structure definition of resources for a query dialog is defined in
 * "avkon.rh". These are defined in an .rss file using the structure
 * AVKON_CONFIRMATION_QUERY and AVKON_DATA_QUERY. A list data array is used for
 * resource definition of the global list query.
 *
 * \subsection Sub311 3.1.1 Yes/No or OK/Cancel selection dialog
 *
 * The resource code for a Yes/No selection dialog is very similar to that of an
 * OK/Cancel selection dialog. The value of the dialog buttons in DIALOG is the
 * only difference between them.
 *
 * <I>Yes/No selection dialog</I>
 *
 * \code
 * RESOURCE DIALOG r_aknexquery_confirmation_query
 *   {
 *   flags = EGeneralQueryFlags;
 *   buttons = R_AVKON_SOFTKEYS_YES_NO;
 *   items =
 *     {
 *     DLG_LINE
 *       {
 *       type = EAknCtQuery;
 *       id = EGeneralQuery;
 *       control = AVKON_CONFIRMATION_QUERY
 *         {
 *         layout = EConfirmationQueryLayout;
 *         label = STRING_r_aknexquery_con_label_text;
 *         bmpfile = AKNEXQUERY_BMPFILE_NAME;
 *         bmpid = AKNEXQUERY_BITMAP_MASK_FLAG;
 *         };
 *       }
 *     };
 *   }
 * \endcode
 *
 * \subsection Sub312 3.1.2 Data input dialog
 *
 * Regarding the resource code of the data input dialog, the member values in
 * the AVKON_DATA_QUERY structure need to be set for each data type. The
 * following are two examples of resource code. One is single data input, the
 * other is multiple data input.
 *
 * <I>Single data input</I>
 *
 * \code
 * RESOURCE DIALOG r_aknexquery_data_query
 *   {
 *   flags = EGeneralQueryFlags;
 *   buttons = R_AVKON_SOFTKEYS_OK_CANCEL;
 *   items =
 *     {
 *     DLG_LINE
 *       {
 *       type = EAknCtQuery;