Symbian3/PDK/Source/GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita
changeset 1 25a17d01db0c
child 5 f345bda72bc4
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita	Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,137 @@
+<?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-&gt;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>
\ No newline at end of file