<?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></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><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><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_d0e50349_href.png" scale="60" placement="inline"></image>
</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><title>Main implementation files</title><p>The implementation file
for the Choice list API is aknchoicelist.h.</p></section>
</conbody><related-links>
<link href="GUID-C29FE12C-C412-40A8-A067-27C63A519D71.dita"><linktext>Choice list
API description</linktext></link>
</related-links></concept>