35     \brief Widget Feedback API is used by widgets for providing feedback information for the feedback framework.

    35     \brief The HbWidgetFeedback class provides an interface for widgets

    36     to inform the feedback framework about user interactions in order

    37     to trigger feedback effects.

    38     

    39     The HbWidgetFeedback class is for use in widget implementations.

    40     It is not relevant when you are simply using existing widgets in

    41     an application.

    42     

    43     As a widget developer, you may want to give feedback when the user

    44     interacts with your widget. Audio signals or vibration are examples of

    45     possible feedback effects. To trigger the feedback effects supported by

    46     the feedback framework, you must inform the feedback framework about

    47     the detected user interaction and its specific type.

    48     

    49     Interactions are divided into two main types:

    50     

    51     <ul>

    52     <li><b>Instant interactions.</b> Short user actions, such as clicking

    53     a button or changing a selection on a list. A typical feedback effect

    54     for these interactions is a fire-and-forget type of event, where

    55     the physical response is played from beginning to end.</li>

    56     <li><b>Continuous interactions.</b> Longer user actions, such as scrolling

    57     or dragging. Playing the feedback for these interactions continues until

    58     explicitly stopped.</li>

    59     </ul>

    60     

    61     HbWidgetFeedback provides static methods for informing the feedback

    62     framework about user interactions:

    63     \link HbWidgetFeedback::triggered() triggered() \endlink for instant interactions,

    64     and \link HbWidgetFeedback::continuousTriggered() continuousTriggered() \endlink

    65     and \link HbWidgetFeedback::continuousStopped() continuousStopped() \endlink

    66     for continuous interactions. Information on the target widget of the interaction

    67     and the interaction type is passed in the method parameters. The feedback framework

    68     makes decisions about the actual effects, based on the widget type, situation,

    69     and specific interaction type.

    70     

    71     A widget should only call interaction methods when the user actually

    72     interacts with the widget, and not when the widget state changes for some

    73     other reason. For example, feedback effects are not desirable when

    74     an application resets widget states by calling the widget API, or when

    75     a progress bar is moved during a file transfer.

    76     

    77     How you use this class or whether you need to use it at all depends on 

    78     what kind of widget you are developing:

    79     

    80     <b>Standard widgets.</b> If you are developing a standard %Hb widget, 

    81     such as HbPushButton, HbComboBox, and so on, you should use this class,

    82     %HbWidgetFeedback, for triggering feedback effects upon user interaction.

    83     See the use case below for details.

    84     

    85     <b>Custom widgets that derive from a standard widget.</b> If you are 

    86     developing a custom widget that derives from one of the standard

    87     %Hb widgets (such as HbPushButton, HbComboBox, and so on),

    88     the base class widget most probably has predefined feedback effects,

    89     and you do not need to do anything. The base class takes care of triggering

    90     the default effects upon user interaction.

    91     

    92     <b>Custom widgets that derive directly from HbWidget.</b> If your custom

    93     widget derives directly from HbWidget, and not through any of the standard

    94     %Hb widgets, you should not use %HbWidgetFeedback. The recommended way

    95     to define feedback for your widget is to use classes HbInstantFeedback and

    96     HbContinuousFeedback.

    97     

    98     \section _usecases_hbwidgetfeedback Using HbWidgetFeedback

    99     

   100     \subsection _uc_standardhb_hbwidgetfeedback Supporting feedback effects in a standard widget

   101     

   102     Call the HbWidgetFeedback methods in a standard widget when the user

   103     interacts with the widget. Choose the correct method according to

   104     the interaction style: instant or continuous.

   105             

   106     To support instant feedback features in a standard %Hb widget, call 

   107     HbWidgetFeedback::triggered() with a suitable Hb::InstantInteraction

   108     parameter to specify the interaction type, whenever you detect any

   109     user interaction that is instant by nature. For example:

   110     

   111     \code

   112     // The widget has been pressed down and released

   113     HbWidgetFeedback::triggered(this, Hb::InstantClicked);

   114     \endcode

   115     

   116     See Hb::InstantInteraction for the list of all predefined instant

   117     interactions.

   118     

   119     Whenever you detect any of the specified continuous user interactions in

   120     your standard %Hb widget, or when the continuous interaction ends, call

   121     either HbWidgetFeedback::continuousTriggered() or HbWidgetFeedback::continuousStopped()

   122     with the suitable Hb::ContinuousInteraction parameter. For example:

   123     

   124     \code

   125     // User has started moving the slider handle.

   126     HbWidgetFeedback::continuousTriggered(this, Hb::ContinuousDragged);

   127     \endcode

   128     

   129     \code

   130     // User has stopped moving the slider handle.

   131     HbWidgetFeedback::continuousStopped(this, Hb::ContinuousDragged);

   132     \endcode

   133     

   134     See Hb::ContinuousInteraction for the list of all predefined

   135     continuous interactions.

   136         

    37     For widgets to support feedback features, a widget needs to call method triggered() with Hb::InstantInteraction parameter

   138     \sa HbInstantFeedback, HbContinuousFeedback

    38     \li Hb::InstantPressed when a widget is pressed down

    39     \li Hb::InstantReleased when a press is released

    40     \li Hb::InstantClicked when an widget is pressed and released immediately

    41     \li Hb::InstantKeyRepeated when an widget sends key repeats and is pressed down

    42     \li Hb::InstantLongPressed when an widget is kept pressed for a while

    43     \li Hb::InstantDraggedOver when the finger is dragged on top of an widget

    44     \li Hb::InstantFlicked when a current widget is flicked using a flick gesture

    45     \li Hb::InstantBoundaryReached when the boundary of a scroll area is reached

    46     \li Hb::InstantRotated90Degrees every time the multitouch area passes 90 degrees of rotation

    47     \li Hb::InstantPopupOpened when a popup, for example a note, tooltip or menu, is opened

    48     \li Hb::InstantPopupClosed when a popup, for example a note, tooltip or menu, is closed

    49     \li between Hb::InstantUser and Hb::InstantMax when a custom widget is being interacted with a custom interaction

    50     

    51     Widget needs to call method continuousTriggered() and continuousStopped() with Hb::ContinuousInteraction parameter

    52     \li Hb::ContinuousScrolled when an widget area is scrolled by quickly flicking or continuously panning the finger

    53     \li Hb::ContinuousDragged when user is dragging a widget like moving slider handle

    54     \li Hb::ContinuousPinched when an widget is being zoomed or rotated with two fingers

    55     \li between Hb::ContinuousUser and Hb::ContinuousMax when a custom widget is being interacted with a continuous custom interaction

    56 

    57     The information provided by HbFeedbackManager is forwarded to the feedback engines.

    58     

    59     Widget should only call interaction methods when <i>user actually interacts with the widget</i> and not for example 

    60     when an application resets widget states by calling an widget API or when a progress bar is moved during a file transfer. 

    61     We don't want to initiate haptic and sound feedback effects when the device is not getting any real user interaction.

    65     Mediates instant interaction information from widgets to feedback manager 

   142     Passes information about an instant interaction from the widget to the

    66     that forwards it to all active feedback plugins.

   143     feedback manager, which forwards it to all active feedback plugins.

    68     \param widget the widget being interacted with

   145     \param widget Target widget of the interaction

    69     \param interaction the interaction

   146     \param interaction The instant interaction type

    70     \param modifiers optional specifiers to the interaction

   147     \param modifiers Optional Hb::InteractionModifier flags with more detailed

   148     information about the interaction

    81     Mediates continuous interaction information from widgets to feedback manager 

   159     Passes information about a started continuous interaction from the

    82     that forwards it to all active feedback plugins.

   160     widget to the feedback manager, which forwards it to all active feedback

   161     plugins.

    84     \param widget the widget being interacted with

   163     \param widget Target widget of the interaction

    85     \param interaction the continuous interaction in progress

   164     \param interaction The continuous interaction type

    86     \param delta supplies the direction and distance of the interaction

   165     \param delta The direction and distance of the interaction

    97     Mediates information about stopped continuous interaction from widget 

   176     Passes information about the stopped continuous interaction from the

    98     to feedback manager that forwards it to all active feedback plugins.

   177     widget to the feedback manager, which forwards it to all active feedback

    99     This methods is needed for knowing when to stop continuous feedback

   178     plugins. This method is needed for stopping the continuous feedback

   102     \param widget the widget being interacted with

   181     \param widget Target widget of the interaction

   103     \param interaction the continuous interaction in progress

   182     \param interaction The continuous interaction type