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