<?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-0822B030-E776-4BD5-B9C9-23D3821BCE1F" xml:lang="en"><title>Selection
list</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>A selection list is a common means of displaying and accessing data in
applications. When a selection list is displayed, the application is typically
in a permanent state, which means that the user can leave the application,
open another application, and later return to the same state. Selection lists
are displayed in the main pane.</p>
<p>Typically, the user can open items in a selection list, leading into another,
more detailed view of the item within the application. In addition to browsing
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>
<p>The usage of the Selection key in selection lists deserves special attention.
Depending on the case, it can do the following actions:</p>
<ul>
<li><p>Selects the item in focus. This should happen whenever it is assumed
that it is clear to the user what happens. Selecting can mean:</p><ul>
<li><p>Opening an item, such as a folder or a date in Calendar, leading to
a detailed view.</p></li>
<li><p>Executing a command when the focused item is a command.</p></li>
</ul></li>
<li><p>Opens the context sensitive Options menu. This should only happen when
the user cannot be assumed to know what happens if the Selection key is pressed.
The menu should contain only high-priority options associated with the item
in focus, not general items such as Settings, Help, or Exit. The maximum amount
of options in the context sensitive Options menu is four.</p></li>
</ul>
<p>The two types of Selection key actions should not be mixed within one list;
one or the other should happen for every item in the list.</p>
<fig id="GUID-010C51B9-5D2A-4DD5-A1DA-67A30CD132FD">
<title>Select action opens a view</title>
<image href="GUID-B7E55764-C137-4877-9083-63ACEAF30BE5_d0e58076_href.png" placement="inline"/>
</fig>
<fig id="GUID-5DD10CF4-6E68-4C81-81D8-1CA45CD674C4">
<title>Select action performs a command</title>
<image href="GUID-06B287CD-C19A-4CAC-8378-5563C552448B_d0e58084_href.png" placement="inline"/>
</fig>
<fig id="GUID-B8275C0A-50B9-4A48-AC20-8E2B84F23F8B">
<title>Context sensitive Options menu opened with the Selection key</title>
<image href="GUID-26778399-0105-413F-A39D-535A3BF5EBE2_d0e58092_href.png" placement="inline"/>
</fig>
<p>The keypad functions for selection lists are as follows:</p>
<table id="GUID-2AF81DA9-8C20-47AE-87DE-8252CC1DAF59"><title>Default key events
in selection list</title>
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry valign="top"><p>Key events</p></entry>
<entry valign="top"><p>Description</p></entry>
</row>
</thead>
<tbody>
<row>
<entry><p>Arrow up / Arrow down</p></entry>
<entry><p>Moves up or down to next visible item in a list.</p></entry>
</row>
<row>
<entry><p>Arrow left / Arrow right</p></entry>
<entry><p>May be ignored, or may have navigation functions associated with
them (see <xref href="GUID-EEF2F892-8900-475F-926B-A49D0D98C1C6.dita">Navigation</xref>).</p></entry>
</row>
<row>
<entry><p>Selection key</p></entry>
<entry><p>Selects the item; see the discussion above.</p></entry>
</row>
<row>
<entry><p>Left softkey (Options)</p></entry>
<entry><p>Opens the Options menu (see <xref href="GUID-BFEEECCA-190B-4DDE-8A04-4FE918BE8690.dita">Options
menu</xref>).</p></entry>
</row>
<row>
<entry><p>Right softkey (Back; Exit)</p></entry>
<entry><p>Back stepping (see<xref href="GUID-EEF2F892-8900-475F-926B-A49D0D98C1C6.dita">Navigation</xref>).</p></entry>
</row>
<row>
<entry><p>Clear</p></entry>
<entry><p>Deletes the item if it can be deleted (confirmation from the user
is required); otherwise ignored.</p></entry>
</row>
<row>
<entry><p>Edit</p></entry>
<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>
</row>
<row>
<entry><p>Numeric keypad</p></entry>
<entry><p>May be ignored, or may have specific functions within the state.</p></entry>
</row>
<row>
<entry><p>Other keys</p></entry>
<entry><p>Do the default action of the key.</p></entry>
</row>
</tbody>
</tgroup>
</table>
<p/>
<p>The following table lists the default touch events for selection list:</p>
<table id="GUID-5B8DA500-4092-4E1A-A035-308C4D352138-GENID-1-10-1-6-1-1-5-1-8-1-1-9-1-10-1-2-13"><title>Default touch
events for Selection list.</title>
<tgroup cols="3"><colspec colname="col1" colwidth="0.80*"/><colspec colname="col2" colwidth="1.01*"/><colspec colname="col3" colwidth="1.19*"/>
<thead>
<row>
<entry valign="top"><p>User action</p></entry>
<entry valign="top"><p>State change</p></entry>
<entry valign="top"><p>Feedback</p></entry>
</row>
</thead>
<tbody>
<row>
<entry><p>Touch down</p></entry>
<entry><p>No effect</p></entry>
<entry><p>Highlight is shown. </p><p>Tactile: Basic list effect and audio
feedback is provided with touch down event.</p></entry>
</row>
<row>
<entry><p>Touch release</p></entry>
<entry><p>Item is activated.</p></entry>
<entry><p>Highlight disappears. </p><p>Tactile: Basic list effect is provided
with touch release event.</p></entry>
</row>
<row>
<entry><p>Touch down and hold</p></entry>
<entry><p>Stylus pop-up menu is opened.</p></entry>
<entry><p>Highlight is shown. Animation is shown to indicate the opening pop-up. </p><p>Tactile:
If activates a long touch, then increasing long touch effect is provided with
hold event. Pop-up effect is provided when the pop-up is opened.</p></entry>
</row>
<row>
<entry><p>Touch event combinations, refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging
and flicking</xref> events.</p></entry>
<entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging
and flicking</xref> events.</p></entry>
<entry><p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging
and flicking</xref> events.</p></entry>
</row>
</tbody>
</tgroup>
</table>
<fig id="GUID-4149CCA2-D8FE-4393-8D82-A736EF5337C5">
<title>Selection lists </title>
<image href="GUID-829C15B1-0769-4E90-935D-4DCA58895E81_d0e58353_href.png" placement="inline"/>
</fig>
<section id="GUID-FA4ACC82-0080-429B-A155-433F175138A6"><title>Using
selection lists in applications</title><p>The API to use for selection lists
is the <xref format="html" href="specs/guides/Lists_API_Specification/Lists_API_Specification.html" scope="peer">Lists API</xref>. For implementation information, see <xref format="htrml" href="specs/guides/Lists_API_Specification/Lists_API_Specification.html#Lists_API_Specification.topic3" scope="peer">Using the Lists API</xref>.</p></section>
</conbody></concept>