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

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

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

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

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

     6 <!-- Initial Contributors:

     7 	Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->  <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"><concept id="GUID-845F3021-E3ED-4676-916A-75740886DCBD" xml:lang="en"><title>Providing

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

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

    12 follow the steps below:</p>

    13 <ol>

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

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

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

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

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

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

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

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

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

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

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

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

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

    27 </ol>

    28 <section><title>Indexing of items in the choice list</title><p>The client

    29 application is responsible for keeping track of item indexes in the choice

    30 list. The choice list component does not do this: it only returns the index

    31 of a list item.</p><p>The choice list items are indexed as follows:</p><ul>

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

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

    34 <li><p>The other items added from the array get indexes 1, 2, 3 and so forth

    35 until the last item has received an index. Therefore, for example, in a list

    36 of four items, the items have indexes 0 - 3.</p></li>

    37 <li><p>If an item is added to the end of the list, it gets the next index

    38 number based on the number of items already in the list. For example, adding

    39 the fifth item in a four-item list results in that item having the index 4.</p></li>

    40 <li><p>If items are added to the middle of the list, the indexes of the items

    41 after the added items are shifted up accordingly. For example, if an item

    42 is added as the fourth item in a six-item list, the old fourth, fifth, and

    43 sixth items with indexes 3 - 5 get indexes 4 - 6.</p></li>

    44 <li><p>If an items is removed from the list, the indexes of the subsequent

    45 items in the list are shifted down accordingly. For example, if the second

    46 item is removed, the old third item becomes the second item and therefore

    47 gets an index of 1.</p></li>

    48 </ul></section>

    49 <section><title>Use cases</title><fig id="GUID-7FFCC838-A49D-4A91-9480-3295B0E036B7">

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    70 </ul></section>

    71 <section><title>Main implementation files</title><p>The implementation file

    72 for the Choice list API is aknchoicelist.h.</p></section>

    73 </conbody><related-links>

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

    75 API description</linktext></link>

    76 </related-links></concept>