Clarify QTouchEvent docs

Mention something about touch handling with QWindow and document the
non-partialness of touch events which has been taken for granted since
4.6, but has not been documented at all.

Change-Id: I9ec75f74153bbc28e146b000d70fb26384e497a3
Reviewed-by: Samuel Rødal <samuel.rodal@nokia.com>

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index 4782fa5..0ea32f3 100644 (file)
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -3292,6 +3292,9 @@ QWindowStateChangeEvent::~QWindowStateChangeEvent()
     QEvent::TouchCancel. Reimplement QWidget::event() or QAbstractScrollArea::viewportEvent() for
     widgets and QGraphicsItem::sceneEvent() for items in a graphics view to receive touch events.
 
+    Unlike widgets, QWindows receive touch events always, there is no need to opt in. When working
+    directly with a QWindow, it is enough to reimplement QWindow::touchEvent().
+
     The QEvent::TouchUpdate and QEvent::TouchEnd events are sent to the widget or item that
     accepted the QEvent::TouchBegin event. If the QEvent::TouchBegin event is not accepted and not
     filtered by an event filter, then no further touch events are sent until the next
@@ -3308,6 +3311,12 @@ QWindowStateChangeEvent::~QWindowStateChangeEvent()
     each touch point can be retrieved using the QTouchEvent::TouchPoint class. The
     Qt::TouchPointState enum describes the different states that a touch point may have.
 
+    \note The list of touchPoints() will never be partial: A touch event will always contain a touch
+    point for each existing physical touch contacts targetting the window or widget to which the
+    event is sent. For instance, assuming that all touches target the same window or widget, an
+    event with a condition of touchPoints().count()==2 is guaranteed to imply that the number of
+    fingers touching the touchscreen or touchpad is exactly two.
+
     \section1 Event Delivery and Propagation
 
     By default, QGuiApplication translates the first touch point in a QTouchEvent into