vtmap_gl library

This library contains the MapLibre GL plugin for Flutter.

To display a map, add a MapLibreMap widget to the widget tree.

In this plugin, the map is configured through the parameters passed to the MapLibreMap constructor and through the VTMapController. The VTMapController is provided at runtime by the MapLibreMap.onMapCreated callback. The controller also allows adding annotations (icons, lines etc.) to the map at runtime and provides some callbacks to get notified when the user clicks those.

The visual appearance of the map is configured through a MapLibre style passed to the styleString parameter of the MapLibreMap constructor. The MapLibre style is a JSON document following the specification at https://maplibre.org/maplibre-style-spec/. The following is supposed to serve as a short introduction to the MapLibre style specification: The style document contains (among other things) sources and layers. Sources determine which data is displayed on the map, layers determine how the data is displayed.

Typical types of sources are raster and vector tiles, as well as GeoJson data. For raster and vector tiles, the entire world is divided into a set of tiles in different zoom levels. Depending on the map's zoom level and viewport, the MapLibre client libraries decide, which tiles are needed to fill the viewport and request them from the source.

The difference between raster and vector tiles is that raster tiles are images that are pre-rendered on a server, whereas vector tiles contain raw geometric information that is rendered on the client. Vector tiles are in the Mapbox Vector Tile (MVT) format, the de-facto standard for vector tiles that is implemented by multiple libraries.

Vector tiles have a number of advantages over raster tiles, including (often) smaller size, the possibility to style them dynamically at runtime (e.g. change the color or visibility of certain features), and the possibility to rotate them and keep text labels horizontal. Raster and vector tiles can be generated from a variety of sources, including OpenStreetMap data and are also available from a number of providers.

Raster sources are displayed by adding a "raster" layer to the MapLibre GL style. Vector and GeoJson sources are displayed by adding a "line", "fill", "symbol" or "circle" layer to the MapLibre GL style and specifying which source to use (by setting the "source" property of the layer to the id of the source) as well as how to style the data by setting other properties of the layer such as "line-color" or "fill-outline-color". For example, a vector source layer (or a GeoJson source layer) with the outlines of countries could be displayed both by a fill layer to fill the countries with a color and by a line layer to draw the outlines of the countries.

Classes

Annotation
Base interface for all data-driven map annotations drawn via style layers (symbols, lines, fills, circles, etc.).
AnnotationManager<T extends Annotation>
Manages a homogeneous set of Annotations (e.g. symbols, lines, fills) by owning their backing style source(s)/layer(s) and performing efficient batched updates.
ArgumentCallbacks<T>
Mutable collection of ArgumentCallback instances, itself an ArgumentCallback.
CameraPosition
The position of the map "camera", the view point from which the world is shown in the map view. Aggregates the camera's target geographical location, its zoom level, tilt angle, and bearing.
CameraTargetBounds
Bounds for the map camera target. Used with _MapLibreMapOptions to wrap a LatLngBounds value. This allows distinguishing between specifying an unbounded target (null LatLngBounds) from not specifying anything (null CameraTargetBounds).
CameraUpdate
Defines a camera move, supporting absolute moves as well as moves relative the current position.
Circle
CircleLayerProperties
CircleManager
CircleOptions
Configuration options for Circle instances.
DownloadRegionStatus
Error
Expressions
Fill
FillExtrusionLayerProperties
FillLayerProperties
FillManager
FillOptions
Configuration options for Fill instances.
GeojsonSourceProperties
HeatmapLayerProperties
HillshadeLayerProperties
ImageSourceProperties
InProgress
LatLng
A pair of latitude and longitude coordinates, stored as degrees.
LatLngBounds
A latitude/longitude aligned rectangle.
LatLngQuad
A geographical area representing a non-aligned quadrilateral This class does not wrap values to the world bounds
LayerProperties
Line
LineLayerProperties
LineManager
LineOptions
Configuration options for Line instances.
LocationEnginePlatforms
Location engine properties that apply across all platforms.
MapLibreMethodChannel
MapLibrePlatform
MapLibreStyles
MapLibre styles used mostly for demonstration.
MinMaxZoomPreference
Preferred bounds for map camera zoom level. Used with _MapLibreMapOptions to wrap min and max zoom. This allows distinguishing between specifying unbounded zooming (null minZoom and maxZoom) from not specifying anything (null MinMaxZoomPreference).
OfflineRegion
Description of a downloaded region including its identifier.
OfflineRegionDefinition
Description of region to be downloaded. Identifier will be generated when the download is initiated.
OfflineRegionStatus
Status of an offline region's download.
RasterDemSourceProperties
RasterLayerProperties
RasterSourceProperties
SourceProperties
Success
Symbol
SymbolLayerProperties
SymbolManager
SymbolOptions
Configuration options for Symbol instances.
UserHeading
Type represents a geomagnetic value, measured in microteslas, relative to a device axis in three dimensional space.
UserLocation
User's observed location
VectorSourceProperties
VideoSourceProperties
VTMap
Shows a MapLibre map. Also refer to the documentation of maplibre_gl and VTMapController.
VTMapController
Controller for a single MapLibreMap instance running on the host platform.

