Symbian3/SDK/Source/GUID-0E695106-4139-4335-A11F-BD04418DD583.dita
changeset 7 51a74ef9ed63
child 8 ae94777fff8f
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-0E695106-4139-4335-A11F-BD04418DD583.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,132 @@
+<?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-0E695106-4139-4335-A11F-BD04418DD583" xml:lang="en"><title>Multi-selection
+list</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>Multi-selection lists are used when the purpose is to emphasize that it
+is possible to select several items from a list at the same time. Typically,
+there is an on-going operation that expects one or more items as input. An
+example of this is when the user is creating a group, and a list of names
+is offered as a multi-selection list.</p>
+<p>In a multi-selection list, the user can browse the items and check and
+uncheck any number of them. The state of each item is indicated in a checkbox
+adjacent to the item. When the user accepts the list, information about the
+marked items is passed to the application.</p>
+<p>Items are checked and unchecked using the Selection key, and the list is
+accepted with the left softkey Done/OK. Note that unlike in a markable list,
+the Options softkey is not available: one can only check and uncheck items
+and then accept or cancel the list.</p>
+<fig id="GUID-5ACB3332-F5FF-4BAD-AC49-2B569DB54378">
+<title>Multi-selection lists: in the main pane (left) and in a setting editor
+(right)</title>
+<image href="GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e62127_href.png" placement="inline"/>
+</fig>
+<p>The keypad functions for multi-selection lists are as follows:</p>
+<table id="GUID-94AC7390-A39D-48A4-AF4E-FF34EBE44593"><title>Default key event
+in multi-selection list</title>
+<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
+<thead>
+<row>
+<entry>Key</entry>
+<entry>Action</entry>
+</row>
+</thead>
+<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>Ignored (can be used to control tabs).</p></entry>
+</row>
+<row>
+<entry><p>Selection key</p></entry>
+<entry><p>Marks / unmarks the current item; toggle.</p></entry>
+</row>
+<row>
+<entry><p>Left softkey (Done)</p></entry>
+<entry><p>Accepts the list, passes the selections to the application.</p></entry>
+</row>
+<row>
+<entry><p>Right softkey (Cancel)</p></entry>
+<entry><p>Cancels the list, returns to the previous state.</p></entry>
+</row>
+<row>
+<entry><p>Clear, Edit, Call creation</p></entry>
+<entry><p>Ignored.</p></entry>
+</row>
+<row>
+<entry><p>Numeric keypad</p></entry>
+<entry><p>Ignored.</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/>
+<table id="GUID-4F77253E-5688-4642-98DD-04CB7FCF38E1-GENID-1-8-1-6-1-1-5-1-11-1-1-6-1-2-8"><title>The default touch
+events for multi-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 change</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>The item is marked/unmarked.</p></entry>
+<entry><p>Highlight disappears. </p><p>Tactile: Basic effect is provided with
+touch release event.</p></entry>
+</row>
+<row>
+<entry><p>Touch down and hold</p></entry>
+<entry><p>Inactive</p></entry>
+<entry><p>Tactile: No effect</p></entry>
+</row>
+<row>
+<entry><p>Touch down and move</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>
+<row>
+<entry><p>Touch down, move and touch release within the list</p></entry>
+<entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging
+and flicking</xref> events.</p><p>Touch release after movement does not mark/unmark
+the item.</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>
+<section id="GUID-3AF7EE7E-50F2-4714-BFC4-4C4A0033D89D"><title>Using
+multi-selection lists in C++ applications</title><p>The API to use for multi-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>
\ No newline at end of file