diff -r 627c4a0fd0e7 -r c3690ec91ef8 src/hbcore/gestures/hbpinchgesture.cpp --- a/src/hbcore/gestures/hbpinchgesture.cpp Fri Jun 11 13:58:22 2010 +0300 +++ b/src/hbcore/gestures/hbpinchgesture.cpp Wed Jun 23 18:33:25 2010 +0300 @@ -31,12 +31,106 @@ @hbcore \class HbPinchGesture - \brief HbPinchGesture is an extension to Qt standard QPinchGesture + \brief The HbPinchGesture class provides multitouch support. + + HbPinchGesture is an extension to Qt standard QPinchGesture. It offers + convenience functions for handling the pinch gesture properties directly + in scene coordinates. This removes any need for manual conversions from + the screen (global) coordinates of the QPinchGesture base class + properties. + + You can use HbPinchGesture, for example, to let the user change an + image size in a photo application by dragging the two opposing corners + of the image at the same time. Another example would be rotating a widget + with two fingers. + + \section _usecases_hbpinchgesture Using the HbPinchGesture class + + This example shows how to make a custom widget recognize the pinch + gesture. The custom widget in the example derives from HbWidget. + +
    +
  1. + In order to receive touch events, which are required by the pinch gesture, + at least one widget in the scene needs to accept the QEvent::TouchBegin event. + To make sure this is done, you can do this in your widget by reimplementing + QGraphicsWidget::event(). + + \code + bool MyWidget::event(QEvent *e) + { + if (e->type() == QEvent::TouchBegin) { + return true; + } + return HbWidget::event(e); + } + \endcode +
    2. + +
  2. + Register for pinch 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 pinch and tap gestures. + grabGesture(Qt::PinchGesture); + grabGesture(Qt::TapGesture); + \endcode +
    3. + +
  3. + Reimplement HbWidgetBase::gestureEvent() to handle gestures that are + meaningful for your custom widget. + + \code + void MyWidget::gestureEvent(QGestureEvent *event) + { + if (HbPinchGesture *pinch = qobject_cast + (event->gesture(Qt::PinchGesture))) { + + switch (pinch->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 +
    4. +
+ \sa QPinchGesture */ /*! - \brief HbPinchGesture constructor + Constructor. \param parent Owner for gesture */ HbPinchGesture::HbPinchGesture(QObject *parent) @@ -50,7 +144,7 @@ } /*! - \brief HbPinchGesture constructor + Constructor required by the shared d-pointer paradigm. \param dd Private data \param parent Owner for gesture */ @@ -64,7 +158,7 @@ } /*! - \brief HbPinchGesture destructor + Destructor. */ HbPinchGesture::~HbPinchGesture() { @@ -72,9 +166,8 @@ } /*! - \property sceneTotalRotationAngle - \brief The total angle covered by the gesture in scene coordinates. - \sa QPinchGesture::totalRotationAngle() + Returns the total angle covered by the gesture in scene coordinates. + \sa setSceneTotalRotationAngle(), QPinchGesture::totalRotationAngle() */ qreal HbPinchGesture::sceneTotalRotationAngle() const { @@ -82,6 +175,12 @@ return d->mSceneTotalRotationAngle; } +/*! + Sets the total angle covered by 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 sceneTotalRotationAngle(), QPinchGesture::setTotalRotationAngle() +*/ void HbPinchGesture::setSceneTotalRotationAngle(qreal value) { Q_D(HbPinchGesture); @@ -89,9 +188,9 @@ } /*! - \property sceneLastRotationAngle - \brief The last reported angle covered by the gesture motion in scene coordinates. - \sa QPinchGesture::lastRotationAngle() + Returns the last reported angle covered by the gesture in scene + coordinates. + \sa setSceneLastRotationAngle(), QPinchGesture::lastRotationAngle() */ qreal HbPinchGesture::sceneLastRotationAngle() const { @@ -99,6 +198,12 @@ return d->mSceneLastRotationAngle; } +/*! + Sets the last reported angle covered by 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 sceneLastRotationAngle(), QPinchGesture::setLastRotationAngle() +*/ void HbPinchGesture::setSceneLastRotationAngle(qreal value) { Q_D(HbPinchGesture); @@ -106,9 +211,9 @@ } /*! - \property sceneRotationAngle - \brief The angle covered by the gesture motion in scene coordinates. - \sa QPinchGesture::rotationAngle() + Returns the angle covered by the gesture since last update + in scene coordinates. + \sa setSceneRotationAngle(), QPinchGesture::rotationAngle() */ qreal HbPinchGesture::sceneRotationAngle() const { @@ -116,6 +221,13 @@ return d->mSceneRotationAngle; } +/*! + Sets the angle covered by the gesture since last update + 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 sceneRotationAngle(), QPinchGesture::setRotationAngle() +*/ void HbPinchGesture::setSceneRotationAngle(qreal value) { Q_D(HbPinchGesture); @@ -123,9 +235,8 @@ } /*! - \property sceneStartCenterPoint - \brief The starting position of the center point in scene coordinates. - \sa QPinchGesture::startCenterPoint() + Returns the starting position of the center point in scene coordinates. + \sa setSceneStartCenterPoint(), QPinchGesture::startCenterPoint() */ QPointF HbPinchGesture::sceneStartCenterPoint() const { @@ -133,6 +244,12 @@ return d->mSceneStartCenterPoint; } +/*! + Sets the starting position of the center point 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 sceneStartCenterPoint(), QPinchGesture::setStartCenterPoint() +*/ void HbPinchGesture::setSceneStartCenterPoint(const QPointF &value) { Q_D(HbPinchGesture); @@ -140,9 +257,9 @@ } /*! - \property sceneLastCenterPoint - \brief The last position of the center point recorded for this gesture in scene coordinates. - \sa QPinchGesture::lastCenterPoint() + Returns the last position of the center point recorded for the gesture + in scene coordinates. + \sa setSceneLastCenterPoint(), QPinchGesture::lastCenterPoint() */ QPointF HbPinchGesture::sceneLastCenterPoint() const { @@ -150,6 +267,13 @@ return d->mSceneLastCenterPoint; } +/*! + Sets the last position of the center point recorded 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 sceneLastCenterPoint(), QPinchGesture::setLastCenterPoint() +*/ void HbPinchGesture::setSceneLastCenterPoint(const QPointF &value) { Q_D(HbPinchGesture); @@ -157,9 +281,8 @@ } /*! - \property sceneCenterPoint - \brief The current center point in scene coordinates. - \sa QPinchGesture::centerPoint() + Returns the current center point in scene coordinates. + \sa setSceneCenterPoint(), QPinchGesture::centerPoint() */ QPointF HbPinchGesture::sceneCenterPoint() const { @@ -167,6 +290,12 @@ return d->mSceneCenterPoint; } +/*! + Sets the current center point 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 sceneCenterPoint(), QPinchGesture::setCenterPoint() +*/ void HbPinchGesture::setSceneCenterPoint(const QPointF &value) { Q_D(HbPinchGesture);