diff options
Diffstat (limited to 'doc/src/frameworks-technologies/gestures.qdoc')
| -rw-r--r-- | doc/src/frameworks-technologies/gestures.qdoc | 49 |
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: |