Nokia N97 SDK
Example Applications Guide

Query Example

1. About this Example
2. User Interface
3. Design and implementation


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:

Global list query:

The following are examples of how queries are used:

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_QUERY001.GIF


1.2 Prerequisites

The AknExQuery example application shows how to use query control classes. The following are very important to understand:


2. User Interface

This section explains how the queries are displayed to the user and explains how to operate them.

2.1 Initial view

When the example application launches, the following screen in is displayed first.

IMAGE_QUERY002.GIF

2.2 Text input

Press the right soft key (Next) in the initial view, and the dialog below opens. In this dialog, the user can input text. Press the Ok or Cancel key, and the dialog closes.

IMAGE_QUERY003.GIF

When the dialog closes, press the right soft key (Next) to open the next dialog in the example application. To close this dialog, press the Ok or Cancel key. When the user presses the Ok key, user input data is displayed.

IMAGE_QUERY006.GIF

When the dialog closes, press the right soft key (Next) to open the next dialog. To close this dialog, press the Ok or Cancel key. When the user presses the Ok key, user input data is displayed.

IMAGE_QUERY008.GIF

2.3 Selecting Yes/No

The next dialog illustrates Yes/No selection (see the figure below). To open it, press the right soft key (Next) after the previous dialog (see the Text input figure) closes. To close this dialog, press the Yes or No key.

IMAGE_QUERY010.GIF

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 (Next) after the previous dialog (see the Selecting Yes/No figure) closes. To close this dialog, press the Ok or Cancel key.

IMAGE_QUERY011.GIF

2.5 Multiple line input

To open the multiple line input dialog (left screen in the figure below), press the right soft key (Next) after the previous dialog closes. This dialog illustrates multiple line data input (Date and Duration input). To close this dialog, press Ok or the 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_QUERY018.GIF

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 (Next). A dialog that demonstrates selection from a list opens. To close this dialog, press the Ok or Cancel key.

IMAGE_QUERY021.GIF

To open the next dialog, press the right soft key (Next). This dialog demonstrates another type of list item selection. To close this dialog, press the Ok or Cancel key.

IMAGE_QUERY022.GIF

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 Ok or Cancel key.

IMAGE_QUERY023.GIF

2.8 Global list query

When multiple selection is finished, press the right soft key (Next) 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 Ok or Cancel to display the index number of the selected item in the list (right screen in the figure below). To close the dialog, press Ok.

IMAGE_QUERY026.GIF

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 Options is selected.

IMAGE_QUERY029.GIF

3. Design and implementation

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.

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.

Yes/No selection dialog

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

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.

Single data input

 RESOURCE DIALOG r_aknexquery_data_query
   {
   flags = EGeneralQueryFlags;
   buttons = R_AVKON_SOFTKEYS_OK_CANCEL;
   items =
     {
     DLG_LINE
       {
       type = EAknCtQuery;
       id = EGeneralQuery;
       control = AVKON_DATA_QUERY
         {
         layout = EDataLayout;
         label = STRING_r_aknexquery_data_label_text;
         control = EDWIN
           {
           flags = EEikEdwinNoHorizScrolling | EEikEdwinResizable;
           width = AKNTAQUERY_EDWIN_WIDTH;
           maxlength = AKNTAQUERY_EDWIN_MAXLENGTH;
           // added to limit expanding in forms. 
           // If you want full screen use 6 here
           max_view_height_in_lines = AKNEXQUERY_EDWIN_LINES; 
           // if you have the line above, you must have this. 
           // It's calculable from LAF
           base_line_delta = 21; 
           };
         };
       }
     };
   }

Multiple data input

 RESOURCE DIALOG r_aknexquery_multi_line_date_and_duration_layout
   {
   flags = EGeneralQueryFlags;
   buttons = R_AVKON_SOFTKEYS_OK_CANCEL;
   items =
     {
     DLG_LINE
       {
       type = EAknCtMultilineQuery;
       id = EMultilineFirstLine;
       control = AVKON_DATA_QUERY
         {
         layout = EMultiDataFirstEdwin;
         label = STRING_r_aknexquery_date_label_text;
         control = DATE_EDITOR
           {
           minDate = DATE
             {
             year = AKNEXQUERY_DATE_EDITOR_MIN_DATE;
             };
           maxDate = DATE
             {
             year = AKNEXQUERY_DATE_EDITOR_MAX_DATE;
             };
           flags = AKNEXQUERY_DATE_EDITOR_FLAGS;
           };
         };
       },
     DLG_LINE
       {
       type = EAknCtMultilineQuery;
       id = EMultilineSecondLine;
       control = AVKON_DATA_QUERY
         {
         layout = EMultiDataSecondEdwin;
         label = STRING_r_aknexquery_dura_label_text;
         control = DURATION_EDITOR
           {
           minDuration = DURATION
             {
             };
           maxDuration = DURATION
             {
             seconds = AKNEXQUERY_DURATION_EDITOR_MAX_SECOND;
             };
           flags = AKNEXQUERY_DURATION_EDITOR_FLAGS;
           };
         };
       }
     };
   }

