<?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-CCC5BE18-E90D-4B81-AE6F-333B96E7A3F7" xml:lang="en"><title>Choice
list</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Choice list is a list type, which allows selection from different choices.
Choice list can either be closed (by default) state or opened state. In case
the choice list is empty, the opening button is dimmed and is inactive. </p>
<p>Choice list displays currently selected value by default in closed state.
When the choice list is opened, choice list pop-up displays the list of available
options (with currently selected focused). Choice list can contain text, icons
or combination of both text and icons. It is recommendation use only text
in the choice list. </p>
<p>It is possible to dynamically add and remove items in choice list. The
user can browse through the list with scroll keys or with the touch event.</p>
<fig id="GUID-920BCB9D-4DFB-411D-A730-D34BA84B1FD2">
<title>Example of Choice list</title>
<image href="GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e55550_href.png" placement="inline"/>
</fig>
<table id="GUID-DA80CFA0-061A-4B07-9D4B-7C29DAEC4E2B"><title>Default key events in a choice list</title>
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry valign="top"><p>Key</p></entry>
<entry valign="top"><p>Action</p></entry>
</row>
</thead>
<tbody>
<row>
<entry><p>Enter</p></entry>
<entry><p>Selects the focused item and closes the choice list.</p></entry>
</row>
<row>
<entry><p>Left selection key (<b>Select</b>)</p></entry>
<entry><p>Choice list item is selected.</p></entry>
</row>
<row>
<entry><p>Right selection key (<b>Close</b>)</p></entry>
<entry><p>Choice list is closed without making a new selection.</p></entry>
</row>
<row>
<entry><p>Arrow left / right keys</p></entry>
<entry><p>Closes the choice list, with focused item selected.</p></entry>
</row>
<row>
<entry><p>Arrow up / down keys</p></entry>
<entry><p>Scrolls through the choice list. Choice list is looping.</p></entry>
</row>
</tbody>
</tgroup>
</table>
<p/>
<table id="GUID-66274DBC-8690-4AF3-AE29-B2DB9D31E752"><title>Default touch events for choice list interaction in closed state</title>
<tgroup cols="3"><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
<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>Inactive, tooltip is shown.</p></entry>
<entry><p>Tactile: <ul>
<li><p>Basic tactile feedback is provided with touch down event.</p></li>
<li><p>Basic list effect given with touch down event.</p></li>
</ul></p></entry>
</row>
<row>
<entry><p>Touch release</p></entry>
<entry><p>Opens the choice list pop-up</p></entry>
<entry><p>Tactile: Pop-up open effect is given. If pop-up owns NGA effect
and they are ON, then increasing long touch effect is provided with touch
release.</p></entry>
</row>
<row>
<entry><p>Touch release</p></entry>
<entry><p>Inactive</p></entry>
<entry/>
</row>
<row>
<entry><p>Touch down and move out of the list</p></entry>
<entry><p>List continues its movement.</p></entry>
<entry><p>Basic tactile feedback is provided with touch down event.</p><p>Refer
to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging and flicking</xref> events.</p></entry>
</row>
</tbody>
</tgroup>
</table>
<p/>
<table id="GUID-E4CBD59F-EE62-4273-83C8-595611C9B302"><title>Default touch events for choice list interaction in opened state</title>
<tgroup cols="3"><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
<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 and release</p></entry>
<entry><p>Touch down moves the focus.</p></entry>
<entry><p>Pressed down highlight.</p><p>Tactile: <ul>
<li><p>Basic tactile feedback is provided with touch down event. </p></li>
<li><p>Basic list effect is provided with touch down event.</p></li>
</ul></p></entry>
</row>
<row>
<entry><p>Touch release</p></entry>
<entry><p>Selects the focused item and closes the choice list.</p></entry>
<entry><p>Tactile: Basic list effect is provided with touch release event.</p></entry>
</row>
<row>
<entry><p>Touch down and move inside the choice list.</p></entry>
<entry><p>The whole list moves along with the finger.</p><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging and flicking</xref> events</p></entry>
<entry><p>Tactile: Basic tactile feedback is provided with touch down event.</p><p>Refer
to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging and flicking</xref> events.</p></entry>
</row>
<row>
<entry><p>Touch down and move out of the choice list</p></entry>
<entry><p>The list continues its movement according to the finger movements
outside the pop-up.</p></entry>
<entry><p>Tactile: Basic tactile feedback is provided with touch down event.</p><p>Refer
to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging and flicking</xref> events.</p></entry>
</row>
<row>
<entry><p>Touch down and release outside the opened choice list.</p></entry>
<entry><p>Inactive</p></entry>
<entry><p>Basic tactile feedback given with touch down event. No advanced
tactile feedback.</p></entry>
</row>
</tbody>
</tgroup>
</table>
<section id="GUID-824E97C2-24CC-4058-B682-EDB71644051C"><title>Using choice
list in applications</title>       <p>The API to use for choice list is the <xref href="GUID-C29FE12C-C412-40A8-A067-27C63A519D71.dita">Choice list API</xref>. For
implementation information, see <xref href="GUID-845F3021-E3ED-4676-916A-75740886DCBD.dita">Providing
a vertical list of selectable items</xref>. </p>     </section>
</conbody></concept>