Allow to create maps with groups of map items

This patch lets a user create an external qml file, and put multiple
map items inside a parent MapItemGroup{}, and add that element to a Map
item.
QDeclarativeGeoMap gets also two associated methods: addMapItemGroup and
removeMapItemGroup to deal with item groups at runtime.
Additionally, clearMapItems now clears also added item groups.

Task-number: QTBUG-55211
Change-Id: Ie4e602e4bda65fb56422b721be5fd34c54eb7954
Reviewed-by: Laszlo Agocs <laszlo.agocs@qt.io>

10 files changed, 406 insertions, 12 deletions

diff --git a/src/imports/location/location.cpp b/src/imports/location/location.cpp
index 44f4bd5a..4536b371 100644
--- a/src/imports/location/location.cpp
+++ b/src/imports/location/location.cpp
@@ -52,6 +52,7 @@
 #include <QtLocation/private/qdeclarativepolygonmapitem_p.h>
 #include <QtLocation/private/qdeclarativegeomapparameter_p.h>
 #include <QtLocation/private/qdeclarativegeomapcopyrightsnotice_p.h>
+#include <QtLocation/private/qdeclarativegeomapitemgroup_p.h>
 
 //Place includes
 #include <QtLocation/private/qdeclarativecategory_p.h>
@@ -173,7 +174,7 @@ public:
             minor = 9;
             qmlRegisterType<QDeclarativeGeoMapParameter>(uri, major, minor, "MapParameter");
             qmlRegisterType<QDeclarativeGeoMapCopyrightNotice>(uri, major, minor, "MapCopyrightNotice");
-
+            qmlRegisterType<QDeclarativeGeoMapItemGroup>(uri, major, minor, "MapItemGroup");
 
             //registrations below are version independent
             qRegisterMetaType<QPlaceCategory>();
diff --git a/src/location/declarativemaps/declarativemaps.pri b/src/location/declarativemaps/declarativemaps.pri
index 52e61049..e1054001 100644
--- a/src/location/declarativemaps/declarativemaps.pri
+++ b/src/location/declarativemaps/declarativemaps.pri
@@ -28,6 +28,7 @@ PRIVATE_HEADERS += \
            declarativemaps/qdeclarativegeomapcopyrightsnotice_p.h \
            declarativemaps/locationvaluetypehelper_p.h \
            declarativemaps/qquickgeomapgesturearea_p.h \
+           declarativemaps/qdeclarativegeomapitemgroup_p.h \
            declarativemaps/mapitemviewdelegateincubator_p.h \
            ../imports/positioning/qquickgeocoordinateanimation_p.h
 
@@ -54,6 +55,7 @@ SOURCES += \
            declarativemaps/error_messages.cpp \
            declarativemaps/locationvaluetypehelper.cpp \
            declarativemaps/qquickgeomapgesturearea.cpp \
+           declarativemaps/qdeclarativegeomapitemgroup.cpp \
            ../imports/positioning/qquickgeocoordinateanimation.cpp \
            declarativemaps/mapitemviewdelegateincubator.cpp
 
diff --git a/src/location/declarativemaps/qdeclarativegeomap.cpp b/src/location/declarativemaps/qdeclarativegeomap.cpp
index 970161fa..00be6376 100644
--- a/src/location/declarativemaps/qdeclarativegeomap.cpp
+++ b/src/location/declarativemaps/qdeclarativegeomap.cpp
@@ -207,6 +207,18 @@ QDeclarativeGeoMap::~QDeclarativeGeoMap()
     }
     m_mapItems.clear();
 
+    for (auto g: qAsConst(m_mapItemGroups)) {
+        if (!g)
+            continue;
+        const QList<QQuickItem *> quickKids = g->childItems();
+        for (auto c: quickKids) {
+            QDeclarativeGeoMapItemBase *itemBase = qobject_cast<QDeclarativeGeoMapItemBase *>(c);
+            if (itemBase)
+                itemBase->setMap(0,0);
+        }
+    }
+    m_mapItemGroups.clear();
+
     delete m_copyrights.data();
     m_copyrights.clear();
 }
