<?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-10A03A8E-E967-4F9C-B911-2F06031C6ADC" xml:lang="en"><title>Using
area registry based feedback</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>To use area registry based feedback, you must usually first call <codeph>MTouchFeedback::Instance</codeph> (unless
you get a reference to it via another class).</p>
<p>It is recommended that you store the returned pointer as a member variable
in those places where it is needed frequently. This is because the pointer
is fetched from thread local storage, which can be somewhat time-consuming. </p>
<p>To add feedback areas to the area registry, use the <codeph>SetFeedbackArea</codeph> function.
Usually the best place to do this is <codeph>SizeChanged</codeph> function,
because that is also the place to update feedback areas in case of a layout
change.</p>
<note><p>You can also use the same <codeph>SetFeedbackArea</codeph> function
for updating the feedback area (the API implementation adds the area to the
registry on the first time, and then just does updates on subsequent calls
to this function). </p></note>
<p>If you want to change the feedback area or type without giving all the
parameters again, use the functions <codeph>ChangeFeedbackArea</codeph> and <codeph>ChangeFeedbackType</codeph> for
the updates. </p>
<p>Also notice that you have to be prepared in case your control is moved
with <codeph>CCoeControl::SetPosition</codeph> function. For this you need
to override <codeph>CCoeControl::PositionChanged</codeph>, and update the
feedback area there the same way as in the <codeph>SizeChanged</codeph> function.
Moreover, notice that this is necessary only for those non-window-owning controls,
which produce area registry based feedback. </p>
<p>Feedback areas of a specific control will be automatically disabled in
case the control becomes dimmed by <codeph>CCoeControl::SetDimmed( ETrue )</codeph> or
invisible by <codeph>CCoeControl::MakeVisible( EFalse )</codeph>. Feedback
will be re-enabled again when control becomes both undimmed and visible. This
functionality is based on using the object provider hierarchy, and thus it
does not work in case the object provider parent has not been set for the
control.</p>
<p> If you need to disable a control’s feedback area temporarily (for other
reasons than dimming or visibility), call <codeph>EnableFeedbackForControl</codeph> with
second parameter <codeph>EFalse</codeph> to disable the feedback. You can
then re-enable feedback by calling <codeph>EnableFeedbackForControl</codeph> with
second parameter <codeph>ETrue</codeph>. Disabling of control’s feedback also
affects direct feedback if it is generated with the overloaded version, which
takes the control’s pointer as the second parameter. </p>
<p>In some special cases it may be necessary to only disable audio- or vibra
feedback for some controls. For this purpose there is a specific overload
of <codeph>EnableFeedbackForControl</codeph> function.</p>
<p>You must remove your control's feedback areas at the latest when you destroy
the control. To do this, call the function <codeph>RemoveFeedbackForControl</codeph> .
This also resets the feedback disabling information for the deleted control.
If needed, you can remove individual feedback areas with the <codeph>RemoveFeedbackArea</codeph> function
any time, but you must still call <codeph>RemoveFeedbackForControl</codeph> you
destroy the control.</p>
<p>The example below illustrates using tactile feedback based on the area
registry. </p>
<ol>
<li id="GUID-95E49C03-19A2-4E39-BBDE-A907EAC87D3A"><p>Add the library <codeph>touchfeedback.lib</codeph> into
your<codeph> .mmp</codeph> file, and then add the following include to your <codeph>.cpp</codeph> file: </p><codeblock xml:space="preserve">#include &lt;touchfeedback.h&gt;</codeblock></li>
<li id="GUID-0E48DB87-9B6B-4E4A-A18D-62CBCD755949"><p>Update the area registry
in the <codeph>SizeChanged</codeph> function. </p><note><p>You don’t need
to check if you have already the area added to the registry or not, because
you can use the <codeph>SetFeedbackArea</codeph> function anyway. (On the
first time this function adds area to the registry, and on the second it updates
the area.) </p></note><codeblock xml:space="preserve">MTouchFeedback* feedback = MTouchFeedback::Instance();

if ( feedback )
    {
    feedback-&gt;SetFeedbackArea( 
        this,
        0, 
        Rect(), 
        ETouchFeedbackBasic,
        ETouchEventStylusDown );
    }
</codeblock><p>The second parameter given to the <codeph>SetFeedbackArea</codeph> function
is an index number, which is used to distinguish the feedback areas of same
control from each other (in case the control has many feedback areas). You
can choose the index numbers freely. It is recommended that you always use
zero as the index if your control only has one feedback area.</p></li>
</ol>
</conbody></concept>