Documentation: Adding comments to QHoverEvent class

Explaining the difference between hover events and enter/leave/move events
Task-number: QT-1116
Reviewed-by: Bjørn Erik Nilsen

2 files changed, 34 insertions, 0 deletions

diff --git a/doc/src/images/hoverevents.png b/doc/src/images/hoverevents.png
new file mode 100644
index 0000000000..ccc079bdf1
--- /dev/null
+++ b/doc/src/images/hoverevents.png
diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index ff97405ea8..c4a25e18c2 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -399,6 +399,40 @@ QMouseEventEx::~QMouseEventEx()
 
     The function pos() gives the current cursor position, while oldPos() gives
     the old mouse position.
+
+    There are a few similarities between the events QEvent::HoverEnter
+    and QEvent::HoverLeave, and the events QEvent::Enter and QEvent::Leave.
+    However, they are slightly different because we do an update() in the event
+    handler of HoverEnter and HoverLeave.
+
+    QEvent::HoverMove is also slightly different from QEvent::MouseMove. Let us
+    consider a top-level window A containing a child B which in turn contains a
+    child C (all with mouse tracking enabled):
+
+    \image hoverEvents.png
+
+    Now, if you move the cursor from the top to the bottom in the middle of A,
+    you will get the following QEvent::MouseMove events:
+
+    \list 1
+        \o A::MouseMove
+        \o B::MouseMove
+        \o C::MouseMove
+    \endlist
+
+    You will get the same events for QEvent::HoverMove, except that the event
+    always propagates to the top-level regardless whether the event is accepted
+    or not. It will only stop propagating with the Qt::WA_NoMousePropagation
+    attribute.
+
+    In this case the events will occur in the following way:
+
+    \list 1
+        \o A::HoverMove
+        \o A::HoverMove, B::HoverMove
+        \o A::HoverMove, B::HoverMove, C::HoverMove
+    \endlist
+    
 */
 
 /*!