Doc: Documentation for gesture features. Still a moving target.

Reviewed-by: Trust Me

4 files changed, 283 insertions, 4 deletions

diff --git a/src/gui/kernel/qapplication.cpp b/src/gui/kernel/qapplication.cpp
index b990fe2..6f6d706 100644
--- a/src/gui/kernel/qapplication.cpp
+++ b/src/gui/kernel/qapplication.cpp
@@ -5643,7 +5643,7 @@ Qt::GestureType QApplication::registerGestureRecognizer(QGestureRecognizer *reco
 
     Unregisters all gesture recognizers of the specified \a type.
 
-    \sa registerGestureRecognizer
+    \sa registerGestureRecognizer()
 */
 void QApplication::unregisterGestureRecognizer(Qt::GestureType type)
 {
diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index 4826704..2ff6d65 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -3563,6 +3563,7 @@ QMenubarUpdatedEvent::QMenubarUpdatedEvent(QMenuBar * const menuBar)
     \brief The QTouchEvent class contains parameters that describe a touch event.
     \since 4.6
     \ingroup events
+    \ingroup multitouch
 
     \section1 Enabling Touch Events
 
@@ -4195,6 +4196,7 @@ QTouchEvent::TouchPoint &QTouchEvent::TouchPoint::operator=(const QTouchEvent::T
     \class QGestureEvent
     \since 4.6
     \ingroup events
+    \ingroup gestures
 
     \brief The QGestureEvent class provides the description of triggered gestures.
 
@@ -4316,4 +4318,44 @@ bool QGestureEvent::isAccepted(QGesture *gesture) const
     return gesture ? gesture->d_func()->accept : false;
 }
 
+#ifdef Q_NO_USING_KEYWORD
+/*!
+    \fn void QGestureEvent::setAccepted(bool accepted)
+
+    Sets or clears the event's internal flag that determines whether it should
+    be delivered to other objects.
+
+    Calling this function with a value of true for \a accepted indicates that the
+    caller has accepted the event and that it should not be propagated further.
+    Calling this function with a value of false indicates that the caller has
+    ignored the event and that it should be delivered to other objects.
+
+    For convenience, the accept flag can also be set with accept(), and cleared
+    with ignore().
+
+    \sa QEvent::accepted
+*/
+/*!
+    \fn bool QGestureEvent::isAccepted() const
+
+    Returns true is the event has been accepted; otherwise returns false.
+
+    \sa QEvent::accepted
+*/
+/*!
+    \fn void QGestureEvent::accept()
+
+    Accepts the event, the equivalent of calling setAccepted(true).
+
+    \sa QEvent::accept()
+*/
+/*!
+    \fn void QGestureEvent::ignore()
+
+    Ignores the event, the equivalent of calling setAccepted(false).
+
+    \sa QEvent::ignore()
+*/
+#endif
+
 QT_END_NAMESPACE
diff --git a/src/gui/kernel/qgesture.cpp b/src/gui/kernel/qgesture.cpp
index 6231d19..fc8df49 100644
--- a/src/gui/kernel/qgesture.cpp
+++ b/src/gui/kernel/qgesture.cpp
@@ -47,6 +47,7 @@ QT_BEGIN_NAMESPACE
  /*!
     \class QGesture
     \since 4.6
+    \ingroup gestures
 
     \brief The QGesture class represents a gesture, containing properties that
     describe the corresponding user input.
@@ -185,8 +186,55 @@ void QGesture::unsetHotSpot()
     d_func()->isHotSpotSet = false;
 }
 
-// QPanGesture
+/*!
+    \class QPanGesture
+    \since 4.6
+    \brief The QPanGesture class describes a panning gesture made by the user.
+    \ingroup gestures
+
+    \image pangesture.png
+
+    \sa {Gestures Programming}, QPinchGesture, QSwipeGesture
+*/
+
+/*!
+    \property QPanGesture::totalOffset
+    \brief the total offset from the first input position to the current input
+    position
+
+    The total offset measures the total change in position of the user's input
+    covered by the gesture on the input device.
+*/
+
+/*!
+    \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.
+
+    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.
+*/
 
+/*!
+    \property QPanGesture::offset
+    \brief the offset from the previous input position to the current input
+    position
+
+    The offset measures the change in position of the user's input on the
+    input device.
+*/
+
+/*!
+    \property QPanGesture::acceleration
+*/
+
+/*!
+    \internal
+*/
 QPanGesture::QPanGesture(QObject *parent)
     : QGesture(*new QPanGesturePrivate, parent)
 {
@@ -234,8 +282,139 @@ void QPanGesture::setAcceleration(qreal value)
     d_func()->acceleration = value;
 }
 
-// QPinchGesture
+/*!
+    \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
+
+    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
+*/
+
+/*!
+    \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)
 {
@@ -345,8 +524,65 @@ void QPinchGesture::setRotationAngle(qreal value)
     d_func()->rotationAngle = value;
 }
 
-// QSwipeGesture
+/*!
+    \class QSwipeGesture
+    \since 4.6
+    \brief The QSwipeGesture class describes a swipe gesture made by the user.
+    \ingroup gestures
+
+    \image swipegesture.png
+
+    \sa {Gestures Programming}, QPanGesture, QPinchGesture
+*/
+
+/*!
+    \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)
 {
diff --git a/src/gui/kernel/qgesturerecognizer.cpp b/src/gui/kernel/qgesturerecognizer.cpp
index 1998cba..9de3bcc 100644
--- a/src/gui/kernel/qgesturerecognizer.cpp
+++ b/src/gui/kernel/qgesturerecognizer.cpp
@@ -49,6 +49,7 @@ QT_BEGIN_NAMESPACE
    \class QGestureRecognizer
    \since 4.6
    \brief The QGestureRecognizer class provides the infrastructure for gesture recognition.
+   \ingroup gestures
 
    Gesture recognizers are responsible for creating and managing QGesture objects and
    monitoring input events sent to QWidget and QGraphicsObject subclasses.