Housekeeping: Improve docs and update outdated references to point to…

… MapLibre (#330) This PR does quite some housekeeping in updating outdated references from mapbox to maplibre, mostly in doc comments in the web sub-package. - updated documentation: - especially added new docs for the maplibre_gl library and MaplibreMapControler and MaplibreMap, as well as removing outdated comments in many places and adding some new ones to help new users better understand the plugin - the updates for the web documentation comments were also mostly done with a series of replace-all, sometimes manually updated to reflect the online API reference of MapLibre JS - the only "code changes" are a couple of (simple) renamings: - main plugin: renamed src/mapbox_map.dart to src/maplibre_map.dart - main plugin: renamed MapboxColorConversion to MapLibreColorConversion - main plugin: maplibreGlPlatform variable (the class was already renamed in the past) in controller.dart - main plugin: _MaplibreMapOptions class - web: "library maplibre" at the top of most files - web: MapboxMapJsImpl to MapLibreMapJsImpl - web: MapboxMapOptionsSink to MapLibreMapOptionsSink All renamings were done only with the IDE renaming function. There are **no functional changes and no changes in the public API**, only some internal renamings and updated doc comments. (This can also be seen by the fact that the example app needs no updates, only two internal variables were renamed).
maplibre · Nov 27, 2023 · 6c88d54 · 6c88d54
1 parent ed74640
commit 6c88d54
Show file tree

Hide file tree

Showing 79 changed files with 980 additions and 1,037 deletions.
diff --git a/README.md b/README.md
@@ -80,7 +80,7 @@ Include the following JavaScript and CSS files in the `<head>` of the `web/index
 
 ## Map Styles
 
-Map styles can be supplied by setting the `styleString` in the `MapOptions`. The following formats are supported:
+Map styles can be supplied by setting the `styleString` in the `MaplibreMap` constructor. The following formats are supported:
 
 1. Passing the URL of the map style. This should be a custom map style served remotely using a URL that start with 'http(s)://'
 2. Passing the style as a local asset. Create a JSON file in the `assets` and add a reference in `pubspec.yml`. Set the style string to the relative path for this asset in order to load it into the map.

diff --git a/example/lib/full_map.dart b/example/lib/full_map.dart
@@ -53,7 +53,6 @@ class FullMapState extends State<FullMap> {
         // ),
         // ),
         body: MaplibreMap(
-      // TODO: styleString: isLight ? MapboxStyles.LIGHT : MapboxStyles.DARK,
       onMapCreated: _onMapCreated,
       initialCameraPosition: const CameraPosition(target: LatLng(0.0, 0.0)),
       onStyleLoadedCallback: _onStyleLoadedCallback,

diff --git a/example/lib/map_ui.dart b/example/lib/map_ui.dart
@@ -346,7 +346,7 @@ class MapUiBodyState extends State<MapUiBody> {
 
   @override
   Widget build(BuildContext context) {
-    final MaplibreMap mapboxMap = MaplibreMap(
+    final MaplibreMap maplibreMap = MaplibreMap(
       onMapCreated: onMapCreated,
       initialCameraPosition: _kInitialPosition,
       trackCameraPosition: true,
@@ -447,7 +447,7 @@ class MapUiBodyState extends State<MapUiBody> {
           child: SizedBox(
             width: _mapExpanded ? null : 300.0,
             height: 200.0,
-            child: mapboxMap,
+            child: maplibreMap,
           ),
         ),
         Expanded(

diff --git a/lib/maplibre_gl.dart b/lib/maplibre_gl.dart
@@ -2,6 +2,37 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+/// 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 [MaplibreMapController].
+/// The [MaplibreMapController] 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.
 library maplibre_gl;
 
 import 'dart:async';
@@ -53,7 +84,7 @@ export 'package:maplibre_gl_platform_interface/maplibre_gl_platform_interface.da
 
 part 'src/controller.dart';
 
-part 'src/mapbox_map.dart';
+part 'src/maplibre_map.dart';
 
 part 'src/global.dart';
 

diff --git a/lib/src/annotation_manager.dart b/lib/src/annotation_manager.dart
@@ -269,25 +269,25 @@ class SymbolManager extends AnnotationManager<Symbol> {
   bool _iconIgnorePlacement;
   bool _textIgnorePlacement;
 
-  /// For more information on what this does, see https://docs.mapbox.com/help/troubleshooting/optimize-map-label-placement/#label-collision
+  /// If true, the icon will be visible even if it collides with other previously drawn symbols.
   Future<void> setIconAllowOverlap(bool value) async {
     _iconAllowOverlap = value;
     await _rebuildLayers();
   }
 
-  /// For more information on what this does, see https://docs.mapbox.com/help/troubleshooting/optimize-map-label-placement/#label-collision
+  /// If true, other symbols can be visible even if they collide with the icon.
   Future<void> setTextAllowOverlap(bool value) async {
     _textAllowOverlap = value;
     await _rebuildLayers();
   }
 
-  /// For more information on what this does, see https://docs.mapbox.com/help/troubleshooting/optimize-map-label-placement/#label-collision
+  /// If true, the text will be visible even if it collides with other previously drawn symbols.
   Future<void> setIconIgnorePlacement(bool value) async {
     _iconIgnorePlacement = value;
     await _rebuildLayers();
   }
 
-  /// For more information on what this does, see https://docs.mapbox.com/help/troubleshooting/optimize-map-label-placement/#label-collision
+  /// If true, other symbols can be visible even if they collide with the text.
   Future<void> setTextIgnorePlacement(bool value) async {
     _textIgnorePlacement = value;
     await _rebuildLayers();

diff --git a/lib/src/color_tools.dart b/lib/src/color_tools.dart
@@ -1,6 +1,6 @@
 part of maplibre_gl;
 
-extension MapBoxColorConversion on Color {
+extension MapLibreColorConversion on Color {
   String toHexStringRGB() {
     final r = red.toRadixString(16).padLeft(2, '0');
     final g = green.toRadixString(16).padLeft(2, '0');