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