Extend touch events.

The capability flags indicate which information is valid in the touch
points. Previously there was no way to tell if e.g. the value returned
by pressure() is actually the value provided by the driver/device or
it is just something bogus due to pressure not being supported.

The points' flags return information about the individual touch
points. One use case is to differentiate between touches made by
finger and pen.

Velocity, if available, is now also exposed.

Each touch point can now contain an additional list of "raw"
positions. These points are not reported individually but are taken
into account in some way by the underlying device and drivers to
generate the final, "accurate" touch point. In case the underlying
drivers expose these additional positions, they are made available in
the lists returned by the touch points' rawScreenPosition().

The raw positions are only available in screen coordinates to prevent
wasting time with mapping from global positions in applications that
do not use this data. Instead, apps can query the QWindow to which the
touch event was sent via QTouchEvent::window() and can call
mapFromGlobal() manually if they need local raw positions.

The capability and device type information is now held in a new
QTouchDevice class. Each touch event will contain only a pointer to
one of the global QTouchDevice instances. On top of type and
capability, the new class also contains a name which can be used to
differentiate between multiple touch input devices (i.e. to tell from
which one a given QTouchEvent originates from).

The introduction of QTouchDevice has three implications: The
QTouchEvent constructor and QWindowSystemInterface::handleTouchEvent
need to be changed (to pass a QTouchDevice pointer instead of merely a
device type value), and each platform or generic plug-in is now
responsible for registering one or more devices using the new API
QWindowSystemInterface::registerTouchDevice.

Change-Id: Ic1468d3e43933d8b5691d75aa67c43e1bc7ffe3e
Reviewed-by: Lars Knoll <[email protected]>

1 files changed, 110 insertions, 17 deletions

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index 0d262680302..035f1b26663 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -3450,34 +3450,25 @@ QWindowStateChangeEvent::~QWindowStateChangeEvent()
 
     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.
+    This enum has been deprecated. Use QTouchDevice::DeviceType instead.
 
-    \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.
+    \sa QTouchDevice::DeviceType, QTouchDevice::type(), QTouchEvent::device()
 */
 
 /*!
-    Constructs a QTouchEvent with the given \a eventType, \a deviceType, and \a touchPoints.
-    The \a touchPointStates and \a modifiers are the current touch point states and keyboard
-    modifiers at the time of the event.
+    Constructs a QTouchEvent with the given \a eventType, \a deviceType, \a
+    touchPoints and \a device. The \a touchPointStates and \a modifiers
+    are the current touch point states and keyboard modifiers at the time of
+    the event.
 */
 QTouchEvent::QTouchEvent(QEvent::Type eventType,
-                         QTouchEvent::DeviceType deviceType,
+                         QTouchDevice *device,
                          Qt::KeyboardModifiers modifiers,
                          Qt::TouchPointStates touchPointStates,
                          const QList<QTouchEvent::TouchPoint> &touchPoints)
     : QInputEvent(eventType, modifiers),
       _widget(0),
-      _deviceType(deviceType),
+      _device(device),
       _touchPointStates(touchPointStates),
       _touchPoints(touchPoints)
 { }
@@ -3493,6 +3484,22 @@ QTouchEvent::~QTouchEvent()
     Returns the widget on which the event occurred.
 */
 
+/*! \fn QWindow *QTouchEvent::window() const
+
+    Returns the window on which the event occurred. Useful for doing
+    global-local mapping on data like rawScreenPositions() which,
+    for performance reasons, only stores the global positions in the
+    touch event.
+*/
+
+/*! \fn QTouchEvent::DeviceType QTouchEvent::deviceType() const
+
+    Returns the touch device Type, which is of type \l {QTouchEvent::DeviceType} {DeviceType}.
+
+    This function has been deprecated. Use QTouchDevice::type() instead.
+
+    \sa QTouchDevice::type(), QTouchEvent::device()
+*/
 
 /*! \fn Qt::TouchPointStates QTouchEvent::touchPointStates() const
 
@@ -3509,6 +3516,11 @@ QTouchEvent::~QTouchEvent()
     Returns the touch device Type, which is of type \l {QTouchEvent::DeviceType} {DeviceType}.
 */
 
