Merge "Merge remote-tracking branch 'origin/5.8' into dev" into refs/staging/dev

1 files changed, 76 insertions, 12 deletions

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index f34d09c4e5..dc61ee9151 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -44,6 +44,7 @@
 #include "qpa/qplatformdrag.h"
 #include "private/qevent_p.h"
 #include "qfile.h"
+#include "qhashfunctions.h"
 #include "qmetaobject.h"
 #include "qmimedata.h"
 #include "private/qdnd_p.h"
@@ -4479,14 +4480,14 @@ 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),
+    It is normally invalid (see \l {QPointingDeviceUniqueId::isValid()} {isValid()}),
     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
+QPointingDeviceUniqueId QTouchEvent::TouchPoint::uniqueId() const
 {
     return d->uniqueId;
 }
@@ -4798,7 +4799,7 @@ void QTouchEvent::TouchPoint::setUniqueId(qint64 uid)
 {
     if (d->ref.load() != 1)
         d = d->detach();
-    d->uniqueId = QPointerUniqueId(uid);
+    d->uniqueId = QPointingDeviceUniqueId::fromNumericId(uid);
 }
 
 /*! \internal */
@@ -5229,36 +5230,99 @@ Qt::ApplicationState QApplicationStateChangeEvent::applicationState() const
 }
 
 /*!
-    \class QPointerUniqueId
+    \class QPointingDeviceUniqueId
     \since 5.8
     \ingroup events
     \inmodule QtGui
 
-    \brief QPointerUniqueId identifies a unique object, such as a tagged token
+    \brief QPointingDeviceUniqueId identifies a unique object, such as a tagged token
     or stylus, which is used with a pointing device.
 
+    QPointingDeviceUniqueIds can be compared for equality, and can be used as keys in a QHash.
+    You get access to the numerical ID via numericId(), if the device supports such IDs.
+    For future extensions, though, you should not use that function, but compare objects
+    of this type using the equality operator.
+
+    This class is a thin wrapper around an integer ID. You pass it into and out of
+    functions by value.
+
+    This type actively prevents you from holding it in a QList, because doing so would
+    be very inefficient. Use a QVector instead, which has the same API as QList, but more
+    efficient storage.
+
     \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.
+    \fn QPointingDeviceUniqueId::QPointingDeviceUniqueId()
+    Constructs an invalid unique pointer ID.
+*/
+
+/*!
+    Constructs a unique pointer ID from numeric ID \a id.
 */
-QPointerUniqueId::QPointerUniqueId(qint64 id)
-    : m_numericId(id)
+QPointingDeviceUniqueId QPointingDeviceUniqueId::fromNumericId(qint64 id)
 {
+    QPointingDeviceUniqueId result;
+    result.m_numericId = id;
+    return result;
 }
 
 /*!
-    \property QPointerUniqueId::numeric
+    \fn bool QPointingDeviceUniqueId::isValid() const
+
+    Returns whether this unique pointer ID is valid, that is, it represents an actual
+    pointer.
+*/
+
+/*!
+    \property QPointingDeviceUniqueId::numericId
     \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;
+    If the device provides a numeric ID, isValid() returns true, and this
+    property provides the numeric ID;
     otherwise it is -1.
+
+    You should not use the value of this property in portable code, but
+    instead rely on equality to identify pointers.
+
+    \sa isValid()
 */
-qint64 QPointerUniqueId::numeric() const
+qint64 QPointingDeviceUniqueId::numericId() const Q_DECL_NOTHROW
 {
     return m_numericId;
 }
 
+/*!
+    \relates QPointingDeviceUniqueId
+    \since 5.8
+
+    Returns whether the two unique pointer IDs \a lhs and \a rhs identify the same pointer
+    (\c true) or not (\c false).
+*/
+bool operator==(QPointingDeviceUniqueId lhs, QPointingDeviceUniqueId rhs) Q_DECL_NOTHROW
+{
+    return lhs.numericId() == rhs.numericId();
+}
+
+/*!
+    \fn bool operator!=(QPointingDeviceUniqueId lhs, QPointingDeviceUniqueId rhs)
+    \relates QPointingDeviceUniqueId
+    \since 5.8
+
+    Returns whether the two unique pointer IDs \a lhs and \a rhs identify different pointers
+    (\c true) or not (\c false).
+*/
+
+/*!
+    \relates QPointingDeviceUniqueId
+    \since 5.8
+
+    Returns the hash value for \a key, using \a seed to seed the calculation.
+*/
+uint qHash(QPointingDeviceUniqueId key, uint seed) Q_DECL_NOTHROW
+{
+    return qHash(key.numericId(), seed);
+}
+
 QT_END_NAMESPACE