Creating a CAknSettingItemList in a Dialog

Introduction

One of the more interesting classes in Avkon or Nokia Series 60 devices is the CAknSettingItemList control.

This control differs from the other list type controls in that it allows items to be edited and displayed in the list. The control will allow you to create a list of items with a wide range of editors.

Whilst there are a number of really good examples on this control and Nokia recently produced a document on this control , there is no clean explanation of how to use this control in a dialog.

In fact the solution provided can be used for most controls as there is a standard pattern for adding a custom control to a dialog in Symbian OS.

Creating the resources

The resources are definitely the most complex part of the operation. Anything wrong here and the dialog will just crash when it is being created.

In the SLIDlg.rss file, locate the string "Article Code from here onward". This is the point at which the new code for the settings dialog has been placed. First a dialog resource is defined. The only things that is important to note here is that the R_AVKON_SOFTKEYS_SELECT_CANCEL is used instead of the normal Ok/Cancel combination. This is very important as will be seen in the dialog section further on in the article.

The next thing that is required is the dialog line. For this, the "type" is set to a custom control type, in this case EAknCtLastControlId as this will not be confused with other intrinsic types, this value or any value higher can be used. (See Avkon.hrh for further details). What we are saying to the Avkon dialog manager is that we are using a custom control in the dialog and to handle it differently to other control. Specifically calling the functions CreateCustomControlL() and ConvertCustomControlTypeToBaseControlType(). Next the "id" of the control is created. In this case anything can be used as there will only be one control in the dialog, though the id must be unique in Series 60.

Finally the resource definition of the control need to be specified. As this control is a very simple settings editor it can be AVKON_SETTING_ITEM_LIST data type. Note however that each AVKON_SETTING_ITEM in the list is composed of three parts. This item itself , a page for the setting caption and value, and an editor.

Now examine the rss file. All the important items have been highlighted with comments starting with "// ****".

Creating the CAknSettingItemList

In order to use the CAknSettingItemList class and to provide editing functionality you will need to derive a class from CAknSettingItemList and then override the CreateSettingItemL() function to provide the relevant editors for each item in the settings list.

For the purposes of this sample we have just stored the data with the derived settings list item. In practise you will need to handle this by passing in your own structure with the data that is to be modified.

Now we have the setting item list we can go ahead and link it to the dialog. As an aside, the document on the Nokia web site has information on how to create new setting item editors.

Creating the dialog

Now we have a CAknSettingItemList we can create the dialog which will instantiate this list from the resources. Once the list is instantiated, the CreateSettingItemL() will be called to create all the components of the settings list.

Internally when the dialog is created using new, the resources will be read by the dialog manager. When it finds a custom control type (In this case CAknCtLastControlId) it will call the CreateCustomControlL() function which will allow the settings dialog class to create an instance of the setting item list.

Once this instance is created the dialog manager will then load the resources associated with the control. The final stage is to set the ConvertCustomControlTypeToBaseControlType() to tell the dialog manager that this control behaves like a popfield type control. The dialog manager uses this to decide how to route events and display the item in a dialog line.

At this stage you should be able to run the sample and have your settings displayed in a dialog box, you should also be able to navigate between the items, but not edit them.

Editing items

After the dialog box resources have been loaded, the settings item list will call CreateSettingItemL() to allow the creation of the controls each of the setting list items.

This will also associate your variables with the control. If your data is not ready at this point then you can set the data in the PostLayoutDynInitL() method of the dialog and call LoadSettingsL() on the item list control object.

This will then tell the settings item list to reload the data for the settings items To edit a settings item we override the OkToExitL() function so that when the user clicks the Select softkey it will edit the control in an item settings editor. You can change the parameter for the EditL() function to edit in place if you prefer.

Finally to save changes, the StoreSettingsL() function should be called which will copy all the data from the editors into your dialog data. Failing to call the StoreSettingsL() will not save the data into the variables.

Download

slidlg.zip

Conclusion

Hopefully this has shown how to create a settings list that can be used in a dialog where I believe most people will be intending to use it.

My thanks to mark_williams and synov on the Nokia forum for providing some code to help get this off the ground and to John Kern for proofreading and commenting on this article.