Update copyright headers
[qt:qt.git] / doc / src / frameworks-technologies / gestures.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page gestures-overview.html
30     \title Gestures Programming
31     \startpage index.html Qt Reference Documentation
32     \ingroup technology-apis
33     \ingroup qt-gui-concepts
34
35     \brief An overview of Qt support for Gesture programming.
36
37     Qt includes a framework for gesture programming that has the ability
38     to form gestures from a series of events, independently of the input methods
39     used. A gesture could be a particular movement of a mouse, a touch screen
40     action, or a series of events from some other source. The nature of the input,
41     the interpretation of the gesture and the action taken are the choice of the
42     developer.
43
44     \tableofcontents
45
46     \section1 Overview
47
48     QGesture is the central class in Qt's gesture framework, providing a container
49     for information about gestures performed by the user. QGesture exposes
50     properties that give general information that is common to all gestures, and
51     these can be extended to provide additional gesture-specific information.
52     Common panning, pinching and swiping gestures are represented by specialized
53     classes: QPanGesture, QPinchGesture and QSwipeGesture.
54
55     Developers can also implement new gestures by subclassing and extending the
56     QGestureRecognizer class. Adding support for a new gesture involves implementing
57     code to recognize the gesture from input events. This is described in the
58     \l{Creating Your Own Gesture Recognizer} section.
59
60     \section1 Using Standard Gestures with Widgets
61
62     Gestures can be enabled for instances of QWidget and QGraphicsObject subclasses.
63     An object that accepts gesture input is referred to throughout the documentation
64     as a \e{target object}.
65
66     To enable a gesture for a target object, call its QWidget::grabGesture() or
67     QGraphicsObject::grabGesture() function with an argument describing the
68     required gesture type. The standard types are defined by the Qt::GestureType
69     enum and include many commonly used gestures.
70
71     \snippet examples/gestures/imagegestures/imagewidget.cpp enable gestures
72
73     In the above code, the gestures are set up in the constructor of the target object
74     itself.
75
76     \section1 Handling Events
77
78     When the user performs a gesture, QGestureEvent events will be delivered to the
79     target object, and these can be handled by reimplementing the QWidget::event()
80     handler function for widgets or QGraphicsItem::sceneEvent() for graphics objects.
81
82     As one target object can subscribe to more than one gesture type, the QGestureEvent
83     can contain more than one QGesture, indicating several possible gestures are active
84     at the same time. It is then up to the widget to determine how to handle those
85     multiple gestures and choose if some should be canceled in favor of others.
86
87     Each QGesture contained within a QGestureEvent object can be accepted() or ignored()
88     individually, or all together. Additionally, you can query the individual QGesture
89     data objects (the state) using several getters.
90
91     \section2 Standard Procedure for Event Handling
92
93     A QGesture is by default accepted when it arrives at your widget. However, it is good
94     practice to always explicitly accept or reject a gesture. The general rule is that, if
95     you accept a gesture, you are using it. If you are ignoring it you are not interested
96     in it. Ignoring a gesture may mean it gets offered to another target object, or it will
97     get canceled.
98
99     Each QGesture has several states it goes through; there is a well defined way to change
100     the state, typically the user input is the cause of state changes (by starting and
101     stopping interaction, for instance) but the widget can also cause state changes.
102
103     The first time a particular QGesture is delivered to a widget or graphics item, it will
104     be in the Qt::GestureStarted state. The way you handle the gesture at this point
105     influences whether you can interact with it later.
106
107     \list
108     \o Accepting the gesture means the widget acts on the gesture and there will follow
109        gestures with the Qt::GestureUpdatedstate.
110     \o Ignoring the gesture will mean the gesture will never be offered to you again.
111        It will be offered to a parent widget or item as well.
112     \o Calling setGestureCancelPolicy() on the gesture when it is in its starting state,
113        and is also accepted can cause other gestures to be canceled.
114     \endlist
115
116     Using QGesture::CancelAllInContext to cancel a gesture will cause all gestures, in any
117     state, to be canceled unless they are explicitly accepted. This means that active
118     gestures on children will get canceled. It also means that gestures delivered in the
119     same QGestureEvent will get canceled if the widget ignores them. This can be a useful
120     way to filter out all gestures except the one you are interested in.
121
122     \section2 Example Event Handling
123
124     For convenience, the \l{Image Gestures Example} reimplements the general
125     \l{QWidget::}{event()} handler function and delegates gesture events to a
126     specialized gestureEvent() function:
127
128     \snippet examples/gestures/imagegestures/imagewidget.cpp event handler
129
130     The gesture events delivered to the target object can be examined individually
131     and dealt with appropriately:
132
133     \snippet examples/gestures/imagegestures/imagewidget.cpp gesture event handler
134
135     Responding to a gesture is simply a matter of obtaining the QGesture object
136     delivered in the QGestureEvent sent to the target object and examining the
137     information it contains.
138
139     \snippet examples/gestures/imagegestures/imagewidget.cpp swipe function
140
141     Here, we examine the direction in which the user swiped the widget and modify
142     its contents accordingly.
143
144
145     \section1 Creating Your Own Gesture Recognizer
146
147     Adding support for a new gesture involves creating and registering a new gesture
148     recognizer. Depending on the recognition process for the gesture, it may also
149     involve creating a new gesture object.
150
151     To create a new recognizer, you need to subclass QGestureRecognizer to create a
152     custom recognizer class. There is one virtual function that you must reimplement
153     and two others that can be reimplemented as required.
154
155     \section2 Filtering Input Events
156
157     The \l{QGestureRecognizer::}{recognize()} function must be reimplemented.
158     This function handles and filters the incoming input events for the target objects
159     and determines whether or not they correspond to the gesture the recognizer is
160     looking for.
161
162     Although the logic for gesture recognition is implemented in this function,
163     possibly using a state machine based on the Qt::GestureState enums, you can store
164     persistent information about the state of the recognition process in the QGesture
165     object supplied.
166
167     Your \l{QGestureRecognizer::}{recognize()} function must return a value of
168     QGestureRecognizer::Result that indicates the state of recognition for a given gesture and
169     target object. This determines whether or not a gesture event will be delivered
170     to a target object.
171
172     \section2 Custom Gestures
173
174     If you choose to represent a gesture by a custom QGesture subclass, you will need to
175     reimplement the \l{QGestureRecognizer::}{create()} function to construct
176     instances of your gesture class instead of standard QGesture instances. Alternatively,
177     you may want to use standard QGesture instances, but add additional dynamic properties
178     to them to express specific details of the gesture you want to handle.
179
180     \section2 Resetting Gestures
181
182     If you use custom gesture objects that need to be reset or otherwise specially
183     handled when a gesture is canceled, you need to reimplement the
184     \l{QGestureRecognizer::}{reset()} function to perform these special tasks.
185
186     Note that QGesture objects are only created once for each combination of target object
187     and gesture type, and they might be reused every time the user attempts to perform the
188     same gesture type on the target object. As a result, it can be useful to reimplement
189     the \l{QGestureRecognizer::}{reset()} function to clean up after each previous attempt
190     at recognizing a gesture.
191
192
193     \section1 Using a New Gesture Recognizer
194
195     To use a gesture recognizer, construct an instance of your QGestureRecognizer
196     subclass, and register it with the application with
197     QGestureRecognizer::registerRecognizer(). A recognizer for a given type of
198     gesture can be removed with QGestureRecognizer::unregisterRecognizer().
199
200
201     \section1 Further Reading
202
203     The \l{gestures/imagegestures}{Image Gestures Example} shows how to enable
204     gestures for a widget in a simple image viewer application.
205 */