Merge branch '4.6' of git@scm.dev.nokia.troll.no:qt/qt into 4.6

1 files changed, 498 insertions, 187 deletions

diff --git a/src/gui/kernel/qgesture.cpp b/src/gui/kernel/qgesture.cpp
index 237ce46..fc8df49 100644
--- a/src/gui/kernel/qgesture.cpp
+++ b/src/gui/kernel/qgesture.cpp
@@ -40,274 +40,585 @@
 ****************************************************************************/
 
 #include "qgesture.h"
-#include <private/qgesture_p.h>
-#include "qgraphicsitem.h"
+#include "private/qgesture_p.h"
 
 QT_BEGIN_NAMESPACE
 
-
-class QEventFilterProxyGraphicsItem : public QGraphicsItem
-{
-public:
-    QEventFilterProxyGraphicsItem(QGesture *g)
-            : gesture(g)
-    {
-    }
-    bool sceneEventFilter(QGraphicsItem *, QEvent *event)
-    {
-        return gesture ? gesture->filterEvent(event) : false;
-    }
-    QRectF boundingRect() const { return QRectF(); }
-    void paint(QPainter*, const QStyleOptionGraphicsItem*, QWidget*) { }
-
-private:
-    QGesture *gesture;
-};
-
-/*!
+ /*!
     \class QGesture
     \since 4.6
-    \preliminary
+    \ingroup gestures
+
+    \brief The QGesture class represents a gesture, containing properties that
+    describe the corresponding user input.
 
-    \brief The QGesture class is the base class for implementing custom
-    gestures.
+    Gesture objects are not constructed directly by developers. They are created by
+    the QGestureRecognizer object that is registered with the application; see
+    QApplication::registerGestureRecognizer().
 
-    This class represents both an object that recognizes a gesture out of a set
-    of input events (a gesture recognizer), and a gesture object itself that
-    can be used to get extended information about the triggered gesture.
+    \section1 Gesture Properties
 
     The class has a list of properties that can be queried by the user to get
-    some gesture-specific parameters (for example, an offset of a Pan gesture).
+    some gesture-specific arguments. For example, the pinch gesture has a scale
+    factor that is exposed as a property.
+
+    Developers of custom gesture recognizers can add additional properties in
+    order to provide additional information about a gesture. This can be done
+    by adding new dynamic properties to a QGesture object, or by subclassing
+    the QGesture class (or one of its subclasses).
+
+    \section1 Lifecycle of a Gesture Object
 
-    Usually gesture recognizer implements a state machine, storing its state
-    internally in the recognizer object. The recognizer receives input events
-    through the \l{QGesture::}{filterEvent()} virtual function and decides
-    whether the event should change the state of the recognizer by emitting an
-    appropriate signal.
+    A QGesture instance is created when the application calls QWidget::grabGesture()
+    or QGraphicsObject::grabGesture() to configure a widget or graphics object (the
+    target object) for gesture input. One gesture object is created for each target
+    object.
 
-    Input events should be either fed to the recognizer one by one with a
-    filterEvent() function, or the gesture recognizer should be attached to an
-    object it filters events for by specifying it as a parent object. The
-    QGesture object installs itself as an event filter to the parent object
-    automatically, the unsetObject() function should be used to remove an event
-    filter from the parent object. To make a
-    gesture that operates on a QGraphicsItem, both the appropriate QGraphicsView
-    should be passed as a parent object and setGraphicsItem() functions should
-    be used to attach a gesture to a graphics item.
+    The registered gesture recognizer monitors the input events for the target
+    object via its \l{QGestureRecognizer::}{filterEvent()} function, updating the
+    properties of the gesture object as required.
 
-    This is a base class, to create a custom gesture type, you should subclass
-    it and implement its pure virtual functions.
+    The gesture object may be delivered to the target object in a QGestureEvent if
+    the corresponding gesture is active or has just been canceled. Each event that
+    is delivered contains a list of gesture objects, since support for more than
+    one gesture may be enabled for the target object. Due to the way events are
+    handled in Qt, gesture events may be filtered by other objects.
 
-    \sa QPanGesture
+    \sa QGestureEvent, QGestureRecognizer
 */
 
