<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-845F3021-E3ED-4676-916A-75740886DCBD" xml:lang="en"><title>Providing

a vertical list of selectable items</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>To provide a vertical list of selectable items using the Choice List API,

follow the steps below:</p>

<ol>

<li id="GUID-7BC9F7F7-7C48-4D8B-AA78-E9F03B0037D1"><p>Link the AVKON libraries

(<codeph>avkon.lib</codeph> and <codeph>eikcoctl.lib</codeph>) to the project

file of the application.</p></li>

<li id="GUID-2AAE484A-042E-413E-95C5-075213B1F9FD"><p>Provide an observer

class that realizes the <codeph>McoeControlObserver</codeph> interface.</p></li>

<li id="GUID-0DB766B5-F05E-4724-AEA3-3AD7ED200941"><p>Create an instance of

the class <codeph>CAknChoiceList</codeph>.</p></li>

<li id="GUID-02B3DF80-EBF2-463C-A347-256A2CEE08F6"><p>Add content to the created

choice list instance.</p></li>

<li id="GUID-4CBFB485-526E-4A94-B177-E7B8C89828F9"><p>Show the choice list.</p></li>

<li id="GUID-1F3926D0-CCBE-4F16-98E2-8E6C0C0DA973"><p>Receive information

from the choice list through the observer interface.</p></li>

<li id="GUID-22CBB678-6954-42CF-8F8E-FA847A7FBEA9"><p>Delete the choice list.</p></li>

</ol>

<section id="GUID-046C0B82-B9A4-4123-9FDD-530A0232B252"><title>Indexing of

items in the choice list</title><p>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.</p><p>The choice

list items are indexed as follows:</p><ul>

<li><p>When the items are added to the choice list from e.g. an array, the

first item gets an index of 0.</p></li>

<li><p>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.</p></li>

<li><p>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.</p></li>

<li><p>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.</p></li>

<li><p>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.</p></li>

</ul></section>

<section id="GUID-42664A41-C3D3-4DAF-802D-8A98B15984CA"><title>Use cases</title><fig id="GUID-7FFCC838-A49D-4A91-9480-3295B0E036B7">

<title>Choice list API use cases</title>

<image href="GUID-92067BE3-40F0-4652-A882-FFDE2816C9BD_d0e71873_href.png" scale="60" placement="inline"/>

</fig><p>To use a choice list in your application, implementing the following

use cases is mandatory:</p><ul>

<li><p><xref href="GUID-462239D1-4B40-4342-92DA-32AB0AF0D2F2.dita">Creating the

choice list</xref></p></li>

<li><p><xref href="GUID-17F3FFF4-00B8-492F-95BD-11AFF02CAAB2.dita">Adding items

to the choice list</xref></p></li>

<li><p><xref href="GUID-F2397B5A-0700-46D5-8E07-CBB9F769DA01.dita">Getting user

selection from the choice list</xref></p></li>

<li><p><xref href="GUID-A84EDC63-0A74-4B93-BED2-7BE273A6DDB3.dita">Deleting the

choice list</xref></p></li>

</ul><p>The following use cases are optional, allowing you to set additional

properties for your choice list:</p><ul>

<li><p><xref href="GUID-E332F544-0759-4C10-B29C-14AA5EAEBD49.dita">Showing the

choice list</xref></p></li>

<li><p><xref href="GUID-73DD8A9B-6F7A-4BF5-87A1-5D86662B30D3.dita">Removing items

from the choice list</xref></p></li>

<li><p><xref href="GUID-210606BE-A36C-4B65-B083-93F71024196C.dita">Setting the

item selected when the choice list is opened</xref></p></li>

</ul></section>

<section id="GUID-6609939C-29EA-405B-9B53-3EF19BAE8230"><title>Main implementation

files</title><p>The implementation file for the Choice list API is <codeph>aknchoicelist.h</codeph>.</p></section>

</conbody><related-links>

<link href="GUID-C29FE12C-C412-40A8-A067-27C63A519D71.dita"><linktext>Choice list

API description</linktext></link>