summaryrefslogtreecommitdiffstats
path: root/doc/src/snippets/gestures/qgesture.cpp
blob: 77f5cc2b5693e6dbd013d567873a97f9d1b6b3fe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

#include "qgesture.h"
#include <private/qgesture_p.h>
#include "qgraphicsitem.h"

QT_BEGIN_NAMESPACE


class QEventFilterProxyGraphicsItem : public QGraphicsItem
{
public:
    QEventFilterProxyGraphicsItem(QGesture *g)
            : gesture(g)
    {
    }
    bool sceneEventFilter(QGraphicsItem *, QEvent *event)
    {
        return gesture ? gesture->filterEvent(event) : false;
    }
    QRectF boundingRect() const { return QRectF(); }
    void paint(QPainter*, const QStyleOptionGraphicsItem*, QWidget*) { }

private:
    QGesture *gesture;
};

/*
    \class QGesture
    \since 4.6

    \brief The QGesture class is the base class for implementing custom
    gestures.

    This class represents both an object that recognizes a gesture out of a set
    of input events (a gesture recognizer), and a gesture object itself that
    can be used to get extended information about the triggered gesture.

    The class has a list of properties that can be queried by the user to get
    some gesture-specific parameters (for example, an offset of a Pan gesture).

    Usually gesture recognizer implements a state machine, storing its state
    internally in the recognizer object. The recognizer receives input events
    through the \l{QGesture::}{filterEvent()} virtual function and decides
    whether the event should change the state of the recognizer by emitting an
    appropriate signal.

    Input events should be either fed to the recognizer one by one with a
    filterEvent() function, or the gesture recognizer should be attached to an
    object it filters events for by specifying it as a parent object. The
    QGesture object installs itself as an event filter to the parent object
    automatically, the unsetObject() function should be used to remove an event
    filter from the parent object. To make a
    gesture that operates on a QGraphicsItem, both the appropriate QGraphicsView
    should be passed as a parent object and setGraphicsItem() functions should
    be used to attach a gesture to a graphics item.

    This is a base class, to create a custom gesture type, you should subclass
    it and implement its pure virtual functions.

    \sa QPanGesture
*/

/* \fn bool QGesture::filterEvent(QEvent *event)

    Parses input \a event and emits a signal when detects a gesture.

    In your reimplementation of this function, if you want to filter the \a
    event out, i.e. stop it being handled further, return true; otherwise
    return false;

    This is a pure virtual function that needs to be implemented in subclasses.
*/

/* \fn void QGesture::started()

    The signal is emitted when the gesture is started. Extended information
    about the gesture is contained in the signal sender object.

    In addition to started(), a triggered() signal should also be emitted.
*/

/* \fn void QGesture::triggered()

    The signal is emitted when the gesture is detected. Extended information
    about the gesture is contained in the signal sender object.
*/

/* \fn void QGesture::finished()

    The signal is emitted when the gesture is finished. Extended information
    about the gesture is contained in the signal sender object.
*/

/* \fn void QGesture::cancelled()

    The signal is emitted when the gesture is cancelled, for example the reset()
    function is called while the gesture was in the process of emitting a
    triggered() signal.  Extended information about the gesture is contained in
    the sender object.
*/


/*
    Creates a new gesture handler object and marks it as a child of \a parent.

    The \a parent object is also the default event source for the gesture,
    meaning that the gesture installs itself as an event filter for the \a
    parent.

    \sa setGraphicsItem()
*/
QGesture::QGesture(QObject *parent)
    : QObject(*new QGesturePrivate, parent)
{
    if (parent)
        parent->installEventFilter(this);
}

/* \internal
 */
QGesture::QGesture(QGesturePrivate &dd, QObject *parent)
    : QObject(dd, parent)
{
    if (parent)
        parent->installEventFilter(this);
}

/*
    Destroys the gesture object.
*/
QGesture::~QGesture()
{
}

/* \internal
 */
bool QGesture::eventFilter(QObject *receiver, QEvent *event)
{
    Q_D(QGesture);
    if (d->graphicsItem && receiver == parent())
        return false;
    return filterEvent(event);
}

/*
    \property QGesture::state

    \brief The current state of the gesture.
*/

/*
  Returns the gesture recognition state.
 */
Qt::GestureState QGesture::state() const
{
    return d_func()->state;
}

/*
  Sets this gesture's recognition state to \a state and emits appropriate
  signals.

  This functions emits the signals according to the old state and the new
  \a state, and it should be called after all the internal properties have been
  initialized.

  \sa started(), triggered(), finished(), cancelled()
 */
void QGesture::updateState(Qt::GestureState state)
{
    Q_D(QGesture);
    if (d->state == state) {
        if (state == Qt::GestureUpdated)
            emit triggered();
        return;
    }
    const Qt::GestureState oldState = d->state;
    d->state = state;
    if (state != Qt::NoGesture && oldState > state) {
        // comparing the state as ints: state should only be changed from
        // started to (optionally) updated and to finished.
        qWarning("QGesture::updateState: incorrect new state");
        return;
    }
    if (oldState == Qt::NoGesture)
        emit started();
    if (state == Qt::GestureUpdated)
        emit triggered();
    else if (state == Qt::GestureFinished)
        emit finished();
    else if (state == Qt::NoGesture)
        emit cancelled();

    if (state == Qt::GestureFinished) {
        // gesture is finished, so we reset the internal state.
        d->state = Qt::NoGesture;
    }
}

/*
    Sets the \a graphicsItem the gesture is filtering events for.

    The gesture will install an event filter to the \a graphicsItem and
    redirect them to the filterEvent() function.

    \sa graphicsItem()
*/
void QGesture::setGraphicsItem(QGraphicsItem *graphicsItem)
{
    Q_D(QGesture);
    if (d->graphicsItem && d->eventFilterProxyGraphicsItem)
        d->graphicsItem->removeSceneEventFilter(d->eventFilterProxyGraphicsItem);
    d->graphicsItem = graphicsItem;
    if (!d->eventFilterProxyGraphicsItem)
        d->eventFilterProxyGraphicsItem = new QEventFilterProxyGraphicsItem(this);
    if (graphicsItem)
        graphicsItem->installSceneEventFilter(d->eventFilterProxyGraphicsItem);
}

/*
    Returns the graphics item the gesture is filtering events for.

    \sa setGraphicsItem()
*/
QGraphicsItem* QGesture::graphicsItem() const
{
    return d_func()->graphicsItem;
}

/* \fn void QGesture::reset()

    Resets the internal state of the gesture. This function might be called by
    the filterEvent() implementation in a derived class, or by the user to
    cancel a gesture.  The base class implementation calls
    updateState(Qt::NoGesture) which emits the cancelled()
    signal if the state() of the gesture indicated it was active.
*/
void QGesture::reset()
{
    updateState(Qt::NoGesture);
}

QT_END_NAMESPACE