--- a/src/hbfeedback/player/hbcontinuousfeedback.cpp Tue Jul 06 14:36:53 2010 +0300
+++ b/src/hbfeedback/player/hbcontinuousfeedback.cpp Wed Aug 18 10:05:37 2010 +0300
@@ -55,17 +55,49 @@
\class HbContinuousFeedback
- \brief Class for continuous feedback effects.
+ \brief The HbContinuousFeedback class is used for setting, playing and
+ stopping continuous feedback effects from custom widgets.
- Continuous feedbacks are feedback effects that last as long as the user is touching the screen,
- for example when dragging a slider handle. Continuous feedback effects need to be started, updated
- and stopped using methods play() and stop().
+ Continuous feedback is used for feedback effects that last as long as the user
+ is touching the screen, for example when dragging a slider handle.
+ You can use the class HbContinuousFeedback to ask the feedback framework
+ to play a selected continuous effect, by giving HbContinuousFeedback
+ a parameter of type HbFeedback::ContinuousEffect. The type
+ HbFeedback::ContinuousEffect has a number of predefined continuous effects,
+ for example \link HbFeedback::ContinuousSlider ContinuousSlider \endlink and
+ \link HbFeedback::ContinuousPinch ContinuousPinch\endlink.
+ The effect \link HbFeedback::ContinuousSmooth ContinuousSmooth \endlink
+ can be used for a generic continuous feedback.
+
+ Continuous feedback effects need to be started and stopped using the
+ HbContinuousFeedback methods play() and stop(), respectively. The effect
+ intensity can be varied during the feedback.
+
+ When you call play() from your widget, HbContinuousFeedback calls
+ the internal feedback framework. If effects are enabled in
+ the current application, the effect will be played. Applications can
+ disable effects with the class HbFeedbackSettings, when effects are
+ not wanted.
+
+ If your custom widget derives from one of the standard %Hb widgets, it
+ probably has some default feedback behaviour defined, and you should
+ rely on the base class widget for triggering the feedback effects through
+ the HbWidgetFeedback class. Note that if you choose to use this class,
+ HbContinuousFeedback, to play effects directly, you may end up getting
+ feedback effects twice, both through your call to HbContinuousFeedback
+ and through the base class widget feedback mechanism.
+
+ If your custom widget derives directly from HbWidget, and not through
+ any other %Hb widget, HbContinuousFeedback is the recommended way
+ to play continuous feedback effects.
+
+ \sa HbFeedback::ContinuousEffect, HbInstantFeedback, HbWidgetFeedback
+
*/
/*!
- \fn void HbContinuousFeedback::setContinuousEffect(HbFeedback::ContinuousEffect effect)
-
- Sets the continuous feedback effect that will be played by the feedback object.
+ Sets the continuous feedback effect to be played when calling play().
+
\sa continuousEffect()
*/
@@ -75,11 +107,10 @@
}
/*!
- \fn void HbFeedback::ContinuousEffect HbContinuousFeedback::continuousEffect() const
-
- Returns the continuous effect of the continuous feedback object.
-
- \sa setContinuousEffect()
+ Returns the continuous effect of this object. The continuous effect is
+ the continuous feedback effect that will be played when calling play().
+
+ \sa HbFeedback::ContinuousEffect
*/
HbFeedback::ContinuousEffect HbContinuousFeedback::continuousEffect() const
@@ -88,12 +119,10 @@
}
/*!
- \fn int HbContinuousFeedback::timeout() const
-
- Returns the timeout value (in milliseconds) of the feedback object. Continuous feedback is
- automatically stopped if it is not updated within the timeout (by subsequent calls to
- play()).
-
+ Returns the timeout value of the feedback in milliseconds. The continuous
+ feedback is automatically stopped if it is not updated within the timeout
+ (by subsequent calls to play()).
+
\sa setTimeout(), play()
*/
@@ -102,12 +131,10 @@
}
/*!
- \fn int HbContinuousFeedback::intensity() const
-
- Returns the intensity of the continuous feedback effect. Intensity can be varied between
- values HbFeedback::IntensityZero and HbFeedback::IntensityFull.
-
- \sa setIntensity()
+ Returns the intensity of the continuous feedback effect. Intensity can vary
+ between HbFeedback::IntensityZero (0) and HbFeedback::IntensityFull (100).
+
+ \sa setIntensity(), HbFeedback::IntensityLevel
*/
int HbContinuousFeedback::intensity() const {
@@ -122,6 +149,9 @@
/*!
Constructor.
+
+ If you use this constructor, you need to set the continuous feedback effect
+ and an owning window before calling play().
*/
HbContinuousFeedback::HbContinuousFeedback() :d(new HbContinuousFeedbackPrivate)
{
@@ -130,8 +160,8 @@
/*!
Constructor.
- \param effect continuous feedback effect to be played
- \param widget used to determine the window where continuous feedback is active.
+ \param effect Continuous feedback effect to be played
+ \param widget Used to determine the window where the continuous feedback is active.
There can only be one ongoing continuous feedback per application window.
*/
HbContinuousFeedback::HbContinuousFeedback(HbFeedback::ContinuousEffect effect, const QWidget *widget) : d(new HbContinuousFeedbackPrivate)
@@ -149,12 +179,13 @@
}
/*!
- Sets the timeout value (in milliseconds) of the feedback object. Continuous feedback is
- automatically stopped if it is not updated within the timeout (by subsequent calls to
- play()). This is a safety mechanism to prevent situations in which the client fails to
- explicitly stop() a continuous feedback effect. The default timeout value is
+ Sets the timeout value in milliseconds. The continuous feedback is
+ automatically stopped if the continuous feedback is not updated
+ within the timeout (by subsequent calls to play()). This is a safety mechanism
+ to prevent situations in which the client fails to explicitly stop()
+ a continuous feedback effect. The default timeout value is
HbFeedback::StandardFeedbackTimeout.
-
+
\sa timeout()
*/
void HbContinuousFeedback::setTimeout(int msecTimeout)
@@ -165,10 +196,11 @@
}
/*!
- Sets the intensity of the continuous feedback effect. The intensity can be varied between
- HbFeedback::IntensityZero and HbFeedback::IntensityFull.
-
- \sa intensity()
+ Sets the intensity of the continuous feedback effect. The intensity can vary
+ between HbFeedback::IntensityZero (0) and HbFeedback::IntensityFull (100).
+ Smaller or bigger values are ignored.
+
+ \sa intensity(), HbFeedback::IntensityLevel
*/
void HbContinuousFeedback::setIntensity(int intensity)
{
@@ -178,8 +210,10 @@
}
/*!
- Starts/updates the continuous feedback.
- The feedback effect will be played untill the timeout is reached or a call to stop() is made.
+ Starts/updates the currently set continuous feedback effect.
+ The feedback effect will be played until the timeout is reached
+ or a call to stop() is made.
+
\sa stop()
*/
void HbContinuousFeedback::play()
@@ -208,7 +242,7 @@
/*!
- Returns true if the continuous feedback is being played.
+ Returns \c true if the continuous feedback is currently being played.
*/
bool HbContinuousFeedback::isPlaying()
{
@@ -224,9 +258,9 @@
/*!
- Continuous feedback is valid if the feedback effect is not set to HbFeedback::ContinuousNone
- and if the owning window has been defined. There can only be one ongoing continuous feedback effect
- per one application window.
+ This object is valid if the feedback effect is not set to HbFeedback::ContinuousNone
+ and if the owning window has been defined. There can only be one ongoing
+ continuous feedback effect per one application window.
*/
bool HbContinuousFeedback::isValid() const
{
@@ -234,7 +268,7 @@
};
/*!
- Assigns a copy of the feedback \a feedback to this feedback, and returns a
+ Assigns a copy of \a feedback to this object, and returns a
reference to it.
*/
HbContinuousFeedback &HbContinuousFeedback::operator=(const HbContinuousFeedback &feedback)
@@ -247,8 +281,8 @@
}
/*!
- Returns true if the continuous feedbacks have the same parent window,
- area rect, continuous effect, timeout and intensity.
+ Returns \c true if this object and \a feedback have the same parent window,
+ area rect, continuous effect, timeout, and intensity.
*/
bool HbContinuousFeedback::operator==(const HbContinuousFeedback &feedback) const
{
@@ -260,8 +294,8 @@
}
/*!
- Returns true if the continuous feedbacks have different parent window,
- area rect, continuous effect, timeout or intensity.
+ Returns \c true if this object and \a feedback have a different parent window,
+ area rect, continuous effect, timeout, or intensity.
*/
bool HbContinuousFeedback::operator!=(const HbContinuousFeedback &feedback) const
{