QTouchEvent: add uniqueId and rotation; TUIO: support fiducial tokens

TUIO supports tracking tagged physical objects on touchscreens by
various means (QR codes, RFIDs etc.)  It can detect both position
and rotation.  Likewise, it may be possible for some touchscreens or
drivers to detect orientation of the fingers.  So, just as QTabletEvent
has rotation, each touchpoint needs to include the rotation value.

When using tokens, each object has a permanent unique ID, whereas
QTouchEvent::TouchPoint::id() is a transient ID which usually auto-
increments each time a finger is pressed to the device.  So we need to
make that available too, to identify each token.  Different platforms
may use different kinds of IDs (int, UUID, QR code etc.); however for
TUIO 1.x, the unique IDs are just 32-bit integers.  QPointerUniqueId
is added, storing only a qint64 for now (like QTabletEvent::uniqueId())
but able to be expanded as necessary later on.

Task-number: QTBUG-51844
Change-Id: I04182042f47fa2954728079139a4664a31184b54
Reviewed-by: Robin Burchell <robin.burchell@viroteck.net>

1 files changed, 79 insertions, 0 deletions

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index 2b3b153537..2d3707c049 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -4421,6 +4421,7 @@ QTouchEvent::~QTouchEvent()
     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.
+    \value Token Indicates that the contact has been made by a fiducial object (e.g. a knob or other token) instead of a finger.
 */
 
 /*!
@@ -4467,6 +4468,22 @@ int QTouchEvent::TouchPoint::id() const
 }
 
 /*!
+    \since 5.8
+    Returns the unique ID of this touch point or token, if any.
+
+    It is normally invalid (with a \l {QPointerUniqueId::numeric()} {numeric()} value of -1),
+    because touchscreens cannot uniquely identify fingers. But when the
+    \l {TouchPoint::InfoFlag} {Token} flag is set, it is expected to uniquely
+    identify a specific token (fiducial object).
+
+    \sa flags
+*/
+QPointerUniqueId QTouchEvent::TouchPoint::uniqueId() const
+{
+    return d->uniqueId;
+}
+
+/*!
     Returns the current state of this touch point.
 */
 Qt::TouchPointState QTouchEvent::TouchPoint::state() const
@@ -4670,6 +4687,19 @@ qreal QTouchEvent::TouchPoint::pressure() const
 }
 
 /*!
+    \since 5.8
+    Returns the angular orientation of this touch point. The return value is in degrees,
+    where zero (the default) indicates the finger or token is pointing upwards,
+    a negative angle means it's rotated to the left, and a positive angle means
+    it's rotated to the right. Most touchscreens do not detect rotation, so
+    zero is the most common value.
+*/
+qreal QTouchEvent::TouchPoint::rotation() const
+{
+    return d->rotation;
+}
+
+/*!
     Returns a velocity vector for this touch point.
     The vector is in the screen's coordinate system, using pixels per seconds for the magnitude.
 
@@ -4720,6 +4750,14 @@ void QTouchEvent::TouchPoint::setId(int id)
 }
 
 /*! \internal */
+void QTouchEvent::TouchPoint::setUniqueId(qint64 uid)
+{
+    if (d->ref.load() != 1)
+        d = d->detach();
+    d->uniqueId = QPointerUniqueId(uid);
+}
+
+/*! \internal */
 void QTouchEvent::TouchPoint::setState(Qt::TouchPointStates state)
 {
     if (d->ref.load() != 1)
@@ -4856,6 +4894,14 @@ void QTouchEvent::TouchPoint::setPressure(qreal pressure)
 }
 
 /*! \internal */
+void QTouchEvent::TouchPoint::setRotation(qreal angle)
+{
+    if (d->ref.load() != 1)
+        d = d->detach();
+    d->rotation = angle;
+}
+
+/*! \internal */
 void QTouchEvent::TouchPoint::setVelocity(const QVector2D &v)
 {
     if (d->ref.load() != 1)
@@ -5126,4 +5172,37 @@ Qt::ApplicationState QApplicationStateChangeEvent::applicationState() const
     return m_applicationState;
 }
 
+/*!
+    \class QPointerUniqueId
+    \since 5.8
+    \ingroup events
+    \inmodule QtGui
+
+    \brief QPointerUniqueId identifies a unique object, such as a tagged token
+    or stylus, which is used with a pointing device.
+
+    \sa QTouchEvent::TouchPoint
+*/
+
+/*!
+    Constructs a unique pointer ID with a numeric \a id provided by the hardware.
+    The default is -1, which means an invalid pointer ID.
+*/
+QPointerUniqueId::QPointerUniqueId(qint64 id)
+    : m_numericId(id)
+{
+}
+
+/*!
+    \property QPointerUniqueId::numeric
+    \brief the numeric unique ID of the token represented by a touchpoint
+
+    This is the numeric unique ID if the device provides that type of ID;
+    otherwise it is -1.
+*/
+qint64 QPointerUniqueId::numeric()
+{
+    return m_numericId;
+}
+
 QT_END_NAMESPACE