|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"><concept id="GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF" xml:lang="en"><title>Tactile |
|
10 feedback</title><prolog><metadata><keywords></keywords></metadata></prolog><conbody> |
|
11 <p>There are two types of cases where vibration or audio of the |
|
12 device is used as an output method when the user is interacting with the device |
|
13 touch screen:</p> |
|
14 <ul> |
|
15 <li><p>When the user has touched an active area of the screen, and an action |
|
16 will be triggered on touch release</p></li> |
|
17 <li><p>Interaction with given components has been successful</p></li> |
|
18 </ul> |
|
19 <p>As with sounds, tactile feedback must be used carefully so as not to desensitize |
|
20 the user to the vibration: the attention grabbing quality remains and functions |
|
21 so long as the feedback is not too frequent.</p> |
|
22 <p>Tactile feedback is included in those common UI components, where seen |
|
23 as beneficial. When new components are designed, tactile feedback is to be |
|
24 included in those if seen beneficial usability-wise. For example, in any button |
|
25 type of UI component the tactile feedback is natural. Application can disable |
|
26 tactile feedback from the common UI components it uses, if seen necessary. |
|
27 This is acceptable only in cases, where tactile feedback would cause interference, |
|
28 like during a phone call or when giving audio commands to the system.</p> |
|
29 <p>The user can choose whether tactile feedback is on or off.</p> |
|
30 <section id="GUID-6F2398F3-DA71-4330-A63A-15F02D7533DF"><title>Characteristics |
|
31 of haptics related APIs</title><p>You can use the following APIs to create |
|
32 haptic effects:</p><ul> |
|
33 <li><p>Tactile |
|
34 Feedback Client API</p><ul> |
|
35 <li><p>available from S60 5.0 onwards</p></li> |
|
36 <li><p>can be used on all S60 5.0 or later mobile devices but the feedback |
|
37 is played only on touch enabled layouts</p></li> |
|
38 <li><p>provides simple functions for triggering various predefined tactile |
|
39 feedback (vibration or audio) effects</p></li> |
|
40 <li><p>enables a consistent user experience in all applications of the mobile |
|
41 device (an application gives a logical feedback type as an input and the actual |
|
42 physical effect depends on the mobile device configuration and end user settings)</p></li> |
|
43 <li><p>when the area feedback is used, latency is the smallest for the feedback |
|
44 triggering (tactile feedback can be triggered at the window server level before |
|
45 the corresponding pointer event is delivered to the visible application)</p></li> |
|
46 <li><p>direct feedback is easy to integrate into <codeph>HandlePointerEventL</codeph> code </p></li> |
|
47 <li><p>an application can select the logical tactile feedback from certain |
|
48 types and the produced effect may be different on various mobile devices</p></li> |
|
49 </ul></li> |
|
50 <li><p>Vibra |
|
51 API</p><ul> |
|
52 <li><p>available from S60 3.0 onwards</p></li> |
|
53 <li><p>can be used for running device vibrator with given intensity for given |
|
54 period of time</p></li> |
|
55 <li><p>a privileged client application can use this for playing pulse effects |
|
56 which have a really short duration (as the ones used for tactile feedback)</p></li> |
|
57 </ul></li> |
|
58 </ul></section> |
|
59 <section id="GUID-8D08AB75-2E24-44B6-88B6-4AE1CEBD70F7"><title>When to use |
|
60 Tactile Feedback Client API and Vibra API</title><p>You should use<ul> |
|
61 <li><p>Tactile Feedback Client API for providing tactile feedback in custom |
|
62 controls (grids, lists, etc.) which comply with the style of the Core UI components |
|
63 to ensure a uniform user experience among applications</p></li> |
|
64 <li><p>Vibra API to produce haptic effects such as ringing tone vibration</p></li> |
|
65 </ul></p></section> |
|
66 <section id="GUID-4003A7DC-0208-4436-B9A1-688D57149F6A"><title>Using |
|
67 tactile feedback in C++ applications</title><p>The API to use for tactile |
|
68 feedback is the <xref href="GUID-8661A7E0-F19A-41F8-9062-FBFAE70CF658.dita">Tactile |
|
69 feedback client API</xref>.</p><p>The Symbian platform includes a tactile |
|
70 feedback interface to add, modify and remove feedback areas in the registry. |
|
71 There is also an option to trigger direct feedback and bypass the registry. |
|
72 <parmname>MTouchFeedback::Instance()</parmname> is used for acquiring a pointer |
|
73 to a touch feedback instance. When touch feedback is activated, the mobile |
|
74 device users get a slight vibration when the control with the feedback interface |
|
75 is touched. </p><note><p>Tactile feedback can be set be disabled in a client |
|
76 application or a mobile device in some situations, for example, during phone |
|
77 calls.</p></note><p>Client applications cannot determine the actual physical |
|
78 feedback that is generated. It depends on device configuration and current |
|
79 settings. In current devices, the user changeable settings include vibration |
|
80 and audio feedback intensity level.</p><p>In your application, you can use |
|
81 the following feedback types, defined in <codeph>TTouchLogicalFeedback</codeph>:</p><table id="GUID-6FF24F72-C352-4027-AA5D-2D34EBFA00F4"> |
|
82 <tgroup cols="2"><colspec colname="col1"></colspec><colspec colname="col2"></colspec> |
|
83 <tbody> |
|
84 <row> |
|
85 <entry><p><codeph>ETouchFeedbackNone</codeph></p></entry> |
|
86 <entry><p>Use for disabling feedback for some areas of the application window |
|
87 when using the area registry.</p></entry> |
|
88 </row> |
|
89 <row> |
|
90 <entry><p><codeph>ETouchFeedbackBasic</codeph></p></entry> |
|
91 <entry><p>Use as default feedback for stylus down events, for example, when |
|
92 the mobile device user taps a button or tab.</p></entry> |
|
93 </row> |
|
94 <row> |
|
95 <entry><p><codeph>ETouchFeedbackSensitive</codeph></p></entry> |
|
96 <entry><p>Sensitive feedback for situations where the triggering action is |
|
97 not very important (e.g. change of focus in a list), or when there can be |
|
98 a large number of feedback instances within a short time (e.g. text selection |
|
99 which gives feedback on every new selected character). Also used for scrolling |
|
100 and dragging.</p></entry> |
|
101 </row> |
|
102 </tbody> |
|
103 </tgroup> |
|
104 </table><p>To use vibration or audio feedback in your application:</p><ol> |
|
105 <li id="GUID-791E80D6-6935-4202-81E0-BA7392A9E1B3"><p>Include <codeph>touchfeedback.lib</codeph> in |
|
106 your <codeph>.mmp</codeph> file.</p></li> |
|
107 <li id="GUID-A185188F-F37B-440B-8213-214D77CF3B8B"><p>Include <parmname>touchfeedback.h</parmname>.</p></li> |
|
108 <li id="GUID-6455F4C1-AEA6-4C30-8E9B-DF9950558E17"><itemgroup><p>To enable |
|
109 tactile feedback for your application, add the following code.</p><codeblock xml:space="preserve">MTouchFeedback* feedback = MTouchFeedback::Instance(); |
|
110 feedback->SetFeedbackEnabledForThisApp(ETrue); // enabling feedback is optional </codeblock><p>Do |
|
111 not delete the pointer in the controller destructor.</p></itemgroup></li> |
|
112 <li id="GUID-FC1B810B-99F4-44E5-82DC-46686D6D4198"><itemgroup><p>To use tactile |
|
113 feedback when a mobile device user points at a control, add the following |
|
114 code.</p><codeblock xml:space="preserve">void CMyContainerControl::HandlePointerEventL(const TPointerEvent& aPointerEvent) |
|
115 { |
|
116 // Feedback is always played at pointer down event |
|
117 if(aPointerEvent.iType == TPointerEvent::EButton1Down) |
|
118 { |
|
119 MTouchFeedback* feedback = MTouchFeedback::Instance(); |
|
120 if (feedback) |
|
121 { |
|
122 feedback->InstantFeedback(ETouchFeedbackBasic); |
|
123 } |
|
124 } |
|
125 |
|
126 // Your other pointer event handling code here |
|
127 </codeblock></itemgroup></li> |
|
128 <li id="GUID-A26D8717-1839-4132-98C4-5C09086BB361"><itemgroup><p>To enable |
|
129 automatic feedback triggering in a specific area of a UI component, add</p><codeblock xml:space="preserve">feedback->SetFeedbackArea(this, |
|
130 1, // area Id |
|
131 TRect(0,0,20,20), |
|
132 ETouchFeedbackBasic, |
|
133 ETouchEventStylusDown); |
|
134 </codeblock></itemgroup></li> |
|
135 </ol><note><p>Using tactile feedback does not require additional platform |
|
136 security capabilities for your application.</p></note></section> |
|
137 </conbody></concept> |