Clarify use of (Map)MouseArea with MapQuickItem, general cleanup

Task-number: QTBUG-23614

Change-Id: If4c0cf53fe16be9083769521a0ec009f2341eac2
Reviewed-by: David Laing <david.laing@nokia.com>

2 files changed, 92 insertions, 23 deletions

diff --git a/src/imports/location/qdeclarativegeomapmousearea.cpp b/src/imports/location/qdeclarativegeomapmousearea.cpp
index 1baf6615..5d0ec441 100644
--- a/src/imports/location/qdeclarativegeomapmousearea.cpp
+++ b/src/imports/location/qdeclarativegeomapmousearea.cpp
@@ -58,27 +58,54 @@ QT_BEGIN_NAMESPACE
     \inqmlmodule QtLocation 5
     \ingroup qml-QtLocation5-maps
 
-   A MapMouseArea is an invisible item that is typically used in conjunction
-   with a visible map object or map item in order to provide mouse handling.
-   By effectively acting as a proxy, the logic for mouse handling can be
-   contained within a MapMouseArea item.
-
-   The \l enabled property is used to enable and disable mouse handling for
-   the proxied item. When disabled, the mouse area becomes transparent to
-   mouse events.
-
-   The \l pressed read-only property indicates whether or not the user is
-   holding down a mouse button over the mouse area. This property is often
-   used in bindings between properties in a user interface.
-
-   Information about the mouse position and button clicks are provided via
-   signals for which event handler properties are defined. The most commonly
-   used involved handling mouse presses and clicks: onClicked, onDoubleClicked,
-   onPressed and onReleased.
-
-   MapMouseArea does not intend to be generic mouse area that supports every
-   possible usage, rather it focuses on catering for the major use-cases. Hence there
-   are some implementation limitations:
+    Like a standard Qt Quick \l{MouseArea}, the MapMouseArea provides mouse
+    handling for an item. Creating a normal Qt Quick MouseArea inside a
+    map object element (eg. MapPolygon) will result in undefined behaviour
+    due to the way in which Map objects are rendered, so MapMouseArea exists to
+    provide this functionality instead.
+
+    The only exception to this is the MapQuickItem, which can have normal
+    MouseArea elements defined within the sourceItem. See the documentation
+    for \l{MapQuickItem} for more details.
+
+    The \l enabled property of the MapMouseArea is used to enable and disable
+    mouse handling for the proxied item. When disabled, the mouse area becomes
+    transparent to mouse events.
+
+    The \l pressed read-only property indicates whether or not the user is
+    holding down a mouse button over the mouse area. This property is often
+    used in bindings between properties in a user interface.
+
+    Information about the mouse position and button clicks are provided via
+    signals for which event handler properties are defined. The most commonly
+    used involved handling mouse presses and clicks: onClicked, onDoubleClicked,
+    onPressed and onReleased.
+
+    \section2 Example Usage
+
+    The following example shows a map containing a MapCircle object. When
+    the user clicks the MapCircle, a message is printed to the console.
+
+    \code
+    Map {
+        MapCircle {
+            center: Coordinate { ... }
+            radius: 100
+
+            MapMouseArea {
+                anchors.fill: parent
+
+                onClicked: {
+                    console.log("You clicked the circle!");
+                }
+            }
+        }
+    }
+    \endcode
+
+    \section2 Limitations
+
+    Some important limitations apply to the use of a MapMouseArea:
     \list
         \i The mouse event is guaranteed only to be valid for the
    duration of the signal handler (e.g. onPositionChanged, onClicked). Consequently
@@ -86,8 +113,7 @@ QT_BEGIN_NAMESPACE
    optimize memory usage; we do not want to allocate heap memory every time the mouse
    moves.
         \i Nested mouse areas are not supported (MapMouseArea { MapMouseArea {} }
-        \i Using normal QML MouseArea in MapItem or Map has no effect
-        \i If mouse areas of map overlap, the declaration order is significant (not e.g. 'z' value)
+        \i If two or more MapMouseAreas overlap, the declaration order is significant (not e.g. 'z' value)
         \i Only one MapMouseArea per MapItem is supported, and it always fills the whole MapItem
     \endlist
 
diff --git a/src/imports/location/qdeclarativegeomapquickitem.cpp b/src/imports/location/qdeclarativegeomapquickitem.cpp
index c46f1e10..e6748e46 100644
--- a/src/imports/location/qdeclarativegeomapquickitem.cpp
+++ b/src/imports/location/qdeclarativegeomapquickitem.cpp
@@ -62,6 +62,9 @@ QT_BEGIN_NAMESPACE
     above the Map, a MapQuickItem will follow the panning (and optionally, the
     zooming) of the Map as if it is on the Map surface.
 
+    The \l{sourceItem} property contains the Qt Quick item to be drawn, which
+    can be any kind of visible element.
+
     \section2 Positioning and Sizing
 
     The positioning of the MapQuickItem on the Map is controlled by two
@@ -83,6 +86,46 @@ QT_BEGIN_NAMESPACE
     "on the screen" rather than "on the map", so that its size remains the same
     regardless of the zoom level of the Map.
 
+    \section2 Interaction
+
+    MapQuickItem is different to the other map object elements in that it can
+    accept "normal" QtQuick mouse and touch interaction elements as well as
+    the MapMouseArea and friends. For example, for a MapQuickItem, the following
+    two situations are equivalent:
+
+    \code
+    MapQuickItem {
+        sourceItem: Rectangle {
+            width: 20; height: 20
+        }
+
+        MapMouseArea {
+            onClicked: {
+                console.log("clicked!");
+            }
+        }
+    }
+    \endcode
+
+    \code
+    MapQuickItem {
+        sourceItem: Rectangle {
+            width: 20; height: 20
+
+            MouseArea {
+                onClicked: {
+                    console.log("clicked!");
+                }
+            }
+        }
+    }
+    \endcode
+
+    MouseAreas used inside a complex \l{sourceItem} can be used to create, for
+    example, a "close" button within a speech bubble that can be clicked
+    separately to the rest of the bubble, which would be impossible using
+    MapMouseArea alone.
+
     \section2 Performance
 
     Performance of a MapQuickItem is normally in the same ballpark as the