<?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-581A8E4B-12BE-41C0-A20E-3087A80FEECF" xml:lang="en"><title>Tactile

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

<p>There are two methods where vibration or audio of the device is used as

an output method (when mobile device users interact with the device touch

screen):</p>

<ul>

<li><p>As a <i>tacticon</i> to inform users through physical feedback, that

an important event is occurring in the device. For example, when a new message

arrives or a warning note is displayed.</p></li>

<li><p>As <i>tactile feedback</i> to indicate to the user that an interaction

event has been successful. For example, users receive tactile feedback when

they press a button on the touch screen.</p></li>

</ul>

<p>As with sounds, tactile feedback must be used carefully so as not to desensitize

the user to the vibration; the attention grabbing quality remains and functions

so long as the feedback is not too frequent.</p>

<p>Tactile feedback is enabled for all the Symbian platform UI components.

Tactile feedback can be disabled for the common UI components in an application.

However, this is acceptable only if tactile feedback causes interference with

other device functions.</p>

<p>The user can choose the level of tactile feedback and turn tacticons ON

and OFF.</p>

<p>The following table lists the tactile feedback effects:</p>

<p><table id="GUID-4969AEA7-3BE4-4644-8232-1FA26D49010B"><title>Tactile feedback

effects</title>

<tgroup cols="2"><colspec colname="col1" colwidth="0.40*"/><colspec colname="col2" colwidth="1.60*"/>

<thead>

<row>

<entry valign="top"><p>Effects</p></entry>

<entry valign="top"><p>Description</p></entry>

</row>

</thead>

<tbody>

<row>

<entry><p><b>Sensitive button</b></p></entry>

<entry><p>It provides single pulse effect on repeated key presses with buttons.

It is also possible with other similar components.</p></entry>

</row>

<row>

<entry><p><b>Basic button</b></p></entry>

<entry><p>It provides stronger single pulse effect to buttons. It is also

possible with other similar components.</p></entry>

</row>

<row>

<entry><p><b>Sensitive list</b></p></entry>

<entry><p>It provides single pulse effect to lists and grids. Effect is used

with move (drag and flick) when new item appears on the screen.</p></entry>

</row>

<row>

<entry><p><b>Basic list</b></p></entry>

<entry><p>It provides stronger single pulse effect to lists and grids. Effect

is used with touch down and release when tap makes an action. </p><p>In hierarchical

list, collapsing/expanding item provides basic list effect with touch down

and release.</p></entry>

</row>

<row>

<entry><p><b>Bounce effect</b></p></entry>

<entry><p>It provides pulse effect when list returns to its normal state after

boundary effect.</p></entry>

</row>

<row>

<entry><p><b>Sensitive slider</b></p></entry>

<entry><p>It provides pulse effect with scrollbar and slider thumbs. Effect

is provided with touch down and release in thumb area.</p></entry>

</row>

<row>

<entry><p><b>Smooth slider</b></p></entry>

<entry><p>It provides continuous smooth feedback when dragging scrollbar or

slider thumb. This can also be increasing or decreasing depending of the slider

type.</p></entry>

</row>

<row>

<entry><p><b>Hold slider</b></p></entry>

<entry><p>It provides sensitive pulse effect when touch down and hold on the

slider or scrollbar area. Slider thumb starts moving step by step towards

the touch point. Every step gives one sensitive pulse. If slider thumb moves

directly to the touch point, then basic slider effect is provided.</p></entry>

</row>

<row>

<entry><p><b>Pop-up</b></p></entry>

<entry><p>It provides sensitive pulse effect when pop-up is opened or closed.

If the theme animations are ON, then pop-up effect is used with opening event

after increasing long touch effect. In this scenario, there is no pop-up effect

while closing. <note> All pop-ups does not have theme animation.</note></p></entry>

</row>

<row>

<entry><p><b>Pop-up close</b></p></entry>

<entry><p>It provides decreasing smooth feedback while closing pop-up and

when theme animations are ON.</p></entry>

</row>

<row>

<entry><p><b>Increasing long touch</b></p></entry>

<entry><p>It provides increasing smooth feedback. This can be used with either

long tap animation or pop-up opening theme effects. If the theme effects are

ON and long tap opens a pop-up, then feedback is provided only with long tap.

This is followed by pop-up.</p></entry>

</row>

<row>

<entry><p><b>Basic tab</b></p></entry>

<entry><p>It provides strong pulse effect with touch down event in tab area.</p></entry>

</row>

<row>

<entry><p><b>Smooth flick</b></p></entry>

<entry><p>It provides smooth feedback with drag when horizontal movement is

possible.</p></entry>

</row>

<row>

<entry><p><b>Sensitive flick</b></p></entry>

<entry><p>It provides sensitive pulse effect with touch release when horizontal

movement is possible.</p></entry>

