<?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>