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-0822B030-E776-4BD5-B9C9-23D3821BCE1F" xml:lang="en"><title>Selection

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

    11 <p>A selection list is a common means of displaying and accessing data in

    12 applications. When a selection list is displayed, the application is typically

    13 in a permanent state, which means that the user can leave the application,

    14 open another application, and later return to the same state. Selection lists

    15 are displayed in the main pane.</p>

    16 <p>Typically, the user can open items in a selection list, leading into another,

    17 more detailed view of the item within the application. In addition to browsing

    18 and selecting items, other functions are available in the Options menu (see <xref href="GUID-BFEEECCA-190B-4DDE-8A04-4FE918BE8690.dita">Options menu</xref>).</p>

    19 <p>The usage of the Selection key in selection lists deserves special attention.

    20 Depending on the case, it can do the following actions:</p>

    21 <ul>

    22 <li><p>Selects the item in focus. This should happen whenever it is assumed

    23 that it is clear to the user what happens. Selecting can mean:</p><ul>

    24 <li><p>Opening an item, such as a folder or a date in Calendar, leading to

    25 a detailed view.</p></li>

    26 <li><p>Executing a command when the focused item is a command.</p></li>

    27 </ul></li>

    28 <li><p>Opens the context sensitive Options menu. This should only happen when

    29 the user cannot be assumed to know what happens if the Selection key is pressed.

    30 The menu should contain only high-priority options associated with the item

    31 in focus, not general items such as Settings, Help, or Exit. The maximum amount

    32 of options in the context sensitive Options menu is four.</p></li>

    33 </ul>

    34 <p>The two types of Selection key actions should not be mixed within one list;

    35 one or the other should happen for every item in the list.</p>

    36 <fig id="GUID-63BEF19B-2754-4AE4-BC37-BCBF767319B4">

    37 <title>Select action opens a view</title>

    38 <image href="GUID-15F35B7F-8CDD-49BA-A015-475C0F6221B8_d0e54972_href.png" scale="40" placement="inline"></image>

    39 </fig>

    40 <fig id="GUID-EB8B5041-9CBF-4580-AEBE-69AF79A11198">

    41 <title>Select action performs a command</title>

    42 <image href="GUID-5365F75F-647F-4225-B63B-35675EBD6038_d0e54980_href.png" scale="40" placement="inline"></image>

    43 </fig>

    44 <fig id="GUID-4F9A7034-DA55-4577-BB41-8BF0B5885242">

    45 <title>Context sensitive Options menu opened with the Selection key</title>

    46 <image href="GUID-2CF4F12C-DF30-43EB-BD3D-A6AF8BAB407A_d0e54988_href.png" scale="40" placement="inline"></image>

    47 </fig>

    48 <p>The keypad functions for selection lists are as follows:</p>

    49 <table id="GUID-2AF81DA9-8C20-47AE-87DE-8252CC1DAF59"><title>Default key events

    50 in selection list</title>

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

    52 <tbody>

    53 <row>

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

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

    56 </row>

    57 <row>

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

    59 <entry><p>May be ignored, or may have navigation functions associated with

    60 them (see <xref href="GUID-EEF2F892-8900-475F-926B-A49D0D98C1C6.dita">Navigation</xref>).</p></entry>

    61 </row>

    62 <row>

    63 <entry><p>Selection key</p></entry>

    64 <entry><p>Selects the item; see the discussion above.</p></entry>

    65 </row>

    66 <row>

    67 <entry><p>Left softkey (Options)</p></entry>

    68 <entry><p>Opens the Options menu (see <xref href="GUID-BFEEECCA-190B-4DDE-8A04-4FE918BE8690.dita">Options

    69 menu</xref>).</p></entry>

    70 </row>

    71 <row>

    72 <entry><p>Right softkey (Back; Exit)</p></entry>

    73 <entry><p>Back stepping (see<xref href="GUID-EEF2F892-8900-475F-926B-A49D0D98C1C6.dita">Navigation</xref>).</p></entry>

    74 </row>

    75 <row>

    76 <entry><p>Clear</p></entry>

    77 <entry><p>Deletes the item if it can be deleted (confirmation from the user

    78 is required); otherwise ignored.</p></entry>

    79 </row>

    80 <row>

    81 <entry><p>Edit</p></entry>

    82 <entry><p>Ignored, or a marking function if the list is markable (see <xref href="GUID-ED784025-4E65-4BE9-ADA8-A13427B6EA30.dita">Markable list</xref>).</p></entry>

    83 </row>

    84 <row>

    85 <entry><p>Numeric keypad</p></entry>

    86 <entry><p>May be ignored, or may have specific functions within the state.</p></entry>

    87 </row>

    88 <row>

    89 <entry><p>Other keys</p></entry>

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

    91 </row>

    92 </tbody>

    93 </tgroup>

    94 </table>

    95 <fig id="GUID-02393CD0-886F-4628-97CE-9FA6DD034634">

    96 <title>Selection lists </title>

    97 <image href="GUID-B0E6F296-1340-4458-B9F6-EDC13BBF20E9_d0e55123_href.png" scale="40" placement="inline"></image>

    98 </fig>

    99 <section><title>Using selection lists

   100 in C++ applications</title><p>The API to use for selection lists is the Lists

   101 API. For implementation information, see Using

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

   103 </conbody></concept>