summaryrefslogtreecommitdiffstats
path: root/src/gui/kernel/qtouchdevice.cpp
blob: a74c8230d0c23f3933b73bcc387e2127cc64d517 (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
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: http://www.qt-project.org/
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** GNU Lesser General Public License Usage
** 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.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU General
** Public License version 3.0 as published by the Free Software Foundation
** and appearing in the file LICENSE.GPL included in the packaging of this
** file. Please review the following information to ensure the GNU General
** Public License version 3.0 requirements will be met:
** http://www.gnu.org/copyleft/gpl.html.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms and
** conditions contained in a signed written agreement between you and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

#include "qtouchdevice.h"
#include "qtouchdevice_p.h"
#include <QList>
#include <QMutex>
#include <QCoreApplication>

QT_BEGIN_NAMESPACE

/*!
    \class QTouchDevice
    \brief The QTouchDevice class describes the device from with touch events originate.
    \since 5.0
    \ingroup touch

    Each QTouchEvent contains a QTouchDevice pointer to allow accessing
    device-specific properties like type and capabilities. It is the
    responsibility of the platform or generic plug-ins to register the
    available touch devices via QWindowSystemInterface before generating any
    touch events. Applications do not need to instantiate this class, they
    should just access the global instances pointed to by QTouchEvent::device().
*/

/*! \enum QTouchDevice::DeviceType

    This enum represents the type of device that generated a QTouchEvent.

    \value TouchScreen In this type of device, the touch surface and display are integrated. This
                       means the surface and display typically have the same size, such that there
                       is a direct relationship between the touch points' physical positions and the
                       coordinate reported by QTouchEvent::TouchPoint. As a result, Qt allows the
                       user to interact directly with multiple QWidgets and QGraphicsItems at the
                       same time.

    \value TouchPad In this type of device, the touch surface is separate from the display. There
                    is not a direct relationship between the physical touch location and the
                    on-screen coordinates. Instead, they are calculated relative to the current
                    mouse position, and the user must use the touch-pad to move this reference
                    point. Unlike touch-screens, Qt allows users to only interact with a single
                    QWidget or QGraphicsItem at a time.
*/

/*! \enum QTouchDevice::CapabilityFlag

    This enum is used with QTouchDevice::capabilities() to indicate what kind of information the
    touch device or its driver can provide.

    \value Position Indicates that position information is available, meaning
                    that the pos() family of functions in the touch points return valid points.

    \value Area Indicates that touch area information is available, meaning that the rect() family
                of functions in the touch points return valid rectangles.

    \value Pressure Indicates that pressure information is available, meaning that pressure()
                    returns a valid value.

    \value Velocity Indicates that velocity information is available, meaning that velocity()
                    returns a valid vector.

    \value RawPositions Indicates that the list returned by QTouchEvent::TouchPoint::rawScreenPositions()
                        may contain one or more positions for each touch point. This is relevant when
                        the touch input gets filtered or corrected on driver level.

    \value NormalizedPosition Indicates that the normalized position is available, meaning that normalizedPos()
                              returns a valid value.
*/

/*!
  Creates a new touch device instance.
  By default the name is empty, the only capability is Position and type is TouchScreen.
  */
QTouchDevice::QTouchDevice()
    : d(new QTouchDevicePrivate)
{
}

QTouchDevice::~QTouchDevice()
{
    delete d;
}

/*!
    Returns the touch device type.
*/
QTouchDevice::DeviceType QTouchDevice::type() const
{
    return d->type;
}

/*!
    Returns the touch device capabilities.
  */
QTouchDevice::Capabilities QTouchDevice::capabilities() const
{
    return d->caps;
}

/*!
    Returns the touch device name.

    This string may often be empty. It is however useful for systems that have
    more than one touch input device because there it can be used to
    differentiate between the devices (i.e. to tell from which device a
    QTouchEvent originates from).
*/
QString QTouchDevice::name() const
{
    return d->name;
}

/*!
  Sets the device type.
  */
void QTouchDevice::setType(DeviceType devType)
{
    d->type = devType;
}

/*!
  Sets the capabilities supported by the device and its driver.
  */
void QTouchDevice::setCapabilities(Capabilities caps)
{
    d->caps = caps;
}

/*!
  Sets the name (a unique identifier) for the device. In most systems it is
  enough to leave this unset and keep the default empty name. This identifier
  becomes important when having multiple touch devices and a need to
  differentiate between them.
  */
void QTouchDevice::setName(const QString &name)
{
    d->name = name;
}

typedef QList<QTouchDevice *> TouchDevices;
Q_GLOBAL_STATIC(TouchDevices, deviceList)
Q_GLOBAL_STATIC(QMutex, devicesMutex)

static void cleanupDevicesList()
{
    QMutexLocker lock(devicesMutex());
    qDeleteAll(*deviceList());
    deviceList()->clear();
}

/*!
  Returns a list of all registered devices.

  \note The returned list cannot be used to add new devices. Use QWindowSystemInterface::registerTouchDevice() instead.
  */
QList<const QTouchDevice *> QTouchDevice::devices()
{
    QMutexLocker lock(devicesMutex());
    QList<QTouchDevice *> *devList = deviceList();
    QList<const QTouchDevice *> constDevList;
    for (int i = 0, count = devList->count(); i != count; ++i)
        constDevList.append(devList->at(i));
    return constDevList;
}

/*!
  \internal
  */
bool QTouchDevicePrivate::isRegistered(QTouchDevice *dev)
{
    QMutexLocker lock(devicesMutex());
    return deviceList()->contains(dev);
}

/*!
  \internal
  */
void QTouchDevicePrivate::registerDevice(QTouchDevice *dev)
{
    QMutexLocker lock(devicesMutex());
    if (deviceList()->isEmpty())
        qAddPostRoutine(cleanupDevicesList);
    deviceList()->append(dev);
}

QT_END_NAMESPACE