For the multiple line query, it is necessary to define two DLG_LINE structures. The first line for the multiple line query is identified by EMultilineFirstLine in "id". The second line is identified by EMultilineSecondLine in "id".

3.1.3 Select list item dialog

The following is the resource code for the Select list item dialog. Selecting an item or items in the listbox is defined in the 'flags' of LISTBOX.

Select list item dialog

 RESOURCE DIALOG r_aknexquery_list_single_pane
   {
   flags = EGeneralQueryFlags;
   buttons = R_AVKON_SOFTKEYS_OK_CANCEL;
   items =
     {
     DLG_LINE
       {
       type = EAknCtListQueryControl;
       id = EListQueryControl;
       control = AVKON_LIST_QUERY_CONTROL
         {
         listtype = EAknCtSinglePopupMenuListBox;
         listbox = LISTBOX
           {
           flags = EAknListBoxMenuList;
           height = AKNEXQUERY_LISTBOX_HEIGHT;
           width = AKNEXQUERY_LISTBOX_WIDTH;
           array_id = r_aknexquery_list_single_pane_item;
           };
         heading = STRING_r_aknexquery_list_title;
         };
       }
     };
   }

3.1.4 Global list query

The following is the resource code for the global list query. In this resource definition, a data array of text strings that is shown in the listbox needs to be set.

Global list query

 RESOURCE ARRAY r_aknexquery_sub_popup_data
   {
   items =
     {
     LBUF
       {
       txt = STRING_r_aknexquery_sub_popup_data1;
       },
     LBUF
       {
       txt = STRING_r_aknexquery_sub_popup_data2;
       },
     LBUF
       {
       txt = STRING_r_aknexquery_sub_popup_data3;
       },
     LBUF
       {
       txt = STRING_r_aknexquery_sub_popup_data4;
       },
     LBUF
       {
       txt = STRING_r_aknexquery_sub_popup_data5;
       }
     };
   }

3.2 Displaying a query dialog and getting a user response

Constructing a query dialog is very similar to constructing a normal dialog. When constructing a query dialog, the target query dialog object to show is created. At this time, the reference is passed to the object to get user response data. After this construction, the ExecuteLD function is called to display the query dialog.

When the user responds to this dialog, the query dialog sets the value of the soft key event of OK or Cancel (or Yes or No) into the reference that is passed at the construction phase. Then the query dialog closes itself and deletes the query dialog object by itself. The program returns to the application from the dialog after the dialog is deleted. In this example application, input text data is shown in the application view.

 TBuf<KAknExQueryTextBufLength> textData;
 CAknTextQueryDialog* dlg;
 dlg = new ( ELeave )CAknTextQueryDialog( textData, CAknQueryDialog::ENoTone );
 TBool answer( dlg->ExecuteLD( aQueryResourceId ) );
 if ( aDisplayFlag && answer )
     {
     iLabelResultMessage->SetTextL( textData );
     }

The following sequence diagram shows the life of a query dialog from the time it is instantiated until it is deleted.

IMAGE_QUERY033.GIF

3.3 Displaying a global query and getting a user response

Using a global list query is different from the query dialog described above.

At first, the active object (CAknExQueryGlobalListObserver class) is instantiated, (see (a)), then CAknExQueryGlobalListObserver::Start() is called. Next, the global list query (CAknGlobalListQuery class) is instantiated, (see (c)), then the iStatus variable of the active object is set into CAknGlobalListQuery::ShowListQueryL() as a parameter and then this function is called. Now the global list query is shown. When the user selects a list item and presses the OK or Cancel soft key, a soft key event occurs and the global list query is closed and the CAknExQueryGlobalListObserver::RunL() function is called by the active object framework. Then an index number (-1 is set when Cancel is selected) of the list that is selected in the global list query is set to iStatus of the active object by the notify framework.

 iDisplayDialog = ETrue;
 SetTextToLabelL( R_AKNEXQUERY_OPERATE_MESSAGE );
 CDesCArray* textArray =
 iCoeEnv->ReadDesCArrayResourceL(R_AKNEXQUERY_SUB_POPUP_DATA);
 CleanupStack::PushL(textArray);
 iGlobalListObserver = CAknTaQueryGlobalListObserver::NewL( this );    // (a)
 iGlobalListObserver->Start();                                     // <-- (b)
 iGlobalListQuery = CAknGlobalListQuery::NewL();                   // <-- (c)
 iGlobalListObserver->SetSelectItemFlag();
 iGlobalListQuery->ShowListQueryL(textArray, iGlobalListObserver->iStatus, 0);
  // (d)
 CleanupStack::PopAndDestroy(); // textArray
 iDisplayDialog = EFalse;

The following sequence diagram shows the life of the active object and global list query:

IMAGE_QUERY034.GIF

© Nokia 2009

Back to top