<?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_d0e61475_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_d0e61483_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_d0e61491_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"/>

<tbody>

<row>

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

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

</row>

<row>

<entry><p>Arrow left / 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-8-1-6-1-1-5-1-11-1-1-4-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_d0e61742_href.png" placement="inline"/>

</fig>

<section id="GUID-FA4ACC82-0080-429B-A155-433F175138A6"><title>Using

selection lists in C++ 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>