|
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 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-10A03A8E-E967-4F9C-B911-2F06031C6ADC" xml:lang="en"><title>Using |
|
13 area registry based feedback</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>To use area registry based feedback, you must usually first call <codeph>MTouchFeedback::Instance</codeph> (unless |
|
15 you get a reference to it via another class).</p> |
|
16 <p>It is recommended that you store the returned pointer as a member variable |
|
17 in those places where it is needed frequently. This is because the pointer |
|
18 is fetched from thread local storage, which can be somewhat time-consuming. </p> |
|
19 <p>To add feedback areas to the area registry, use the <codeph>SetFeedbackArea</codeph> function. |
|
20 Usually the best place to do this is <codeph>SizeChanged</codeph> function, |
|
21 because that is also the place to update feedback areas in case of a layout |
|
22 change.</p> |
|
23 <note><p>You can also use the same <codeph>SetFeedbackArea</codeph> function |
|
24 for updating the feedback area (the API implementation adds the area to the |
|
25 registry on the first time, and then just does updates on subsequent calls |
|
26 to this function). </p></note> |
|
27 <p>If you want to change the feedback area or type without giving all the |
|
28 parameters again, use the functions <codeph>ChangeFeedbackArea</codeph> and <codeph>ChangeFeedbackType</codeph> for |
|
29 the updates. </p> |
|
30 <p>Also notice that you have to be prepared in case your control is moved |
|
31 with <codeph>CCoeControl::SetPosition</codeph> function. For this you need |
|
32 to override <codeph>CCoeControl::PositionChanged</codeph>, and update the |
|
33 feedback area there the same way as in the <codeph>SizeChanged</codeph> function. |
|
34 Moreover, notice that this is necessary only for those non-window-owning controls, |
|
35 which produce area registry based feedback. </p> |
|
36 <p>Feedback areas of a specific control will be automatically disabled in |
|
37 case the control becomes dimmed by <codeph>CCoeControl::SetDimmed( ETrue )</codeph> or |
|
38 invisible by <codeph>CCoeControl::MakeVisible( EFalse )</codeph>. Feedback |
|
39 will be re-enabled again when control becomes both undimmed and visible. This |
|
40 functionality is based on using the object provider hierarchy, and thus it |
|
41 does not work in case the object provider parent has not been set for the |
|
42 control.</p> |
|
43 <p> If you need to disable a control’s feedback area temporarily (for other |
|
44 reasons than dimming or visibility), call <codeph>EnableFeedbackForControl</codeph> with |
|
45 second parameter <codeph>EFalse</codeph> to disable the feedback. You can |
|
46 then re-enable feedback by calling <codeph>EnableFeedbackForControl</codeph> with |
|
47 second parameter <codeph>ETrue</codeph>. Disabling of control’s feedback also |
|
48 affects direct feedback if it is generated with the overloaded version, which |
|
49 takes the control’s pointer as the second parameter. </p> |
|
50 <p>In some special cases it may be necessary to only disable audio- or vibra |
|
51 feedback for some controls. For this purpose there is a specific overload |
|
52 of <codeph>EnableFeedbackForControl</codeph> function.</p> |
|
53 <p>You must remove your control's feedback areas at the latest when you destroy |
|
54 the control. To do this, call the function <codeph>RemoveFeedbackForControl</codeph> . |
|
55 This also resets the feedback disabling information for the deleted control. |
|
56 If needed, you can remove individual feedback areas with the <codeph>RemoveFeedbackArea</codeph> function |
|
57 any time, but you must still call <codeph>RemoveFeedbackForControl</codeph> you |
|
58 destroy the control.</p> |
|
59 <p>The example below illustrates using tactile feedback based on the area |
|
60 registry. </p> |
|
61 <ol> |
|
62 <li id="GUID-95E49C03-19A2-4E39-BBDE-A907EAC87D3A"><p>Add the library <codeph>touchfeedback.lib</codeph> into |
|
63 your<codeph> .mmp</codeph> file, and then add the following include to your <codeph>.cpp</codeph> file: </p><codeblock xml:space="preserve">#include <touchfeedback.h></codeblock></li> |
|
64 <li id="GUID-0E48DB87-9B6B-4E4A-A18D-62CBCD755949"><p>Update the area registry |
|
65 in the <codeph>SizeChanged</codeph> function. </p><note><p>You don’t need |
|
66 to check if you have already the area added to the registry or not, because |
|
67 you can use the <codeph>SetFeedbackArea</codeph> function anyway. (On the |
|
68 first time this function adds area to the registry, and on the second it updates |
|
69 the area.) </p></note><codeblock xml:space="preserve">MTouchFeedback* feedback = MTouchFeedback::Instance(); |
|
70 |
|
71 if ( feedback ) |
|
72 { |
|
73 feedback->SetFeedbackArea( |
|
74 this, |
|
75 0, |
|
76 Rect(), |
|
77 ETouchFeedbackBasic, |
|
78 ETouchEventStylusDown ); |
|
79 } |
|
80 </codeblock><p>The second parameter given to the <codeph>SetFeedbackArea</codeph> function |
|
81 is an index number, which is used to distinguish the feedback areas of same |
|
82 control from each other (in case the control has many feedback areas). You |
|
83 can choose the index numbers freely. It is recommended that you always use |
|
84 zero as the index if your control only has one feedback area.</p></li> |
|
85 </ol> |
|
86 </conbody></concept> |