|
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 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-8661A7E0-F19A-41F8-9062-FBFAE70CF658" xml:lang="en"><title>Tactile |
|
13 feedback client API</title><shortdesc>The Tactile feedback client API is used for producing tactile feedback |
|
14 for different touch events.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>The Tactile feedback client API is a library API that has been implemented |
|
16 with a client-server technique. A major part of the processing is done on |
|
17 the client side, and thus API calls don't necessarily generate a client-server |
|
18 transaction immediately. Instead for example, changes to area registry are |
|
19 buffered, and then transferred to server-side at once.</p> |
|
20 <p>You can use tactile feedback in, for example, the following cases:</p> |
|
21 <ul> |
|
22 <li>When the user starts to scroll with the scroll bar, user can feel and/or |
|
23 hear when the scroll bar thumb has been caught.</li> |
|
24 <li>When button is pressed, user can feel and/or hear the button being pressed.</li> |
|
25 </ul> |
|
26 <p>The concept of logical feedback type is very important from this API's |
|
27 point of view. </p> |
|
28 <p>In practice it means that, for example, you should not try to use this |
|
29 API for producing vibrator feedback only. Instead, logical feedback types |
|
30 such as "basic" or "sensitive" are used on this level, and the actual physical |
|
31 effect then depends on the settings and device configuration. This way the |
|
32 feedback works in a unified way from the end user point of view in the whole |
|
33 device.</p> |
|
34 <section id="GUID-44CAF194-6B6A-4661-AB29-88BF700BBC60"><p>For user experience |
|
35 guidelines on tactile feedback, see <xref href="GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita">Tactile |
|
36 feedback</xref>.</p><p>For information on using the API, see <xref href="GUID-786D76B7-B827-43B7-8202-BA7A7E5EE03E.dita">Providing |
|
37 tactile feedback for touch events</xref>.</p><p>For the Tactile feedback client |
|
38 API classes and header files, see Classes and Definitions.</p></section> |
|
39 <section id="GUID-E44747A5-92BF-4D7A-895C-C469112A4D32"><title>API class structure</title><p>All |
|
40 functionality of the Tactile feedback client API is provided in the class <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classMTouchFeedback.html" format="application/java-archive"><codeph>MTouchFeedback</codeph></xref>.</p></section> |
|
41 <section id="GUID-0D0648C0-5AAE-48C1-82BD-025D6908E3B1"><title>Constraints</title><p>This |
|
42 API is valid for all platforms running on Symbian OS v9.4 or later.</p></section> |
|
43 <section id="GUID-E8D3D7BC-F365-45D7-A4AE-4393CF1B6795"><title>Error handling</title><p>The |
|
44 leave mechanism of Symbian environment is used to handle memory exhaustion. |
|
45 The panic mechanism is not used.</p> <p>The table below presents possible |
|
46 error conditions and responses to them.</p> <table id="GUID-E9186B9F-2C9B-4C09-B054-69D093BBE41D"> |
|
47 <title>Possible error situations when using Tactile Feedback Client API</title> |
|
48 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
49 <thead> |
|
50 <row> |
|
51 <entry>Error situation</entry> |
|
52 <entry>Response</entry> |
|
53 </row> |
|
54 </thead> |
|
55 <tbody> |
|
56 <row> |
|
57 <entry><codeph>SetFeedbackArea</codeph> returns <codeph>KErrNoMemory</codeph> in |
|
58 case of an OOM situation.</entry> |
|
59 <entry>This error can usually be ignored by the application.</entry> |
|
60 </row> |
|
61 <row> |
|
62 <entry><codeph>SetFeedbackArea</codeph> returns <codeph>KErrArgument</codeph></entry> |
|
63 <entry>The given <codeph>CCoeControl</codeph> pointer is a <codeph>NULL</codeph> pointer |
|
64 or the control does not have any window associated with it (the feedback area |
|
65 setting is attempted before <codeph>SetContainerWindow</codeph> has been called |
|
66 on the control).</entry> |
|
67 </row> |
|
68 <row> |
|
69 <entry><codeph>SetFeedbackArea</codeph> returns <codeph>KErrNotSupported</codeph>.</entry> |
|
70 <entry>The given logical feedback type or triggering event type is out of |
|
71 range.</entry> |
|
72 </row> |
|
73 <row> |
|
74 <entry>A tactile feedback enabled control is moved with <codeph>CCoeControl::SetPosition</codeph>, |
|
75 but the feedback area is not moved.</entry> |
|
76 <entry>The control must override the <codeph>CCoeControl::PositionChanged</codeph> function, |
|
77 and update the feedback area there the same way as in the <codeph>SizeChanged</codeph> function.</entry> |
|
78 </row> |
|
79 <row> |
|
80 <entry>Area registry updates not are effective fast enough. This might happen |
|
81 in some applications which use very many frequently running active objects, |
|
82 so that the <codeph>CIdle</codeph> object used by the implementation of this |
|
83 API gets no change to run.</entry> |
|
84 <entry>Use the <codeph>FlushRegistryUpdates</codeph> function for forcing |
|
85 an update to the server side after doing all updates on the client side.</entry> |
|
86 </row> |
|
87 <row> |
|
88 <entry>A control's feedback areas are not automatically disabled when the |
|
89 control is dimmed.</entry> |
|
90 <entry><codeph>CCoeControl::SetMopParent</codeph> has not been called on the |
|
91 control, and thus the object provider hierarchy is broken.</entry> |
|
92 </row> |
|
93 </tbody> |
|
94 </tgroup> |
|
95 </table></section> |
|
96 <section id="GUID-2190CCB3-0569-4A43-A300-BBE83AAD64B6"><title>Memory overhead</title><p>Using |
|
97 direct feedback does not cause additional memory overhead.</p> <p>Area registry |
|
98 based feedback consumes approximately 32 bytes for each feedback area.</p></section> |
|
99 <section id="GUID-F903AC63-2526-4767-B326-56D43344B23B"><title>Extensions |
|
100 to the API</title><p>New logical feedback types can be added in later releases. |
|
101 Otherwise the Tactile feedback client API does not explicitly support any |
|
102 kinds of extensions to it.</p></section> |
|
103 </conbody></concept> |