-/*! \fn bool QGesture::filterEvent(QEvent *event)
+/*!
+    Constructs a new gesture object with the given \a parent.
+
+    QGesture objects are created by gesture recognizers in the
+    QGestureRecognizer::createGesture() function.
+*/
+QGesture::QGesture(QObject *parent)
+    : QObject(*new QGesturePrivate, parent)
+{
+    d_func()->gestureType = Qt::CustomGesture;
+}
+
+/*!
+    \internal
+*/
+QGesture::QGesture(QGesturePrivate &dd, QObject *parent)
+    : QObject(dd, parent)
+{
+}
 
-    Parses input \a event and emits a signal when detects a gesture.
+/*!
+    Destroys the gesture object.
+*/
+QGesture::~QGesture()
+{
+}
 
-    In your reimplementation of this function, if you want to filter the \a
-    event out, i.e. stop it being handled further, return true; otherwise
-    return false;
+/*!
+    \property QGesture::state
+    \brief the current state of the gesture
+*/
 
-    This is a pure virtual function that needs to be implemented in subclasses.
+/*!
+    \property QGesture::gestureType
+    \brief the type of the gesture
 */
 
-/*! \fn void QGesture::started()
+/*!
+    \property QGesture::hotSpot
+
+    \brief The point that is used to find the receiver for the gesture event.
+
+    If the hot-spot is not set, the targetObject is used as the receiver of the
+    gesture event.
+*/
 
-    The signal is emitted when the gesture is started. Extended information
-    about the gesture is contained in the signal sender object.
+/*!
+    \property QGesture::hasHotSpot
+    \brief whether the gesture has a hot-spot
+*/
 
-    In addition to started(), a triggered() signal should also be emitted.
+/*!
+    \property QGesture::targetObject
+    \brief the target object which will receive the gesture event if the hotSpot is
+    not set
 */
 
-/*! \fn void QGesture::triggered()
+Qt::GestureType QGesture::gestureType() const
+{
+    return d_func()->gestureType;
+}
+
+Qt::GestureState QGesture::state() const
+{
+    return d_func()->state;
+}
+
+QObject *QGesture::targetObject() const
+{
+    return d_func()->targetObject;
+}
+
+void QGesture::setTargetObject(QObject *value)
+{
+    d_func()->targetObject = value;
+}
+
+QPointF QGesture::hotSpot() const
+{
+    return d_func()->hotSpot;
+}
+
+void QGesture::setHotSpot(const QPointF &value)
+{
+    Q_D(QGesture);
+    d->hotSpot = value;
+    d->isHotSpotSet = true;
+}
+
+bool QGesture::hasHotSpot() const
+{
+    return d_func()->isHotSpotSet;
+}
+
+void QGesture::unsetHotSpot()
+{
+    d_func()->isHotSpotSet = false;
+}
+
+/*!
+    \class QPanGesture
+    \since 4.6
+    \brief The QPanGesture class describes a panning gesture made by the user.
+    \ingroup gestures
 
-    The signal is emitted when the gesture is detected. Extended information
-    about the gesture is contained in the signal sender object.
+    \image pangesture.png
+
+    \sa {Gestures Programming}, QPinchGesture, QSwipeGesture
 */
 
-/*! \fn void QGesture::finished()
+/*!
+    \property QPanGesture::totalOffset
+    \brief the total offset from the first input position to the current input
+    position
 
-    The signal is emitted when the gesture is finished. Extended information
-    about the gesture is contained in the signal sender object.
+    The total offset measures the total change in position of the user's input
+    covered by the gesture on the input device.
 */
 
