src/gui/kernel/qtouchdevice.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   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 Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/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 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qtouchdevice.h"
  43 #include "qtouchdevice_p.h"
  44 #include <QList>
  45 #include <QMutex>
  46 #include <QCoreApplication>
  47
  48 QT_BEGIN_NAMESPACE
  49
  50 /*!
  51     \class QTouchDevice
  52     \brief The QTouchDevice class describes the device from with touch events originate.
  53     \since 5.0
  54     \ingroup touch
  55     \inmodule QtGui
  56
  57     Each QTouchEvent contains a QTouchDevice pointer to allow accessing
  58     device-specific properties like type and capabilities. It is the
  59     responsibility of the platform or generic plug-ins to register the
  60     available touch devices via QWindowSystemInterface before generating any
  61     touch events. Applications do not need to instantiate this class, they
  62     should just access the global instances pointed to by QTouchEvent::device().
  63 */
  64
  65 /*! \enum QTouchDevice::DeviceType
  66
  67     This enum represents the type of device that generated a QTouchEvent.
  68
  69     \value TouchScreen In this type of device, the touch surface and display are integrated. This
  70                        means the surface and display typically have the same size, such that there
  71                        is a direct relationship between the touch points' physical positions and the
  72                        coordinate reported by QTouchEvent::TouchPoint. As a result, Qt allows the
  73                        user to interact directly with multiple QWidgets and QGraphicsItems at the
  74                        same time.
  75
  76     \value TouchPad In this type of device, the touch surface is separate from the display. There
  77                     is not a direct relationship between the physical touch location and the
  78                     on-screen coordinates. Instead, they are calculated relative to the current
  79                     mouse position, and the user must use the touch-pad to move this reference
  80                     point. Unlike touch-screens, Qt allows users to only interact with a single
  81                     QWidget or QGraphicsItem at a time.
  82 */
  83
  84 /*! \enum QTouchDevice::CapabilityFlag
  85
  86     This enum is used with QTouchDevice::capabilities() to indicate what kind of information the
  87     touch device or its driver can provide.
  88
  89     \value Position Indicates that position information is available, meaning
  90                     that the pos() family of functions in the touch points return valid points.
  91
  92     \value Area Indicates that touch area information is available, meaning that the rect() family
  93                 of functions in the touch points return valid rectangles.
  94
  95     \value Pressure Indicates that pressure information is available, meaning that pressure()
  96                     returns a valid value.
  97
  98     \value Velocity Indicates that velocity information is available, meaning that velocity()
  99                     returns a valid vector.
 100
 101     \value RawPositions Indicates that the list returned by QTouchEvent::TouchPoint::rawScreenPositions()
 102                         may contain one or more positions for each touch point. This is relevant when
 103                         the touch input gets filtered or corrected on driver level.
 104
 105     \value NormalizedPosition Indicates that the normalized position is available, meaning that normalizedPos()
 106                               returns a valid value.
 107 */
 108
 109 /*!
 110   Creates a new touch device instance.
 111   By default the name is empty, the only capability is Position and type is TouchScreen.
 112   */
 113 QTouchDevice::QTouchDevice()
 114     : d(new QTouchDevicePrivate)
 115 {
 116 }
 117
 118 /*!
 119   Destroys a touch device instance.
 120   */
 121 QTouchDevice::~QTouchDevice()
 122 {
 123     delete d;
 124 }
 125
 126 /*!
 127     Returns the touch device type.
 128 */
 129 QTouchDevice::DeviceType QTouchDevice::type() const
 130 {
 131     return d->type;
 132 }
 133
 134 /*!
 135     Returns the touch device capabilities.
 136   */
 137 QTouchDevice::Capabilities QTouchDevice::capabilities() const
 138 {
 139     return d->caps;
 140 }
 141
 142 /*!
 143     Returns the touch device name.
 144
 145     This string may often be empty. It is however useful for systems that have
 146     more than one touch input device because there it can be used to
 147     differentiate between the devices (i.e. to tell from which device a
 148     QTouchEvent originates from).
 149 */
 150 QString QTouchDevice::name() const
 151 {
 152     return d->name;
 153 }
 154
 155 /*!
 156   Sets the device type \a devType.
 157   */
 158 void QTouchDevice::setType(DeviceType devType)
 159 {
 160     d->type = devType;
 161 }
 162
 163 /*!
 164   Sets the capabilities \a caps supported by the device and its driver.
 165   */
 166 void QTouchDevice::setCapabilities(Capabilities caps)
 167 {
 168     d->caps = caps;
 169 }
 170
 171 /*!
 172   Sets the \a name (a unique identifier) for the device. In most systems it is
 173   enough to leave this unset and keep the default empty name. This identifier
 174   becomes important when having multiple touch devices and a need to
 175   differentiate between them.
 176   */
 177 void QTouchDevice::setName(const QString &name)
 178 {
 179     d->name = name;
 180 }
 181
 182 typedef QList<QTouchDevice *> TouchDevices;
 183 Q_GLOBAL_STATIC(TouchDevices, deviceList)
 184 static QBasicMutex devicesMutex;
 185
 186 static void cleanupDevicesList()
 187 {
 188     QMutexLocker lock(&devicesMutex);
 189     qDeleteAll(*deviceList());
 190     deviceList()->clear();
 191 }
 192
 193 /*!
 194   Returns a list of all registered devices.
 195
 196   \note The returned list cannot be used to add new devices. Use QWindowSystemInterface::registerTouchDevice() instead.
 197   */
 198 QList<const QTouchDevice *> QTouchDevice::devices()
 199 {
 200     QMutexLocker lock(&devicesMutex);
 201     QList<QTouchDevice *> *devList = deviceList();
 202     QList<const QTouchDevice *> constDevList;
 203     for (int i = 0, count = devList->count(); i != count; ++i)
 204         constDevList.append(devList->at(i));
 205     return constDevList;
 206 }
 207
 208 /*!
 209   \internal
 210   */
 211 bool QTouchDevicePrivate::isRegistered(QTouchDevice *dev)
 212 {
 213     QMutexLocker lock(&devicesMutex);
 214     return deviceList()->contains(dev);
 215 }
 216
 217 /*!
 218   \internal
 219   */
 220 void QTouchDevicePrivate::registerDevice(QTouchDevice *dev)
 221 {
 222     QMutexLocker lock(&devicesMutex);
 223     if (deviceList()->isEmpty())
 224         qAddPostRoutine(cleanupDevicesList);
 225     deviceList()->append(dev);
 226 }
 227
 228 QT_END_NAMESPACE