<?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>
</related-links></concept>