Doc: clarify event handling

The current documentation says:

"All controls, except non-interactive indicators,
do not let clicks and touches through to items below them.
For example, if Pane is used as the header or footer of
ApplicationWindow, items underneath it will not get mouse
or touch events."

This can be confusing, because a Pane declared as a child
of a MouseArea is "below" the MouseArea in code, but is
"above" the MouseArea in the scene.

Add a code example to make it less ambiguous.

Also, link to the Event Handling section from Pane's docs.

Task-number: QTBUG-71735
Change-Id: I97f4d6501af410bd5d5c0c0e48b14ca65605357d
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>

2 files changed, 15 insertions, 5 deletions

diff --git a/src/quicktemplates2/qquickcontrol.cpp b/src/quicktemplates2/qquickcontrol.cpp
index 90bbf22a..1fa70662 100644
--- a/src/quicktemplates2/qquickcontrol.cpp
+++ b/src/quicktemplates2/qquickcontrol.cpp
@@ -122,10 +122,20 @@ QT_BEGIN_NAMESPACE
     \section1 Event Handling
 
     All controls, except non-interactive indicators, do not let clicks and
-    touches through to items below them. For example, if \l Pane is used as the
-    \l {ApplicationWindow::}{header} or \l {ApplicationWindow::}{footer} of
-    \l ApplicationWindow, items underneath it will not get mouse or touch
-    events.
+    touches through to items below them. For example, the \c console.log()
+    call in the example below will never be executed when clicking on the
+    Pane, because the \l MouseArea is below it in the scene:
+
+    \code
+    MouseArea {
+        anchors.fill: parent
+        onClicked: console.log("MouseArea was clicked")
+
+        Pane {
+            anchors.fill: parent
+        }
+    }
+    \endcode
 
     \sa ApplicationWindow, Container
 */
diff --git a/src/quicktemplates2/qquickpane.cpp b/src/quicktemplates2/qquickpane.cpp
index d923267f..3edbce9d 100644
--- a/src/quicktemplates2/qquickpane.cpp
+++ b/src/quicktemplates2/qquickpane.cpp
@@ -104,7 +104,7 @@ QT_BEGIN_NAMESPACE
     \endcode
 
     \sa {Customizing Pane}, {Container Controls},
-        {Focus Management in Qt Quick Controls 2}
+        {Focus Management in Qt Quick Controls 2}, {Event Handling}
 */
 
 void QQuickPanePrivate::init()