-/*! \fn void QGesture::canceled()
+/*!
+    \property QPanGesture::lastOffset
+    \brief the last offset recorded for this gesture
+
+    The last offset contains the change in position of the user's input as
+    reported in the \l offset property when a previous gesture event was
+    delivered for this gesture.
 
-  The signal is emitted when the gesture is canceled, for example the
-  reset() function is called while the gesture was in the process of
-  emitting a triggered() signal.  Extended information about the
-  gesture is contained in the sender object.
+    If no previous event was delivered with information about this gesture
+    (i.e., this gesture object contains information about the first movement
+    in the gesture) then this property contains a zero size.
 */
 
 /*!
-  Creates a new gesture handler object and marks it as a child of \a
-  parent.  \a gestureTarget is the object that the gesture will watch
-  for events.
+    \property QPanGesture::offset
+    \brief the offset from the previous input position to the current input
+    position
 
-  The \a parent object is also the default event source for the
-  gesture, meaning that the gesture installs itself as an event filter
-  for the \a parent.
+    The offset measures the change in position of the user's input on the
+    input device.
+*/
 
-  \sa setGraphicsItem()
+/*!
+    \property QPanGesture::acceleration
 */
-QGesture::QGesture(QObject *gestureTarget, QObject *parent)
-    : QObject(*new QGesturePrivate, parent)
+
+/*!
+    \internal
+*/
+QPanGesture::QPanGesture(QObject *parent)
+    : QGesture(*new QPanGesturePrivate, parent)
 {
-    setGestureTarget(gestureTarget);
+    d_func()->gestureType = Qt::PanGesture;
 }
 
-/*! \internal
- */
-QGesture::QGesture(QGesturePrivate &dd, QObject *gestureTarget, QObject *parent)
-    : QObject(dd, parent)
+QSizeF QPanGesture::totalOffset() const
 {
-    setGestureTarget(gestureTarget);
+    return d_func()->totalOffset;
 }
 
-/*!
-    Destroys the gesture object.
-*/
-QGesture::~QGesture()
+QSizeF QPanGesture::lastOffset() const
 {
+    return d_func()->lastOffset;
 }
 
-/*!
-    \property QGesture::gestureTarget
+QSizeF QPanGesture::offset() const
+{
+    return d_func()->offset;
+}
 
-    Gesture target is the object that the gesture will watch for events.
-    Typically this means that the gesture installs an event filter on the
-    target object.
-*/
-void QGesture::setGestureTarget(QObject *object)
+qreal QPanGesture::acceleration() const
 {
-    d_func()->setupGestureTarget(object);
+    return d_func()->acceleration;
 }
 
-QObject* QGesture::gestureTarget() const
+
+void QPanGesture::setTotalOffset(const QSizeF &value)
 {
-    return d_func()->gestureTarget;
+    d_func()->totalOffset = value;
 }
 
-void QGesturePrivate::setupGestureTarget(QObject *object)
+void QPanGesture::setLastOffset(const QSizeF &value)
 {
-    Q_Q(QGesture);
-    if (gestureTarget)
-        gestureTarget->removeEventFilter(q);
-    if (object)
-        object->installEventFilter(q);
-    gestureTarget = object;
+    d_func()->lastOffset = value;
 }
 
-/*! \internal
- */
-bool QGesture::eventFilter(QObject *receiver, QEvent *event)
+void QPanGesture::setOffset(const QSizeF &value)
 {
-    Q_D(QGesture);
-    if (d->graphicsItem && receiver == parent())
-        return false;
-    return filterEvent(event);
+    d_func()->offset = value;
+}
+
+void QPanGesture::setAcceleration(qreal value)
+{
+    d_func()->acceleration = value;
 }
 
 /*!
-    \property QGesture::state
+    \class QPinchGesture
+    \since 4.6
+    \brief The QPinchGesture class describes a pinch gesture made my the user.
+    \ingroup multitouch
+    \ingroup gestures
+
+    A pinch gesture is a form of multitouch user input in which the user typically
+    touches two points on the input device with a thumb and finger, before moving
+    them closer together or further apart to change the scale factor, zoom, or level
+    of detail of the user interface.
+
+    \image pinchgesture.png
 
-    \brief The current state of the gesture.
+    Instead of repeatedly applying the same pinching gesture, the user may
+    continue to touch the input device in one place, and apply a second touch
+    to a new point, continuing the gesture. When this occurs, gesture events
+    will continue to be delivered to the target object, containing an instance
+    of QPinchGesture in the Qt::GestureUpdated state.
+
+    \sa {Gestures Programming}, QPanGesture, QSwipeGesture
 */
 
 /*!
-  Returns the gesture recognition state.
- */
-Qt::GestureState QGesture::state() const
+    \enum QPinchGesture::WhatChange
+    
+    This enum describes the changes that can occur to the properties of
+    the gesture object.
+
+    \value ScaleFactorChanged The scale factor held by scaleFactor changed.
+    \value RotationAngleChanged The rotation angle held by rotationAngle changed.
+    \value CenterPointChanged The center point held by centerPoint changed.
+
+    \sa whatChanged
+*/
+
+/*!
+    \property QPinchGesture::whatChanged
+    \brief the property of the gesture that has changed
+
+    This property indicates which of the other properties has changed since
+    the previous gesture event included information about this gesture. You
+    can use this information to determine which aspect of your user interface
+    needs to be updated.
+
+    \sa scaleFactor, rotationAngle, centerPoint
+*/
+
+/*!
+    \property QPinchGesture::totalScaleFactor
+    \brief the total scale factor
+
+    The total scale factor measures the total change in scale factor from the
+    original value to the current scale factor.
+
+    \sa scaleFactor, lastScaleFactor
+*/
+/*!
+    \property QPinchGesture::lastScaleFactor
+    \brief the last scale factor recorded for this gesture
+
+    The last scale factor contains the scale factor reported in the
+    \l scaleFactor property when a previous gesture event included
+    information about this gesture.
+
+    If no previous event was delivered with information about this gesture
+    (i.e., this gesture object contains information about the first movement
+    in the gesture) then this property contains zero.
+
+    \sa scaleFactor, totalScaleFactor
+*/
+/*!
+    \property QPinchGesture::scaleFactor
+    \brief the current scale factor
+
+    The scale factor measures the scale factor associated with the distance
+    between two of the user's inputs on a multitouch device.
+
+    \sa totalScaleFactor, lastScaleFactor
+*/
+
+/*!
+    \property QPinchGesture::totalRotationAngle
+    \brief the total angle covered by the gesture
+
+    This total angle measures the complete angle covered by the gesture. Usually, this
+    is equal to the value held by the \l rotationAngle property, except in the case where
+    the user performs multiple rotations by removing and repositioning one of the touch
+    points, as described above. In this case, the total angle will be the sum of the
+    rotation angles for the multiple stages of the gesture.
+
+    \sa rotationAngle, lastRotationAngle
+*/
+/*!
+    \property QPinchGesture::lastRotationAngle
+    \brief the last reported angle covered by the gesture motion
+
+    The last rotation angle is the angle as reported in the \l rotationAngle property
+    when a previous gesture event was delivered for this gesture.
+
+    \sa rotationAngle, totalRotationAngle
+*/
+/*!
+    \property QPinchGesture::rotationAngle
+    \brief the angle covered by the gesture motion
+
+    \sa totalRotationAngle, lastRotationAngle
+*/
+
+/*!
+    \property QPinchGesture::startCenterPoint
+    \brief the starting position of the center point
+
+    \sa centerPoint, lastCenterPoint
+*/
+/*!
+    \property QPinchGesture::lastCenterPoint
+    \brief the last position of the center point recorded for this gesture
+
+    \sa centerPoint, startCenterPoint
+*/
+/*!
+    \property QPinchGesture::centerPoint
+    \brief the current center point
+
+    The center point is the midpoint between the two input points in the gesture.
+
+    \sa startCenterPoint, lastCenterPoint
+*/
+
+/*!
+    \internal
+*/
+QPinchGesture::QPinchGesture(QObject *parent)
+    : QGesture(*new QPinchGesturePrivate, parent)
 {
-    return d_func()->state;
+    d_func()->gestureType = Qt::PinchGesture;
 }
 
