Move QEventPoint and QPointingDeviceUniqueId out of qevent

qevent.h/cpp are huge already, no need for more classes. Move QEventPoint
into new qeventpoint.h/cpp files, and QPointingDeviceUniqueId into
qpointingdevice.cpp; the class is already declared in qpointingdevice.h.

Move the documentation of QEventPoint APIs next to the implementation,
and document all APIs as properties. Add Q_PROPERTY macro where missing.

QEventPoint::device needs a workaround of qdoc due to the type being a
pointer-to-const; qdoc doesn't know how to tie a \property to it, but
documents it correctly.

While at it, move the logging category declarations to the header
matching the .cpp file where they are defined.

Change-Id: I096e609edbb760b5686d577e7fe47eea0807904e
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

1 files changed, 1 insertions, 647 deletions

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index a4e44f5b8d..9d27961071 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -61,10 +61,6 @@
 
 QT_BEGIN_NAMESPACE
 
-Q_LOGGING_CATEGORY(lcPointerGrab, "qt.pointer.grab")
-Q_LOGGING_CATEGORY(lcPointerVel, "qt.pointer.velocity")
-Q_LOGGING_CATEGORY(lcEPDetach, "qt.pointer.eventpoint.detach")
-
 /*!
     \class QEnterEvent
     \ingroup events
@@ -226,392 +222,6 @@ QInputEvent::~QInputEvent()
 */
 
 /*!
-    \internal
-    Constructs an invalid event point with the given \a id and the \a device
-    from which it originated.
-
-    This acts as a default constructor in usages like QMap<int, QEventPoint>,
-    as in qgraphicsscene_p.h.
-*/
-QEventPoint::QEventPoint(int id, const QPointingDevice *device)
-    : d(new QEventPointPrivate(id, device)) {}
-
-/*!
-    Constructs an event point with the given \a pointId, \a state,
-    \a scenePosition and \a globalPosition.
-*/
-QEventPoint::QEventPoint(int pointId, State state, const QPointF &scenePosition, const QPointF &globalPosition)
-    : d(new QEventPointPrivate(pointId, state, scenePosition, globalPosition)) {}
-
-/*!
-    Constructs an event point by making a shallow copy of \a other.
-*/
-QEventPoint::QEventPoint(const QEventPoint &other)
-    : d(other.d)
-{
-    if (d)
-        d->refCount++;
-}
-
-/*!
-    Assigns \a other to this event point and returns a reference to this
-    event point.
-*/
-QEventPoint &QEventPoint::operator=(const QEventPoint &other)
-{
-    if (other.d)
-        other.d->refCount++;
-    if (d && !(--d->refCount))
-        delete d;
-    d = other.d;
-    return *this;
-}
-
-/*!
-    \fn QEventPoint::QEventPoint(QEventPoint &&other) noexcept
-
-    Constructs an event point by moving \a other.
-*/
-
-/*!
-    \fn QEventPoint &QEventPoint::operator=(QEventPoint &&other) noexcept
-
-    Move-assigns \a other to this event point instance.
-*/
-
-/*!
-    Returns \c true if this event point is equal to \a other, otherwise
-    return \c false.
-*/
-bool QEventPoint::operator==(const QEventPoint &other) const noexcept
-{
-    if (d == other.d)
-        return true;
-    if (!d || !other.d)
-        return false;
-    return *d == *other.d;
-}
-
-/*!
-    \fn bool QEventPoint::operator!=(const QEventPoint &other) const noexcept
-
-    Returns \c true if this event point is not equal to \a other, otherwise
-    return \c false.
-*/
-
-/*!
-    Destroys the event point.
-*/
-QEventPoint::~QEventPoint()
-{
-    if (d && !(--d->refCount))
-        delete d;
-}
-
-QPointF QEventPoint::position() const
-{ return d->pos; }
-
-QPointF QEventPoint::pressPosition() const
-{ return d->globalPressPos - d->globalPos + d->pos; }
-
-QPointF QEventPoint::grabPosition() const
-{ return d->globalGrabPos - d->globalPos + d->pos; }
-
-QPointF QEventPoint::lastPosition() const
-{ return d->globalLastPos - d->globalPos + d->pos; }
-
-QPointF QEventPoint::scenePosition() const
-{ return d->scenePos; }
-
-QPointF QEventPoint::scenePressPosition() const
-{ return d->globalPressPos - d->globalPos + d->scenePos; }
-
-QPointF QEventPoint::sceneGrabPosition() const
-{ return d->globalGrabPos - d->globalPos + d->scenePos; }
-
-QPointF QEventPoint::sceneLastPosition() const
-{ return d->globalLastPos - d->globalPos + d->scenePos; }
-
-QPointF QEventPoint::globalPosition() const
-{ return d->globalPos; }
-
-QPointF QEventPoint::globalPressPosition() const
-{ return d->globalPressPos; }
-
-QPointF QEventPoint::globalGrabPosition() const
-{ return d->globalGrabPos; }
-
-QPointF QEventPoint::globalLastPosition() const
-{ return d->globalLastPos; }
-
-QVector2D QEventPoint::velocity() const
-{ return d->velocity; }
-
-QEventPoint::State QEventPoint::state() const
-{ return d->state; }
-
-const QPointingDevice *QEventPoint::device() const
-{ return d->device; }
-
-int QEventPoint::id() const
-{ return d->pointId; }
-
-QPointingDeviceUniqueId QEventPoint::uniqueId() const
-{ return d->uniqueId; }
-
-ulong QEventPoint::timestamp() const
-{ return d->timestamp; }
-
-ulong QEventPoint::pressTimestamp() const
-{ return d->pressTimestamp; }
-
-qreal QEventPoint::timeHeld() const
-{ return (d->timestamp - d->pressTimestamp) / qreal(1000); }
-
-qreal QEventPoint::pressure() const
-{ return d->pressure; }
-
-qreal QEventPoint::rotation() const
-{ return d->rotation; }
-
-QSizeF QEventPoint::ellipseDiameters() const
-{ return d->ellipseDiameters; }
-
-bool QEventPoint::isAccepted() const
-{ return d->accept; }
-
-/*!
-    Returns the time from the previous QPointerEvent that contained this point.
-
-    \sa globalLastPosition()
-*/
-ulong QEventPoint::lastTimestamp() const
-{ return d->lastTimestamp; }
-
-/*!
-    Sets the accepted state of the point to \a accepted.
-
-    In widget-based applications, this function is not used so far, because
-    it's only meaningful for a widget to accept or reject a complete QInputEvent.
-
-    In Qt Quick however, it's normal for an Item or Event Handler to accept
-    only the individual points in a QTouchEvent that are actually participating
-    in a gesture, while other points can be delivered to other items or
-    handlers. For the sake of consistency, that applies to any QPointerEvent;
-    and delivery is done only when all points in a QPointerEvent have been
-    accepted.
-
-    \sa QEvent::setAccepted()
-*/
-void QEventPoint::setAccepted(bool accepted)
-{
-    d->accept = accepted;
-}
-
-/*!
-    \obsolete
-    \fn QPointF QPointerEvent::normalizedPos() const
-
-    Deprecated since Qt 6.0. Use normalizedPosition() instead.
-*/
-
-/*!
-    Returns the normalized position of this point.
-
-    The coordinates are calculated by transforming globalPosition() into the
-    space of QInputDevice::availableVirtualGeometry(), i.e. \c (0, 0) is the
-    top-left corner and \c (1, 1) is the bottom-right corner.
-
-    \sa globalPosition()
-*/
-QPointF QEventPoint::normalizedPosition() const
-{
-    auto geom = d->device->availableVirtualGeometry();
-    if (geom.isNull())
-        return QPointF();
-    return (globalPosition() - geom.topLeft()) / geom.width();
-}
-
-/*!
-    \obsolete
-    Deprecated since Qt 6.0. Use globalPressPosition() instead.
-
-    Returns the normalized press position of this point.
-*/
-QPointF QEventPoint::startNormalizedPos() const
-{
-    auto geom = d->device->availableVirtualGeometry();
-    if (geom.isNull())
-        return QPointF();
-    return (globalPressPosition() - geom.topLeft()) / geom.width();
-}
-
-/*!
-    \obsolete
-    Deprecated since Qt 6.0. Use globalLastPosition() instead.
-
-    Returns the normalized position of this point from the previous press or
-    move event.
-
-    The coordinates are normalized to QInputDevice::availableVirtualGeometry(),
-    i.e. \c (0, 0) is the top-left corner and \c (1, 1) is the bottom-right corner.
-
-    \sa normalizedPos(), startNormalizedPos()
-*/
-QPointF QEventPoint::lastNormalizedPos() const
-{
-    auto geom = d->device->availableVirtualGeometry();
-    if (geom.isNull())
-        return QPointF();
-    return (globalLastPosition() - geom.topLeft()) / geom.width();
-}
-
-
-/*! \internal
-    This class is explicitly shared, which means if you construct an event and
-    then the point(s) that it holds are modified before the event is delivered,
-    the event will be seen to hold the modified points. The workaround is that
-    any code which modifies an eventpoint that could already be included in an
-    event, or code that wants to save an eventpoint for later, has
-    responsibility to detach before calling any setters, so as to hold and
-    modify an independent copy. (The independent copy can then be used in a
-    subsequent event.) If detaching is unnecessary, because refCount shows that
-    there is only one QEventPoint referring to the QEventPointPrivate instance,
-    this function does nothing.
-*/
-void QMutableEventPoint::detach()
-{
-    if (d->refCount == 1)
-        return; // no need: there is only one QEventPoint using it
-    qCDebug(lcEPDetach) << "detaching: refCount" << d->refCount << this;
-    auto old = d;
-    d = new QEventPointPrivate(*d);
-    d->refCount = 1;
-    --old->refCount;
-}
-
-/*! \internal
-    Update current state from the given \a other point, assuming that this
-    instance contains state from the previous event and \a other contains new
-    values that came in from a device.
-
-    That is: global position and other valuators will be updated, but
-    the following properties will not be updated:
-
-    \list
-    \li other properties that are not likely to be set after a fresh touchpoint
-    has been received from a device
-    \li properties that should be persistent between events (such as grabbers)
-    \endlist
-*/
-void QMutableEventPoint::updateFrom(const QEventPoint &other)
-{
-    detach();
-    setPressure(other.pressure());
-
-    switch (other.state()) {
-    case QEventPoint::State::Pressed:
-        setGlobalPressPosition(other.globalPosition());
-        setGlobalLastPosition(other.globalPosition());
-        if (pressure() < 0)
-            setPressure(1);
-        break;
-
-    case QEventPoint::State::Released:
-        if (globalPosition() != other.globalPosition())
-            setGlobalLastPosition(globalPosition());
-        setPressure(0);
-        break;
-
-    default: // update or stationary
-        if (globalPosition() != other.globalPosition())
-            setGlobalLastPosition(globalPosition());
-        if (pressure() < 0)
-            setPressure(1);
-        break;
-    }
-
-    setState(other.state());
-    setPosition(other.position());
-    setScenePosition(other.scenePosition());
-    setGlobalPosition(other.globalPosition());
-    setEllipseDiameters(other.ellipseDiameters());
-    setRotation(other.rotation());
-    setVelocity(other.velocity());
-}
-
-/*! \internal
-    Set the timestamp from the event that updated this point's positions,
-    and calculate a new value for velocity().
-
-    The velocity calculation is done here because none of the QPointerEvent
-    subclass constructors take the timestamp directly, and because
-    QGuiApplication traditionally constructs an event first and then sets its
-    timestamp (see for example QGuiApplicationPrivate::processMouseEvent()).
-
-    This function looks up the corresponding instance in QPointingDevicePrivate::activePoints,
-    and assumes that its timestamp() still holds the previous time when this point
-    was updated, its velocity() holds this point's last-known velocity, and
-    its globalPosition() and globalLastPosition() hold this point's current
-    and previous positions, respectively.  We assume timestamps are in milliseconds.
-
-    The velocity calculation is skipped if the platform has promised to
-    provide velocities already by setting the QInputDevice::Velocity capability.
-*/
-void QMutableEventPoint::setTimestamp(const ulong t)
-{
-    // On mouse press, if the mouse has moved from its last-known location,
-    // QGuiApplicationPrivate::processMouseEvent() sends first a mouse move and
-    // then a press. Both events will get the same timestamp. So we need to set
-    // the press timestamp and position even when the timestamp isn't advancing,
-    // but skip setting lastTimestamp and velocity because those need a time delta.
-    if (state() == QEventPoint::State::Pressed) {
-        d->pressTimestamp = t;
-        d->globalPressPos = d->globalPos;
-    }
-    if (d->timestamp == t)
-        return;
-    detach();
-    if (device()) {
-        // get the persistent instance out of QPointingDevicePrivate::activePoints
-        // (which sometimes might be the same as this instance)
-        QEventPointPrivate *pd = QPointingDevicePrivate::get(
-                    const_cast<QPointingDevice *>(d->device))->pointById(id())->eventPoint.d;
-        if (t > pd->timestamp) {
-            pd->lastTimestamp = pd->timestamp;
-            pd->timestamp = t;
-            if (state() == QEventPoint::State::Pressed)
-                pd->pressTimestamp = t;
-            if (pd->lastTimestamp > 0 && !device()->capabilities().testFlag(QInputDevice::Capability::Velocity)) {
-                // calculate instantaneous velocity according to time and distance moved since the previous point
-                QVector2D newVelocity = QVector2D(pd->globalPos - pd->globalLastPos) / (t - pd->lastTimestamp) * 1000;
-                // VERY simple kalman filter: does a weighted average
-                // where the older velocities get less and less significant
-                static const float KalmanGain = 0.7f;
-                pd->velocity = newVelocity * KalmanGain + pd->velocity * (1.0f - KalmanGain);
-                qCDebug(lcPointerVel) << "velocity" << newVelocity << "filtered" << pd->velocity <<
-                                         "based on movement" << pd->globalLastPos << "->" << pd->globalPos <<
-                                         "over time" << pd->lastTimestamp << "->" << pd->timestamp;
-            }
-            if (d != pd) {
-                d->lastTimestamp = pd->lastTimestamp;
-                d->velocity = pd->velocity;
-            }
-        }
-    }
-    d->timestamp = t;
-}
-
-/*! \internal
-    void QMutableEventPoint::setPosition(const QPointF &pos)
-    Sets the localized position.
-    Often events need to be localized before delivery to specific widgets or
-    items. This can be done directly, or in a copy (for which we have a copy
-    constructor), depending on whether the original point needs to be retained.
-    Usually it's calculated by mapping scenePosition() to the target anyway.
-*/
-
-/*!
     \class QPointerEvent
     \since 6.0
     \inmodule QtGui
@@ -868,7 +478,7 @@ void QPointerEvent::clearPassiveGrabbers(const QEventPoint &point)
     Returns the position of the point in this event, relative to the window or
     scene.
 
-    \sa QEventPoint::scenePosition()
+    \sa QEventPoint::scenePosition
 */
 
 /*! \fn QPointF QSinglePointEvent::globalPosition() const
@@ -4843,177 +4453,6 @@ bool QTouchEvent::isEndEvent() const
     \sa QPointerEvent::point(), QPointerEvent::pointCount()
 */
 
