MapParameters for accessing specific features of custom QGeoMaps

This patch adds a new MapParameter object to give users access to
specific features of a custom QGeoMap otherwise not accessible through
the standard API.

A MapParameter is implemented by a QDeclarativeGeoMapParameter, which,
in turns, inherits from QGeoMapParameter in the location module.

In this way QGeoMap & subclasses won't depend on declarative, from
this side, still allowing a QMapWidget someday.

The implementation is based, on both sides, on the dynamic
properties of QObjects for defining the MapProperty data.
This allows high flexibility in defining various types of
MapParameters (essentially by duck typing them), and therefore
each plugin which makes use of them must document each of them.

Change-Id: I5f3a8c18e996f290beb8e4ff37d3c2c655eefc6c
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

6 files changed, 344 insertions, 2 deletions

diff --git a/src/imports/location/location.cpp b/src/imports/location/location.cpp
index 6405313b..f9b3545f 100644
--- a/src/imports/location/location.cpp
+++ b/src/imports/location/location.cpp
@@ -49,6 +49,7 @@
 #include "qdeclarativeroutemapitem_p.h"
 #include "qdeclarativepolylinemapitem_p.h"
 #include "qdeclarativepolygonmapitem_p.h"
+#include "qdeclarativegeomapparameter_p.h"
 
 //Place includes
 #include "qdeclarativecategory_p.h"
@@ -166,6 +167,11 @@ public:
             minor = 7;
             qmlRegisterType<QDeclarativeGeoManeuver>(uri, major, minor, "RouteManeuver");
 
+            // Register the 5.9 types
+            minor = 9;
+            qmlRegisterType<QDeclarativeGeoMapParameter>(uri, major, minor, "MapParameter");
+
+
             //registrations below are version independent
             qRegisterMetaType<QPlaceCategory>();
             qRegisterMetaType<QPlace>();
diff --git a/src/imports/location/location.pro b/src/imports/location/location.pro
index 57172ad8..e733a768 100644
--- a/src/imports/location/location.pro
+++ b/src/imports/location/location.pro
@@ -30,7 +30,8 @@ HEADERS += \
            qquickgeomapgesturearea_p.h\
            ../positioning/qquickgeocoordinateanimation_p.h \
            mapitemviewdelegateincubator.h \
-           qdeclarativegeomapitemview_p_p.h
+           qdeclarativegeomapitemview_p_p.h \
+           qdeclarativegeomapparameter_p.h
 
 SOURCES += \
            location.cpp \
@@ -56,7 +57,8 @@ SOURCES += \
            locationvaluetypehelper.cpp \
            qquickgeomapgesturearea.cpp \
            ../positioning/qquickgeocoordinateanimation.cpp \
-           mapitemviewdelegateincubator.cpp
+           mapitemviewdelegateincubator.cpp \
+           qdeclarativegeomapparameter.cpp
 
 include(declarativeplaces/declarativeplaces.pri)
 
diff --git a/src/imports/location/qdeclarativegeomap.cpp b/src/imports/location/qdeclarativegeomap.cpp
index dcf8b203..49d6ddd1 100644
--- a/src/imports/location/qdeclarativegeomap.cpp
+++ b/src/imports/location/qdeclarativegeomap.cpp
@@ -42,6 +42,7 @@
 #include "qgeomappingmanager_p.h"
 #include "qgeocameracapabilities_p.h"
 #include "qgeomap_p.h"
+#include "qdeclarativegeomapparameter_p.h"
 #include <QtPositioning/QGeoCircle>
 #include <QtPositioning/QGeoRectangle>
 #include <QtQuick/QQuickWindow>
@@ -359,6 +360,7 @@ void QDeclarativeGeoMap::pluginReady()
 void QDeclarativeGeoMap::componentComplete()
 {
     m_componentCompleted = true;
+    populateParameters();
     populateMap();
     QQuickItem::componentComplete();
 }
@@ -454,6 +456,19 @@ void QDeclarativeGeoMap::populateMap()
     }
 }
 
