51    \brief HbTapGesture is an extension to Qt standard QTapGesture.

    51    \brief The HbTapGesture class provides support for widgets needing both

    52 

    52    the tap and the tap-and-hold gestures.

    53    HbTapGesture extends QTapGesture with additional information related

    53    

    54    to the tap gesture, but most important use for HbTapGesture is

    54    HbTapGesture is an extension to the Qt standard QTapGesture. It is

    55    in widgets needing both tap and tap-and-hold. HbTapGesture

    55    optimized for mobile touch screens, and also supports recognition of

    56    provides both -- use of Qt::TapAndHoldGesture

    56    mouse events for development purposes. Moreover, HbTapGesture extends

    57    in conjunction with Qt::TapGesture in the same widget makes it

    57    QTapGesture by supporting both tap and tap-and-hold gestures. Use of

    58    difficult to handle state updates and finishes in the widget.

    58    Qt::TapAndHoldGesture in conjunction with Qt::TapGesture in the same

    59    HbTapGesture::tapStylehint() can be used to query whether

    59    widget would make it difficult to handle state updates and finishes in

    60    the tap was a normal tap, or tap-and-hold at the time of Qt::GestureUpdated

    60    the widget.

    61    of Qt::GestureFinished. A gesture update will be sent at the time

    61    

    62    when the tap-and-hold timer triggers. No updates are sent

    62    Compared to QTapGesture, HbTapGesture also provides additional information

    63    of the finger movement during the tap.

    63    about the tap gesture position. Moreover, it has convenience functions for

    64 

    64    handling the position information directly in scene coordinates, without

    65    \sa QTapGesture, HbTapGesture::TapStyleHint

    65    any need for manual conversions from global to scene coordinates. 

    66 

    66    

    67 */

    67    Some of the existing Hb widgets (for example HbPushButton) already

    68 

    68    support tap gestures by emitting a signal such as clicked() or longPress()

    69 /*!

    69    when they are tapped. If, however, you are implementing a custom widget

    70     \brief HbTapGesture constructor

    70    whose base class does not emit the needed signals, you need to add

    71     \param parent Parent for the gesture

    71    tap gesture handling by using either QTapGesture or HbTapGesture.

    72    HbTapGesture is a recommended choice if your widget needs both tap and

    73    tap-and-hold gestures.

    74    

    75    HbTapGesture does not support double tap.

    76    

    77    \section _usecases_hbtapgesture Using the HbTapGesture class

    78       

    79    This example shows how to make a custom widget recognize the tap and

    80    tap-and-hold gestures. The custom widget in the example derives from

    81    HbWidget.

    82 

    83    <ol>

    84    <li>   

    85    Register for tap gestures by using the base class function

    86    QGraphicsObject::grabGesture(). QGraphicsObject::grabGesture() can be

    87    called several times with different arguments, if the widget is interested

    88    in other gesture types as well.

    89    

    90    \code

    91    // This widget is interested in tap and pan gestures.

    92    grabGesture(Qt::TapGesture);

    93    grabGesture(Qt::PanGesture);

    94    \endcode

    95    </li>

    96    

    97    <li> 

    98    Reimplement HbWidgetBase::gestureEvent() to handle gestures that are

    99    meaningful for your custom widget.

   100    

   101    HbTapGesture::tapStyleHint() can be used to query whether the tap was

   102    a normal tap or tap-and-hold at the time of Qt::GestureUpdated or

   103    Qt::GestureFinished. A gesture update will be sent at the time when

   104    the tap-and-hold timer triggers. No updates are sent of the finger

   105    movement during the tap.

   106      

   107    \code

   108    void MyWidget::gestureEvent(QGestureEvent *event)

   109    {

   110        if (HbTapGesture *tap = qobject_cast<HbTapGesture *>

   111            (event->gesture(Qt::TapGesture))) {

   112        

   113            switch (tap->state()) {

   114            

   115            case Qt::GestureStarted:

   116                // Visualize the active state of the widget.

   117                break;

   118            case Qt::GestureUpdated:

   119            

   120                // Long tap is triggered if the gesture takes

   121                // more than 0.5 seconds. Handle it here.

   122                if (tap->tapStyleHint() == HbTapGesture::TapAndHold) {               

   123                    // Emit a long tap signal.               

   124                }

   125                

   126                break;

   127            case Qt::GestureCanceled:

   128                // Visualize the non-active state of the widget.

   129                break;

   130            case Qt::GestureFinished:

   131            

   132                // Visualize the non-active state of the widget.

   133                

   134                // Short tap is handled when the gesture is finished.

   135                if (tap->tapStyleHint() == HbTapGesture::Tap) {               

   136                    // Emit a short tap signal.               

   137                }

   138                

   139                break;

   140            default:

   141                break;

   142            }           

   143        }

   144        

   145        // Handle other gesture types that have been grabbed. There may be

   146        // several, since all gestures that are active at the same moment

   147        // are sent within the same gesture event.

   148        if (HbPanGesture *pan = qobject_cast<HbPanGesture *>

   149            (event->gesture(Qt::PanGesture))) {

   150            // handle the pan gesture

   151        }

   152        

   153    }   

   154    \endcode

   155    </li>

   156    </ol>

   157 

   158    \sa TapStyleHint, QTapGesture

   159 

   160 */

   161 

   162 /*!

   163     \enum HbTapGesture::TapStyleHint

   164     Defines the tap style.

   165 */

   166 

   167 /*!

   168     \var HbTapGesture::TapStyleHint HbTapGesture::Tap

   169     Normal (short) tap.

   170 */

   171 

   172 /*!

   173     \var HbTapGesture::TapStyleHint HbTapGesture::TapAndHold

   174     Long press (tap-and-hold).

   175 */

   176 

   177 /*!

   178     Constructor.

   179     

   180     \param parent Parent for the gesture.

    80     \brief HbTapGesture constructor

   189     Constructor required by the shared d-pointer paradigm.

    81     \param dd Custom private data

   190     \param dd Custom private data.

    82     \param parent Parent for the gesture

   191     \param parent Parent for the gesture.

    92     \brief HbTapGesture destructor

   201     Destructor.

   101     \property startPos

   210     Returns the starting position of the tap gesture in screen coordinates.

   102     \brief Stores the starting position of the tap gesture in screen coordinates.

   211     

   212     \sa setStartPos()

   117     \property sceneStartPos

   234     Returns the starting position of the tap gesture in scene coordinates.

   118     \brief Stores the starting position of the tap gesture in scene coordinates.

   235     

   236     \sa setSceneStartPos()

   133     \property scenePosition

   258     Returns the current position of the tap gesture in scene coordinates.

   134     \brief Stores the current position of the tap gesture in scene coordinates.

   259     

   135     \sa QTapGesture::position()

   260     \sa setScenePosition(), QTapGesture::position()

   150     \property tapStyleHint

   282     Returns information about whether the tap is a short tap or long press

   151     \brief Indicates whether tap is normal tap or long press.

   283     (tap-and-hold).

   152 

   284 

   153     TapStyleHint is by default Tap and in case of long press, the gesture

   285     The tapStyleHint property is by default Tap and in case of long press,

   154     update event is sent and TapStyleHint changed to TapAndHold.

   286     a gesture update event is sent and tapStyleHint changed to TapAndHold.