From 2a22ff7f1b1991109d404ebff9d487f4fe311ac3 Mon Sep 17 00:00:00 2001 From: "Thiago Marcos P. Santos" Date: Tue, 3 Jan 2017 17:43:56 -0200 Subject: [Qt] Add more docs --- platform/qt/include/qmapboxgl.hpp | 4 +- platform/qt/src/qmapboxgl.cpp | 531 ++++++++++++++++++++++++++++++++------ 2 files changed, 457 insertions(+), 78 deletions(-) diff --git a/platform/qt/include/qmapboxgl.hpp b/platform/qt/include/qmapboxgl.hpp index 1a050540a1..086601af25 100644 --- a/platform/qt/include/qmapboxgl.hpp +++ b/platform/qt/include/qmapboxgl.hpp @@ -181,6 +181,8 @@ public: void setTransitionOptions(qint64 duration, qint64 delay = 0); + void addAnnotationIcon(const QString &name, const QImage &sprite); + QMapbox::AnnotationID addPointAnnotation(const QMapbox::PointAnnotation &); QMapbox::AnnotationID addShapeAnnotation(const QMapbox::ShapeAnnotation &); @@ -199,8 +201,6 @@ public: void resize(const QSize &size, const QSize &framebufferSize); - void addAnnotationIcon(const QString &name, const QImage &sprite); - QPointF pixelForCoordinate(const QMapbox::Coordinate &) const; QMapbox::Coordinate coordinateForPixel(const QPointF &) const; diff --git a/platform/qt/src/qmapboxgl.cpp b/platform/qt/src/qmapboxgl.cpp index d9f8d48b2f..86604a945f 100644 --- a/platform/qt/src/qmapboxgl.cpp +++ b/platform/qt/src/qmapboxgl.cpp @@ -141,14 +141,14 @@ std::unique_ptr toSpriteImage(const QImage &sprite) { /*! \enum QMapboxGLSettings::GLContextMode - This enum sets the expectations for the GL state. + This enum sets the expectations for the OpenGL state. - \value UniqueGLContext The GL context is only used by QMapboxGL, so it is not + \value UniqueGLContext The OpenGL context is only used by QMapboxGL, so it is not reset before each rendering. Use this mode if the intention is to only draw a fullscreen map. - \value SharedGLContext The GL context is shared and the state will be restored - before rendering. This mode is safer when GL calls are performed prior of after + \value SharedGLContext The OpenGL context is shared and the state will be restored + before rendering. This mode is safer when OpenGL calls are performed prior of after we call QMapboxGL::render for rendering a map. \sa contextMode() @@ -202,7 +202,7 @@ QMapboxGLSettings::QMapboxGLSettings() /*! Returns the OpenGL context mode. This is specially important when mixing - with other GL draw calls. + with other OpenGL draw calls. By default, it is set to QMapboxGLSettings::SharedGLContext. */ @@ -285,7 +285,7 @@ void QMapboxGLSettings::setCacheDatabaseMaximumSize(unsigned size) \l {https://github.com/mapbox/mapbox-gl-native/blob/master/bin/offline.sh} {Offline Tool}. - By default, it is set to \b :memory: meaning it will create an in-memory + By default, it is set to \c :memory: meaning it will create an in-memory cache instead of a file on disk. */ QString QMapboxGLSettings::cacheDatabasePath() const @@ -296,7 +296,7 @@ QString QMapboxGLSettings::cacheDatabasePath() const /*! Sets the cache database \a path. - Setting the \a path to \b :memory: will create an in-memory cache. + Setting the \a path to \c :memory: will create an in-memory cache. */ void QMapboxGLSettings::setCacheDatabasePath(const QString &path) { @@ -305,7 +305,7 @@ void QMapboxGLSettings::setCacheDatabasePath(const QString &path) /*! Returns the asset path, which is the root directory from where - the \b asset:// scheme gets resolved in a style. \b asset:// can be used + the \c asset:// scheme gets resolved in a style. \c asset:// can be used for loading a resource from the disk in a style rather than fetching it from the network. @@ -327,7 +327,7 @@ void QMapboxGLSettings::setAssetPath(const QString &path) /*! Returns the access token. - By default, it is taken from the environment variable \b MAPBOX_ACCESS_TOKEN + By default, it is taken from the environment variable \c MAPBOX_ACCESS_TOKEN or empty if the variable is not set. */ QString QMapboxGLSettings::accessToken() const { @@ -381,11 +381,61 @@ void QMapboxGLSettings::setApiBaseUrl(const QString& url) QNetworkAccessManager for HTTP requests and QString for UTF-8 manipulation. QMapboxGL is not thread-safe and it is assumed that it will be accessed from - the same thread as the thread where the GL context lives. + the same thread as the thread where the OpenGL context lives. \since 4.7 */ +/*! + \enum QMapboxGL::MapChange + + This enum represents the last changed occurred to the map state. + + \value MapChangeRegionWillChange A region of the map will change, like + when resizing the map. + + \value MapChangeRegionWillChangeAnimated Not in use by QMapboxGL. + + \value MapChangeRegionIsChanging A region of the map is changing. + + \value MapChangeRegionDidChange A region of the map finished changing. + + \value MapChangeRegionDidChangeAnimated Not in use by QMapboxGL. + + \value MapChangeWillStartLoadingMap The map is getting loaded. This state + is set only once right after QMapboxGL is created and a style is set. + + \value MapChangeDidFinishLoadingMap All the resources were loaded and parsed + and the map is fully rendered. After this state the mapChanged() signal won't fire again unless + the is some client side interaction with the map or a tile expires, causing a new resource + to be requested from the network. + + \value MapChangeDidFailLoadingMap An error occurred when loading the map. + + \value MapChangeWillStartRenderingFrame Just before rendering the frame. This + is the state of the map just after calling render() and might happened many times before + the map is fully loaded. + + \value MapChangeDidFinishRenderingFrame The current frame was rendered but was + left in a partial state. Some parts of the map might be missing because have not arrived + from the network or are being parsed. + + \value MapChangeDidFinishRenderingFrameFullyRendered The current frame was fully rendered. + + \value MapChangeWillStartRenderingMap Set once when the map is about to get + rendered for the first time. + + \value MapChangeDidFinishRenderingMap Not in use by QMapboxGL. + + \value MapChangeDidFinishRenderingMapFullyRendered Map is fully loaded and rendered. + + \value MapChangeDidFinishLoadingStyle The style was loaded. + + \value MapChangeSourceDidChange A source has changed. + + \sa mapChanged() +*/ + /*! \enum QMapboxGL::NorthOrientation @@ -445,7 +495,7 @@ void QMapboxGL::cycleDebugOptions() Sets a new \a style from a JSON that must conform to the \l {https://www.mapbox.com/mapbox-gl-style-spec/} - {Mapbox Style Specification}. + {Mapbox style specification}. \note In case of a invalid style it will trigger a mapChanged signal with QMapboxGL::MapChangeDidFailLoadingMap as argument. @@ -506,8 +556,9 @@ void QMapboxGL::setLatitude(double latitude_) \property QMapboxGL::longitude \brief the map current longitude in degrees. - Setting a longitude doesn't necessarily mean it will be accepted since QMapboxGL - might constrain it within the limits of the Web Mercator projection. + Setting a longitude beyond the limits of the Web Mercator projection will make + the map wrap. As an example, setting the longitude to 360 is effectively the same + as setting it to 0. */ double QMapboxGL::longitude() const { @@ -524,8 +575,11 @@ void QMapboxGL::setLongitude(double longitude_) \brief the map scale factor. This property is used to zoom the map. When \a center is defined, the map will - scale in the direction of the center pixel coordinates. This function could be used for - implementing a pinch gesture or zooming by using the mouse scroll wheel. + scale in the direction of the center pixel coordinates. The \a center will remain + at the same pixel coordinate after scaling as before calling this method. + + \note This function could be used for implementing a pinch gesture or zooming + by using the mouse scroll wheel. \sa zoom() */ @@ -559,11 +613,21 @@ void QMapboxGL::setZoom(double zoom_) d_ptr->mapObj->setZoom(zoom_, d_ptr->margins); } +/*! + Returns the minimum zoom level allowed for the map. + + \sa maximumZoom() +*/ double QMapboxGL::minimumZoom() const { return d_ptr->mapObj->getMinZoom(); } +/*! + Returns the maximum zoom level allowed for the map. + + \sa minimumZoom() +*/ double QMapboxGL::maximumZoom() const { return d_ptr->mapObj->getMaxZoom(); @@ -583,12 +647,14 @@ Coordinate QMapboxGL::coordinate() const return Coordinate(latLng.latitude, latLng.longitude); } -void QMapboxGL::setCoordinate(const Coordinate &coordinate_) +void QMapboxGL::setCoordinate(const QMapbox::Coordinate &coordinate_) { d_ptr->mapObj->setLatLng(mbgl::LatLng { coordinate_.first, coordinate_.second }, d_ptr->margins); } /*! + \fn QMapboxGL::setCoordinateZoom(const QMapbox::Coordinate &coordinate, double zoom) + Convenience method for setting the \a coordinate and \a zoom simultaneously. \note Setting \a coordinate and \a zoom at once is more efficient than doing @@ -597,7 +663,7 @@ void QMapboxGL::setCoordinate(const Coordinate &coordinate_) \sa zoom() \sa coordinate() */ -void QMapboxGL::setCoordinateZoom(const Coordinate &coordinate_, double zoom_) +void QMapboxGL::setCoordinateZoom(const QMapbox::Coordinate &coordinate_, double zoom_) { d_ptr->mapObj->setLatLngZoom( mbgl::LatLng { coordinate_.first, coordinate_.second }, zoom_, d_ptr->margins); @@ -678,27 +744,38 @@ void QMapboxGL::setPitch(double pitch_) d_ptr->mapObj->setPitch(pitch_); } +/*! + Returns the north orientation mode. +*/ QMapboxGL::NorthOrientation QMapboxGL::northOrientation() const { return static_cast(d_ptr->mapObj->getNorthOrientation()); } +/*! + Sets the north orientation mode to \a orientation. +*/ void QMapboxGL::setNorthOrientation(NorthOrientation orientation) { d_ptr->mapObj->setNorthOrientation(static_cast(orientation)); } -void QMapboxGL::setGestureInProgress(bool inProgress) +/*! + Tells the map rendering engine that there is currently a gesture in \a progress. This + affects how the map renders labels, as it will use different texture filters if a gesture + is ongoing. +*/ +void QMapboxGL::setGestureInProgress(bool progress) { - d_ptr->mapObj->setGestureInProgress(inProgress); + d_ptr->mapObj->setGestureInProgress(progress); } /*! Adds an \a className to the list of active classes. Layers tagged with a certain class will only be active when the class is added. - This was removed from \l {https://www.mapbox.com/mapbox-gl-style-spec/#layer-paint.*} - {the vector tiles specification} and should no longer be used. + This was removed from the \l {https://www.mapbox.com/mapbox-gl-style-spec/#layer-paint.*} + {Mapbox style specification} and should no longer be used. \deprecated \sa removeClass() @@ -756,6 +833,13 @@ QStringList QMapboxGL::getClasses() const return classNames; } +/*! + Sets the \a duration and \a delay of style class transitions. Style property + values transition to new values with animation when a new class is set. + + \deprecated + \sa addClass() +*/ void QMapboxGL::setTransitionOptions(qint64 duration, qint64 delay) { static auto convert = [](qint64 value) -> mbgl::optional { return std::chrono::duration_cast(mbgl::Milliseconds(value)); @@ -770,77 +854,206 @@ mbgl::Annotation fromPointAnnotation(const PointAnnotation &pointAnnotation) { return mbgl::SymbolAnnotation { mbgl::Point { coordinate.second, coordinate.first }, icon.toStdString() }; } -AnnotationID QMapboxGL::addPointAnnotation(const PointAnnotation &pointAnnotation) +/*! + Adds a \a point annotation to the map. + + Returns the unique identifier for the new annotation. + + \sa addAnnotationIcon() +*/ +QMapbox::AnnotationID QMapboxGL::addPointAnnotation(const QMapbox::PointAnnotation &point) { - return d_ptr->mapObj->addAnnotation(fromPointAnnotation(pointAnnotation)); + return d_ptr->mapObj->addAnnotation(fromPointAnnotation(point)); } -void QMapboxGL::updatePointAnnotation(AnnotationID id, const PointAnnotation &pointAnnotation) +/*! + Updates an existing \a point annotation referred by \a id. + + \sa addAnnotationIcon() +*/ +void QMapboxGL::updatePointAnnotation(QMapbox::AnnotationID id, const QMapbox::PointAnnotation &point) { - d_ptr->mapObj->updateAnnotation(id, fromPointAnnotation(pointAnnotation)); + d_ptr->mapObj->updateAnnotation(id, fromPointAnnotation(point)); } -AnnotationID QMapboxGL::addShapeAnnotation(const ShapeAnnotation &shapeAnnotation) +/*! + Adds a \a shape annotation to the map. + + Returns the unique identifier for the new annotation. +*/ +QMapbox::AnnotationID QMapboxGL::addShapeAnnotation(const QMapbox::ShapeAnnotation &shape) { - return d_ptr->mapObj->addAnnotation(fromQMapboxGLShapeAnnotation(shapeAnnotation)); + return d_ptr->mapObj->addAnnotation(fromQMapboxGLShapeAnnotation(shape)); } -void QMapboxGL::removeAnnotation(AnnotationID annotationID) +/*! + Removes an existing annotation referred by \a id. +*/ +void QMapboxGL::removeAnnotation(QMapbox::AnnotationID id) { - d_ptr->mapObj->removeAnnotation(annotationID); + d_ptr->mapObj->removeAnnotation(id); } -void QMapboxGL::setLayoutProperty(const QString& layer_, const QString& property, const QVariant& value) +/*! + Sets a layout \a property \a value to an existing \a layer. The \a property string can be any + as defined by the \l {https://www.mapbox.com/mapbox-gl-style-spec/} {Mapbox style specification} + for layout properties. + + This example hides the layer \c route: + + \code + map->setLayoutProperty("route", "visibility", "none"); + \endcode + + This table describes the mapping between \l {https://www.mapbox.com/mapbox-gl-style-spec/#types} + {style types} and Qt types accepted by setLayoutProperty(): + + \table + \header + \li Mapbox style type + \li Qt type + \row + \li Enum + \li QString + \row + \li String + \li QString + \row + \li Boolean + \li \c bool + \row + \li Number + \li \c int, \c double or \c float + \row + \li Array + \li QVariantList + \endtable +*/ +void QMapboxGL::setLayoutProperty(const QString& layer, const QString& property, const QVariant& value) { using namespace mbgl::style; - Layer* layer = d_ptr->mapObj->getLayer(layer_.toStdString()); - if (!layer) { - qWarning() << "Layer not found:" << layer_; + Layer* layer_ = d_ptr->mapObj->getLayer(layer.toStdString()); + if (!layer_) { + qWarning() << "Layer not found:" << layer; return; } - if (conversion::setLayoutProperty(*layer, property.toStdString(), value)) { - qWarning() << "Error setting layout property:" << layer_ << "-" << property; + if (conversion::setLayoutProperty(*layer_, property.toStdString(), value)) { + qWarning() << "Error setting layout property:" << layer << "-" << property; return; } } -void QMapboxGL::setPaintProperty(const QString& layer_, const QString& property, const QVariant& value, const QString& klass_) +/*! + Sets a paint \a property \a value to an existing \a layer. The \a property string can be any + as defined by the \l {https://www.mapbox.com/mapbox-gl-style-spec/} {Mapbox style specification} + for paint properties. + + The argument \a styleClass is deprecated and is used for defining the style class for the paint + property. + + For paint properties that take a color as \a value, such as \c fill-color, a string such as + \c blue can be passed or a QColor. + + \code + map->setPaintProperty("route", "line-color", QColor("blue")); + \endcode + + This table describes the mapping between \l {https://www.mapbox.com/mapbox-gl-style-spec/#types} + {style types} and Qt types accepted by setPaintProperty(): + + \table + \header + \li Mapbox style type + \li Qt type + \row + \li Color + \li QString or QColor + \row + \li Enum + \li QString + \row + \li String + \li QString + \row + \li Boolean + \li \c bool + \row + \li Number + \li \c int, \c double or \c float + \row + \li Array + \li QVariantList + \endtable + + If the style specification defines the property's type as \b Array, use a QVariantList. For + example, the following code sets a \c route layer's \c line-dasharray property: + + \code + QVariantList lineDashArray; + lineDashArray.append(1); + lineDashArray.append(2); + + map->setPaintProperty("route","line-dasharray", lineDashArray); + \endcode +*/ +void QMapboxGL::setPaintProperty(const QString& layer, const QString& property, const QVariant& value, const QString& styleClass) { using namespace mbgl::style; - Layer* layer = d_ptr->mapObj->getLayer(layer_.toStdString()); - if (!layer) { - qWarning() << "Layer not found:" << layer_; + Layer* layer_ = d_ptr->mapObj->getLayer(layer.toStdString()); + if (!layer_) { + qWarning() << "Layer not found:" << layer; return; } mbgl::optional klass; - if (!klass_.isEmpty()) { - klass = klass_.toStdString(); + if (!styleClass.isEmpty()) { + klass = styleClass.toStdString(); } - if (conversion::setPaintProperty(*layer, property.toStdString(), value, klass)) { - qWarning() << "Error setting paint property:" << layer_ << "-" << property; + if (conversion::setPaintProperty(*layer_, property.toStdString(), value, klass)) { + qWarning() << "Error setting paint property:" << layer << "-" << property; return; } } +/*! + Returns true when the map is completely rendered, false otherwise. A partially + rendered map ranges from nothing rendered at all to only labels missing. +*/ bool QMapboxGL::isFullyLoaded() const { return d_ptr->mapObj->isFullyLoaded(); } +/*! + Pan the map by \a offset in pixels. + + The pixel coordinate origin is located at the upper left corner of the map. +*/ void QMapboxGL::moveBy(const QPointF &offset) { d_ptr->mapObj->moveBy(mbgl::ScreenCoordinate { offset.x(), offset.y() }); } +/*! + \fn QMapboxGL::scaleBy(double scale, const QPointF ¢er) + + Scale the map by \a scale in the direction of the \a center. This function + can be used for implementing a pinch gesture. +*/ void QMapboxGL::scaleBy(double scale_, const QPointF ¢er) { d_ptr->mapObj->scaleBy(scale_, mbgl::ScreenCoordinate { center.x(), center.y() }); } +/*! + Rotate the map from the \a first screen coordinate to the \a second screen coordinate. + This method can be used for implementing rotating the map by clicking and dragging, + being \a first the cursor coordinate at the last frame and \a second the cursor coordinate + at the current frame. +*/ void QMapboxGL::rotateBy(const QPointF &first, const QPointF &second) { d_ptr->mapObj->rotateBy( @@ -848,6 +1061,17 @@ void QMapboxGL::rotateBy(const QPointF &first, const QPointF &second) mbgl::ScreenCoordinate { second.x(), second.y() }); } +/*! + Resize the map to \a size and scale to fit at \a framebufferSize. For + high DPI screens, the size will be smaller than the \a framebufferSize. + + This fallowing example will double the pixel density of the map for + a given \c size: + + \code + map->resize(size / 2, size); + \endcode +*/ void QMapboxGL::resize(const QSize& size, const QSize& framebufferSize) { if (d_ptr->size == size && d_ptr->fbSize == framebufferSize) return; @@ -875,7 +1099,18 @@ void QMapboxGL::addAnnotationIcon(const QString &name, const QImage &icon) d_ptr->mapObj->addAnnotationIcon(name.toStdString(), toSpriteImage(icon)); } -QPointF QMapboxGL::pixelForCoordinate(const Coordinate &coordinate_) const +/*! + \fn QMapboxGL::pixelForCoordinate(const QMapbox::Coordinate &coordinate) const + + Returns the offset in pixels for \a coordinate. The origin pixel coordinate is + located at the top left corner of the map view. + + This method returns the correct value for any coordinate, even if the coordinate + is not currently visible on the screen. + + /note The return value is affected by the current zoom level, bearing and pitch. +*/ +QPointF QMapboxGL::pixelForCoordinate(const QMapbox::Coordinate &coordinate_) const { const mbgl::ScreenCoordinate pixel = d_ptr->mapObj->pixelForLatLng(mbgl::LatLng { coordinate_.first, coordinate_.second }); @@ -883,7 +1118,10 @@ QPointF QMapboxGL::pixelForCoordinate(const Coordinate &coordinate_) const return QPointF(pixel.x, pixel.y); } -Coordinate QMapboxGL::coordinateForPixel(const QPointF &pixel) const +/*! + Returns the geographic coordinate for the \a pixel coordinate. +*/ +QMapbox::Coordinate QMapboxGL::coordinateForPixel(const QPointF &pixel) const { const mbgl::LatLng latLng = d_ptr->mapObj->latLngForPixel(mbgl::ScreenCoordinate { pixel.x(), pixel.y() }); @@ -891,7 +1129,11 @@ Coordinate QMapboxGL::coordinateForPixel(const QPointF &pixel) const return Coordinate(latLng.latitude, latLng.longitude); } -CoordinateZoom QMapboxGL::coordinateZoomForBounds(const Coordinate &sw, Coordinate &ne) const +/*! + Returns the coordinate and zoom combination needed in order to make the coordinate + bounding box \a sw and \a ne visible. +*/ +QMapbox::CoordinateZoom QMapboxGL::coordinateZoomForBounds(const QMapbox::Coordinate &sw, QMapbox::Coordinate &ne) const { auto bounds = mbgl::LatLngBounds::hull(mbgl::LatLng { sw.first, sw.second }, mbgl::LatLng { ne.first, ne.second }); mbgl::CameraOptions camera = d_ptr->mapObj->cameraForLatLngBounds(bounds, d_ptr->margins); @@ -899,8 +1141,13 @@ CoordinateZoom QMapboxGL::coordinateZoomForBounds(const Coordinate &sw, Coordina return {{ (*camera.center).latitude, (*camera.center).longitude }, *camera.zoom }; } -CoordinateZoom QMapboxGL::coordinateZoomForBounds(const Coordinate &sw, Coordinate &ne, +/*! + Returns the coordinate and zoom combination needed in order to make the coordinate + bounding box \a sw and \a ne visible taking into account \a newBearing and \a newPitch. +*/ +QMapbox::CoordinateZoom QMapboxGL::coordinateZoomForBounds(const QMapbox::Coordinate &sw, QMapbox::Coordinate &ne, double newBearing, double newPitch) + { // FIXME: mbgl::Map::cameraForLatLngBounds should // take bearing and pitch as input too, so this @@ -946,12 +1193,30 @@ QMargins QMapboxGL::margins() const ); } -void QMapboxGL::addSource(const QString &sourceID, const QVariantMap ¶ms) +/*! + Adds a source \a id to the map as specified by the \l + {https://www.mapbox.com/mapbox-gl-style-spec/#root-sources}{Mapbox style specification} with + \a params. + + This example reads a GeoJSON from the Qt resource system and adds it as source: + + \code + QFile geojson(":source1.geojson"); + geojson.open(QIODevice::ReadOnly); + + QVariantMap routeSource; + routeSource["type"] = "geojson"; + routeSource["data"] = geojson.readAll(); + + map->addSource("routeSource", routeSource); + \endcode +*/ +void QMapboxGL::addSource(const QString &id, const QVariantMap ¶ms) { using namespace mbgl::style; using namespace mbgl::style::conversion; - Result> source = convert>(QVariant(params), sourceID.toStdString()); + Result> source = convert>(QVariant(params), id.toStdString()); if (!source) { qWarning() << "Unable to add source:" << source.error().message.c_str(); return; @@ -960,14 +1225,20 @@ void QMapboxGL::addSource(const QString &sourceID, const QVariantMap ¶ms) d_ptr->mapObj->addSource(std::move(*source)); } -void QMapboxGL::updateSource(const QString &sourceID, const QVariantMap ¶ms) +/*! + Updates the source \a id with new \a params. + + If the source does not exist, it will be added like in addSource(). Only + GeoJSON sources can be updated. +*/ +void QMapboxGL::updateSource(const QString &id, const QVariantMap ¶ms) { using namespace mbgl::style; using namespace mbgl::style::conversion; - auto source = d_ptr->mapObj->getSource(sourceID.toStdString()); + auto source = d_ptr->mapObj->getSource(id.toStdString()); if (!source) { - addSource(sourceID, params); + addSource(id, params); return; } @@ -985,20 +1256,33 @@ void QMapboxGL::updateSource(const QString &sourceID, const QVariantMap ¶ms) } } -void QMapboxGL::removeSource(const QString& sourceID) +/*! + Removes the source \a id. + + This method has no effect if the source does not exist. +*/ +void QMapboxGL::removeSource(const QString& id) { - auto sourceIDStdString = sourceID.toStdString(); + auto sourceIDStdString = id.toStdString(); if (d_ptr->mapObj->getSource(sourceIDStdString)) { d_ptr->mapObj->removeSource(sourceIDStdString); } } +/*! + Adds a custom layer \a id with the initialization function \a initFn, the + render function \a renderFn and the deinitialization function \a deinitFn with + the user data \a context before the existing layer \a before. + + \warning This is used for delegating the rendering of a layer to the user of + this API and is not officially supported. Use at your own risk. +*/ void QMapboxGL::addCustomLayer(const QString &id, QMapbox::CustomLayerInitializeFunction initFn, QMapbox::CustomLayerRenderFunction renderFn, QMapbox::CustomLayerDeinitializeFunction deinitFn, - void *context_, + void *context, char *before) { d_ptr->mapObj->addLayer(std::make_unique( @@ -1008,10 +1292,29 @@ void QMapboxGL::addCustomLayer(const QString &id, // CustomLayerRenderParameters members remains the same. (mbgl::style::CustomLayerRenderFunction)renderFn, reinterpret_cast(deinitFn), - context_), + context), before ? mbgl::optional(before) : mbgl::optional()); } +/*! + Adds a style layer to the map as specified by the \l + {https://www.mapbox.com/mapbox-gl-style-spec/#root-layers}{Mapbox style specification} with + \a params. + + This example shows how to add a layer that will be used to show a route line on the map. Note + that nothing will be drawn until we set paint properties using setPaintProperty(). + + \code + QVariantMap route; + route["id"] = "route"; + route["type"] = "line"; + route["source"] = "routeSource"; + + map->addLayer(route); + \endcode + + /note The source must exist prior to adding a layer. +*/ void QMapboxGL::addLayer(const QVariantMap ¶ms) { using namespace mbgl::style; @@ -1026,63 +1329,108 @@ void QMapboxGL::addLayer(const QVariantMap ¶ms) d_ptr->mapObj->addLayer(std::move(*layer)); } +/*! + Removes the layer \a id. +*/ void QMapboxGL::removeLayer(const QString& id) { d_ptr->mapObj->removeLayer(id.toStdString()); } -void QMapboxGL::addImage(const QString &name, const QImage &sprite) +/*! + Adds the \a image with the identifier \a id that can be used + later by a symbol layer. + + If the \a id was already added, it gets replaced by the new + \a image only if the dimensions of the image are the same as + the old image, otherwise it has no effect. + + \sa addLayer() +*/ +void QMapboxGL::addImage(const QString &id, const QImage &image) { - if (sprite.isNull()) return; + if (image.isNull()) return; - d_ptr->mapObj->addImage(name.toStdString(), toSpriteImage(sprite)); + d_ptr->mapObj->addImage(id.toStdString(), toSpriteImage(image)); } -void QMapboxGL::removeImage(const QString &name) +/*! + Removes the image \a id. +*/ +void QMapboxGL::removeImage(const QString &id) { - d_ptr->mapObj->removeImage(name.toStdString()); + d_ptr->mapObj->removeImage(id.toStdString()); } -void QMapboxGL::setFilter(const QString& layer_, const QVariant& filter_) +/*! + Adds a \a filter to a style \a layer using the format described in the \l + {https://www.mapbox.com/mapbox-gl-style-spec/#types-filter}{Mapbox style specification}. + + Given a layer \c marker from an arbitrary GeoJSON source containing features of type \b + "Point" and \b "LineString", this example shows how to make sure the layer will only tag + features of type \b "Point". + + \code + QVariantList filterExpression; + filterExpression.append("=="); + filterExpression.append("$type"); + filterExpression.append("Point"); + + QVariantList filter; + filter.append(filterExpression); + + map->setFilter("marker", filter); + \endcode +*/ +void QMapboxGL::setFilter(const QString& layer, const QVariant& filter) { using namespace mbgl::style; using namespace mbgl::style::conversion; - Layer* layer = d_ptr->mapObj->getLayer(layer_.toStdString()); - if (!layer) { - qWarning() << "Layer not found:" << layer_; + Layer* layer_ = d_ptr->mapObj->getLayer(layer.toStdString()); + if (!layer_) { + qWarning() << "Layer not found:" << layer; return; } - Filter filter; + Filter filter_; - Result converted = convert(filter_); + Result converted = convert(filter); if (!converted) { qWarning() << "Error parsing filter:" << converted.error().message.c_str(); return; } - filter = std::move(*converted); + filter_ = std::move(*converted); - if (layer->is()) { - layer->as()->setFilter(filter); + if (layer_->is()) { + layer_->as()->setFilter(filter_); return; } - if (layer->is()) { - layer->as()->setFilter(filter); + if (layer_->is()) { + layer_->as()->setFilter(filter_); return; } - if (layer->is()) { - layer->as()->setFilter(filter); + if (layer_->is()) { + layer_->as()->setFilter(filter_); return; } - if (layer->is()) { - layer->as()->setFilter(filter); + if (layer_->is()) { + layer_->as()->setFilter(filter_); return; } qWarning() << "Layer doesn't support filters"; } +/*! + Renders the map using OpenGL draw calls. If \a fbo is passed, it will + make sure to bind the framebuffer object before drawing; otherwise a + valid OpenGL context is expected with an appropriate OpenGL viewport state set + for the size of the canvas. + + This function should be called only after the signal needsRendering() is + emitted at least once. +*/ #if QT_VERSION >= 0x050000 void QMapboxGL::render(QOpenGLFramebufferObject *fbo) { @@ -1106,11 +1454,42 @@ void QMapboxGL::render() } #endif +/*! + Informs the map that the network connection has been established, causing + all network requests that previously timed out to be retried immediately. +*/ void QMapboxGL::connectionEstablished() { d_ptr->connectionEstablished(); } +/*! + \fn void QMapboxGL::needsRendering() + + This signal is emitted when the visual contents of the map have changed + and a redraw is needed in order to keep the map visually consistent + with the current state. + + \sa render() +*/ + +/*! + \fn void QMapboxGL::mapChanged(QMapboxGL::MapChange change) + + This signal is emitted when the state of the map has changed. This signal + may be used for detecting errors when loading a style or detecting when + a map is fully loaded by analyzing the parameter \a change. +*/ + +/*! + \fn void QMapboxGL::copyrightsChanged(const QString ©rightsHtml); + + This signal is emitted when the copyrights of the current content of the map + have changed. This can be caused by a style change or adding a new source. + + \a copyrightsHtml is a string with a HTML snippet. +*/ + QMapboxGLPrivate::QMapboxGLPrivate(QMapboxGL *q, const QMapboxGLSettings &settings, const QSize &size_, qreal pixelRatio) : QObject(q) , size(size_) -- cgit v1.2.1