+void QDeclarativeGeoMap::populateParameters()
+{
+    QObjectList kids = children();
+    QList<QQuickItem *> quickKids = childItems();
+    for (int i = 0; i < quickKids.count(); ++i)
+        kids.append(quickKids.at(i));
+    for (int i = 0; i < kids.size(); ++i) {
+        QDeclarativeGeoMapParameter *mapParameter = qobject_cast<QDeclarativeGeoMapParameter *>(kids.at(i));
+        if (mapParameter)
+            addMapParameter(mapParameter);
+    }
+}
+
 /*!
     \internal
 */
@@ -589,6 +604,11 @@ void QDeclarativeGeoMap::mappingManagerInitialized()
         if (item)
             item.data()->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)
+        m_map->addParameter(p);
 }
 
 /*!
@@ -1206,6 +1226,95 @@ void QDeclarativeGeoMap::addMapItem(QDeclarativeGeoMapItemBase *item)
 }
 
 /*!
+    \qmlmethod void QtLocation::Map::addMapParameter(MapParameter parameter)
+
+    Adds a MapParameter object to the map. The effect of this call is dependent
+    on the combination of the content of the MapParameter and the type of
+    underlying QGeoMap. If a MapParameter that is not supported by the underlying
+    QGeoMap gets added, the call has no effect.
+
+    The release of this API with Qt 5.9 is a Technology Preview.
+
+    \sa MapParameter, removeMapParameter, mapParameters, clearMapParameters
+
+    \since 5.9
+*/
+void QDeclarativeGeoMap::addMapParameter(QDeclarativeGeoMapParameter *parameter)
+{
+    if (!parameter->isComponentComplete()) {
+        connect(parameter, &QDeclarativeGeoMapParameter::completed, this, &QDeclarativeGeoMap::addMapParameter);
+        return;
+    }
+
+    disconnect(parameter);
+    if (m_mapParameters.contains(parameter))
+        return;
+    parameter->setParent(this);
+    m_mapParameters.insert(parameter); // parameter now owned by QDeclarativeGeoMap
+    if (m_map)
+        m_map->addParameter(parameter);
+}
+
+/*!
+    \qmlmethod void QtLocation::Map::removeMapParameter(MapParameter parameter)
+
+    Removes the given MapParameter object from the map.
+
+    The release of this API with Qt 5.9 is a Technology Preview.
+
+    \sa MapParameter, addMapParameter, mapParameters, clearMapParameters
+
+    \since 5.9
+*/
+void QDeclarativeGeoMap::removeMapParameter(QDeclarativeGeoMapParameter *parameter)
+{
+    if (!m_mapParameters.contains(parameter))
+        return;
+    if (m_map)
+        m_map->removeParameter(parameter);
+    m_mapParameters.remove(parameter);
+}
+
+/*!
+    \qmlmethod void QtLocation::Map::clearMapParameters()
+
+    Removes all map parameters from the map.
+
+    The release of this API with Qt 5.9 is a Technology Preview.
+
+    \sa MapParameter, mapParameters, addMapParameter, removeMapParameter, clearMapParameters
+
+    \since 5.9
+*/
+void QDeclarativeGeoMap::clearMapParameters()
+{
+    if (m_map)
+        m_map->clearParameters();
+    m_mapParameters.clear();
+}
+
+/*!
+    \qmlproperty list<MapParameters> QtLocation::Map::mapParameters
+
+    Returns the list of all map parameters in no particular order.
+    These items include map parameters that were declared statically as part of
+    the type declaration, as well as dynamical map parameters (\l addMapParameter).
+
+    The release of this API with Qt 5.9 is a Technology Preview.
+
+    \sa MapParameter, addMapParameter, removeMapParameter, clearMapParameters
+
+    \since 5.9
+*/
+QList<QObject *> QDeclarativeGeoMap::mapParameters()
+{
+    QList<QObject *> ret;
+    for (QDeclarativeGeoMapParameter *p : m_mapParameters)
+        ret << p;
+    return ret;
+}
+
+/*!
     \qmlproperty list<MapItem> QtLocation::Map::mapItems
 
     Returns the list of all map items in no particular order.
diff --git a/src/imports/location/qdeclarativegeomap_p.h b/src/imports/location/qdeclarativegeomap_p.h
index 468046d1..e0940f97 100644
--- a/src/imports/location/qdeclarativegeomap_p.h
+++ b/src/imports/location/qdeclarativegeomap_p.h
@@ -54,6 +54,7 @@
 #include "qgeocameradata_p.h"
 #include <QtQuick/QQuickItem>
 #include <QtCore/QPointer>
+#include <QtCore/QSet>
 #include <QtGui/QColor>
 #include <QtPositioning/qgeoshape.h>
 
@@ -62,6 +63,7 @@ QT_BEGIN_NAMESPACE
 class QDeclarativeGeoServiceProvider;
 class QDeclarativeGeoMapType;
 class QDeclarativeGeoMapCopyrightNotice;
+class QDeclarativeGeoMapParameter;
 
 class QDeclarativeGeoMap : public QQuickItem
 {
@@ -76,6 +78,7 @@ class QDeclarativeGeoMap : public QQuickItem
     Q_PROPERTY(QQmlListProperty<QDeclarativeGeoMapType> supportedMapTypes READ supportedMapTypes NOTIFY supportedMapTypesChanged)
     Q_PROPERTY(QGeoCoordinate center READ center WRITE setCenter NOTIFY centerChanged)
     Q_PROPERTY(QList<QObject *> mapItems READ mapItems NOTIFY mapItemsChanged)
+    Q_PROPERTY(QList<QObject *> mapParameters READ mapParameters)
     Q_PROPERTY(QGeoServiceProvider::Error error READ error NOTIFY errorChanged)
     Q_PROPERTY(QString errorString READ errorString NOTIFY errorChanged)
     Q_PROPERTY(QGeoShape visibleRegion READ visibleRegion WRITE setVisibleRegion)
@@ -119,9 +122,15 @@ public:
 
     Q_INVOKABLE void removeMapItem(QDeclarativeGeoMapItemBase *item);
     Q_INVOKABLE void addMapItem(QDeclarativeGeoMapItemBase *item);
+
     Q_INVOKABLE void clearMapItems();
     QList<QObject *> mapItems();
 
+    Q_INVOKABLE void addMapParameter(QDeclarativeGeoMapParameter *parameter);
+    Q_INVOKABLE void removeMapParameter(QDeclarativeGeoMapParameter *parameter);
+    Q_INVOKABLE void clearMapParameters();
+    QList<QObject *> mapParameters();
+
     Q_INVOKABLE QGeoCoordinate toCoordinate(const QPointF &position, bool clipToViewPort = true) const;
     Q_INVOKABLE QPointF fromCoordinate(const QGeoCoordinate &coordinate, bool clipToViewPort = true) const;
 
@@ -177,6 +186,7 @@ private Q_SLOTS:
 private:
     void setupMapView(QDeclarativeGeoMapItemView *view);
     void populateMap();
+    void populateParameters();
     void fitViewportToMapItemsRefine(bool refine);
     void fitViewportToGeoShape();
     bool isInteractive();
@@ -202,6 +212,7 @@ private:
     double m_maximumViewportLatitude;
     bool m_initialized;
     bool m_validRegion;
+    QSet<QDeclarativeGeoMapParameter *> m_mapParameters;
 
     friend class QDeclarativeGeoMapItem;
     friend class QDeclarativeGeoMapItemView;
diff --git a/src/imports/location/qdeclarativegeomapparameter.cpp b/src/imports/location/qdeclarativegeomapparameter.cpp
new file mode 100644
index 00000000..88d609f4
--- /dev/null
+++ b/src/imports/location/qdeclarativegeomapparameter.cpp
@@ -0,0 +1,125 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 "qdeclarativegeomapparameter_p.h"
+
+#include <QByteArray>
+#include <QMetaObject>
+#include <QMetaProperty>
+#include <QSignalMapper>
+
+QT_BEGIN_NAMESPACE
+
+/*!
+    \qmltype MapParameter
+    \instantiates QDeclarativeGeoMapParameter
+    \inqmlmodule QtLocation
+    \ingroup qml-QtLocation5-maps
+    \since Qt Location 5.9
+
+    \brief The MapParameter type represents a parameter for a Map element.
+    This type provides a mean to specify plugin-dependent optional parameters
+    for a map.
+
+    MapParameters by default contain only the \l type property, and
+    are highly plugin-dependent.
+    For this reason, additional properties have to be defined inside a
+    MapParameter at declaration time, using the QML syntax "property var foo".
+
+    What properties have to be put inside a particular MapParameter type for
+    a particular plugin can be found in the documentation of the plugin.
+    Note that MapProperties are \b optional.
+    By not specifying any of them, the Map will have the default behavior.
+
+    The release of this API with Qt 5.9 is a Technology Preview.
+*/
+
+/*!
+    \qmlproperty georectangle QtLocation::MapParameter::type
+
+    Set-once property which holds a string defining the type of the MapParameter
+*/
+
+QDeclarativeGeoMapParameter::QDeclarativeGeoMapParameter(QObject *parent)
+:   QGeoMapParameter(parent), m_initialPropertyCount(metaObject()->propertyCount()), m_complete(false)
+{
+
+}
+
+QDeclarativeGeoMapParameter::~QDeclarativeGeoMapParameter()
+{
+}
+
+bool QDeclarativeGeoMapParameter::isComponentComplete() const
+{
+    return m_complete;
+}
+
+int QDeclarativeGeoMapParameter::initialPropertyCount() const
+{
+    return m_initialPropertyCount;
+}
+
+void QDeclarativeGeoMapParameter::classBegin()
+{
+}
+
+void QDeclarativeGeoMapParameter::componentComplete()
+{
+    for (int i = m_initialPropertyCount; i < metaObject()->propertyCount(); ++i) {
+        QMetaProperty property = metaObject()->property(i);
+
+        if (!property.hasNotifySignal()) {
+            return;
+        }
+
+        QSignalMapper *mapper = new QSignalMapper(this);
+        mapper->setMapping(this, i);
+
+        const QByteArray signalName = '2' + property.notifySignal().methodSignature(); // TODO: explain why '2'
+        QObject::connect(this, signalName, mapper, SLOT(map()));
+        QObject::connect(mapper, SIGNAL(mapped(int)), this, SLOT(onPropertyUpdated(int)));
+    }
+    m_complete = true;
+    emit completed(this);
+}
+
+void QDeclarativeGeoMapParameter::onPropertyUpdated(int index)
+{
+    emit propertyUpdated(this, metaObject()->property(index).name());
+}
+
+QT_END_NAMESPACE
diff --git a/src/imports/location/qdeclarativegeomapparameter_p.h b/src/imports/location/qdeclarativegeomapparameter_p.h
new file mode 100644
index 00000000..31ea5b04
--- /dev/null
+++ b/src/imports/location/qdeclarativegeomapparameter_p.h
@@ -0,0 +1,89 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 QDECLARATIVEGEOMAPPARAMETER_P_H
+#define QDECLARATIVEGEOMAPPARAMETER_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/qgeomapparameter_p.h>
+#include <QQmlParserStatus>
+#include <qqml.h>
+
+QT_BEGIN_NAMESPACE
+
+class QDeclarativeGeoMapParameter : public QGeoMapParameter, public QQmlParserStatus
+{
+    Q_OBJECT
+    Q_INTERFACES(QQmlParserStatus)
+
+public:
+    explicit QDeclarativeGeoMapParameter(QObject *parent = 0);
+    virtual ~QDeclarativeGeoMapParameter();
+
+    bool isComponentComplete() const;
+
+Q_SIGNALS:
+    void completed(QDeclarativeGeoMapParameter *);
+
+protected:
+    int initialPropertyCount() const;
+    // QQmlParserStatus implementation
+    void classBegin() override;
+    void componentComplete() override;
+
+private slots:
+    void onPropertyUpdated(int index);
+
+private:
+    int m_initialPropertyCount;
+    bool m_complete;
+};
+
+QT_END_NAMESPACE
+
+QML_DECLARE_TYPE(QDeclarativeGeoMapParameter)
+
+#endif // QDECLARATIVEGEOMAPPARAMETER_P_H