</row>

<row>

<entry><p><b>Sensitive edit</b></p></entry>

<entry><p>It provides sensitive pulse effect in editors with touch down and

release.</p></entry>

</row>

<row>

<entry><p><b>Text edit</b></p></entry>

<entry><p>It provides pulse effect when painting the text. Effect is provided

with every character while painting the text.</p></entry>

</row>

<row>

<entry><p><b>Blank edit</b></p></entry>

<entry><p>It provides pulse effect when painting blank character. By default,

it is none.</p></entry>

</row>

<row>

<entry><p><b>Line edit</b></p></entry>

<entry><p>It provides pulse effect when painting a line.</p></entry>

</row>

<row>

<entry><p><b>Empty line</b></p></entry>

<entry><p>It provides pulse effect when painting an empty line. By default,

it is none.</p></entry>

</row>

<row>

<entry><p><b>Check box</b></p></entry>

<entry><p>It provides pulse effect when marking/unmarking a check box.</p></entry>

</row>

<row>

<entry><p><b>Multi-touch recognition</b></p></entry>

<entry><p>It provides double pulse (sensitive + sensitive) effect when multi-touch

is recognized (generally, when second finger is touched down).</p></entry>

</row>

<row>

<entry><p><b>Smooth pinch</b></p></entry>

<entry><p>It provides smooth continuous feedback while moving fingers in multi-touch

pinch situation.</p></entry>

</row>

<row>

<entry><p><b>Smooth rotate</b></p></entry>

<entry><p>It provides smooth continuous feedback  while moving fingers in

multi-touch rotate situation.</p></entry>

</row>

</tbody>

</tgroup>

</table></p>

<section id="GUID-B9A35CA3-B830-4D97-9B0A-E22DC4A3CDA1"><title>Characteristics

of haptics related  APIs</title><p>You can use the following APIs to create

haptic effects:</p><ul>

<li><p><xref href="GUID-8661A7E0-F19A-41F8-9062-FBFAE70CF658.dita">Tactile Feedback

Client API</xref></p><ul>

<li><p>It is available from S60 5th Edition onwards</p></li>

<li><p>It can be used on all S60 5th Edition or later mobile devices. However,

the feedback is played only on touch enabled layouts.</p></li>

<li><p>It provides simple functions for triggering various predefined tactile

feedback (vibration or audio) effects.</p></li>

<li><p>It enables a consistent user experience in all applications of the

mobile device (an application gives a logical feedback type as an input and

the actual physical effect depends on the mobile device configuration and

end user settings).</p></li>

<li><p>When the area feedback is used, latency is low for the feedback triggering

(a tactile feedback can already be triggered at the window server level prior

to the corresponding pointer event being delivered to the visible application).</p></li>

<li><p>Direct feedback can be easily integrated into <codeph>CCoeControl::HandlePointerEventL()</codeph> . </p></li>

<li><p>An application can select the logical tactile feedback from certain

types. The produced effect may be different on various mobile devices.</p></li>

</ul></li>

<li><p><xref href="jar:GUID-558A5A9B-811E-4A87-B3DD-AE734C9AA966.jar!/public_specs/GuidesA/Haptics_API_Specification/Haptics_API_Specification.html" format="application/java-archive">Haptics

API</xref></p><ul>

<li><p>It is available from S60 5.2 Edition onwards.</p></li>

<li><p>It can be used in touch and hybrid mobile devices.</p></li>

<li><p>It provides an interface for accessing Haptics player that can control

different actuator types.</p></li>

<li><p>It enables producing of complex vibrator effects, such as an explosion

or machine gun effect in a game, bass boost for a music player, advanced ringing

tone vibration, and so on.</p></li>

<li><p>It enables simultaneous playing of different kinds of basis effects

and modifying them when played. </p></li>

<li><p>It allows for designing complex effects (using a separate PC application)

that can be loaded on Haptics player for playing.</p></li>

<li><p>It may require a special license key  for third-party applications

(to be set at runtime) to enable the Haptics player functionality.</p></li>

</ul></li>

<li><p><xref href="GUID-D53A00E4-CF37-5F11-8D15-C5ECCCE64597.dita">Vibra API</xref></p><ul>

<li><p>It available from S60 3.0 onwards</p></li>

<li><p>It can be used for running device vibrator with given intensity for

a given period of time</p></li>

<li><p>It can be used by a privileged client application to play pulse effects,

which have a very short duration (as the ones used for tactile feedback)</p></li>

</ul></li>

</ul></section>

<section id="GUID-428F693C-1CA8-4588-9A7D-C4265D2AED91"><title>When to use

Tactile Feedback Client API, Haptics API, and Vibra API</title><p>You must

use<ul>

<li><p>Tactile Feedback Client API for providing tactile feedback in custom