@@ -506,6 +518,8 @@ QQuickGeoMapGestureArea *QDeclarativeGeoMap::gesture()
 
 /*!
     \internal
+
+    This may happen before mappingManagerInitialized()
 */
 void QDeclarativeGeoMap::populateMap()
 {
@@ -525,6 +539,13 @@ void QDeclarativeGeoMap::populateMap()
         QDeclarativeGeoMapItemBase *mapItem = qobject_cast<QDeclarativeGeoMapItemBase *>(kids.at(i));
         if (mapItem) {
             addMapItem(mapItem);
+            continue;
+        }
+        // Allow to add to the map Map items contained inside a parent QQuickItem, but only those at one level of nesting.
+        QDeclarativeGeoMapItemGroup *itemGroup = qobject_cast<QDeclarativeGeoMapItemGroup *>(kids.at(i));
+        if (itemGroup) {
+            addMapItemGroup(itemGroup);
+            continue;
         }
     }
 }
@@ -686,6 +707,17 @@ void QDeclarativeGeoMap::mappingManagerInitialized()
         }
     }
 
+    // Any map item groups that were added before the plugin was ready
+    // need to have setMap called again on their children map items
+    for (auto g: qAsConst(m_mapItemGroups)) {
+        const QList<QQuickItem *> quickKids = g->childItems();
+        for (auto c: quickKids) {
+            QDeclarativeGeoMapItemBase *itemBase = qobject_cast<QDeclarativeGeoMapItemBase *>(c);
+            if (itemBase)
+                itemBase->setMap(this, m_map);
+        }
+    }
+
     // All map parameters that were added before the plugin was ready
     // need to be added to m_map
     for (QDeclarativeGeoMapParameter *p : m_mapParameters)
