From 20fd14900702103442ee95dd025706c6f263c6f6 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Fri, 16 Oct 2009 17:07:48 +0200 Subject: Doc: Documentation for gesture features. Still a moving target. Reviewed-by: Trust Me --- doc/src/diagrams/gestures/pangesture.svg | 273 +++++++++++++++++ doc/src/diagrams/gestures/pinchgesture.svg | 341 +++++++++++++++++++++ doc/src/diagrams/gestures/swipegesture-details.svg | 168 ++++++++++ doc/src/diagrams/gestures/swipegesture.svg | 158 ++++++++++ doc/src/frameworks-technologies/gestures.qdoc | 20 +- doc/src/images/pangesture.png | Bin 0 -> 7153 bytes doc/src/images/pinchgesture.png | Bin 0 -> 10094 bytes doc/src/images/swipegesture.png | Bin 0 -> 6864 bytes examples/gestures/imagegestures/imagewidget.cpp | 7 +- examples/gestures/imagegestures/imagewidget.h | 16 +- examples/gestures/imagegestures/mainwidget.h | 2 + src/gui/kernel/qapplication.cpp | 2 +- src/gui/kernel/qevent.cpp | 42 +++ src/gui/kernel/qgesture.cpp | 242 ++++++++++++++- src/gui/kernel/qgesturerecognizer.cpp | 1 + 15 files changed, 1246 insertions(+), 26 deletions(-) create mode 100644 doc/src/diagrams/gestures/pangesture.svg create mode 100644 doc/src/diagrams/gestures/pinchgesture.svg create mode 100644 doc/src/diagrams/gestures/swipegesture-details.svg create mode 100644 doc/src/diagrams/gestures/swipegesture.svg create mode 100644 doc/src/images/pangesture.png create mode 100644 doc/src/images/pinchgesture.png create mode 100644 doc/src/images/swipegesture.png diff --git a/doc/src/diagrams/gestures/pangesture.svg b/doc/src/diagrams/gestures/pangesture.svg new file mode 100644 index 0000000..c5b95ca --- /dev/null +++ b/doc/src/diagrams/gestures/pangesture.svg @@ -0,0 +1,273 @@ + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/src/diagrams/gestures/pinchgesture.svg b/doc/src/diagrams/gestures/pinchgesture.svg new file mode 100644 index 0000000..1c520b9 --- /dev/null +++ b/doc/src/diagrams/gestures/pinchgesture.svg @@ -0,0 +1,341 @@ + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/src/diagrams/gestures/swipegesture-details.svg b/doc/src/diagrams/gestures/swipegesture-details.svg new file mode 100644 index 0000000..0f7de5b --- /dev/null +++ b/doc/src/diagrams/gestures/swipegesture-details.svg @@ -0,0 +1,168 @@ + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + diff --git a/doc/src/diagrams/gestures/swipegesture.svg b/doc/src/diagrams/gestures/swipegesture.svg new file mode 100644 index 0000000..fc60a4d --- /dev/null +++ b/doc/src/diagrams/gestures/swipegesture.svg @@ -0,0 +1,158 @@ + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + diff --git a/doc/src/frameworks-technologies/gestures.qdoc b/doc/src/frameworks-technologies/gestures.qdoc index e5947a2..a619fe8 100644 --- a/doc/src/frameworks-technologies/gestures.qdoc +++ b/doc/src/frameworks-technologies/gestures.qdoc @@ -41,10 +41,9 @@ /*! \page gestures-overview.html - \startpage index.html Qt Reference Documentation - \title Gestures Programming \ingroup frameworks-technologies + \startpage index.html Qt Reference Documentation \brief An overview of the Qt support for Gesture programming. @@ -60,10 +59,11 @@ \section1 Overview QGesture is the central class in Qt's gesture framework, providing a container - for information about gestures performed by the user, such as panning, pinching - and swiping. QGesture exposes properties that give general information that is - common to all gestures, and these can be extended to provide additional - gesture-specific information. + for information about gestures performed by the user. QGesture exposes + properties that give general information that is common to all gestures, and + these can be extended to provide additional gesture-specific information. + Common panning, pinching and swiping gestures are represented by specialized + classes: QPanGesture, QPinchGesture and QSwipeGesture. Developers can also implement new gestures by subclassing and extending the QGestureRecognizer class. Adding support for a new gesture involves implementing @@ -80,7 +80,7 @@ required gesture type. The standard types are defined by the Qt::GestureType enum and include many commonly used gestures. - \snippet examples/gestures/imageviewer/imagewidget.cpp enable gestures + \snippet examples/gestures/imagegestures/imagewidget.cpp enable gestures In the above code, the gesture is set up in the constructor of the target object itself. @@ -93,18 +93,18 @@ \l{QWidget::}{event()} handler function and delegates gesture events to a specialized gestureEvent() function: - \snippet examples/gestures/imageviewer/imagewidget.cpp event handler + \snippet examples/gestures/imagegestures/imagewidget.cpp event handler The gesture events delivered to the target object can be examined individually and dealt with appropriately: - \snippet examples/gestures/imageviewer/imagewidget.cpp gesture event handler + \snippet examples/gestures/imagegestures/imagewidget.cpp gesture event handler Responding to a gesture is simply a matter of obtaining the QGesture object delivered in the QGestureEvent sent to the target object and examining the information it contains. - \snippet examples/gestures/imageviewer/imagewidget.cpp swipe function + \snippet examples/gestures/imagegestures/imagewidget.cpp swipe function Here, we examine the direction in which the user swiped the widget and modify its contents accordingly. diff --git a/doc/src/images/pangesture.png b/doc/src/images/pangesture.png new file mode 100644 index 0000000..24caf91 Binary files /dev/null and b/doc/src/images/pangesture.png differ diff --git a/doc/src/images/pinchgesture.png b/doc/src/images/pinchgesture.png new file mode 100644 index 0000000..95614c4 Binary files /dev/null and b/doc/src/images/pinchgesture.png differ diff --git a/doc/src/images/swipegesture.png b/doc/src/images/swipegesture.png new file mode 100644 index 0000000..0b7d35a Binary files /dev/null and b/doc/src/images/swipegesture.png differ diff --git a/examples/gestures/imagegestures/imagewidget.cpp b/examples/gestures/imagegestures/imagewidget.cpp index c4a4e50..95525c5 100644 --- a/examples/gestures/imagegestures/imagewidget.cpp +++ b/examples/gestures/imagegestures/imagewidget.cpp @@ -43,6 +43,7 @@ #include +//! [constructor] ImageWidget::ImageWidget(QWidget *parent) : QWidget(parent), position(0), @@ -52,19 +53,15 @@ ImageWidget::ImageWidget(QWidget *parent) scaleFactor(1) { - setObjectName("ImageWidget"); setMinimumSize(QSize(100,100)); - setAttribute(Qt::WA_PaintOnScreen); - setAttribute(Qt::WA_OpaquePaintEvent); - setAttribute(Qt::WA_NoSystemBackground); - //! [enable gestures] grabGesture(Qt::PanGesture); grabGesture(Qt::PinchGesture); grabGesture(Qt::SwipeGesture); //! [enable gestures] } +//! [constructor] //! [event handler] bool ImageWidget::event(QEvent *event) diff --git a/examples/gestures/imagegestures/imagewidget.h b/examples/gestures/imagegestures/imagewidget.h index 7b91fbf..56e2316 100644 --- a/examples/gestures/imagegestures/imagewidget.h +++ b/examples/gestures/imagegestures/imagewidget.h @@ -53,28 +53,28 @@ class QPinchGesture; class QSwipeGesture; QT_END_NAMESPACE +//! [class definition begin] class ImageWidget : public QWidget { Q_OBJECT public: ImageWidget(QWidget *parent = 0); - void openDirectory(const QString &path); protected: - bool event(QEvent*); - bool gestureEvent(QGestureEvent*); - void paintEvent(QPaintEvent*); - void resizeEvent(QResizeEvent*); - void mouseDoubleClickEvent(QMouseEvent*); + bool event(QEvent *event); + void paintEvent(QPaintEvent *event); + void resizeEvent(QResizeEvent *event); + void mouseDoubleClickEvent(QMouseEvent *event); private: + bool gestureEvent(QGestureEvent *event); void panTriggered(QPanGesture*); void pinchTriggered(QPinchGesture*); void swipeTriggered(QSwipeGesture*); +//! [class definition begin] -private: void updateImage(); QImage loadImage(const QString &fileName); void loadImage(); @@ -93,6 +93,8 @@ private: float verticalOffset; float rotationAngle; float scaleFactor; +//! [class definition end] }; +//! [class definition end] #endif diff --git a/examples/gestures/imagegestures/mainwidget.h b/examples/gestures/imagegestures/mainwidget.h index 1a99155..71b09b0 100644 --- a/examples/gestures/imagegestures/mainwidget.h +++ b/examples/gestures/imagegestures/mainwidget.h @@ -44,6 +44,8 @@ #include +class ImageWidget; + class MainWidget : public QMainWindow { Q_OBJECT 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. -- cgit v0.12