Providing a vertical list of selectable items

To provide a vertical list of selectable items using the Choice List API, follow the steps below:

  1. Link the AVKON libraries (avkon.lib and eikcoctl.lib) to the project file of the application.

  2. Provide an observer class that realizes the McoeControlObserver interface.

  3. Create an instance of the class CAknChoiceList.

  4. Add content to the created choice list instance.

  5. Show the choice list.

  6. Receive information from the choice list through the observer interface.

  7. Delete the choice list.

Indexing of items in the choice list

The client application is responsible for keeping track of item indexes in the choice list. The choice list component does not do this: it only returns the index of a list item.

The choice list items are indexed as follows:

  • When the items are added to the choice list from e.g. an array, the first item gets an index of 0.

  • The other items added from the array get indexes 1, 2, 3 and so forth until the last item has received an index. Therefore, for example, in a list of four items, the items have indexes 0 - 3.

  • If an item is added to the end of the list, it gets the next index number based on the number of items already in the list. For example, adding the fifth item in a four-item list results in that item having the index 4.

  • If items are added to the middle of the list, the indexes of the items after the added items are shifted up accordingly. For example, if an item is added as the fourth item in a six-item list, the old fourth, fifth, and sixth items with indexes 3 - 5 get indexes 4 - 6.

  • If an items is removed from the list, the indexes of the subsequent items in the list are shifted down accordingly. For example, if the second item is removed, the old third item becomes the second item and therefore gets an index of 1.

Use cases

Figure: Choice list API use cases

To use a choice list in your application, implementing the following use cases is mandatory:

The following use cases are optional, allowing you to set additional properties for your choice list:

Main implementation files

The implementation file for the Choice list API is aknchoicelist.h.

Related concepts