<?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-ED784025-4E65-4BE9-ADA8-A13427B6EA30" xml:lang="en"><title>Markable

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

<p>A markable list is a selection list with the added marking feature. The

user can mark any number of items on the list while browsing it, and then

execute a single command, which is applied to all the marked items. This is

analogous to the multiple-item highlight feature used in computer GUIs.</p>

<p>The marking feature is typically applied to lists the user manages, containing

a large number of items that may be for example sent, moved, or deleted. By

marking items first and then selecting a command, the user can perform certain

operations more quickly and with less key presses than by performing the command

separately for each of the items.</p>

<p>Marked items are indicated graphically.</p>

<fig id="GUID-171B4713-C197-4D05-9FBC-E3296C26ABFF">

<title>Markable list. Marked items are indicated graphically in the list.</title>

<image href="GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e61778_href.png" placement="inline"/>

</fig>

<p>The <b>Mark</b> and <b>Unmark</b> functions are available in the Options

menu of the markable list. Alternatively, or as a shortcut, the user can keep

the Hash (#) key pressed while using the Arrow keys and the Selection key

in the following way:</p>

<ul>

<li><p>Pressing the Hash (#) key marks the current item. This is a toggling

function, so pressing the Hash (#) key on a marked item unmarks the item. </p></li>

<li><p>Pressing an Arrow key (up or down) while holding down the Hash (#)

key marks both the current item and the one onto which the focus moves. If

the user keeps holding the Hash (#) key and scrolls further in the same direction,

all the scrolled items become marked; to unmark the items in reverse order

the user can scroll into the opposite direction while holding the Hash (#)

key down. </p></li>

<li><p>Items can be unmarked by pressing the Hash (#) key together with scrolling:

if the user starts holding the Hash (#) key down when on a marked item and

then scrolls, all the scrolled items become unmarked. </p></li>

<li><p>Several marking actions can be done subsequently. The user can mark

an item, then release the Hash (#) key, browse and move the focus onto some

other item on the list, and then mark that item. The first item remains marked,

and the ones between the two do not become marked. </p></li>

<li><p>All items become unmarked when the user exits the list, for example

by back stepping. There may be exceptions to this rule in certain applications

that require selecting items from several levels of folder hierarchy. An example

of this is creating a play list in the Media Player application. Items remain

marked if the user opens and cancels the <b>Options</b> menu, or swaps applications. </p></li>

<li><p>Pressing the Selection key when there are marked items on the list

opens the context sensitive <b>Options</b> menu containing only those functions

that apply to multiple items.</p></li>

</ul>

<p>A markable list functions exactly like a normal selection list, except

for the marking feature.</p>

<p>Devices that have the optional Edit key perform these same functions by

using the Edit key and arrow keys instead of the Hash (#) key.</p>

<p>The user may access the <b>Options</b> menu to perform functions on all

marked items at once. When user has one or more items marked, <b>Options</b> menu

does not contain items that apply to one item only (such as <b>Open</b>).

Exceptions are Help and Exit, which should appear in every <b>Options</b> menu.

Appropriate error handling must be designed for functions that do not apply

to some or all of the marked items.</p>

<ul>

<li><p>When executing a function, if any of the items are marked, all the

marked items are affected by the function. If the focus is on an item that

is not marked, the function does not affect that item. </p></li>

<li><p>After the selected function is successfully done, all items are unmarked.

In an error case, when the function cannot be applied, the marks should remain

in place.</p></li>

</ul>

<p>The Options menu includes the marking and unmarking functions in a submenu

so that any user can find the feature. The submenu has also the <b>Mark all</b> and <b>Unmark</b> all

options.</p>

<p>For other keypad actions, see <xref href="GUID-0822B030-E776-4BD5-B9C9-23D3821BCE1F.dita">Selection

list</xref>.</p>

<table id="GUID-385DFE50-AC9B-4C4E-BCE4-98A088443E77"><title>Default touch

events for Markable lists</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>The marked/unmarked status of all items remains unchanged.</p></entry>

<entry><p>Highlight is shown. </p><p>Tactile: Basic list effect and audio

feedback is provided with touch down.</p></entry>

</row>

<row>

<entry><p>Touch release, while no item is marked</p></entry>

<entry><p>Activates the item</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, while no item is marked</p></entry>

<entry><p>Stylus pop-up menu is opened with an option Mark <i>§QTN_OPTIONS_LIST_MARK_ONE§</i>. </p><p>If

user selects Mark, the pop-up is closed, highlight removed and the item becomes

marked.</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 and pop-up effect is provided when the pop-up is opened.</p></entry>

</row>

<row>

<entry><p>Touch release, while at least one item is marked</p></entry>

<entry><p>A context specific options menu opens. The marked/unmarked status

of all items remains unchanged. </p><p>Context specific options menu should

contain items for Mark/Unmark and any needed items that apply to all marked

items.</p></entry>

<entry><p>Highlight disappears. Tactile: Pop-up open effect is provided. If

pop-up has theme effects and they are ON, then increasing long touch effect

is provided with touch release.</p></entry>

</row>

<row>

<entry><p>Touch down and hold, while at least one item is marked</p></entry>

<entry><p>Inactive</p></entry>

<entry><p>Tactile: No effect</p></entry>

</row>

</tbody>

</tgroup>

</table>

<p/>

<table id="GUID-BD658610-F69D-4CF6-9025-1BC567D3025A"><title>Default touch/key

events for markable lists</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>Control and touch down</p></entry>

<entry><p>Mark/unmark the item touched. </p><p>Toggle between marked and unmarked.</p></entry>

<entry><p>Highlight is shown. </p><p>Tactile: Basic list effect and audio

feedback is provided with touch down.</p></entry>

</row>

<row>

<entry><p>Control and touch release</p></entry>

<entry><p>No effect</p></entry>

<entry><p>Highlight disappears. </p><p>Tactile: No effect.</p></entry>

</row>

<row>

<entry><p>Shift and touch down</p></entry>

<entry><p>If there is highlight brought by the hardware key event, mark/unmark

all items between focused and touched down item. </p><p>If the item touched

down is unmarked, then all items between the item and focused item are marked,

and vice versa.</p></entry>

<entry><p>Highlight is shown.</p><p>Tactile: Basic list effect and audio feedback

is provided with touch down.</p></entry>

</row>

<row>

<entry><p>Control/Shift and touch down and hold</p></entry>

<entry><p>Inactive</p></entry>

<entry><p>Tactile: No effect</p></entry>

</row>

</tbody>

</tgroup>

</table>

<section id="GUID-69189A53-90FA-4874-AC60-D18D120C9C90"><title>Using

markable lists in C++ applications</title><p>The API to use for markable 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>