-/*!
-  Sets this gesture's recognition state to \a state and emits appropriate
-  signals.
+QPinchGesture::WhatChanged QPinchGesture::whatChanged() const
+{
+    return d_func()->whatChanged;
+}
+
+void QPinchGesture::setWhatChanged(QPinchGesture::WhatChanged value)
+{
+    d_func()->whatChanged = value;
+}
 
-  This functions emits the signals according to the old state and the new
-  \a state, and it should be called after all the internal properties have been
-  initialized.
 
-  \sa started(), triggered(), finished(), canceled()
- */
-void QGesture::updateState(Qt::GestureState state)
+QPointF QPinchGesture::startCenterPoint() const
 {
-    Q_D(QGesture);
-    if (d->state == state) {
-        if (state == Qt::GestureUpdated)
-            emit triggered();
-        return;
-    }
-    const Qt::GestureState oldState = d->state;
-    if (state != Qt::NoGesture && oldState > state) {
-        // comparing the state as ints: state should only be changed from
-        // started to (optionally) updated and to finished.
-        d->state = state;
-        qWarning("QGesture::updateState: incorrect new state");
-        return;
-    }
-    if (oldState == Qt::NoGesture) {
-        d->state = Qt::GestureStarted;
-        emit started();
-    }
-    d->state = state;
-    if (state == Qt::GestureUpdated)
-        emit triggered();
-    else if (state == Qt::GestureFinished)
-        emit finished();
-    else if (state == Qt::NoGesture)
-        emit canceled();
-
-    if (state == Qt::GestureFinished) {
-        // gesture is finished, so we reset the internal state.
-        d->state = Qt::NoGesture;
-    }
-}
-
-/*!
-    Sets the \a graphicsItem the gesture is filtering events for.
-
-    The gesture will install an event filter to the \a graphicsItem and
-    redirect them to the filterEvent() function.
-
-    \sa graphicsItem()
-*/
-void QGesture::setGraphicsItem(QGraphicsItem *graphicsItem)
+    return d_func()->startCenterPoint;
+}
+
+QPointF QPinchGesture::lastCenterPoint() const
 {
-    Q_D(QGesture);
-    if (d->graphicsItem && d->eventFilterProxyGraphicsItem)
-        d->graphicsItem->removeSceneEventFilter(d->eventFilterProxyGraphicsItem);
-    d->graphicsItem = graphicsItem;
-    if (!d->eventFilterProxyGraphicsItem)
-        d->eventFilterProxyGraphicsItem = new QEventFilterProxyGraphicsItem(this);
-    if (graphicsItem)
-        graphicsItem->installSceneEventFilter(d->eventFilterProxyGraphicsItem);
+    return d_func()->lastCenterPoint;
+}
+
+QPointF QPinchGesture::centerPoint() const
+{
+    return d_func()->centerPoint;
+}
+
+void QPinchGesture::setStartCenterPoint(const QPointF &value)
+{
+    d_func()->startCenterPoint = value;
+}
+
+void QPinchGesture::setLastCenterPoint(const QPointF &value)
+{
+    d_func()->lastCenterPoint = value;
+}
+
+void QPinchGesture::setCenterPoint(const QPointF &value)
+{
+    d_func()->centerPoint = value;
+}
+
+
+qreal QPinchGesture::totalScaleFactor() const
+{
+    return d_func()->totalScaleFactor;
+}
+
+qreal QPinchGesture::lastScaleFactor() const
+{
+    return d_func()->lastScaleFactor;
+}
+
+qreal QPinchGesture::scaleFactor() const
+{
+    return d_func()->scaleFactor;
+}
+
+void QPinchGesture::setTotalScaleFactor(qreal value)
+{
+    d_func()->totalScaleFactor = value;
+}
+
+void QPinchGesture::setLastScaleFactor(qreal value)
+{
+    d_func()->lastScaleFactor = value;
+}
+
+void QPinchGesture::setScaleFactor(qreal value)
+{
+    d_func()->scaleFactor = value;
+}
+
+
+qreal QPinchGesture::totalRotationAngle() const
+{
+    return d_func()->totalRotationAngle;
+}
+
+qreal QPinchGesture::lastRotationAngle() const
+{
+    return d_func()->lastRotationAngle;
+}
+
+qreal QPinchGesture::rotationAngle() const
+{
+    return d_func()->rotationAngle;
+}
+
+void QPinchGesture::setTotalRotationAngle(qreal value)
+{
+    d_func()->totalRotationAngle = value;
+}
+
+void QPinchGesture::setLastRotationAngle(qreal value)
+{
+    d_func()->lastRotationAngle = value;
+}
+
+void QPinchGesture::setRotationAngle(qreal value)
+{
+    d_func()->rotationAngle = value;
 }
 
 /*!
-    Returns the graphics item the gesture is filtering events for.
+    \class QSwipeGesture
+    \since 4.6
+    \brief The QSwipeGesture class describes a swipe gesture made by the user.
+    \ingroup gestures
+
+    \image swipegesture.png
 
-    \sa setGraphicsItem()
+    \sa {Gestures Programming}, QPanGesture, QPinchGesture
 */
