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-0E695106-4139-4335-A11F-BD04418DD583" xml:lang="en"><title>Multi-selection

    10 list</title><prolog><metadata><keywords></keywords></metadata></prolog><conbody>

    11 <p>Multi-selection lists are used when the purpose is to emphasize that it

    12 is possible to select several items from a list at the same time. Typically,

    13 there is an on-going operation that expects one or more items as input. An

    14 example of this is when the user is creating a group, and a list of names

    15 is offered as a multi-selection list.</p>

    16 <p>In a multi-selection list, the user can browse the items and check and

    17 uncheck any number of them. The state of each item is indicated in a checkbox

    18 adjacent to the item. When the user accepts the list, information about the

    19 marked items is passed to the application.</p>

    20 <p>Items are checked and unchecked using the Selection key, and the list is

    21 accepted with the left softkey Done/OK. Note that unlike in a markable list,

    22 the Options softkey is not available: one can only check and uncheck items

    23 and then accept or cancel the list.</p>

    24 <fig id="GUID-073BC74E-AB7F-4C22-B6E1-B5C4749B28B3">

    25 <title>Multi-selection lists: in the main pane (left) and in a setting editor

    26 (right)</title>

    27 <image href="GUID-1A03B210-4175-4BE0-A5B3-647E7FA8E573_d0e55282_href.png" scale="60" placement="inline"></image>

    28 </fig>

    29 <p>The keypad functions for multi-selection lists are as follows:</p>

    30 <table id="GUID-94AC7390-A39D-48A4-AF4E-FF34EBE44593"><title>Default key event

    31 in multi-selection list</title>

    32 <tgroup cols="2"><colspec colname="col1"></colspec><colspec colname="col2"></colspec>

    33 <thead>

    34 <row>

    35 <entry>Key</entry>

    36 <entry>Action</entry>

    37 </row>

    38 </thead>

    39 <tbody>

    40 <row>

    41 <entry><p>Arrow up / down</p></entry>

    42 <entry><p>Moves the focus in the list.</p></entry>

    43 </row>

    44 <row>

    45 <entry><p>Arrow left / right</p></entry>

    46 <entry><p>Ignored (can be used to control tabs).</p></entry>

    47 </row>

    48 <row>

    49 <entry><p>Selection key</p></entry>

    50 <entry><p>Marks / unmarks the current item; toggle.</p></entry>

    51 </row>

    52 <row>

    53 <entry><p>Left softkey (Done)</p></entry>

    54 <entry><p>Accepts the list, passes the selections to the application.</p></entry>

    55 </row>

    56 <row>

    57 <entry><p>Right softkey (Cancel)</p></entry>

    58 <entry><p>Cancels the list, returns to the previous state.</p></entry>

    59 </row>

    60 <row>

    61 <entry><p>Clear, Edit, Call creation</p></entry>

    62 <entry><p>Ignored.</p></entry>

    63 </row>

    64 <row>

    65 <entry><p>Numeric keypad</p></entry>

    66 <entry><p>Ignored.</p></entry>

    67 </row>

    68 <row>

    69 <entry><p>Other keys</p></entry>

    70 <entry><p>Do the default action of the key.</p></entry>

    71 </row>

    72 </tbody>

    73 </tgroup>

    74 </table>

    75 <section><title>Using multi-selection

    76 lists in C++ applications</title><p>The API to use for multi-selection lists

    77 is the Lists

    78 API. For implementation information, see Using

    79 the Lists API.</p></section>

    80 </conbody></concept>