-/*! \class QEventPoint
-    \brief The QEventPoint class provides information about a point in a QPointerEvent.
-    \since 6.0
-    \inmodule QtGui
-*/
-
-/*!
-    \enum QEventPoint::State
-
-    Specifies the state of this event point.
-
-    \value  Unknown
-            Unknown state.
-
-    \value  Stationary
-            The event point did not move.
-
-    \value  Pressed
-            The touch point or button is pressed.
-
-    \value  Updated
-            The event point was updated.
-
-    \value  Released
-            The touch point or button was released.
-*/
-
-/*! \fn int QEventPoint::id() const
-
-    Returns the ID number of this event point.
-
-    \note Do not assume that ID numbers start at zero or that they are
-          sequential. Such an assumption is often false due to the way
-          the underlying drivers work.
-*/
-
-/*! \fn QPointingDeviceUniqueId QEventPoint::uniqueId() const
-
-    Returns the unique ID of this point or token, if any.
-
-    It is often invalid (see \l {QPointingDeviceUniqueId::isValid()} {isValid()}),
-    because touchscreens cannot uniquely identify fingers.
-
-    When it comes from a QTabletEvent, it identifies the serial number of the
-    stylus in use.
-
-    It may identify a specific token (fiducial object) when the TUIO driver is
-    in use with a touchscreen that supports them.
-*/
-
-/*! \fn QEventPoint::State QEventPoint::state() const
-    Returns the current state of this point.
-*/
-
-/*! \fn QPointF QEventPoint::position() const
-
-    Returns the position of this point, relative to the widget
-    or item that received the event.
-*/
-
-/*! \fn QPointF QEventPoint::pos() const
-    \obsolete
-    Deprecated since Qt 6.0. Use position() instead.
-
-    Returns the position of this point, relative to the widget
-    or item that received the event.
-*/
-
-/*! \fn QPointF QEventPoint::scenePosition() const
-    Returns the position of this point relative to the window or scene.
-
-    The scene position is the position relative to QQuickWindow if handled in QQuickItem::event(),
-    in QGraphicsScene coordinates if handled by an override of QGraphicsItem::touchEvent(),
-    or the window position in widget applications.
-
-    \sa scenePressPosition(), position(), globalPosition()
-*/
-
-/*! \fn QPointF QEventPoint::globalPosition() const
-    Returns the position of this point on the screen or virtual desktop.
-
-    \sa globalPressPosition(), position(), scenePosition()
-*/
-
-/*! \fn QPointF QEventPoint::pressPosition() const
-    Returns the position at which this point was pressed, relative to the
-    widget or item that received the event.
-
-    \sa position()
-*/
-
-/*! \fn QPointF QEventPoint::scenePressPosition() const
-    Returns the scene position at which this point was pressed.
-
-    The scene position is the position relative to QQuickWindow if handled in QQuickItem::event(),
-    in QGraphicsScene coordinates if handled by an override of QGraphicsItem::touchEvent(),
-    or the window position in widget applications.
-
-    \sa scenePosition(), pressPosition(), globalPressPosition()
-*/
-
-/*! \fn QPointF QEventPoint::globalPressPosition() const
-    Returns the position at which this point was pressed on the screen or virtual desktop.
-
-    \sa globalPosition(), pressPosition(), scenePressPosition()
-*/
-
-/*! \fn QPointF QEventPoint::lastPosition() const
-    Returns the position of this point from the previous press or move event,
-    relative to the widget or QGraphicsItem that received the event.
-
-    \sa position(), pressPosition()
-*/
-
-/*! \fn QPointF QEventPoint::sceneLastPosition() const
-    Returns the scene position of this point from the previous press or move event.
-
-    The scene position is the position in QGraphicsScene coordinates
-    if the QTouchEvent is handled by a QGraphicsItem::touchEvent()
-    reimplementation, and identical to the screen position for
-    widgets.
-
-    \sa scenePosition(), scenePressPosition()
-*/
-
-/*! \fn qreal QEventPoint::pressure() const
-    Returns the pressure of this point. The return value is in
-    the range \c 0.0 to \c 1.0.
-*/
-
-/*! \fn qreal QEventPoint::rotation() const
-
-    Returns the angular orientation of this point. The return value is in degrees,
-    where zero (the default) indicates the finger, token or stylus 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.
-*/
-
-/*! \fn QSizeF QEventPoint::ellipseDiameters() const
-
-    Returns the width and height of the bounding ellipse of the touch point.
-    The return value is in logical pixels. Most touchscreens do not detect the
-    shape of the contact point, and no mice or tablet devices can detect it,
-    so a null size is the most common value. On some touchscreens the diameters
-    may be nonzero and always equal (the ellipse is approximated as a circle).
-*/
-
-/*!
-    \fn QVector2D QEventPoint::velocity() const
-    Returns a velocity vector, in units of pixels per second, in the coordinate
-    system of the screen or desktop.
-
-    \note If the device's capabilities include QInputDevice::Velocity, it means
-    velocity comes from the operating system (perhaps the touch hardware or
-    driver provides it). But usually the \c Velocity capability is not set,
-    indicating that the velocity is calculated by Qt, using a simple Kalman
-    filter to provide a smoothed average velocity rather than an instantaneous
-    value. Effectively it tells how fast and in what direction the user has
-    been dragging this point over the last few events, with the most recent
-    event having the strongest influence.
-
-    \sa QInputDevice::capabilities(), QInputEvent::device()
-*/
-
-/*! \fn ulong QEventPoint::timestamp() const
-    Returns the most recent time at which this point was included in a QPointerEvent.
-
-    \sa QPointerEvent::timestamp()
-*/
-
 /*!
     \class QScrollPrepareEvent
     \since 4.8
@@ -5256,91 +4695,6 @@ void QMutableTouchEvent::addPoint(const QEventPoint &point)
     m_touchPointStates |= point.state();
 }
 
-/*!
-    \class QPointingDeviceUniqueId
-    \since 5.8
-    \ingroup events
-    \inmodule QtGui
-
-    \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.
-
-    \sa QEventPoint
-*/
-
-/*!
-    \fn QPointingDeviceUniqueId::QPointingDeviceUniqueId()
-    Constructs an invalid unique pointer ID.
-*/
-
-/*!
-    Constructs a unique pointer ID from numeric ID \a id.
-*/
-QPointingDeviceUniqueId QPointingDeviceUniqueId::fromNumericId(qint64 id)
-{
-    QPointingDeviceUniqueId result;
-    result.m_numericId = id;
-    return result;
-}
-
-/*!
-    \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
-
-    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 QPointingDeviceUniqueId::numericId() const noexcept
-{
-    return m_numericId;
-}
 
-/*!
-    \fn bool QPointingDeviceUniqueId::operator==(QPointingDeviceUniqueId lhs, QPointingDeviceUniqueId rhs)
-    \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).
-*/
-
-/*!
-    \fn bool QPointingDeviceUniqueId::operator!=(QPointingDeviceUniqueId lhs, QPointingDeviceUniqueId rhs)
-    \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.
-*/
-size_t qHash(QPointingDeviceUniqueId key, size_t seed) noexcept
-{
-    return qHash(key.numericId(), seed);
-}
 
 QT_END_NAMESPACE