From 048447346bc1b78992be3ce4bf3292fc272f7e1a Mon Sep 17 00:00:00 2001 From: Marc Mutz Date: Thu, 8 Sep 2016 10:10:12 +0200 Subject: QPointerUniqueId: make fit for release - Declare as Q_MOVABLE_TYPE - Prevent QList from being instantiated (use QVector instead) - Add equality relational operators - Add qHash() overload - Replace non-default ctor with named ctor. - Add Q_DECL_NOTHROW. - Add Q_DECL_CONSTEXPR. - Rename numeric() -> numericId(). - Update docs. The extension vector for this class calls for additional properties to be added later, but these are not user- settable. It thus suffices to rely on the only data member, a qint64, which can be reinterpreted to an index into an array or hash with actual objects. This allows to make the class a Trivial Type (ie. no overhead over an int) while still supporting later extension. Cf. QSslEllipticCurve as another example of such a class. The extension has to maintain the following invariants, encoded into user code by way of being used in inline functions: - m_numericId == -1 <=> !isValid() This is trivial to support. An extension could not and still cannot reinterpret the qint64 member as a d-pointer, but a d-pointer is only necessary for user-settable properties where updating a central private data structure would cause too much contention. Add a test. Since this type is used in other modules, keep the existing functions, but mark them as deprecated with the expectation that these compat functions be removed before 5.8.0 final. Task-number: QTBUG-54616 Change-Id: Ia3ede0ecaeeef4cd3ffa94a72b1050bd409713a5 Reviewed-by: Shawn Rutledge --- src/gui/kernel/qevent.cpp | 82 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 73 insertions(+), 9 deletions(-) (limited to 'src/gui/kernel/qevent.cpp') diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp index 254b8926c8..72cd374419 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" @@ -4474,7 +4475,7 @@ 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 {QPointerUniqueId::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). @@ -4757,7 +4758,7 @@ void QTouchEvent::TouchPoint::setUniqueId(qint64 uid) { if (d->ref.load() != 1) d = d->detach(); - d->uniqueId = QPointerUniqueId(uid); + d->uniqueId = QPointerUniqueId::fromNumericId(uid); } /*! \internal */ @@ -5184,28 +5185,91 @@ Qt::ApplicationState QApplicationStateChangeEvent::applicationState() const \brief QPointerUniqueId identifies a unique object, such as a tagged token or stylus, which is used with a pointing device. + QPointerUniqueIds 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 QPointerUniqueId::QPointerUniqueId() + Constructs an invalid unique pointer ID. +*/ + +/*! + Constructs a unique pointer ID from numeric ID \a id. */ -QPointerUniqueId::QPointerUniqueId(qint64 id) - : m_numericId(id) +QPointerUniqueId QPointerUniqueId::fromNumericId(qint64 id) { + QPointerUniqueId result; + result.m_numericId = id; + return result; } /*! - \property QPointerUniqueId::numeric + \fn bool QPointerUniqueId::isValid() + + Returns whether this unique pointer ID is valid, that is, it represents an actual + pointer. +*/ + +/*! + \property QPointerUniqueId::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 QPointerUniqueId::numericId() const Q_DECL_NOTHROW { return m_numericId; } +/*! + \relates QPointerUniqueId + \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==(QPointerUniqueId lhs, QPointerUniqueId rhs) Q_DECL_NOTHROW +{ + return lhs.numericId() == rhs.numericId(); +} + +/*! + \fn bool operator!=(QPointerUniqueId lhs, QPointerUniqueId rhs) + \relates QPointerUniqueId + \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 QPointerUniqueId + \since 5.8 + + Returns the hash value for \a key, using \a seed to seed the calculation. +*/ +uint qHash(QPointerUniqueId key, uint seed) Q_DECL_NOTHROW +{ + return qHash(key.numericId(), seed); +} + QT_END_NAMESPACE -- cgit v1.2.3 From 7df0c7a309ada7f9ab70a2c20f86c0707288e31e Mon Sep 17 00:00:00 2001 From: Shawn Rutledge Date: Thu, 1 Dec 2016 12:47:55 +0100 Subject: rename QPointerUniqueId -> QPointingDeviceUniqueId Several people agreed that the name was confusing and that this one is better. Task-number: QTBUG-54616 Change-Id: I31cf057f4bc818332b0551a27d1711599440207c Reviewed-by: Marc Mutz Reviewed-by: Sune Vuorela --- src/gui/kernel/qevent.cpp | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'src/gui/kernel/qevent.cpp') diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp index 72cd374419..b198fa0832 100644 --- a/src/gui/kernel/qevent.cpp +++ b/src/gui/kernel/qevent.cpp @@ -4475,14 +4475,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 (see \l {QPointerUniqueId::isValid()} {isValid()}), + 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; } @@ -4758,7 +4758,7 @@ void QTouchEvent::TouchPoint::setUniqueId(qint64 uid) { if (d->ref.load() != 1) d = d->detach(); - d->uniqueId = QPointerUniqueId::fromNumericId(uid); + d->uniqueId = QPointingDeviceUniqueId::fromNumericId(uid); } /*! \internal */ @@ -5177,15 +5177,15 @@ 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. - QPointerUniqueIds can be compared for equality, and can be used as keys in a QHash. + 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. @@ -5201,29 +5201,29 @@ Qt::ApplicationState QApplicationStateChangeEvent::applicationState() const */ /*! - \fn QPointerUniqueId::QPointerUniqueId() + \fn QPointingDeviceUniqueId::QPointingDeviceUniqueId() Constructs an invalid unique pointer ID. */ /*! Constructs a unique pointer ID from numeric ID \a id. */ -QPointerUniqueId QPointerUniqueId::fromNumericId(qint64 id) +QPointingDeviceUniqueId QPointingDeviceUniqueId::fromNumericId(qint64 id) { - QPointerUniqueId result; + QPointingDeviceUniqueId result; result.m_numericId = id; return result; } /*! - \fn bool QPointerUniqueId::isValid() + \fn bool QPointingDeviceUniqueId::isValid() Returns whether this unique pointer ID is valid, that is, it represents an actual pointer. */ /*! - \property QPointerUniqueId::numericId + \property QPointingDeviceUniqueId::numericId \brief the numeric unique ID of the token represented by a touchpoint If the device provides a numeric ID, isValid() returns true, and this @@ -5235,26 +5235,26 @@ QPointerUniqueId QPointerUniqueId::fromNumericId(qint64 id) \sa isValid() */ -qint64 QPointerUniqueId::numericId() const Q_DECL_NOTHROW +qint64 QPointingDeviceUniqueId::numericId() const Q_DECL_NOTHROW { return m_numericId; } /*! - \relates QPointerUniqueId + \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==(QPointerUniqueId lhs, QPointerUniqueId rhs) Q_DECL_NOTHROW +bool operator==(QPointingDeviceUniqueId lhs, QPointingDeviceUniqueId rhs) Q_DECL_NOTHROW { return lhs.numericId() == rhs.numericId(); } /*! - \fn bool operator!=(QPointerUniqueId lhs, QPointerUniqueId rhs) - \relates QPointerUniqueId + \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 @@ -5262,12 +5262,12 @@ bool operator==(QPointerUniqueId lhs, QPointerUniqueId rhs) Q_DECL_NOTHROW */ /*! - \relates QPointerUniqueId + \relates QPointingDeviceUniqueId \since 5.8 Returns the hash value for \a key, using \a seed to seed the calculation. */ -uint qHash(QPointerUniqueId key, uint seed) Q_DECL_NOTHROW +uint qHash(QPointingDeviceUniqueId key, uint seed) Q_DECL_NOTHROW { return qHash(key.numericId(), seed); } -- cgit v1.2.3 From 5b8957247f5e2845dd9f59545ba567d051c4e436 Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Fri, 9 Dec 2016 12:34:33 +0100 Subject: Doc: QPointingDeviceUniqueId: Fix documentation warning Fix the following warning by adding a const qualifier: warning: No documentation for 'QPointingDeviceUniqueId::isValid()' Change-Id: I1ebeda8f45e88efb7cb844b67409352c695e6354 Reviewed-by: Shawn Rutledge --- src/gui/kernel/qevent.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/gui/kernel/qevent.cpp') diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp index b198fa0832..219f782737 100644 --- a/src/gui/kernel/qevent.cpp +++ b/src/gui/kernel/qevent.cpp @@ -5216,7 +5216,7 @@ QPointingDeviceUniqueId QPointingDeviceUniqueId::fromNumericId(qint64 id) } /*! - \fn bool QPointingDeviceUniqueId::isValid() + \fn bool QPointingDeviceUniqueId::isValid() const Returns whether this unique pointer ID is valid, that is, it represents an actual pointer. -- cgit v1.2.3