@@ -1406,7 +1438,9 @@ void QDeclarativeGeoMap::addMapItem(QDeclarativeGeoMapItemBase *item)
 {
     if (!item || item->quickMap())
         return;
-    item->setParentItem(this);
+    // If the item comes from a MapItemGroup, do not reparent it.
+    if (!qobject_cast<QDeclarativeGeoMapItemGroup *>(item->parentItem()))
+        item->setParentItem(this);
     m_mapItems.append(item);
     if (m_map) {
         item->setMap(this, m_map);
@@ -1542,8 +1576,9 @@ void QDeclarativeGeoMap::removeMapItem(QDeclarativeGeoMapItemBase *ptr)
     QPointer<QDeclarativeGeoMapItemBase> item(ptr);
     if (!m_mapItems.contains(item))
         return;
-    item.data()->setParentItem(0);
-    item.data()->setMap(0, 0);
+    if (item->parentItem() == this)
+        item->setParentItem(0);
+    item->setMap(0, 0);
     // these can be optimized for perf, as we already check the 'contains' above
     m_mapItems.removeOne(item);
     emit mapItemsChanged();
@@ -1552,26 +1587,86 @@ void QDeclarativeGeoMap::removeMapItem(QDeclarativeGeoMapItemBase *ptr)
 /*!
     \qmlmethod void QtLocation::Map::clearMapItems()
 
-    Removes all items from the map.
+    Removes all items and item groups from the map.
 
-    \sa mapItems, addMapItem, removeMapItem
+    \sa mapItems, addMapItem, removeMapItem, addMapItemGroup, removeMapItemGroup
 */
 void QDeclarativeGeoMap::clearMapItems()
 {
     m_map->clearMapItems();
     if (m_mapItems.isEmpty())
         return;
-    for (int i = 0; i < m_mapItems.count(); ++i) {
-        if (m_mapItems.at(i)) {
-            m_mapItems.at(i).data()->setParentItem(0);
-            m_mapItems.at(i).data()->setMap(0, 0);
+    for (auto i : qAsConst(m_mapItems)) {
+        if (i) {
+            i->setMap(0, 0);
+            if (i->parentItem() == this)
+                i->setParentItem(0);
         }
     }
     m_mapItems.clear();
+    m_mapItemGroups.clear();
     emit mapItemsChanged();
 }
 
 /*!
+    \qmlmethod void QtLocation::Map::addMapItemGroup(MapItemGroup itemGroup)
+
+    Adds the map items contained in the given \a itemGroup to the Map
+    (for example MapQuickItem, MapCircle). These items will be reparented, and the map
+    will be their new parent. Property bindings defined using \e{parent.} inside a MapItemGroup
+    will therefore not work.
+
+    \sa MapItemGroup, removeMapItemGroup
+
+    \since 5.9
+*/
+void QDeclarativeGeoMap::addMapItemGroup(QDeclarativeGeoMapItemGroup *itemGroup)
+{
+    if (!itemGroup)
+        return;
+
+    QPointer<QDeclarativeGeoMapItemGroup> g(itemGroup);
+    if (m_mapItemGroups.contains(g))
+        return;
+
+    m_mapItemGroups.append(g);
+    const QList<QQuickItem *> quickKids = g->childItems();
+    for (auto c: quickKids) {
+        QDeclarativeGeoMapItemBase *mapItem = qobject_cast<QDeclarativeGeoMapItemBase *>(c);
+        if (mapItem)
+            addMapItem(mapItem);
+    }
+    itemGroup->setParentItem(this);
+}
+
+/*!
+    \qmlmethod void QtLocation::Map::removeMapItemGroup(MapItemGroup itemGroup)
+
+    Removes \a itemGroup and the items contained therein from the Map.
+
+    \sa MapItemGroup, addMapItemGroup
+
+    \since 5.9
+*/
+void QDeclarativeGeoMap::removeMapItemGroup(QDeclarativeGeoMapItemGroup *itemGroup)
+{
+    if (!itemGroup)
+        return;
+
+    QPointer<QDeclarativeGeoMapItemGroup> g(itemGroup);
+    if (!m_mapItemGroups.removeOne(g))
+        return;
+
+    const QList<QQuickItem *> quickKids = itemGroup->childItems();
+    for (auto c: quickKids) {
+        QDeclarativeGeoMapItemBase *mapItem = qobject_cast<QDeclarativeGeoMapItemBase *>(c);
+        if (mapItem)
+            removeMapItem(mapItem);
+    }
+    itemGroup->setParentItem(0);
+}
+
+/*!
     \qmlproperty MapType QtLocation::Map::activeMapType
 
     \brief Access to the currently active \l{MapType}{map type}.
diff --git a/src/location/declarativemaps/qdeclarativegeomap_p.h b/src/location/declarativemaps/qdeclarativegeomap_p.h
index b010bda2..1bf1ecd6 100644
--- a/src/location/declarativemaps/qdeclarativegeomap_p.h
+++ b/src/location/declarativemaps/qdeclarativegeomap_p.h
@@ -51,7 +51,7 @@
 #include <QtLocation/private/qlocationglobal_p.h>
 #include <QtLocation/private/qdeclarativegeomapitemview_p.h>
 #include <QtLocation/private/qquickgeomapgesturearea_p.h>
-
+#include <QtLocation/private/qdeclarativegeomapitemgroup_p.h>
 #include <QtLocation/qgeoserviceprovider.h>
 #include <QtLocation/private/qgeocameradata_p.h>
 #include <QtQuick/QQuickItem>
@@ -153,6 +153,9 @@ public:
     Q_INVOKABLE void removeMapItem(QDeclarativeGeoMapItemBase *item);
     Q_INVOKABLE void addMapItem(QDeclarativeGeoMapItemBase *item);
 
+    Q_INVOKABLE void addMapItemGroup(QDeclarativeGeoMapItemGroup *itemGroup);
+    Q_INVOKABLE void removeMapItemGroup(QDeclarativeGeoMapItemGroup *itemGroup);
+
     Q_INVOKABLE void clearMapItems();
     QList<QObject *> mapItems();
 
@@ -242,6 +245,7 @@ private:
     QGeoMap *m_map;
     QPointer<QDeclarativeGeoMapCopyrightNotice> m_copyrights;
     QList<QPointer<QDeclarativeGeoMapItemBase> > m_mapItems;
+    QList<QPointer<QDeclarativeGeoMapItemGroup> > m_mapItemGroups;
     QString m_errorString;
     QGeoServiceProvider::Error m_error;
     QGeoRectangle m_visibleRegion;
diff --git a/src/location/declarativemaps/qdeclarativegeomapitemgroup.cpp b/src/location/declarativemaps/qdeclarativegeomapitemgroup.cpp
new file mode 100644
index 00000000..a60d7aec
--- /dev/null
+++ b/src/location/declarativemaps/qdeclarativegeomapitemgroup.cpp
@@ -0,0 +1,150 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the QtLocation module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL3$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPLv3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or later as published by the Free
+** Software Foundation and appearing in the file LICENSE.GPL included in
+** the packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 2.0 requirements will be
+** met: http://www.gnu.org/licenses/gpl-2.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qdeclarativegeomapitemgroup_p.h"
+
+QT_BEGIN_NAMESPACE
+
+/*!
+    \qmltype MapItemGroup
+    \instantiates QDeclarativeGeoMapItemGroup
+    \inqmlmodule QtLocation
+    \ingroup qml-QtLocation5-maps
+    \since Qt Location 5.9
+
+    \brief The MapItemGroup type is a container for map items.
+
+    Its purpose is to enable code modularization by allowing the usage
+    of qml files containing map elements related to each other, and
+    the associated bindings.
+
+    \note The release of this API with Qt 5.9 is a Technology Preview.
+
+    \section2 Example Usage
+
+    The following snippet shows how to use a MapItemGroup to create a MapCircle, centered at
+    the coordinate (63, -18) with a radius of 100km, filled in red, surrounded by an ondulated green border,
+    both contained in a semitransparent blue circle with a MouseArea that moves the whole group.
+    This group is defined in a separate file named PolygonGroup.qml:
+
+    \code
+    import QtQuick 2.4
+    import QtPositioning 5.6
+    import QtLocation 5.9
+
+    MapItemGroup {
+        id: itemGroup
+        property alias position: mainCircle.center
+        property var radius: 100 * 1000
+        property var borderHeightPct : 0.3
+
+        MapCircle {
+            id: mainCircle
+            center : QtPositioning.coordinate(40, 0)
+            radius: itemGroup.radius * (1.0 + borderHeightPct)
+            opacity: 0.05
+            visible: true
+            color: 'blue'
+
+            MouseArea{
+                anchors.fill: parent
+                drag.target: parent
+                id: maItemGroup
+            }
+        }
+
+        MapCircle {
+            id: groupCircle
+            center: itemGroup.position
+            radius: itemGroup.radius
+            color: 'crimson'
+
+            onCenterChanged: {
+                groupPolyline.populateBorder();
+            }
+        }
+
+        MapPolyline {
+            id: groupPolyline
+            line.color: 'green'
+            line.width: 3
+
+            function populateBorder() {
+                groupPolyline.path = [] // clearing the path
+                var waveLength = 8.0;
+                var waveAmplitude = groupCircle.radius * borderHeightPct;
+                for (var i=0; i <= 360; i++) {
+                    var wavePhase = (i/360.0 * 2.0 * Math.PI )* waveLength
+                    var waveHeight = (Math.cos(wavePhase) + 1.0) / 2.0
+                    groupPolyline.addCoordinate(groupCircle.center.atDistanceAndAzimuth(groupCircle.radius + waveAmplitude * waveHeight , i))
+                }
+            }
+
+            Component.onCompleted: {
+                populateBorder()
+            }
+        }
+    }
+    \endcode
+
+    PolygonGroup.qml is now a reusable component that can then be used in a Map as:
+
+    \code
+    Map {
+        id: map
+        PolygonGroup {
+            id: polygonGroup
+            position: QtPositioning.coordinate(63,-18)
+        }
+    }
+    \endcode
+
+    \image api-mapitemgroup.png
+*/
+
+QDeclarativeGeoMapItemGroup::QDeclarativeGeoMapItemGroup(QQuickItem *parent): QQuickItem(parent)
+{
+
+}
+
+QDeclarativeGeoMapItemGroup::~QDeclarativeGeoMapItemGroup()
+{
+
+}
+
+#include "moc_qdeclarativegeomapitemgroup_p.cpp"
+
+QT_END_NAMESPACE
diff --git a/src/location/declarativemaps/qdeclarativegeomapitemgroup_p.h b/src/location/declarativemaps/qdeclarativegeomapitemgroup_p.h
new file mode 100644
index 00000000..1b008d71
--- /dev/null
+++ b/src/location/declarativemaps/qdeclarativegeomapitemgroup_p.h
@@ -0,0 +1,69 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the QtLocation module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL3$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPLv3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or later as published by the Free
+** Software Foundation and appearing in the file LICENSE.GPL included in
+** the packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 2.0 requirements will be
+** met: http://www.gnu.org/licenses/gpl-2.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QDECLARATIVEGEOMAPITEMGROUP_P_H
+#define QDECLARATIVEGEOMAPITEMGROUP_P_H
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is not part of the Qt API.  It exists purely as an
+// implementation detail.  This header file may change from version to
+// version without notice, or even be removed.
+//
+// We mean it.
+//
+
+#include <QtLocation/private/qlocationglobal_p.h>
+#include <QtQuick/QQuickItem>
+
+QT_BEGIN_NAMESPACE
+
+class Q_LOCATION_PRIVATE_EXPORT QDeclarativeGeoMapItemGroup : public QQuickItem
+{
+    Q_OBJECT
+public:
+    explicit QDeclarativeGeoMapItemGroup(QQuickItem *parent = 0);
+    virtual ~QDeclarativeGeoMapItemGroup();
+
+};
+
+QT_END_NAMESPACE
+
+QML_DECLARE_TYPE(QDeclarativeGeoMapItemGroup)
+
+#endif // QDECLARATIVEGEOMAPITEMGROUP_P_H
diff --git a/src/location/doc/images/api-mapitemgroup.png b/src/location/doc/images/api-mapitemgroup.png
new file mode 100644
index 00000000..4dbdfe65
--- /dev/null
+++ b/src/location/doc/images/api-mapitemgroup.png
diff --git a/tests/auto/declarative_ui/ItemGroup.qml b/tests/auto/declarative_ui/ItemGroup.qml
new file mode 100644
index 00000000..57108ec7
--- /dev/null
+++ b/tests/auto/declarative_ui/ItemGroup.qml
@@ -0,0 +1,62 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the test suite of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:GPL-EXCEPT$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 as published by the Free Software
+** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.4
+import QtPositioning 5.6
+import QtLocation 5.9
+import QtLocation.Test 5.6
+
+MapItemGroup {
+    id: itemGroup
+    property double latitude : (mainRectangle.topLeft.latitude + mainRectangle.bottomRight.latitude) / 2.0
+    property double longitude: (mainRectangle.topLeft.longitude + mainRectangle.bottomRight.longitude) / 2.0
+    property double radius: 100 * 1000
+
+    MapRectangle {
+        id: mainRectangle
+        topLeft: QtPositioning.coordinate(43, -3)
+        bottomRight: QtPositioning.coordinate(37, 3)
+        opacity: 0.05
+        visible: true
+        color: 'blue'
+    }
+
+    MapCircle {
+        id: groupCircle
+        center: QtPositioning.coordinate(parent.latitude, parent.longitude)
+        radius: parent.radius
+        color: 'crimson'
+    }
+
+    MapRectangle {
+        id: groupRectangle
+        topLeft: QtPositioning.coordinate(parent.latitude + 5, parent.longitude - 5)
+        bottomRight: QtPositioning.coordinate(parent.latitude, parent.longitude )
+        color: 'yellow'
+    }
+}
diff --git a/tests/auto/declarative_ui/declarative_ui.pro b/tests/auto/declarative_ui/declarative_ui.pro
index d3a2f08e..6734b1f9 100644
--- a/tests/auto/declarative_ui/declarative_ui.pro
+++ b/tests/auto/declarative_ui/declarative_ui.pro
@@ -16,3 +16,6 @@ TESTDATA = $$OTHER_FILES
 
 # Import path used by 'make check' since CI doesn't install test imports
 IMPORTPATH = $$OUT_PWD/../../../qml
+
+DISTFILES += \
+    ItemGroup.qml
diff --git a/tests/auto/declarative_ui/tst_map_item.qml b/tests/auto/declarative_ui/tst_map_item.qml
index 8ede357f..b75daf38 100644
--- a/tests/auto/declarative_ui/tst_map_item.qml
+++ b/tests/auto/declarative_ui/tst_map_item.qml
@@ -28,7 +28,7 @@
 
 import QtQuick 2.0
 import QtTest 1.0
-import QtLocation 5.6
+import QtLocation 5.9
 import QtPositioning 5.5
 import QtLocation.Test 5.6
 
@@ -75,6 +75,10 @@ Item {
     }
     Item { id: someItem }
 
+    ItemGroup {
+        id: itemGroup1
+    }
+
     MapCircle {
         id: extMapCircle
         center {
@@ -403,6 +407,10 @@ Item {
             mouseClick(map, map.width + 5, point.y + 5)
             tryCompare(extMapQuickItemClicked, "count", 1)
             map.removeMapItem(extMapQuickItem)
+
+            var numItemsOnMap = map.mapItems.length
+            map.addMapItemGroup( itemGroup1 )
+            compare(map.mapItems.length, numItemsOnMap + 3)
         }
 
         function test_drag()