<?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-8F6F6C2C-C00E-4412-A880-5EEBF7270265" xml:lang="en"><title>Generic

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

<p>Button is a generic component, which may have touch down and release and/or

touch down and hold functionality. Touch down and hold can be interpreted

as touch down and hold or key repeat. Generic buttons can be placed, for example,

inside the toolbar. </p>

<p>The generic button can have the following properties:<ul>

<li><p><b>ON/OFF button</b> - it can be used for active/inactive type of functions

such as Loudspeaker or Font italics.</p></li>

<li><p><b>Mode toggle button</b> - can be used for switching between several

modes as in Flash.</p></li>

<li><p><b>Command button</b> - it offers direct action (functions/view access)

such as Send or New contact with a button press feedback. </p></li>

</ul> </p>

<p>Buttons can have the following states:<ul>

<li><p><i>Unavailable / dimmed</i> when button function is not available</p></li>

<li><p><i>Available and not pressed with or without focus</i> when the button

is active but has not been pressed</p></li>

<li><p><i>Latched down with or without focus</i>, for example, in case where

there are many different text formatting options ON at the same time. In multiple

mode buttons, user can switch between the different ’selected’ modes by touching

the multiple mode button again. States change after touch release and current

mode’s function is executed. Button states loop when the user touches those

again</p></li>

<li><p><i>Pressed with or without focus</i> - This state indicates to the

user that touch down has activated the button</p></li>

</ul></p>

<table id="GUID-ED68DB7B-934F-4ABA-93F6-ECE636CF3760"><title>Default touch

events for generic button</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>Button pressed effect. On down event application specific functionality.</p></entry>

<entry><p>Graphical indication and possible tooltip </p><p>Tactile: Basic

button effect and audio feedback is provided with touch down.</p></entry>

</row>

<row>

<entry><p>Touch release</p></entry>

<entry><p>Activates the button, launches other view or event. </p><p>Button

is latched down or set to available and non-pressed.</p></entry>

<entry><p>Switches between down look and non-pressed look of the button.</p><p> When

the toolbar button launches another view or event, the button does not appear

latched down. </p><p>Tactile: Basic button effect is provided with touch release.

No audio feedback is provided.</p></entry>

</row>

<row>

<entry><p>Touch down on a multiple mode button</p></entry>

<entry><p>Button is pressed.</p></entry>

<entry><p>Tactile: Basic button effect and audio feedback is provided with

touch down.</p></entry>

</row>

<row>

<entry><p>Touch release on a multiple mode button</p></entry>

<entry><p>Current mode’s function is executed.</p><p> User can switch between

different modes by touching the multiple mode button again. State changes

after touch release and current mode’s functions are executed. Button states

loop when the user touches those again.</p></entry>

<entry><p>Tactile: Basic button effect given with touch release. No audio

feedback given.</p></entry>

</row>

<row>

<entry><p>Touch down and hold (also known as long tap)</p></entry>

<entry><p>Activates the button functionality, assigned for the touch down

and hold event. </p><p>Application specific</p></entry>

<entry><p>Tactile: Basic button effect and audio feedback is provided with

touch down event.</p></entry>

</row>

<row>

<entry><p>Touch down and hold (also known as key repeat</p></entry>

<entry><p>May or may not have key repeat functionality</p><p>Application specific</p></entry>

<entry><p>Tactile: Basic button effect is provide with touch down. In case

of key repeat, sensitive button effect is provided.</p></entry>

</row>

<row>

<entry><p>Touch down and move out from the button and releasing</p></entry>

<entry><p>If the drag moves outside the container, button functionality is

canceled with release event.</p></entry>

<entry><p>Tactile: Basic button effect and audio feedback with touch down

is provided. No feedback with release.</p></entry>

</row>

<row>

<entry><p>Touch down and move out from the button and then back before up

event</p></entry>

<entry><p>As in touch down and release.</p></entry>

<entry><p>Tactile: Basic button effect and audio feedback is provided with

touch down. If release activates a function, then basic button effect is also

provided with touch release. No audio feedback with touch release.</p></entry>

</row>

<row>

<entry><p>Touch down and move out from a button to another button and then

releasing</p></entry>

<entry><p>If the drag goes outside the container, button functionality is

canceled with release event and does not activate the other button.</p></entry>

<entry><p>Tactile: Basic button effect and audio feedback with touch down.

No feedback with release.</p></entry>

</row>

</tbody>

</tgroup>

</table>

<section id="GUID-6A8BFD02-3F77-4C95-BFC4-180D2DD211EF"><title>Using generic

buttons in C++ applications</title>The API to use for creating the generic

button component is the <xref href="GUID-F3EE1000-71A6-4D48-A30B-3D2357BF20FB.dita">Generic

Button API</xref>. </section>

</conbody></concept>