-QGraphicsItem* QGesture::graphicsItem() const
+
+/*!
+    \enum QSwipeGesture::SwipeDirection
+
+    This enum describes the possible directions for the gesture's motion
+    along the horizontal and vertical axes.
+
+    \value NoDirection The gesture had no motion associated with it on a particular axis.
+    \value Left     The gesture involved a horizontal motion to the left.
+    \value Right    The gesture involved a horizontal motion to the right.
+    \value Up       The gesture involved an upward vertical motion.
+    \value Down     The gesture involved a downward vertical motion.
+*/
+
+/*!
+    \property QSwipeGesture::horizontalDirection
+    \brief the horizontal direction of the gesture
+
+    If the gesture has a horizontal component, the horizontal direction
+    is either Left or Right; otherwise, it is NoDirection.
+
+    \sa verticalDirection, swipeAngle
+*/
+
+/*!
+    \property QSwipeGesture::verticalDirection
+    \brief the vertical direction of the gesture
+
+    If the gesture has a vertical component, the vertical direction
+    is either Up or Down; otherwise, it is NoDirection.
+
+    \sa horizontalDirection, swipeAngle
+*/
+
+/*!
+    \property QSwipeGesture::swipeAngle
+    \brief the angle of the motion associated with the gesture
+
+    If the gesture has either a horizontal or vertical component, the
+    swipe angle describes the angle between the direction of motion and the
+    x-axis as defined using the standard widget
+    \l{The Coordinate System}{coordinate system}.
+
+    \sa horizontalDirection, verticalDirection
+*/
+
+/*!
+    \internal
+*/
+QSwipeGesture::QSwipeGesture(QObject *parent)
+    : QGesture(*new QSwipeGesturePrivate, parent)
+{
+    d_func()->gestureType = Qt::SwipeGesture;
+}
+
+QSwipeGesture::SwipeDirection QSwipeGesture::horizontalDirection() const
 {
-    return d_func()->graphicsItem;
+    Q_D(const QSwipeGesture);
+    if (d->swipeAngle < 0 || d->swipeAngle == 90 || d->swipeAngle == 270)
+        return QSwipeGesture::NoDirection;
+    else if (d->swipeAngle < 90 || d->swipeAngle > 270)
+        return QSwipeGesture::Right;
+    else
+        return QSwipeGesture::Left;
 }
 
-/*! \fn void QGesture::reset()
+QSwipeGesture::SwipeDirection QSwipeGesture::verticalDirection() const
+{
+    Q_D(const QSwipeGesture);
+    if (d->swipeAngle <= 0 || d->swipeAngle == 180)
+        return QSwipeGesture::NoDirection;
+    else if (d->swipeAngle < 180)
+        return QSwipeGesture::Up;
+    else
+        return QSwipeGesture::Down;
+}
 
-    Resets the internal state of the gesture. This function might be called by
-    the filterEvent() implementation in a derived class, or by the user to
-    cancel a gesture.  The base class implementation calls
-    updateState(Qt::NoGesture) which emits the canceled()
-    signal if the state() of the gesture indicated it was active.
-*/
-void QGesture::reset()
+qreal QSwipeGesture::swipeAngle() const
+{
+    return d_func()->swipeAngle;
+}
+
+void QSwipeGesture::setSwipeAngle(qreal value)
 {
-    updateState(Qt::NoGesture);
+    d_func()->swipeAngle = value;
 }
 
 QT_END_NAMESPACE