1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtGui module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
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 https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qtouchdevice.h"
41#include "qtouchdevice_p.h"
42#include <QList>
43#include <QMutex>
44#include <QCoreApplication>
45
46#include <private/qdebug_p.h>
47#include <private/qlocking_p.h>
48
49QT_BEGIN_NAMESPACE
50
51/*!
52 \class QTouchDevice
53 \brief The QTouchDevice class describes the device from which touch events originate.
54 \since 5.0
55 \ingroup touch
56 \inmodule QtGui
57
58 Each QTouchEvent contains a QTouchDevice pointer to allow accessing
59 device-specific properties like type and capabilities. It is the
60 responsibility of the platform or generic plug-ins to register the
61 available touch devices via QWindowSystemInterface before generating any
62 touch events. Applications do not need to instantiate this class, they
63 should just access the global instances pointed to by QTouchEvent::device().
64*/
65
66/*! \enum QTouchDevice::DeviceType
67
68 This enum represents the type of device that generated a QTouchEvent.
69
70 \value TouchScreen In this type of device, the touch surface and display are integrated. This
71 means the surface and display typically have the same size, such that there
72 is a direct relationship between the touch points' physical positions and the
73 coordinate reported by QTouchEvent::TouchPoint. As a result, Qt allows the
74 user to interact directly with multiple QWidgets and QGraphicsItems at the
75 same time.
76
77 \value TouchPad In this type of device, the touch surface is separate from the display. There
78 is not a direct relationship between the physical touch location and the
79 on-screen coordinates. Instead, they are calculated relative to the current
80 mouse position, and the user must use the touch-pad to move this reference
81 point. Unlike touch-screens, Qt allows users to only interact with a single
82 QWidget or QGraphicsItem at a time.
83*/
84
85/*! \enum QTouchDevice::CapabilityFlag
86
87 This enum is used with QTouchDevice::capabilities() to indicate what kind of information the
88 touch device or its driver can provide.
89
90 \value Position Indicates that position information is available, meaning
91 that the pos() family of functions in the touch points return valid points.
92
93 \value Area Indicates that touch area information is available, meaning that the rect() family
94 of functions in the touch points return valid rectangles.
95
96 \value Pressure Indicates that pressure information is available, meaning that pressure()
97 returns a valid value.
98
99 \value Velocity Indicates that velocity information is available, meaning that velocity()
100 returns a valid vector.
101
102 \value RawPositions Indicates that the list returned by QTouchEvent::TouchPoint::rawScreenPositions()
103 may contain one or more positions for each touch point. This is relevant when
104 the touch input gets filtered or corrected on driver level.
105
106 \value NormalizedPosition Indicates that the normalized position is available, meaning that normalizedPos()
107 returns a valid value.
108
109 \value MouseEmulation Indicates that the device synthesizes mouse events.
110 This enum value has been introduced in Qt 5.5.
111*/
112
113/*!
114 Creates a new touch device instance.
115 By default the name is empty, the only capability is Position and type is TouchScreen.
116 */
117QTouchDevice::QTouchDevice()
118 : d(new QTouchDevicePrivate)
119{
120}
121
122/*!
123 Destroys a touch device instance.
124 */
125QTouchDevice::~QTouchDevice()
126{
127 delete d;
128}
129
130/*!
131 Returns the touch device type.
132*/
133QTouchDevice::DeviceType QTouchDevice::type() const
134{
135 return d->type;
136}
137
138/*!
139 Returns the touch device capabilities.
140 */
141QTouchDevice::Capabilities QTouchDevice::capabilities() const
142{
143 return d->caps;
144}
145
146/*!
147 Returns the maximum number of simultaneous touch points (fingers) that
148 can be detected.
149 \since 5.2
150 */
151int QTouchDevice::maximumTouchPoints() const
152{
153 return d->maxTouchPoints;
154}
155
156/*!
157 Returns the touch device name.
158
159 This string may often be empty. It is however useful for systems that have
160 more than one touch input device because there it can be used to
161 differentiate between the devices (i.e. to tell from which device a
162 QTouchEvent originates from).
163*/
164QString QTouchDevice::name() const
165{
166 return d->name;
167}
168
169/*!
170 Sets the device type \a devType.
171 */
172void QTouchDevice::setType(DeviceType devType)
173{
174 d->type = devType;
175}
176
177/*!
178 Sets the capabilities \a caps supported by the device and its driver.
179 */
180void QTouchDevice::setCapabilities(Capabilities caps)
181{
182 d->caps = caps;
183}
184
185/*!
186 Sets the maximum number of simultaneous touchpoints \a max
187 supported by the device and its driver.
188 */
189void QTouchDevice::setMaximumTouchPoints(int max)
190{
191 d->maxTouchPoints = max;
192}
193
194/*!
195 Sets the \a name (a unique identifier) for the device. In most systems it is
196 enough to leave this unset and keep the default empty name. This identifier
197 becomes important when having multiple touch devices and a need to
198 differentiate between them.
199 */
200void QTouchDevice::setName(const QString &name)
201{
202 d->name = name;
203}
204
205static QBasicMutex devicesMutex;
206
207struct TouchDevices {
208 TouchDevices();
209 QList<const QTouchDevice *> list;
210};
211Q_GLOBAL_STATIC(TouchDevices, deviceList)
212
213TouchDevices::TouchDevices()
214{
215 qAddPostRoutine([]{
216 const auto locker = qt_scoped_lock(mutex&: devicesMutex);
217 qDeleteAll(c: qExchange(t&: deviceList->list, newValue: {}));
218 });
219}
220
221/*!
222 Returns a list of all registered devices.
223
224 \note The returned list cannot be used to add new devices. To add a simulated
225 touch screen for an autotest, QTest::createTouchDevice() can be used.
226 To add real touch screens to QPA plugins, the private
227 \c QWindowSystemInterface::registerTouchDevice() function can be used.
228 */
229QList<const QTouchDevice *> QTouchDevice::devices()
230{
231 const auto locker = qt_scoped_lock(mutex&: devicesMutex);
232 return deviceList->list;
233}
234
235/*!
236 \internal
237 */
238bool QTouchDevicePrivate::isRegistered(const QTouchDevice *dev)
239{
240 const auto locker = qt_scoped_lock(mutex&: devicesMutex);
241 return deviceList->list.contains(t: dev);
242}
243
244const QTouchDevice *QTouchDevicePrivate::deviceById(quint8 id)
245{
246 const auto locker = qt_scoped_lock(mutex&: devicesMutex);
247 for (const QTouchDevice *dev : qAsConst(t&: deviceList->list))
248 if (QTouchDevicePrivate::get(q: const_cast<QTouchDevice *>(dev))->id == id)
249 return dev;
250 return nullptr;
251}
252
253/*!
254 \internal
255 */
256void QTouchDevicePrivate::registerDevice(const QTouchDevice *dev)
257{
258 const auto locker = qt_scoped_lock(mutex&: devicesMutex);
259 deviceList->list.append(t: dev);
260}
261
262/*!
263 \internal
264 */
265void QTouchDevicePrivate::unregisterDevice(const QTouchDevice *dev)
266{
267 const auto locker = qt_scoped_lock(mutex&: devicesMutex);
268 deviceList->list.removeOne(t: dev);
269}
270
271#ifndef QT_NO_DEBUG_STREAM
272QDebug operator<<(QDebug debug, const QTouchDevice *device)
273{
274 QDebugStateSaver saver(debug);
275 debug.nospace();
276 debug.noquote();
277 debug << "QTouchDevice(";
278 if (device) {
279 debug << '"' << device->name() << "\", type=";
280 QtDebugUtils::formatQEnum(debug, value: device->type());
281 debug << ", capabilities=";
282 QtDebugUtils::formatQFlags(debug, value: device->capabilities());
283 debug << ", maximumTouchPoints=" << device->maximumTouchPoints();
284 } else {
285 debug << '0';
286 }
287 debug << ')';
288 return debug;
289}
290#endif // !QT_NO_DEBUG_STREAM
291
292QT_END_NAMESPACE
293

source code of qtbase/src/gui/kernel/qtouchdevice.cpp