Providing a vertical list of selectable items

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 1. Choice list API use cases

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

• Creating the choice list

• Adding items to the choice list

• Getting user selection from the choice list

• Deleting the choice list

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

• Showing the choice list

• Removing items from the choice list

• Setting the item selected when the choice list is opened

Main implementation files

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