QMapboxGL Class
The QMapboxGL class is a Qt wrapper for the Mapbox GL Native engine. More...
| Header: | #include <QMapboxGL> |
| Since: | Qt 4.7 |
| Inherits: | QObject |
Public Types
| enum | MapChange { MapChangeRegionWillChange, MapChangeRegionWillChangeAnimated, MapChangeRegionIsChanging, MapChangeRegionDidChange, ..., MapChangeSourceDidChange } |
| enum | NorthOrientation { NorthUpwards, NorthRightwards, NorthDownwards, NorthLeftwards } |
Properties
|
- 1 property inherited from QObject
Public Functions
| QMapboxGL(QObject *parent = 0, const QMapboxGLSettings &settings = QMapboxGLSettings(), const QSize &size = QSize(), qreal pixelRatio = 1) | |
| virtual | ~QMapboxGL() |
| QMapbox::AnnotationID | addAnnotation(const QMapbox::Annotation &annotation) |
| void | addAnnotationIcon(const QString &name, const QImage &icon) |
| void | addCustomLayer(const QString &id, QMapbox::CustomLayerInitializeFunction initFn, QMapbox::CustomLayerRenderFunction renderFn, QMapbox::CustomLayerDeinitializeFunction deinitFn, void *context, const QString &before = QString()) |
| void | addImage(const QString &id, const QImage &image) |
| void | addLayer(const QVariantMap ¶ms, const QString &before = QString()) |
| void | addSource(const QString &id, const QVariantMap ¶ms) |
| double | bearing() const |
| QMapbox::Coordinate | coordinate() const |
| QMapbox::Coordinate | coordinateForPixel(const QPointF &pixel) const |
| QMapbox::Coordinate | coordinateForProjectedMeters(const QMapbox::ProjectedMeters &projectedMeters) const |
| QMapbox::CoordinateZoom | coordinateZoomForBounds(const QMapbox::Coordinate &sw, QMapbox::Coordinate &ne) const |
| QMapbox::CoordinateZoom | coordinateZoomForBounds(const QMapbox::Coordinate &sw, QMapbox::Coordinate &ne, double newBearing, double newPitch) |
| void | cycleDebugOptions() |
| bool | isFullyLoaded() const |
| void | jumpTo(const QMapboxGLCameraOptions &camera) |
| double | latitude() const |
| bool | layerExists(const QString &id) |
| double | longitude() const |
| QMargins | margins() const |
| double | maximumZoom() const |
| double | metersPerPixelAtLatitude(double latitude, double zoom) const |
| double | minimumZoom() const |
| void | moveBy(const QPointF &offset) |
| NorthOrientation | northOrientation() const |
| double | pitch() const |
| QPointF | pixelForCoordinate(const QMapbox::Coordinate &coordinate) const |
| QMapbox::ProjectedMeters | projectedMetersForCoordinate(const QMapbox::Coordinate &coordinate_) const |
| void | removeAnnotation(QMapbox::AnnotationID id) |
| void | removeImage(const QString &id) |
| void | removeLayer(const QString &id) |
| void | removeSource(const QString &id) |
| void | resize(const QSize &size, const QSize &framebufferSize) |
| void | rotateBy(const QPointF &first, const QPointF &second) |
| double | scale() const |
| void | scaleBy(double scale, const QPointF ¢er = QPointF()) |
| void | setBearing(double degrees) |
| void | setBearing(double degrees, const QPointF ¢er) |
| void | setCoordinate(const QMapbox::Coordinate &) |
| void | setCoordinateZoom(const QMapbox::Coordinate &coordinate, double zoom) |
| void | setFilter(const QString &layer, const QVariant &filter) |
| void | setGestureInProgress(bool progress) |
| void | setLatitude(double latitude) |
| void | setLayoutProperty(const QString &layer, const QString &property, const QVariant &value) |
| void | setLongitude(double longitude) |
| void | setMargins(const QMargins &margins) |
| void | setNorthOrientation(NorthOrientation orientation) |
| void | setPaintProperty(const QString &layer, const QString &property, const QVariant &value, const QString &styleClass = QString()) |
| void | setPitch(double pitch) |
| void | setScale(double scale, const QPointF ¢er = QPointF()) |
| void | setStyleJson(const QString &) |
| void | setStyleUrl(const QString &) |
| void | setZoom(double zoom) |
| bool | sourceExists(const QString &sourceID) |
| QString | styleJson() const |
| QString | styleUrl() const |
| void | updateAnnotation(QMapbox::AnnotationID id, const QMapbox::Annotation &annotation) |
| void | updateSource(const QString &id, const QVariantMap ¶ms) |
| double | zoom() const |
- 32 public functions inherited from QObject
Public Slots
| void | connectionEstablished() |
| void | render(QOpenGLFramebufferObject *fbo = NULL) |
- 1 public slot inherited from QObject
Signals
| void | copyrightsChanged(const QString ©rightsHtml) |
| void | mapChanged(QMapboxGL::MapChange change) |
| void | needsRendering() |
- 2 signals inherited from QObject
Additional Inherited Members
Detailed Description
The QMapboxGL class is a Qt wrapper for the Mapbox GL Native engine.
QMapboxGL is a Qt friendly version the Mapbox GL Native engine using Qt types and deep integration with Qt event loop. QMapboxGL relies as much as possible on Qt, trying to minimize the external dependencies. For instance it will use 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 OpenGL context lives.
Member Type Documentation
enum QMapboxGL::MapChange
This enum represents the last changed occurred to the map state.
| Constant | Value | Description |
|---|---|---|
QMapboxGL::MapChangeRegionWillChange | 0 | A region of the map will change, like when resizing the map. |
QMapboxGL::MapChangeRegionWillChangeAnimated | 1 | Not in use by QMapboxGL. |
QMapboxGL::MapChangeRegionIsChanging | 2 | A region of the map is changing. |
QMapboxGL::MapChangeRegionDidChange | 3 | A region of the map finished changing. |
QMapboxGL::MapChangeRegionDidChangeAnimated | 4 | Not in use by QMapboxGL. |
QMapboxGL::MapChangeWillStartLoadingMap | 5 | The map is getting loaded. This state is set only once right after QMapboxGL is created and a style is set. |
QMapboxGL::MapChangeDidFinishLoadingMap | 6 | 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. |
QMapboxGL::MapChangeDidFailLoadingMap | 7 | An error occurred when loading the map. |
QMapboxGL::MapChangeWillStartRenderingFrame | 8 | 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. |
QMapboxGL::MapChangeDidFinishRenderingFrame | 9 | 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. |
QMapboxGL::MapChangeDidFinishRenderingFrameFullyRendered | 10 | The current frame was fully rendered. |
QMapboxGL::MapChangeWillStartRenderingMap | 11 | Set once when the map is about to get rendered for the first time. |
QMapboxGL::MapChangeDidFinishRenderingMap | 12 | Not in use by QMapboxGL. |
QMapboxGL::MapChangeDidFinishRenderingMapFullyRendered | 13 | Map is fully loaded and rendered. |
QMapboxGL::MapChangeDidFinishLoadingStyle | 14 | The style was loaded. |
QMapboxGL::MapChangeSourceDidChange | 15 | A source has changed. |
See also mapChanged().
enum QMapboxGL::NorthOrientation
This enum sets the orientation of the north bearing. It will directly affect bearing when resetting the north (i.e. setting bearing to 0).
| Constant | Value | Description |
|---|---|---|
QMapboxGL::NorthUpwards | 0 | The north is pointing up in the map. This is usually how maps are oriented. |
QMapboxGL::NorthRightwards | 1 | The north is pointing right. |
QMapboxGL::NorthDownwards | 2 | The north is pointing down. |
QMapboxGL::NorthLeftwards | 3 | The north is pointing left. |
See also northOrientation() and bearing().
Property Documentation
bearing : double
This property holds the map bearing in degrees.
Set the angle in degrees. Negative values and values over 360 are valid and will wrap. The direction of the rotation is counterclockwise.
When center is defined, the map will rotate around the center pixel coordinate respecting the margins if defined.
Access functions:
| double | bearing() const |
| void | setBearing(double degrees) |
| void | setBearing(double degrees, const QPointF ¢er) |
See also margins().
coordinate : QMapbox::Coordinate
This property holds the map center coordinate.
Centers the map at a geographic coordinate respecting the margins, if set.
Access functions:
| QMapbox::Coordinate | coordinate() const |
| void | setCoordinate(const QMapbox::Coordinate &) |
See also margins().
latitude : double
This property holds the map's current latitude in degrees.
Setting a latitude doesn't necessarily mean it will be accepted since QMapboxGL might constrain it within the limits of the Web Mercator projection.
Access functions:
| double | latitude() const |
| void | setLatitude(double latitude) |
longitude : double
This property holds the map current longitude in degrees.
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.
Access functions:
| double | longitude() const |
| void | setLongitude(double longitude) |
margins : QMargins
This property holds the map margins in pixels from the corners of the map.
This property sets a new reference center for the map.
Access functions:
| QMargins | margins() const |
| void | setMargins(const QMargins &margins) |
pitch : double
This property holds the map pitch in degrees.
Pitch toward the horizon measured in degrees, with 0 resulting in a two-dimensional map. It will be constrained at 60 degrees.
Access functions:
| double | pitch() const |
| void | setPitch(double pitch) |
See also margins().
scale : double
This property holds the map scale factor.
This property is used to zoom the map. When center is defined, the map will scale in the direction of the center pixel coordinates. The 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.
Access functions:
| double | scale() const |
| void | setScale(double scale, const QPointF ¢er = QPointF()) |
See also zoom().
styleJson : QString
This property holds the map style JSON.
Sets a new style from a JSON that must conform to the Mapbox style specification.
Note: In case of a invalid style it will trigger a mapChanged signal with QMapboxGL::MapChangeDidFailLoadingMap as argument.
Access functions:
| QString | styleJson() const |
| void | setStyleJson(const QString &) |
styleUrl : QString
This property holds the map style URL.
Sets a URL for fetching a JSON that will be later fed to setStyleJson. URLs using the Mapbox scheme (mapbox://) are also accepted and translated automatically to an actual HTTPS request.
The Mapbox scheme is not enforced and a style can be fetched from anything that QNetworkAccessManager can handle.
Note: In case of a invalid style it will trigger a mapChanged signal with QMapboxGL::MapChangeDidFailLoadingMap as argument.
Access functions:
| QString | styleUrl() const |
| void | setStyleUrl(const QString &) |
zoom : double
This property holds the map zoom factor.
This property is used to zoom the map. When center is defined, the map will zoom in the direction of the center. This function could be used for implementing a pinch gesture or zooming by using the mouse scroll wheel.
Access functions:
| double | zoom() const |
| void | setZoom(double zoom) |
See also scale().
Member Function Documentation
QMapboxGL::QMapboxGL(QObject *parent = 0, const QMapboxGLSettings &settings = QMapboxGLSettings(), const QSize &size = QSize(), qreal pixelRatio = 1)
Constructs a QMapboxGL object with settings and sets parent as the parent object. The settings cannot be changed after the object is constructed. The size represents the size of the viewport and the pixelRatio the initial pixel density of the screen.
[virtual] QMapboxGL::~QMapboxGL()
Destroys this QMapboxGL.
QMapbox::AnnotationID QMapboxGL::addAnnotation(const QMapbox::Annotation &annotation)
Adds an annotation to the map.
Returns the unique identifier for the new annotation.
See also addAnnotationIcon().
void QMapboxGL::addAnnotationIcon(const QString &name, const QImage &icon)
Adds an icon to the annotation icon pool. This can be later used by the annotation functions to shown any drawing on the map by referencing its name.
Unlike using addIcon() for runtime styling, annotations added with addAnnotation() will survive style changes.
See also addAnnotation().
void QMapboxGL::addCustomLayer(const QString &id, QMapbox::CustomLayerInitializeFunction initFn, QMapbox::CustomLayerRenderFunction renderFn, QMapbox::CustomLayerDeinitializeFunction deinitFn, void *context, const QString &before = QString())
Adds a custom layer id with the initialization function initFn, the render function renderFn and the deinitialization function deinitFn with the user data context before the existing layer 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::addImage(const QString &id, const QImage &image)
Adds the image with the identifier id that can be used later by a symbol layer.
If the id was already added, it gets replaced by the new image only if the dimensions of the image are the same as the old image, otherwise it has no effect.
See also addLayer().
void QMapboxGL::addLayer(const QVariantMap ¶ms, const QString &before = QString())
Adds a style layer to the map as specified by the Mapbox style specification with params. The layer will be added under the layer specified by before, if specified. Otherwise it will be added as the topmost layer.
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().
QVariantMap route; route["id"] = "route"; route["type"] = "line"; route["source"] = "routeSource"; map->addLayer(route);
/note The source must exist prior to adding a layer.
void QMapboxGL::addSource(const QString &id, const QVariantMap ¶ms)
Adds a source id to the map as specified by the Mapbox style specification with params.
This example reads a GeoJSON from the Qt resource system and adds it as source:
QFile geojson(":source1.geojson"); geojson.open(QIODevice::ReadOnly); QVariantMap routeSource; routeSource["type"] = "geojson"; routeSource["data"] = geojson.readAll(); map->addSource("routeSource", routeSource);
[slot] void QMapboxGL::connectionEstablished()
Informs the map that the network connection has been established, causing all network requests that previously timed out to be retried immediately.
QMapbox::Coordinate QMapboxGL::coordinateForPixel(const QPointF &pixel) const
Returns the geographic coordinate for the pixel coordinate.
QMapbox::Coordinate QMapboxGL::coordinateForProjectedMeters(const QMapbox::ProjectedMeters &projectedMeters) const
Returns the coordinate for a given projectedMeters object.
QMapbox::CoordinateZoom QMapboxGL::coordinateZoomForBounds(const QMapbox::Coordinate &sw, QMapbox::Coordinate &ne) const
Returns the coordinate and zoom combination needed in order to make the coordinate bounding box sw and ne visible.
QMapbox::CoordinateZoom QMapboxGL::coordinateZoomForBounds(const QMapbox::Coordinate &sw, QMapbox::Coordinate &ne, double newBearing, double newPitch)
Returns the coordinate and zoom combination needed in order to make the coordinate bounding box sw and ne visible taking into account newBearing and newPitch.
[signal] 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.
copyrightsHtml is a string with a HTML snippet.
void QMapboxGL::cycleDebugOptions()
Cycles through several debug options like showing the tile borders, tile numbers, expiration time and wireframe.
bool QMapboxGL::isFullyLoaded() const
Returns true when the map is completely rendered, false otherwise. A partially rendered map ranges from nothing rendered at all to only labels missing.
void QMapboxGL::jumpTo(const QMapboxGLCameraOptions &camera)
Atomically jumps to the camera options.
bool QMapboxGL::layerExists(const QString &id)
Returns true if the layer with given id exists, false otherwise.
[signal] 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 change.
double QMapboxGL::maximumZoom() const
Returns the maximum zoom level allowed for the map.
See also minimumZoom().
double QMapboxGL::metersPerPixelAtLatitude(double latitude, double zoom) const
Returns the amount of meters per pixel from a given latitude and zoom.
double QMapboxGL::minimumZoom() const
Returns the minimum zoom level allowed for the map.
See also maximumZoom().
void QMapboxGL::moveBy(const QPointF &offset)
Pan the map by offset in pixels.
The pixel coordinate origin is located at the upper left corner of the map.
[signal] 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.
See also render().
NorthOrientation QMapboxGL::northOrientation() const
Returns the north orientation mode.
See also setNorthOrientation().
QPointF QMapboxGL::pixelForCoordinate(const QMapbox::Coordinate &coordinate) const
Returns the offset in pixels for 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.
QMapbox::ProjectedMeters QMapboxGL::projectedMetersForCoordinate(const QMapbox::Coordinate &coordinate_) const
Return the projected meters for a given coordinate object.
void QMapboxGL::removeAnnotation(QMapbox::AnnotationID id)
Removes an existing annotation referred by id.
void QMapboxGL::removeImage(const QString &id)
Removes the image id.
void QMapboxGL::removeLayer(const QString &id)
Removes the layer with given id.
void QMapboxGL::removeSource(const QString &id)
Removes the source id.
This method has no effect if the source does not exist.
[slot] void QMapboxGL::render(QOpenGLFramebufferObject *fbo = NULL)
Renders the map using OpenGL draw calls. If 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.
void QMapboxGL::resize(const QSize &size, const QSize &framebufferSize)
Resize the map to size and scale to fit at framebufferSize. For high DPI screens, the size will be smaller than the framebufferSize.
This fallowing example will double the pixel density of the map for a given size:
map->resize(size / 2, size);
void QMapboxGL::rotateBy(const QPointF &first, const QPointF &second)
Rotate the map from the first screen coordinate to the second screen coordinate. This method can be used for implementing rotating the map by clicking and dragging, being first the cursor coordinate at the last frame and second the cursor coordinate at the current frame.
void QMapboxGL::scaleBy(double scale, const QPointF ¢er = QPointF())
Scale the map by scale in the direction of the center. This function can be used for implementing a pinch gesture.
void QMapboxGL::setCoordinateZoom(const QMapbox::Coordinate &coordinate, double zoom)
Convenience method for setting the coordinate and zoom simultaneously.
Note: Setting coordinate and zoom at once is more efficient than doing it in two steps.
See also zoom() and coordinate().
void QMapboxGL::setFilter(const QString &layer, const QVariant &filter)
Adds a filter to a style layer using the format described in the Mapbox style specification.
Given a layer marker from an arbitrary GeoJSON source containing features of type "Point" and "LineString", this example shows how to make sure the layer will only tag features of type "Point".
QVariantList filterExpression; filterExpression.append("=="); filterExpression.append("$type"); filterExpression.append("Point"); QVariantList filter; filter.append(filterExpression); map->setFilter("marker", filter);
void QMapboxGL::setGestureInProgress(bool progress)
Tells the map rendering engine that there is currently a gesture in progress. This affects how the map renders labels, as it will use different texture filters if a gesture is ongoing.
void QMapboxGL::setLayoutProperty(const QString &layer, const QString &property, const QVariant &value)
Sets a layout property value to an existing layer. The property string can be any as defined by the Mapbox style specification for layout properties.
This example hides the layer route:
map->setLayoutProperty("route", "visibility", "none");
This table describes the mapping between style types and Qt types accepted by setLayoutProperty():
| Mapbox style type | Qt type |
|---|---|
| Enum | QString |
| String | QString |
| Boolean | bool |
| Number | int, double or float |
| Array | QVariantList |
void QMapboxGL::setNorthOrientation(NorthOrientation orientation)
Sets the north orientation mode to orientation.
See also northOrientation().
void QMapboxGL::setPaintProperty(const QString &layer, const QString &property, const QVariant &value, const QString &styleClass = QString())
Sets a paint property value to an existing layer. The property string can be any as defined by the Mapbox style specification for paint properties.
The argument styleClass is deprecated and is used for defining the style class for the paint property.
For paint properties that take a color as value, such as fill-color, a string such as blue can be passed or a QColor.
map->setPaintProperty("route", "line-color", QColor("blue"));
This table describes the mapping between style types and Qt types accepted by setPaintProperty():
| Mapbox style type | Qt type |
|---|---|
| Color | QString or QColor |
| Enum | QString |
| String | QString |
| Boolean | bool |
| Number | int, double or float |
| Array | QVariantList |
If the style specification defines the property's type as Array, use a QVariantList. For example, the following code sets a route layer's line-dasharray property:
QVariantList lineDashArray; lineDashArray.append(1); lineDashArray.append(2); map->setPaintProperty("route","line-dasharray", lineDashArray);
bool QMapboxGL::sourceExists(const QString &sourceID)
Returns true if the layer with given id exists, false otherwise.
void QMapboxGL::updateAnnotation(QMapbox::AnnotationID id, const QMapbox::Annotation &annotation)
Updates an existing annotation referred by id.
See also addAnnotationIcon().
void QMapboxGL::updateSource(const QString &id, const QVariantMap ¶ms)
Updates the source id with new params.
If the source does not exist, it will be added like in addSource(). Only GeoJSON sources can be updated.