summaryrefslogtreecommitdiffstats
path: root/doc/src/frameworks-technologies/gestures.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/frameworks-technologies/gestures.qdoc')
-rw-r--r--doc/src/frameworks-technologies/gestures.qdoc49
1 files changed, 47 insertions, 2 deletions
diff --git a/doc/src/frameworks-technologies/gestures.qdoc b/doc/src/frameworks-technologies/gestures.qdoc
index 927df22..f7c8312 100644
--- a/doc/src/frameworks-technologies/gestures.qdoc
+++ b/doc/src/frameworks-technologies/gestures.qdoc
@@ -60,7 +60,8 @@
\section1 Using Standard Gestures with Widgets
Gestures can be enabled for instances of QWidget and QGraphicsObject subclasses.
- An object that accepts gesture input is referred to as a \e{target object}.
+ An object that accepts gesture input is referred to throughout the documentation
+ as a \e{target object}.
To enable a gesture for a target object, call its QWidget::grabGesture() or
QGraphicsObject::grabGesture() function with an argument describing the
@@ -69,13 +70,57 @@
\snippet examples/gestures/imagegestures/imagewidget.cpp enable gestures
- In the above code, the gesture is set up in the constructor of the target object
+ In the above code, the gestures are set up in the constructor of the target object
itself.
+ \section1 Handling Events
+
When the user performs a gesture, QGestureEvent events will be delivered to the
target object, and these can be handled by reimplementing the QWidget::event()
handler function for widgets or QGraphicsItem::sceneEvent() for graphics objects.
+ As one target object can subscribe to more than one gesture type, the QGestureEvent
+ can contain more than one QGesture, indicating several possible gestures are active
+ at the same time. It is then up to the widget to determine how to handle those
+ multiple gestures and choose if some should be canceled in favor of others.
+
+ Each QGesture contained within a QGestureEvent object can be accepted() or ignored()
+ individually, or all together. Additionally, you can query the individual QGesture
+ data objects (the state) using several getters.
+
+ \section2 Standard Procedure for Event Handling
+
+ A QGesture is by default accepted when it arrives at your widget. However, it is good
+ practice to always explicitly accept or reject a gesture. The general rule is that, if
+ you accept a gesture, you are using it. If you are ignoring it you are not interested
+ in it. Ignoring a gesture may mean it gets offered to another target object, or it will
+ get canceled.
+
+ Each QGesture has several states it goes through; there is a well defined way to change
+ the state, typically the user input is the cause of state changes (by starting and
+ stopping interaction, for instance) but the widget can also cause state changes.
+
+ The first time a particular QGesture is delivered to a widget or graphics item, it will
+ be in the Qt::GestureStarted state. The way you handle the gesture at this point
+ influences whether you can interact with it later.
+
+ \list
+ \o Accepting the gesture means the widget acts on the gesture and there will follow
+ gestures with the Qt::GestureUpdatedstate.
+ \o Ignoring the gesture will mean the gesture will never be offered to you again.
+ It will be offered to a parent widget or item as well.
+ \o Calling setGestureCancelPolicy() on the gesture when it is in its starting state,
+ and is also accepted can cause other gestures to be canceled.
+ \endlist
+
+ Using QGesture::CancelAllInContext to cancel a gesture will cause all gestures, in any
+ state, to be canceled unless they are explicitly accepted. This means that active
+ gestures on children will get canceled. It also means that gestures delivered in the
+ same QGestureEvent will get canceled if the widget ignores them. This can be a useful
+ way to filter out all gestures except the one you are interested in.
+
+ \section2 Example Event Handling
+
For convenience, the \l{Image Gestures Example} reimplements the general
\l{QWidget::}{event()} handler function and delegates gesture events to a
specialized gestureEvent() function: