53 @beta |
53 @beta |
54 @hbfeedback |
54 @hbfeedback |
55 |
55 |
56 \class HbContinuousFeedback |
56 \class HbContinuousFeedback |
57 |
57 |
58 \brief Class for continuous feedback effects. |
58 \brief The HbContinuousFeedback class is used for setting, playing and |
59 |
59 stopping continuous feedback effects from custom widgets. |
60 Continuous feedbacks are feedback effects that last as long as the user is touching the screen, |
60 |
61 for example when dragging a slider handle. Continuous feedback effects need to be started, updated |
61 Continuous feedback is used for feedback effects that last as long as the user |
62 and stopped using methods play() and stop(). |
62 is touching the screen, for example when dragging a slider handle. |
63 */ |
63 You can use the class HbContinuousFeedback to ask the feedback framework |
64 |
64 to play a selected continuous effect, by giving HbContinuousFeedback |
65 /*! |
65 a parameter of type HbFeedback::ContinuousEffect. The type |
66 \fn void HbContinuousFeedback::setContinuousEffect(HbFeedback::ContinuousEffect effect) |
66 HbFeedback::ContinuousEffect has a number of predefined continuous effects, |
67 |
67 for example \link HbFeedback::ContinuousSlider ContinuousSlider \endlink and |
68 Sets the continuous feedback effect that will be played by the feedback object. |
68 \link HbFeedback::ContinuousPinch ContinuousPinch\endlink. |
|
69 The effect \link HbFeedback::ContinuousSmooth ContinuousSmooth \endlink |
|
70 can be used for a generic continuous feedback. |
|
71 |
|
72 Continuous feedback effects need to be started and stopped using the |
|
73 HbContinuousFeedback methods play() and stop(), respectively. The effect |
|
74 intensity can be varied during the feedback. |
|
75 |
|
76 When you call play() from your widget, HbContinuousFeedback calls |
|
77 the internal feedback framework. If effects are enabled in |
|
78 the current application, the effect will be played. Applications can |
|
79 disable effects with the class HbFeedbackSettings, when effects are |
|
80 not wanted. |
|
81 |
|
82 If your custom widget derives from one of the standard %Hb widgets, it |
|
83 probably has some default feedback behaviour defined, and you should |
|
84 rely on the base class widget for triggering the feedback effects through |
|
85 the HbWidgetFeedback class. Note that if you choose to use this class, |
|
86 HbContinuousFeedback, to play effects directly, you may end up getting |
|
87 feedback effects twice, both through your call to HbContinuousFeedback |
|
88 and through the base class widget feedback mechanism. |
|
89 |
|
90 If your custom widget derives directly from HbWidget, and not through |
|
91 any other %Hb widget, HbContinuousFeedback is the recommended way |
|
92 to play continuous feedback effects. |
|
93 |
|
94 \sa HbFeedback::ContinuousEffect, HbInstantFeedback, HbWidgetFeedback |
|
95 |
|
96 */ |
|
97 |
|
98 /*! |
|
99 Sets the continuous feedback effect to be played when calling play(). |
|
100 |
69 \sa continuousEffect() |
101 \sa continuousEffect() |
70 */ |
102 */ |
71 |
103 |
72 void HbContinuousFeedback::setContinuousEffect(HbFeedback::ContinuousEffect effect) |
104 void HbContinuousFeedback::setContinuousEffect(HbFeedback::ContinuousEffect effect) |
73 { |
105 { |
74 d->cEffect = effect; |
106 d->cEffect = effect; |
75 } |
107 } |
76 |
108 |
77 /*! |
109 /*! |
78 \fn void HbFeedback::ContinuousEffect HbContinuousFeedback::continuousEffect() const |
110 Returns the continuous effect of this object. The continuous effect is |
79 |
111 the continuous feedback effect that will be played when calling play(). |
80 Returns the continuous effect of the continuous feedback object. |
112 |
81 |
113 \sa HbFeedback::ContinuousEffect |
82 \sa setContinuousEffect() |
|
83 */ |
114 */ |
84 |
115 |
85 HbFeedback::ContinuousEffect HbContinuousFeedback::continuousEffect() const |
116 HbFeedback::ContinuousEffect HbContinuousFeedback::continuousEffect() const |
86 { |
117 { |
87 return d->cEffect; |
118 return d->cEffect; |
88 } |
119 } |
89 |
120 |
90 /*! |
121 /*! |
91 \fn int HbContinuousFeedback::timeout() const |
122 Returns the timeout value of the feedback in milliseconds. The continuous |
92 |
123 feedback is automatically stopped if it is not updated within the timeout |
93 Returns the timeout value (in milliseconds) of the feedback object. Continuous feedback is |
124 (by subsequent calls to play()). |
94 automatically stopped if it is not updated within the timeout (by subsequent calls to |
125 |
95 play()). |
|
96 |
|
97 \sa setTimeout(), play() |
126 \sa setTimeout(), play() |
98 */ |
127 */ |
99 |
128 |
100 int HbContinuousFeedback::timeout() const { |
129 int HbContinuousFeedback::timeout() const { |
101 return d->cTimeout; |
130 return d->cTimeout; |
102 } |
131 } |
103 |
132 |
104 /*! |
133 /*! |
105 \fn int HbContinuousFeedback::intensity() const |
134 Returns the intensity of the continuous feedback effect. Intensity can vary |
106 |
135 between HbFeedback::IntensityZero (0) and HbFeedback::IntensityFull (100). |
107 Returns the intensity of the continuous feedback effect. Intensity can be varied between |
136 |
108 values HbFeedback::IntensityZero and HbFeedback::IntensityFull. |
137 \sa setIntensity(), HbFeedback::IntensityLevel |
109 |
|
110 \sa setIntensity() |
|
111 */ |
138 */ |
112 |
139 |
113 int HbContinuousFeedback::intensity() const { |
140 int HbContinuousFeedback::intensity() const { |
114 return d->cIntensity; |
141 return d->cIntensity; |
115 } |
142 } |
147 { |
177 { |
148 delete d; |
178 delete d; |
149 } |
179 } |
150 |
180 |
151 /*! |
181 /*! |
152 Sets the timeout value (in milliseconds) of the feedback object. Continuous feedback is |
182 Sets the timeout value in milliseconds. The continuous feedback is |
153 automatically stopped if it is not updated within the timeout (by subsequent calls to |
183 automatically stopped if the continuous feedback is not updated |
154 play()). This is a safety mechanism to prevent situations in which the client fails to |
184 within the timeout (by subsequent calls to play()). This is a safety mechanism |
155 explicitly stop() a continuous feedback effect. The default timeout value is |
185 to prevent situations in which the client fails to explicitly stop() |
|
186 a continuous feedback effect. The default timeout value is |
156 HbFeedback::StandardFeedbackTimeout. |
187 HbFeedback::StandardFeedbackTimeout. |
157 |
188 |
158 \sa timeout() |
189 \sa timeout() |
159 */ |
190 */ |
160 void HbContinuousFeedback::setTimeout(int msecTimeout) |
191 void HbContinuousFeedback::setTimeout(int msecTimeout) |
161 { |
192 { |
162 if (msecTimeout > 0) { |
193 if (msecTimeout > 0) { |
163 d->cTimeout = msecTimeout; |
194 d->cTimeout = msecTimeout; |
164 } |
195 } |
165 } |
196 } |
166 |
197 |
167 /*! |
198 /*! |
168 Sets the intensity of the continuous feedback effect. The intensity can be varied between |
199 Sets the intensity of the continuous feedback effect. The intensity can vary |
169 HbFeedback::IntensityZero and HbFeedback::IntensityFull. |
200 between HbFeedback::IntensityZero (0) and HbFeedback::IntensityFull (100). |
170 |
201 Smaller or bigger values are ignored. |
171 \sa intensity() |
202 |
|
203 \sa intensity(), HbFeedback::IntensityLevel |
172 */ |
204 */ |
173 void HbContinuousFeedback::setIntensity(int intensity) |
205 void HbContinuousFeedback::setIntensity(int intensity) |
174 { |
206 { |
175 if (intensity >= 0 && intensity <= HbFeedback::IntensityFull) { |
207 if (intensity >= 0 && intensity <= HbFeedback::IntensityFull) { |
176 d->cIntensity = intensity; |
208 d->cIntensity = intensity; |
177 } |
209 } |
178 } |
210 } |
179 |
211 |
180 /*! |
212 /*! |
181 Starts/updates the continuous feedback. |
213 Starts/updates the currently set continuous feedback effect. |
182 The feedback effect will be played untill the timeout is reached or a call to stop() is made. |
214 The feedback effect will be played until the timeout is reached |
|
215 or a call to stop() is made. |
|
216 |
183 \sa stop() |
217 \sa stop() |
184 */ |
218 */ |
185 void HbContinuousFeedback::play() |
219 void HbContinuousFeedback::play() |
186 { |
220 { |
187 HbFeedbackPlayer *feedbackPlayer = HbFeedbackPlayer::instance(); |
221 HbFeedbackPlayer *feedbackPlayer = HbFeedbackPlayer::instance(); |
222 return feedbackOngoing; |
256 return feedbackOngoing; |
223 } |
257 } |
224 |
258 |
225 |
259 |
226 /*! |
260 /*! |
227 Continuous feedback is valid if the feedback effect is not set to HbFeedback::ContinuousNone |
261 This object is valid if the feedback effect is not set to HbFeedback::ContinuousNone |
228 and if the owning window has been defined. There can only be one ongoing continuous feedback effect |
262 and if the owning window has been defined. There can only be one ongoing |
229 per one application window. |
263 continuous feedback effect per one application window. |
230 */ |
264 */ |
231 bool HbContinuousFeedback::isValid() const |
265 bool HbContinuousFeedback::isValid() const |
232 { |
266 { |
233 return d->cEffect != HbFeedback::ContinuousNone && window(); |
267 return d->cEffect != HbFeedback::ContinuousNone && window(); |
234 }; |
268 }; |
235 |
269 |
236 /*! |
270 /*! |
237 Assigns a copy of the feedback \a feedback to this feedback, and returns a |
271 Assigns a copy of \a feedback to this object, and returns a |
238 reference to it. |
272 reference to it. |
239 */ |
273 */ |
240 HbContinuousFeedback &HbContinuousFeedback::operator=(const HbContinuousFeedback &feedback) |
274 HbContinuousFeedback &HbContinuousFeedback::operator=(const HbContinuousFeedback &feedback) |
241 { |
275 { |
242 HbAbstractFeedback::operator =(feedback); |
276 HbAbstractFeedback::operator =(feedback); |