Enums

AnnotationType
AttributionButtonPosition
Attribution Button Position
CameraAnimationInterpolation
Easing curve for MapLibreMapController.easeCamera animations.
CompassViewPosition
Compass View Position
DragEventType
HoverEventType
LocationPriority
An enum representing the priority for location accuracy and power usage. (Android only)
LogoViewPosition
Logo View Position
MyLocationRenderMode
Specifies if and how the user's heading/bearing is rendered in the user location indicator.
MyLocationTrackingMode
The camera mode, which determines how the map camera will track the rendered location.
ScaleControlPosition
Scale Control Position
ScaleControlUnit
Scale Control Unit

Functions

buildFeatureCollection(List<Map<String, dynamic>> features) → Map<String, dynamic>
clearAmbientCache() → Future<void>
Removes all tiles from the shared ambient cache that are not associated with any offline region. Call this after deleteOfflineRegion to fully evict tiles that would otherwise be reused by a future download of the same area.
deleteOfflineRegion(int id) → Future
downloadOfflineRegion(OfflineRegionDefinition definition, {Map<String, dynamic> metadata = const {}, dynamic onEvent(DownloadRegionStatus event)?}) → Future<OfflineRegion>
getListOfRegions() → Future<List<OfflineRegion>>
getOfflineRegionStatus(int id) → Future<OfflineRegionStatus>
Gets the current download status of an offline region.
getRandomString([int length = 10]) → String
installOfflineMapTiles(String tilesDb) → Future<void>
Copy tiles db file passed in to the tiles cache directory (sideloaded) to make tiles available offline.
mergeOfflineRegions(String path) → Future<List<OfflineRegion>>
pauseOfflineRegionDownload(int id) → Future<void>
Pauses an in-progress offline region download.
resetOfflineDatabase() → Future<void>
Resets the entire offline database: deletes every offline region and clears the ambient cache. Use with care — offline regions cannot be recovered afterwards.
resumeOfflineRegionDownload(int id) → Future<void>
Resumes a paused offline region download.
setHttpHeaders(Map<String, String> headers) → Future<void>
setOffline(bool offline) → Future
setOfflineMaxConcurrentRequests({int? maxRequests, int? maxRequestsPerHost}) → Future<void>
Sets the maximum number of concurrent HTTP requests for tile downloads.
setOfflineTileCountLimit(int limit) → Future
updateOfflineRegionMetadata(int id, Map<String, dynamic> metadata) → Future<OfflineRegion>

Typedefs

MapCreatedCallback = void Function(VTMapController controller)
OnCameraIdleCallback = void Function()
OnCameraMoveCallback = void Function(CameraPosition cameraPosition)
OnCameraTrackingChangedCallback = void Function(MyLocationTrackingMode mode)
OnCameraTrackingDismissedCallback = void Function()
OnFeatureDragCallback = void Function(Point<double> point, LatLng origin, LatLng current, LatLng delta, String id, Annotation? annotation, DragEventType eventType)
OnFeatureHoverCallback = void Function(Point<double> point, LatLng coordinates, String id, Annotation? annotation, HoverEventType eventType)
OnFeatureInteractionCallback = void Function(Point<double> point, LatLng coordinates, String id, String layerId, Annotation? annotation)
OnMapClickCallback = void Function(Point<double> point, LatLng coordinates)
OnMapIdleCallback = void Function()
OnMapLongClickCallback = void Function(Point<double> point, LatLng coordinates)
OnMapMouseMoveCallback = void Function(Point<double> point, LatLng coordinates)
OnPlatformViewCreatedCallback = void Function(int)
The default instance of MapLibrePlatform to use.
OnStyleLoadedCallback = void Function()
OnUserLocationUpdated = void Function(UserLocation location)