controls (grids, lists, and so on) which will comply with the style of Core

UI components to ensure a uniform user experience among applications</p></li>

<li><p>Haptics API on touch and hybrid mobile devices for producing complex

vibration feedback which cannot be achieved with Tactile Framework (games,

simulations, demos, and so on.)</p></li>

<li><p>Vibra API for producing haptic effects such as ringing tone vibration

in those mobile devices where Haptics API is not available or functional</p></li>

</ul></p></section>

<section id="GUID-8334E102-8F04-4726-9CD2-1D8004A417E1"><title>Using

tactile feedback in C++ applications</title><p>The API to use for tactile

feedback is the <xref href="GUID-8661A7E0-F19A-41F8-9062-FBFAE70CF658.dita">Tactile

feedback client API</xref>.</p><p>The Symbian platform includes a tactile

feedback interface to add, modify and remove feedback areas in the registry.

There is also an option to trigger direct feedback and bypass the registry.

 <parmname>MTouchFeedback::Instance()</parmname> is used for acquiring a pointer

to a touch feedback instance. When touch feedback is activated, the mobile

device users get a slight vibration when the control with the feedback interface

is touched. </p><note><p>Tactile feedback can be set and disabled in a client

application or a mobile device in some scenarios, for example, during phone

calls.</p></note><p>Client applications cannot determine the actual physical

feedback that is generated. It depends on device configuration and current

settings. In current devices, the user changeable settings include vibration

and audio feedback intensity level.</p><p>In your application, you can use

the following feedback types, defined in <codeph>TTouchLogicalFeedback</codeph>:</p><table id="GUID-6FF24F72-C352-4027-AA5D-2D34EBFA00F4">

<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>

<tbody>

<row>

<entry><p><codeph>ETouchFeedbackNone</codeph></p></entry>

<entry><p>It is used for disabling feedback in some areas of the application

window while using the area registry.</p></entry>

</row>

<row>

<entry><p><codeph>ETouchFeedbackBasic</codeph></p></entry>

<entry><p>It is used as a default feedback for stylus touch down events. For

example, when the mobile device user taps a button or tab.</p></entry>

</row>

<row>

<entry><p><codeph>ETouchFeedbackSensitive</codeph></p></entry>

<entry><p>It provides sensitive feedback in situations when:<ul>

<li><p>the triggering action is not very important (for example, change of

focus in a list)</p></li>

<li><p>there can be a large number of feedback instances within a short time

(for example, text selection which gives feedback on every new selected character).</p></li>

</ul> It is also used for scrolling and dragging.</p></entry>

</row>

</tbody>

</tgroup>

</table><p>To use vibration or audio feedback in your application:</p><ol>

<li id="GUID-791E80D6-6935-4202-81E0-BA7392A9E1B3"><p>Include <codeph>touchfeedback.lib</codeph> in

your <codeph>.mmp</codeph> file.</p></li>

<li id="GUID-A185188F-F37B-440B-8213-214D77CF3B8B"><p>Include <parmname>touchfeedback.h</parmname>.</p></li>

<li id="GUID-6455F4C1-AEA6-4C30-8E9B-DF9950558E17"><itemgroup><p>To enable

tactile feedback for your application, add the following code.</p><codeblock xml:space="preserve">MTouchFeedback* feedback = MTouchFeedback::Instance();

feedback-&gt;SetFeedbackEnabledForThisApp(ETrue); // enabling feedback is optional  </codeblock><p>Do

not delete the pointer in the controller destructor.</p></itemgroup></li>

<li id="GUID-FC1B810B-99F4-44E5-82DC-46686D6D4198"><itemgroup><p>To use tactile

feedback when a mobile device user points at a control, add the following

code.</p><codeblock xml:space="preserve">void CMyContainerControl::HandlePointerEventL(const TPointerEvent&amp; aPointerEvent)

    {

    // Feedback is always played at pointer down event

    if(aPointerEvent.iType == TPointerEvent::EButton1Down)

        {

        MTouchFeedback* feedback = MTouchFeedback::Instance();  

        if (feedback) 

             { 

             feedback->InstantFeedback(ETouchFeedbackBasic);  

             }  

        }

    // Your other pointer event handling code here

</codeblock></itemgroup></li>

<li id="GUID-A26D8717-1839-4132-98C4-5C09086BB361"><itemgroup><p>To enable

automatic feedback triggering in a specific area of a UI component, add</p><codeblock xml:space="preserve">feedback-&gt;SetFeedbackArea( this, 

                           1, // area Id

                           TRect( 0,0,20,20 ), 

                           ETouchFeedbackBasic, 

                           ETouchEventStylusDown );

</codeblock></itemgroup></li>

</ol><note><p>To use tactile feedback in an application, additional platform

security capabilities are not required.</p></note></section>

</conbody></concept>