List Dialogs

Series 60 provides two types of list dialogs: a selection list dialog, as shown in Figure 6-27, and a markable list dialog, as shown in Figure 6-28. The lists behave in the same way as standard lists, but are contained within a dialog. A selection list dialog can optionally have a find pane ”this allows the user to search for items in the list by entering matching characters from the start of the item name .

Figure 6-27. Selection list dialog with find pane.

Figure 6-28. Markable list dialog.

Both types of list are constructed using the same techniques. The focus in this subsection is on the selection list dialog ”the application ListDlg is used to illustrate the main principles involved.

On startup, the ListDlg application displays a list of saved games . Each has a small icon representing the number of players and a single line of text representing the name. There is a find pane at the bottom of the screen, which allows the user to search for items in the list. As characters are typed in, a filter is applied to the list so that only those items that match the entered text are listed, as shown in Figure 6-29. In the ListDlg example, selection of an item from the list results in a call to the empty method PlaySelectedGame() ”no game-playing functionality has been implemented.

Figure 6-29. List filtering.

Defining a Selection List Dialog in a Resource

A selection list dialog should be defined in a DIALOG resource structure. A find pane is implemented in the resource file, so the DIALOG resource structure in this example has two DLG_LINE sections. If the filtering facility is not required, the second line can simply be omitted. The list items could be defined dynamically in the code, but here they are defined statically in the resource r_listdlg_list_array :

 RESOURCE DIALOG r_listdlg_dialog    {    flags = EAknDialogSelectionList;    buttons = R_AVKON_SOFTKEYS_OK_CANCEL;    items =       {       DLG_LINE          {          type = EAknCtSingleGraphicListBox;          id = ESelectionListControl;          control = LISTBOX             {             flags = EAknListBoxSelectionList;             array_id = r_listdlg_list_array;             };          },       DLG_LINE          {          itemflags = EEikDlgItemNonFocusing;          id = EFindControl;          type = EAknCtSelectionListFixedFind;          }       };    } 

Further details of list types, item formats, and their appearance are provided in Chapter 7.

Constructing a Selection List Dialog

Construction of a selection list dialog is performed using its NewL() method. This function has three mandatory parameters. The first, a TInt& , is used to return the selected item in the list. The second parameter is the list item array. This is a standard list item array, containing descriptors representing the list items. In ListDlg , the list items are defined statically in the resource, so this parameter is set to NULL . However, if a dynamic array of items is required, an array of descriptors can be created and passed through instead. The list does not take ownership of the array, so its subsequent deletion must be performed externally. The third parameter should be the value of the resource for any menu bar required. In the ListDlg example, the dialog is defined in the resource file with Ok and Cancel soft keys, so there is no need for a menu bar, and so zero is passed in. If an Options menu is needed, an appropriate MENU_BAR resource should be passed in here.

In ListDlg , the dialog is constructed in CListDlgContainer::ConstructL() :

 TInt openedItem(0); // Construct and prepare the dialog CAknSelectionListDialog* dialog = CAknSelectionListDialog::NewL(openedItem, NULL, 0); 

Adding Icons to a Selection List Dialog

For a selection list to contain graphics items, they must be added to the dialog's icon array.

[View full width]
[View full width]
dialog->PrepareLC(R_LISTDLG_DIALOG); HBufC* iconFileName = StringLoader::LoadLC(R_ICON_FILE_NAME); CArrayPtr<CGulIcon>* icons = new (ELeave) CAknIconArray(KNumberOfIcons); CleanupStack::PushL(icons); icons->AppendL(iEikonEnv->CreateIconL(*iconFileName, EMbmDialoglistex11player, EMbmDialoglistex11player_mask)); icons->AppendL(iEikonEnv->CreateIconL(*iconFileName, EMbmDialoglistex12player, EMbmDialoglistex12player_mask)); dialog->SetIconArrayL(icons); // transferring ownership of icons CleanupStack::Pop(icons); ... CleanupStack::PopAndDestroy(iconFileName);

The list's item drawer owns the icons. Icons cannot be added to the list before it exists, so the dialog must be prepared first. This is performed using the standard dialog PrepareLC() method, passing in the dialog resource. A standard array of list icons could then be created and set into the dialog using its SetIconArrayL() method. See Chapter 8 for further details on lists and icon arrays.

Executing a Selection List Dialog

After the dialog has been prepared, it is executed using the standard RunLD() method. If dialog preparation is not required, then the standard ExecuteLD() method can be used instead.

 if (dialog->RunLD ())    {    PlaySelectedGame(openedItem);    } 

As usual, this returns a TBool indicating whether the dialog closed with a positive or negative action. Once closed, the TInt , supplied on construction, in this case openedItem , will contain the index value of the selected item.

Markable List Dialogs

To create a markable list dialog that allows the user to select more than one item, a few alterations are necessary to the ListDlg application.

The DIALOG resource should be defined as for the selection list, but the flags should be set to EAknDialogMarkableList and the LISTBOX flags should be EAknListBoxMarkableList . A markable list dialog is defined by the CAknMarkableListDialog class. It is instantiated by passing in an array ( CArrayFix<TInt> ) by reference, which contains the selected indices. A reference to a context-sensitive menu can also be passed in.

For a markable list without graphics, default marking icons will be supplied automatically. For a markable list with graphics, they are supplied as in the selection list example ListDlg . The marking graphics are added as the first element of the array. (The IDs for the standard marking graphic can be accessed from avkon.mbg .)

The array is executed using the usual ExecuteLD() , or PrepareLC() and RunLD() .

Developing Series 60 Applications. A Guide for Symbian OS C++ Developers
Developing Series 60 Applications: A Guide for Symbian OS C++ Developers: A Guide for Symbian OS C++ Developers
ISBN: 0321227220
EAN: 2147483647
Year: 2003
Pages: 139 © 2008-2017.
If you may any questions please contact us: