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-786D76B7-B827-43B7-8202-BA7A7E5EE03E" xml:lang="en"><title>Providing

    10 tactile feedback for touch events</title><prolog><metadata><keywords></keywords></metadata></prolog><conbody>

    11 <p>The Tactile feedback client API provides area registry based feedback and

    12 direct feedback to Symbian applications and UI components. You

    13 can use the API to add, modify and remove feedback areas, trigger direct feedback

    14 and disable feedback for certain UI components or the whole application. </p>

    15 <section id="GUID-F1980AF1-191A-4D61-AAA9-EF76BA173C5D"><p>To provide tactile

    16 feedback using the using the Tactile feedback client API, follow the steps

    17 below:</p><ol>

    18 <li id="GUID-5FA4DF79-88DD-43DA-B666-D3FC398C73B4">Include the Tactile Feedback

    19 Client library <codeph>touchfeedback.lib</codeph> in your <codeph>.mmp</codeph> file.</li>

    20 <li id="GUID-7FA6526A-0D2C-4F2A-A2ED-67291FA1AD31"><p>Include the header files touchfeedback.h and touchlogicalfeedback.h.</p></li>

    21 <li id="GUID-A508E628-FEBF-4BDC-B235-731948C11BF6">Use the <codeph>MTouchFeedback::Instance</codeph> function

    22 for acquiring a pointer to the interface.</li>

    23 <li id="GUID-23CB9F1A-9090-4B2D-8531-1BFFD7A963F6">Set feedback areas for

    24 your UI controls using the <codeph>SizeChanged</codeph> function (or in another

    25 approriate place).</li>

    26 <li id="GUID-86AF1A90-69BC-42E3-AAFE-74E23C8A427E">Update the feedback areas

    27 using the <codeph>PositionChanged</codeph> function (for non-window-owning

    28 controls).</li>

    29 <li id="GUID-4F098AAF-1E71-4334-8D94-732CCE25A7DA">Call <codeph>RemoveFeedbackForControl</codeph> in

    30 your control's destructor.</li>

    31 <li id="GUID-E6F49D08-5F41-4638-91EE-526E67E15FE6">If you want to use direct

    32 feedback, trigger it in the <codeph>HandlePointerEventL</codeph> function

    33 with a call to <codeph>InstantFeedback</codeph>.</li>

    34 </ol></section>

    35 <section id="GUID-158ECB24-37E7-48DE-80F4-9606AC58F183"><title>Use cases</title><fig id="GUID-B8FF99CA-CC09-4B25-BEB6-0DA7053D1B7F">

    36 <title>Tactile feedback client API use cases</title>

    37 <image href="GUID-7E8C363C-5908-445D-8595-D53F217186ED_d0e51370_href.png" scale="90" placement="inline"></image>

    38 </fig><p>To provide tactile feedback for touch events in your applications,

    39 implement the following use cases:</p><ul>

    40 <li><p><xref href="GUID-27897E0D-D9D6-4007-A45E-62C366F1267C.dita">Using direct

    41 feedback</xref></p><ul>

    42 <li>Feedback effect is played according to given logical feedback type.</li>

    43 </ul></li>

    44 <li><p><xref href="GUID-10A03A8E-E967-4F9C-B911-2F06031C6ADC.dita">Using area registry

    45 based feedback</xref></p><ul>

    46 <li><p>Set feedback area</p><ul>

    47 <li>New feedback area is added to area registry.</li>

    48 <li>Can also be used for modifying existing feedback area.</li>

    49 </ul></li>

    50 <li><p>Change feedback area</p><ul>

    51 <li>Change feedback area coordinates, or feedback type for a given area.</li>

    52 </ul></li>

    53 <li><p>Remove feedback area</p><ul>

    54 <li>Given feedback area is removed from the registry</li>

    55 </ul></li>

    56 </ul> </li>

    57 <li><p><xref href="GUID-129FCE62-5498-4717-864B-7DC6A5C5944D.dita">Removing feedback

    58 from a control</xref></p><ul>

    59 <li>All feedback areas belonging to given control are removed from registry.</li>

    60 <li>All cached information about the control is also removed.</li>

    61 </ul></li>

    62 </ul><p>The following use cases are optional, allowing you to use additional

    63 tactile feedback features:</p> <ul>

    64 <li><p><xref href="GUID-842D8557-076B-4A6E-B823-81164368FD86.dita">Disabling and

    65 enabling feedback</xref></p><ul>

    66 <li><p>Enable or disable feedback for you application</p><ul>

    67 <li>Disable feedback for this application at run-time.</li>

    68 <li>Enable feedback for this application at run-time.</li>

    69 <li>Query whether feedback is currently enabled for this application.</li>

    70 <li>Enable only audio- or vibra feedback for this application at run-time.</li>

    71 </ul></li>

    72 <li><p>Enable or disable feedback for a control</p><ul>

    73 <li>Temporarily disable feedback for given control.</li>

    74 <li>Re-enable feedback for given control.</li>

    75 <li>Temporarily enable only audio or vibra feedback.</li>

    76 </ul></li>

    77 </ul></li>

    78 <li><p><xref href="GUID-BF6ECC83-C7A0-4183-B835-6299CC2114AF.dita">Querying if

    79 feedback is supported</xref></p><ul>

    80 <li>Check if tactile feedback is supported in this device.</li>

    81 </ul></li>

    82 <li><p><xref href="GUID-D3F52BB9-7230-499C-9BB7-CFAEDBA8F48B.dita">Managing feedback

    83 areas</xref></p><ul>

    84 <li> You can sort feedback areas for achieving desired functionality in case

    85 of overlapping areas.</li>

    86 </ul></li>

    87 <li><p><xref href="GUID-2BF409EA-82BF-407C-B048-DA0973B7F61D.dita">Optimizing feedback

    88 latency</xref></p></li>

    89 </ul> </section>

    90 <section id="GUID-0F6F2C15-23C0-47A7-916C-15C92DDED877"><p>For an overview

    91 of using tactile feedback in your application, see <xref href="GUID-2632A013-AA87-485E-855D-C50E211057D6.dita">Tactile

    92 feedback implementation example</xref>.</p></section>

    93 <section id="GUID-03DB8FD1-D1FE-434E-B15F-D4B5DD80926B"><title>Main implementation

    94 files</title><p>The implementation files for the Tactile feedback client API

    95 are touchfeedback.h and touchlogicalfeedback.h.</p></section>

    96 </conbody></concept>