QQuickPointerEvent: cleanup of docs and file organization

Change-Id: I104edaabc35a073e14e8c66cd268ecd3782ed361
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@qt.io>

2 files changed, 63 insertions, 42 deletions

diff --git a/src/quick/items/qquickevents.cpp b/src/quick/items/qquickevents.cpp
index c79f77061a..9c32c9781c 100644
--- a/src/quick/items/qquickevents.cpp
+++ b/src/quick/items/qquickevents.cpp
@@ -439,7 +439,24 @@ Item {
     \l inverted always returns false.
 */
 
+/*!
+    \internal
+    \class QQuickPointerEvent
+
+    QQuickPointerEvent is used as a long-lived object to store data related to
+    an event from a pointing device, such as a mouse, touch or tablet event,
+    during event delivery. It also provides properties which may be used later
+    to expose the event to QML, the same as is done with QQuickMouseEvent,
+    QQuickTouchPoint, QQuickKeyEvent, etc. Since only one event can be
+    delivered at a time, this class is effectively a singleton.  We don't worry
+    about the QObject overhead because we never dynamically create and destroy
+    objects of this type.
+*/
 
+/*!
+    \internal
+    Reset the current event to \a ev, which must be a touch, mouse or tablet event.
+*/
 QQuickPointerEvent *QQuickPointerEvent::reset(QEvent *ev) {
     m_event = static_cast<QInputEvent*>(ev);
     if (isMouseEvent()) {
@@ -495,19 +512,26 @@ void QQuickPointerEvent::initFromTouch(QTouchEvent *ev) {
         m_touchPoints.at(i)->reset(tps.at(i));
 }
 
+/*!
+    \internal
+    Returns the original touch event, or nullptr if it was not a touch event.
+*/
 QTouchEvent *QQuickPointerEvent::asTouchEvent() const {
     if (!isTouchEvent())
         return nullptr;
     return static_cast<QTouchEvent *>(m_event);
 }
 
+/*!
+    \internal
+    Returns the original mouse event, or nullptr if it was not a mouse event.
+*/
 QMouseEvent *QQuickPointerEvent::asMouseEvent() const {
     if (isMouseEvent())
         return static_cast<QMouseEvent *>(m_event);
     return nullptr;
 }
 
-
 bool QQuickPointerEvent::isMouseEvent() const
 {
     return m_event
@@ -538,10 +562,36 @@ bool QQuickPointerEvent::isTabletEvent() const
     }
 }
 
-/*
-   \internal
+const QQuickEventPoint *QQuickPointerEvent::point(int i) const {
+    if (Q_UNLIKELY(i < 0 || i >= m_pointCount))
+        return nullptr;
+    if (isTouchEvent())
+        return m_touchPoints.at(i);
+    if (isMouseEvent())
+        return m_mousePoint;
+    return nullptr;
+}
+
+/*!
+    \internal
+    Returns a pointer to the original TouchPoint which has the same
+    \l {QTouchEvent::TouchPoint::id}{id} as \a pointId, if the original event is a
+    QTouchEvent, and if that point is found. Otherwise, returns nullptr.
+*/
+const QTouchEvent::TouchPoint *QQuickPointerEvent::touchPointById(int pointId) const {
+    const QTouchEvent *ev = asTouchEvent();
+    if (!ev)
+        return nullptr;
+    const QList<QTouchEvent::TouchPoint> &tps = ev->touchPoints();
+    auto it = std::find_if(tps.constBegin(), tps.constEnd(),
+        [&pointId](QTouchEvent::TouchPoint const& tp) { return tp.id() == pointId; } );
+    // return the pointer to the actual TP in QTouchEvent::_touchPoints
+    return (it == tps.end() ? nullptr : it.operator->());
+}
 
-   make a new QTouchEvent, giving it a subset of the original touch points
+/*!
+    \internal
+    Make a new QTouchEvent, giving it a subset of the original touch points.
 */
 QTouchEvent *QQuickPointerEvent::touchEventForItem(const QList<const QQuickEventPoint *> &newPoints, QQuickItem *relativeTo) const
 {
@@ -592,15 +642,4 @@ QTouchEvent *QQuickPointerEvent::touchEventForItem(const QList<const QQuickEvent
     return touchEvent;
 }
 
-const QTouchEvent::TouchPoint *QQuickPointerEvent::touchPointById(int pointId) const {
-    const QTouchEvent *ev = asTouchEvent();
-    if (!ev)
-        return nullptr;
-    const QList<QTouchEvent::TouchPoint> &tps = ev->touchPoints();
-    auto it = std::find_if(tps.constBegin(), tps.constEnd(),
-        [&pointId](QTouchEvent::TouchPoint const& tp) { return tp.id() == pointId; } );
-    // return the pointer to the actual TP in QTouchEvent::_touchPoints
-    return (it == tps.end() ? nullptr : it.operator->());
-}
-
 QT_END_NAMESPACE
diff --git a/src/quick/items/qquickevents_p_p.h b/src/quick/items/qquickevents_p_p.h
index 0ce395d7df..e5f2ac3fb7 100644
--- a/src/quick/items/qquickevents_p_p.h
+++ b/src/quick/items/qquickevents_p_p.h
@@ -398,26 +398,16 @@ public:
       , m_pointCount(0)
       , m_mousePoint(nullptr) { }
 
-    /** Reset the current event to \a ev.
-     *
-     * ev must be a touch, mouse or tablet event.
-     */
-    QQuickPointerEvent *reset(QEvent *ev);
-
+public: // property accessors
     const QQuickPointerDevice *device() const { return m_device; }
     Qt::KeyboardModifiers modifiers() const { return m_event ? m_event->modifiers() : Qt::NoModifier; }
     Qt::MouseButton button() const { return m_button; }
     Qt::MouseButtons buttons() const { return m_pressedButtons; }
 
-    // ----------------------------------------------------
-    // helpers for C++ event delivery, not for QML properties
+public: // helpers for C++ only (during event delivery)
+    QQuickPointerEvent *reset(QEvent *ev);
 
-    /** Returns the original touch event. */
     QTouchEvent *asTouchEvent() const;
-
-    /** Returns the original mouse event.
-     *
-     * Returns nullptr in case the original event was not a mouse event. */
     QMouseEvent *asMouseEvent() const;
 
     bool isMouseEvent() const;
@@ -426,21 +416,17 @@ public:
     bool isValid() const { return m_event != nullptr; }
 
     int pointCount() const { return m_pointCount; }
-    const QQuickEventPoint *point(int i) const {
-        if (Q_UNLIKELY(i < 0 || i >= m_pointCount))
-            return nullptr;
-        if (isTouchEvent())
-            return m_touchPoints.at(i);
-        if (isMouseEvent())
-            return m_mousePoint;
-        return nullptr;
-    }
+    const QQuickEventPoint *point(int i) const;
 
     const QTouchEvent::TouchPoint *touchPointById(int pointId) const;
 
     QTouchEvent *touchEventForItem(const QList<const QQuickEventPoint *> &newPoints, QQuickItem *relativeTo) const;
 
-protected:
+private:
+    void initFromMouse(QMouseEvent *ev);
+    void initFromTouch(QTouchEvent *ev);
+
+private:
     const QQuickPointerDevice *m_device;
     QInputEvent *m_event; // original event as received by QQuickWindow
     Qt::MouseButton m_button;
@@ -449,10 +435,6 @@ protected:
     QVector<QQuickEventTouchPoint *> m_touchPoints;
     QQuickEventPoint *m_mousePoint;
 
-private:
-    void initFromMouse(QMouseEvent *ev);
-    void initFromTouch(QTouchEvent *ev);
-
     Q_DISABLE_COPY(QQuickPointerEvent)
 };