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-8661A7E0-F19A-41F8-9062-FBFAE70CF658" xml:lang="en"><title>Tactile

    10 feedback client API</title><shortdesc>The Tactile feedback client API is used for producing tactile feedback

    11 for different touch events.</shortdesc><prolog><metadata><keywords></keywords></metadata></prolog><conbody>

    12 <p>The Tactile feedback client API is a library API that has been implemented

    13 with a client-server technique. A major part of the processing is done on

    14 the client side, and thus API calls don't necessarily generate a client-server

    15 transaction immediately. Instead for e.g. changes to area registry are buffered,

    16 and then transferred to server-side at once.</p>

    17 <p>You can use tactile feedback in, for example, the following cases:</p>

    18 <ul>

    19 <li>When the user starts to scroll with the scroll bar, user can feel and/or

    20 hear when the scroll bar thumb has been caught.</li>

    21 <li>When button is pressed, user can feel and/or hear the button being pressed.</li>

    22 </ul>

    23 <p>The concept of logical feedback type is very important from this API's

    24 point of view. </p>

    25 <p>In practice it means that, for example, you should not try to use this

    26 API for producing vibrator feedback only. Instead, logical feedback types

    27 such as "basic" or "sensitive" are used on this level, and the actual physical

    28 effect then depends on the settings and device configuration. This way the

    29 feedback works in a unified way from the end user point of view in the whole

    30 device.</p>

    31 <section id="GUID-44CAF194-6B6A-4661-AB29-88BF700BBC60"><p>For user experience guidelines on tactile feedback, see <xref href="GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita">Tactile feedback</xref>.</p><p>For

    32 information on using the API, see <xref href="GUID-786D76B7-B827-43B7-8202-BA7A7E5EE03E.dita">Providing

    33 tactile feedback for touch events</xref>.</p><p>For the Tactile feedback client

    34 API classes and header files, see Classes

    35 and Definitions.</p></section>

    36 <section id="GUID-E44747A5-92BF-4D7A-895C-C469112A4D32"><title>API class structure</title><p>All functionality of the Tactile

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

    38 <section id="GUID-0D0648C0-5AAE-48C1-82BD-025D6908E3B1"><title>Constraints</title><p>This API is valid for all platforms

    39 running on Symbian OS 9.4 or later.</p></section>

    40 <section id="GUID-E8D3D7BC-F365-45D7-A4AE-4393CF1B6795"><title>Error handling</title><p>The leave mechanism of Symbian environment is used to handle memory exhaustion. The panic mechanism is not

    41 used.</p> <p>The table below presents possible error conditions and responses

    42 to them.</p> <table id="GUID-E9186B9F-2C9B-4C09-B054-69D093BBE41D"><title>Possible

    43 error situations when using Tactile Feedback Client API</title>

    44 <tgroup cols="2"><colspec colname="col1"></colspec><colspec colname="col2"></colspec>

    45 <thead>

    46 <row>

    47 <entry>Error situation</entry>

    48 <entry>Response</entry>

    49 </row>

    50 </thead>

    51 <tbody>

    52 <row>

    53 <entry><codeph>SetFeedbackArea</codeph> returns <codeph>KErrNoMemory</codeph> in

    54 case of an OOM situation.</entry>

    55 <entry>This error can usually be ignored by the application.</entry>

    56 </row>

    57 <row>

    58 <entry><codeph>SetFeedbackArea</codeph> returns <codeph>KErrArgument</codeph></entry>

    59 <entry>The given <codeph>CCoeControl</codeph> pointer is a <codeph>NULL</codeph> pointer

    60 or the control does not have any window associated with it (i.e., the feedback

    61 area setting is attempted before <codeph>SetContainerWindow</codeph> has been

    62 called on the control).</entry>

    63 </row>

    64 <row>

    65 <entry><codeph>SetFeedbackArea</codeph> returns <codeph>KErrNotSupported</codeph>.</entry>

    66 <entry>The given logical feedback type or triggering event type is out of

    67 range.</entry>

    68 </row>

    69 <row>

    70 <entry>A tactile feedback enabled control is moved with <codeph>CCoeControl::SetPosition</codeph>,

    71 but the feedback area is not moved.</entry>

    72 <entry>The control must override the <codeph>CCoeControl::PositionChanged</codeph> function,

    73 and update the feedback area there the same way as in the <codeph>SizeChanged</codeph> function.</entry>

    74 </row>

    75 <row>

    76 <entry>Area registry updates not are effective fast enough. This might happen

    77 in some applications which use very many frequently running active objects,

    78 so that the <codeph>CIdle</codeph> object used by the implementation of this

    79 API gets no change to run.</entry>

    80 <entry>Use the <codeph>FlushRegistryUpdates</codeph> function for forcing

    81 an update to the server side after doing all updates on the client side.</entry>

    82 </row>

    83 <row>

    84 <entry>A control's feedback areas are not automatically disabled when the

    85 control is dimmed.</entry>

    86 <entry><codeph>CCoeControl::SetMopParent</codeph> has not been called on the

    87 control, and thus the object provider hierarchy is broken.</entry>

    88 </row>

    89 </tbody>

    90 </tgroup>

    91 </table></section>

    92 <section id="GUID-2190CCB3-0569-4A43-A300-BBE83AAD64B6"><title>Memory overhead</title><p>Using direct feedback does not cause

    93 additional memory overhead.</p> <p>Area registry based feedback consumes approximately

    94 32 bytes for each feedback area.</p></section>

    95 <section id="GUID-F903AC63-2526-4767-B326-56D43344B23B"><title>Extensions to the API</title><p>New logical feedback types

    96 can be added in later releases. Otherwise the Tactile feedback client API

    97 does not explicitly support any kinds of extensions to it.</p></section>

    98 </conbody></concept>