diff -r 627c4a0fd0e7 -r c3690ec91ef8 src/hbcore/gestures/hbpangesture.cpp --- a/src/hbcore/gestures/hbpangesture.cpp Fri Jun 11 13:58:22 2010 +0300 +++ b/src/hbcore/gestures/hbpangesture.cpp Wed Jun 23 18:33:25 2010 +0300 @@ -36,12 +36,92 @@ @hbcore \class HbPanGesture - \brief HbPanGesture is an extension to Qt standard QPanGesture + \brief The HbPanGesture class provides support for receiving a dragging + (pan) gesture. + + HbPanGesture is an extension to the Qt standard QPanGesture. It is + optimized for mobile touch screens, and also supports recognition of + mouse events for development purposes. Moreover, HbPanGesture + adds some new properties (startPos and velocity) to the existing + QPanGesture properties, and also provides variants of all these expressed + in scene coordinates. This removes any need for manual conversions from + the screen (global) coordinates of the QPanGesture base class properties. + + A pan gesture is used in situations where the user drags content to a new + position. Make sure your application gives instant feedback to the user + with each gesture update by moving the content, not only when the gesture + is finished. + + \section _usecases_hbpangesture Using the HbPanGesture class + + This example shows how to make a custom widget recognize the pan + gesture. The custom widget in the example derives from HbWidget. + +
    +
  1. + Register for pan gestures by using the base class function + QGraphicsObject::grabGesture(). QGraphicsObject::grabGesture() can be + called several times with different arguments, if the widget is + interested in other gesture types as well. + + \code + // This widget is interested in pan and tap gestures. + grabGesture(Qt::PanGesture); + grabGesture(Qt::TapGesture); + \endcode +
    2. + +
  2. + Reimplement HbWidgetBase::gestureEvent() to handle gestures that are + meaningful for your custom widget. + + \code + void MyWidget::gestureEvent(QGestureEvent *event) + { + if (HbPanGesture *pan = qobject_cast + (event->gesture(Qt::PanGesture))) { + + switch (pan->state()) { + + case Qt::GestureStarted: + // Visualize the active state of the widget. + // Emit a signal to move the content + break; + case Qt::GestureUpdated: + // Emit a signal to move the content. + break; + case Qt::GestureCanceled: + // Visualize the non-active state of the widget. + // Emit a signal to return the content to the starting + // position. + break; + case Qt::GestureFinished: + // Visualize the non-active state of the widget. + // Emit a signal to move the content. + break; + default: + break; + } + } + + // Handle other gesture types that have been grabbed. There may be + // several, since all gestures that are active at the same moment + // are sent within the same gesture event. + if (HbTapGesture *tap = qobject_cast + (event->gesture(Qt::TapGesture))) { + // handle the tap gesture + } + + } + \endcode +
    3. +
+ \sa QPanGesture */ /*! - \brief HbPanGesture constructor + Constructor. \param parent Owner for gesture */ @@ -51,7 +131,7 @@ } /*! - \brief HbPanGesture constructor + Constructor required by the shared d-pointer paradigm. \param dd Private data \param parent Owner for gesture @@ -63,7 +143,7 @@ } /*! - \brief HbPanGesture destructor + Destructor. */ HbPanGesture::~HbPanGesture() { @@ -71,9 +151,8 @@ } /*! - \property startPos - \brief Starting position for gesture in global coordinates. - \sa HbPanGesture::sceneStartPos + Returns the starting position for the gesture in global coordinates. + \sa setStartPos(), sceneStartPos() */ QPointF HbPanGesture::startPos() const { @@ -81,6 +160,12 @@ return d->mStartPos; } +/*! + Sets the starting position for the gesture in global coordinates. + This function is used by the framework gesture recognition logic, + and it should not be used by the widget receiving the gesture. + \sa startPos(), setSceneStartPos() +*/ void HbPanGesture::setStartPos(const QPointF &startPos) { Q_D(HbPanGesture); @@ -88,9 +173,9 @@ } /*! - \property velocity - \brief Panning velocity in global coordinates. - \sa HbPanGesture::sceneVelocity + Returns the panning velocity in global coordinates. + The unit is pixels per millisecond. + \sa setVelocity(), sceneVelocity() */ QPointF HbPanGesture::velocity() const { @@ -98,15 +183,21 @@ return HbVelocityCalculator( d->mAxisX, d->mAxisY ).velocity(QTime::currentTime()); } +/*! + Sets the panning velocity in global coordinates. + This function is used by the framework gesture recognition logic, + and it should not be used by the widget receiving the gesture. + \sa velocity() +*/ void HbPanGesture::setVelocity(const QPointF &) { Q_ASSERT(false); } /*! - \property sceneLastOffset - \brief The total offset from start position to second last position in scene coordinates. - \sa QPanGesture::lastOffset() + Returns the total offset from start position to second last position + in scene coordinates. + \sa setSceneLastOffset(), QPanGesture::lastOffset() */ QPointF HbPanGesture::sceneLastOffset() const { @@ -114,6 +205,13 @@ return d->mSceneLastOffset; } +/*! + Sets the total offset from start position to second last position + in scene coordinates. + This function is used by the framework gesture recognition logic, + and it should not be used by the widget receiving the gesture. + \sa sceneLastOffset(), QPanGesture::setLastOffset() +*/ void HbPanGesture::setSceneLastOffset(const QPointF &lastOffset) { Q_D(HbPanGesture); @@ -121,9 +219,9 @@ } /*! - \property sceneOffset - \brief The total offset from start position to current position in scene coordinates. - \sa QPanGesture::offset() + Returns the total offset from start position to current position + in scene coordinates. + \sa setSceneOffset(), QPanGesture::offset() */ QPointF HbPanGesture::sceneOffset() const { @@ -131,6 +229,13 @@ return d->mSceneOffset; } +/*! + Sets the total offset from start position to current position + in scene coordinates. + This function is used by the framework gesture recognition logic, + and it should not be used by the widget receiving the gesture. + \sa sceneOffset(), QPanGesture::setOffset() +*/ void HbPanGesture::setSceneOffset(const QPointF &offset) { Q_D(HbPanGesture); @@ -138,9 +243,8 @@ } /*! - \property sceneStartPos - \brief Starting position for gesture in scene coordinates. - \sa HbPanGesture::startPos() + Returns the starting position for the gesture in scene coordinates. + \sa setSceneStartPos(), startPos() */ QPointF HbPanGesture::sceneStartPos() const { @@ -148,6 +252,12 @@ return d->mSceneStartPos; } +/*! + Sets the starting position for the gesture in scene coordinates. + This function is used by the framework gesture recognition logic, + and it should not be used by the widget receiving the gesture. + \sa sceneStartPos(), setStartPos() +*/ void HbPanGesture::setSceneStartPos(const QPointF &startPos) { Q_D(HbPanGesture); @@ -155,9 +265,9 @@ } /*! - \property sceneVelocity - \brief Panning velocity in scene coordinates. - \sa HbPanGesture::velocity() + Returns the panning velocity in scene coordinates. + The unit is pixels per millisecond. + \sa velocity() */ QPointF HbPanGesture::sceneVelocity() const { @@ -166,8 +276,7 @@ } /*! - \property sceneAcceleration - \brief Panning acceleration in scene coordinates. + Returns the panning acceleration in scene coordinates. \sa QPanGesture::acceleration() */ QPointF HbPanGesture::sceneAcceleration() const @@ -176,8 +285,7 @@ } /*! - \property sceneDelta - \brief Distance between last two points in scene coordinates. + Returns the distance between the last two points in scene coordinates. \sa QPanGesture::delta() */ QPointF HbPanGesture::sceneDelta() const