<?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></keywords></metadata></prolog><conbody>

<p>There are two types of cases where vibration or audio of the

device is used as an output method when the user is interacting with the device

touch screen:</p>

<ul>

<li><p>When the user has touched an active area of the screen, and an action

will be triggered on touch release</p></li>

<li><p>Interaction with given components has been successful</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 included in those common UI components, where seen

as beneficial. When new components are designed, tactile feedback is to be

included in those if seen beneficial usability-wise. For example, in any button

type of UI component the tactile feedback is natural. Application can disable

tactile feedback from the common UI components it uses, if seen necessary.

This is acceptable only in cases, where tactile feedback would cause interference,

like during a phone call or when giving audio commands to the system.</p>

<p>The user can choose whether tactile feedback is on or off.</p>

<section id="GUID-6F2398F3-DA71-4330-A63A-15F02D7533DF"><title>Characteristics

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

haptic effects:</p><ul>

<li><p>Tactile

Feedback Client API</p><ul>

<li><p>available from S60 5.0 onwards</p></li>

<li><p>can be used on all S60 5.0 or later mobile devices but the feedback

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

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

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

<li><p>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 the smallest for the feedback

triggering (tactile feedback can be triggered at the window server level before

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

<li><p>direct feedback is easy to integrate into <codeph>HandlePointerEventL</codeph> code </p></li>

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

types and the produced effect may be different on various mobile devices</p></li>

</ul></li>

<li><p>Vibra

API</p><ul>

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

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

period of time</p></li>

<li><p>a privileged client application can use this for playing pulse effects

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

</ul></li>

</ul></section>

<section id="GUID-8D08AB75-2E24-44B6-88B6-4AE1CEBD70F7"><title>When to use

Tactile Feedback Client API and Vibra API</title><p>You should use<ul>

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

controls (grids, lists, etc.) which comply with the style of the Core UI components

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

<li><p>Vibra API to produce haptic effects such as ringing tone vibration</p></li>

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

<section id="GUID-4003A7DC-0208-4436-B9A1-688D57149F6A"><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 be disabled in a client

application or a mobile device in some situations, 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><colspec colname="col2"></colspec>

<tbody>

<row>

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

<entry><p>Use for disabling feedback for some areas of the application window

when using the area registry.</p></entry>

</row>

<row>

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

<entry><p>Use as default feedback for stylus 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>Sensitive feedback for situations where the triggering action is

not very  important (e.g. change of focus in a list), or when there can be

a large number of feedback instances within a short time (e.g. text selection

which gives feedback on every new selected character). 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>Using tactile feedback does not require additional platform

security capabilities for your application.</p></note></section>

</conbody></concept>