+/*! \fn QTouchDevice* QTouchEvent::device() const
+
+    Returns the touch device from which this touch event originates.
+*/
+
 /*! \fn void QTouchEvent::setWidget(QWidget *widget)
 
     \internal
@@ -3516,6 +3528,13 @@ QTouchEvent::~QTouchEvent()
     Sets the widget for this event.
 */
 
+/*! \fn void QTouchEvent::setWindow(QWindow *window)
+
+    \internal
+
+    Sets the window for this event.
+*/
+
 /*! \fn void QTouchEvent::setTouchPointStates(Qt::TouchPointStates touchPointStates)
 
     \internal
@@ -3538,11 +3557,25 @@ QTouchEvent::~QTouchEvent()
     {DeviceType}.
 */
 
+/*! \fn void QTouchEvent::setTouchDevice(QTouchDevice *device)
+
+    \internal
+
+    Sets the touch event's device to the given one.
+*/
+
 /*! \class QTouchEvent::TouchPoint
     \brief The TouchPoint class provides information about a touch point in a QTouchEvent.
     \since 4.6
 */
 
+/*! \enum QTouchEvent::TouchPoint::InfoFlags
+
+    The values of this enum describe additional information about a touch point.
+
+    \value Pen Indicates that the contact has been made by a designated pointing device (e.g. a pen) instead of a finger.
+*/
+
 /*! \internal
 
     Constructs a QTouchEvent::TouchPoint for use in a QTouchEvent.
@@ -3795,6 +3828,42 @@ qreal QTouchEvent::TouchPoint::pressure() const
     return d->pressure;
 }
 
+/*!
+    Returns a velocity vector for this touch point.
+    The vector is in the screen's coordinate system, using pixels per seconds for the magnitude.
+
+    \note The returned vector is only valid if the touch device's capabilities include QTouchDevice::Velocity.
+
+    \sa QTouchDevice::capabilities(), device()
+*/
+QVector2D QTouchEvent::TouchPoint::velocity() const
+{
+    return d->velocity;
+}
+
+/*!
+  Returns additional information about the touch point.
+
+  \sa QTouchEvent::TouchPoint::InfoFlags
+  */
+QTouchEvent::TouchPoint::InfoFlags QTouchEvent::TouchPoint::flags() const
+{
+    return d->flags;
+}
+
+/*!
+  Returns the raw, unfiltered positions for the touch point. The positions are in screen coordinates.
+  To get local coordinates you can use mapFromGlobal() of the QWindow returned by QTouchEvent::window().
+
+  \note Returns an empty list if the touch device's capabilities do not include QTouchDevice::RawPositions.
+
+  \sa QTouchDevice::capabilities(), device(), window()
+  */
+QList<QPointF> QTouchEvent::TouchPoint::rawScreenPositions() const
+{
+    return d->rawScreenPositions;
+}
+
 /*! \internal */
 void QTouchEvent::TouchPoint::setId(int id)
 {
@@ -3940,6 +4009,30 @@ void QTouchEvent::TouchPoint::setPressure(qreal pressure)
 }
 
 /*! \internal */
+void QTouchEvent::TouchPoint::setVelocity(const QVector2D &v)
+{
+    if (d->ref.load() != 1)
+        d = d->detach();
+    d->velocity = v;
+}
+
+/*! \internal */
+void QTouchEvent::TouchPoint::setRawScreenPositions(const QList<QPointF> &positions)
+{
+    if (d->ref.load() != 1)
+        d = d->detach();
+    d->rawScreenPositions = positions;
+}
+
+/* \internal */
+void QTouchEvent::TouchPoint::setFlags(InfoFlags flags)
+{
+    if (d->ref.load() != 1)
+        d = d->detach();
+    d->flags = flags;
+}
+
+/*! \internal */
 QTouchEvent::TouchPoint &QTouchEvent::TouchPoint::operator=(const QTouchEvent::TouchPoint &other)
 {
     other.d->ref.ref();