|
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-786D76B7-B827-43B7-8202-BA7A7E5EE03E" xml:lang="en"><title>Providing |
|
13 tactile feedback for touch events</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The Tactile feedback client API provides area registry based feedback and |
|
15 direct feedback to Symbian applications and UI components. You can use the |
|
16 API to add, modify and remove feedback areas, trigger direct feedback and |
|
17 disable feedback for certain UI components or the whole application. </p> |
|
18 <section id="GUID-F1980AF1-191A-4D61-AAA9-EF76BA173C5D"><p>To provide tactile |
|
19 feedback using the using the Tactile feedback client API, follow the steps |
|
20 below:</p><ol> |
|
21 <li id="GUID-5FA4DF79-88DD-43DA-B666-D3FC398C73B4">Include the Tactile Feedback |
|
22 Client library <codeph>touchfeedback.lib</codeph> in your <codeph>.mmp</codeph> file.</li> |
|
23 <li id="GUID-7FA6526A-0D2C-4F2A-A2ED-67291FA1AD31"><p>Include the header files <codeph>touchfeedback.h</codeph> and <codeph>touchlogicalfeedback.h</codeph>.</p></li> |
|
24 <li id="GUID-A508E628-FEBF-4BDC-B235-731948C11BF6">Use the <codeph>MTouchFeedback::Instance</codeph> function |
|
25 for acquiring a pointer to the interface.</li> |
|
26 <li id="GUID-23CB9F1A-9090-4B2D-8531-1BFFD7A963F6">Set feedback areas for |
|
27 your UI controls using the <codeph>SizeChanged</codeph> function (or in another |
|
28 approriate place).</li> |
|
29 <li id="GUID-86AF1A90-69BC-42E3-AAFE-74E23C8A427E">Update the feedback areas |
|
30 using the <codeph>PositionChanged</codeph> function (for non-window-owning |
|
31 controls).</li> |
|
32 <li id="GUID-4F098AAF-1E71-4334-8D94-732CCE25A7DA">Call <codeph>RemoveFeedbackForControl</codeph> in |
|
33 your control's destructor.</li> |
|
34 <li id="GUID-E6F49D08-5F41-4638-91EE-526E67E15FE6">If you want to use direct |
|
35 feedback, trigger it in the <codeph>HandlePointerEventL</codeph> function |
|
36 with a call to <codeph>InstantFeedback</codeph>.</li> |
|
37 </ol></section> |
|
38 <section id="GUID-158ECB24-37E7-48DE-80F4-9606AC58F183"><title>Use cases</title><fig id="GUID-B8FF99CA-CC09-4B25-BEB6-0DA7053D1B7F"> |
|
39 <title>Tactile feedback client API use cases</title> |
|
40 <image href="GUID-7E8C363C-5908-445D-8595-D53F217186ED_d0e78726_href.png" scale="90" placement="inline"/> |
|
41 </fig><p>To provide tactile feedback for touch events in your applications, |
|
42 implement the following use cases:</p><ul> |
|
43 <li><p><xref href="GUID-27897E0D-D9D6-4007-A45E-62C366F1267C.dita">Using direct |
|
44 feedback</xref></p><ul> |
|
45 <li>Feedback effect is played according to given logical feedback type.</li> |
|
46 </ul></li> |
|
47 <li><p><xref href="GUID-10A03A8E-E967-4F9C-B911-2F06031C6ADC.dita">Using area registry |
|
48 based feedback</xref></p><ul> |
|
49 <li><p>Set feedback area</p><ul> |
|
50 <li>New feedback area is added to area registry.</li> |
|
51 <li>Can also be used for modifying existing feedback area.</li> |
|
52 </ul></li> |
|
53 <li><p>Change feedback area</p><ul> |
|
54 <li>Change feedback area coordinates, or feedback type for a given area.</li> |
|
55 </ul></li> |
|
56 <li><p>Remove feedback area</p><ul> |
|
57 <li>Given feedback area is removed from the registry</li> |
|
58 </ul></li> |
|
59 </ul> </li> |
|
60 <li><p><xref href="GUID-129FCE62-5498-4717-864B-7DC6A5C5944D.dita">Removing feedback |
|
61 from a control</xref></p><ul> |
|
62 <li>All feedback areas belonging to given control are removed from registry.</li> |
|
63 <li>All cached information about the control is also removed.</li> |
|
64 </ul></li> |
|
65 </ul><p>The following use cases are optional, allowing you to use additional |
|
66 tactile feedback features:</p> <ul> |
|
67 <li><p><xref href="GUID-842D8557-076B-4A6E-B823-81164368FD86.dita">Disabling and |
|
68 enabling feedback</xref></p><ul> |
|
69 <li><p>Enable or disable feedback for you application</p><ul> |
|
70 <li>Disable feedback for this application at run-time.</li> |
|
71 <li>Enable feedback for this application at run-time.</li> |
|
72 <li>Query whether feedback is currently enabled for this application.</li> |
|
73 <li>Enable only audio- or vibra feedback for this application at run-time.</li> |
|
74 </ul></li> |
|
75 <li><p>Enable or disable feedback for a control</p><ul> |
|
76 <li>Temporarily disable feedback for given control.</li> |
|
77 <li>Re-enable feedback for given control.</li> |
|
78 <li>Temporarily enable only audio or vibra feedback.</li> |
|
79 </ul></li> |
|
80 </ul></li> |
|
81 <li><p><xref href="GUID-BF6ECC83-C7A0-4183-B835-6299CC2114AF.dita">Querying if |
|
82 feedback is supported</xref></p><ul> |
|
83 <li>Check if tactile feedback is supported in this device.</li> |
|
84 </ul></li> |
|
85 <li><p><xref href="GUID-D3F52BB9-7230-499C-9BB7-CFAEDBA8F48B.dita">Managing feedback |
|
86 areas</xref></p><ul> |
|
87 <li> You can sort feedback areas for achieving desired functionality in case |
|
88 of overlapping areas.</li> |
|
89 </ul></li> |
|
90 <li><p><xref href="GUID-2BF409EA-82BF-407C-B048-DA0973B7F61D.dita">Optimizing feedback |
|
91 latency</xref></p></li> |
|
92 </ul> </section> |
|
93 <section id="GUID-0F6F2C15-23C0-47A7-916C-15C92DDED877"><p>For an overview |
|
94 of using tactile feedback in your application, see <xref href="GUID-2632A013-AA87-485E-855D-C50E211057D6.dita">Tactile |
|
95 feedback implementation example</xref>.</p></section> |
|
96 <section id="GUID-03DB8FD1-D1FE-434E-B15F-D4B5DD80926B"><title>Main implementation |
|
97 files</title><p>The implementation files for the Tactile feedback client API |
|
98 are <codeph>touchfeedback.h</codeph> and <codeph>touchlogicalfeedback.h</codeph>.</p></section> |
|
99 </conbody></concept> |