Migrating To v6

Extension methods are now used to add the required functionality to the standard 'dart:math' Point object.

To migrate, most cases should just need to replace all occurrences of CustomPoint with Point.

This import path was getting increasingly useless and exposing increasingly less features compared to the standard import. It also covered the standard import in the auto-generated DartDoc documentation, as it exported it as well.

All features that need to be exposed are now exposed through the primary import, and the dedicated plugin import has been removed.

FlutterMapState previously represented all of the map's state. However, to improve the maintainability of this library's internals, and to improve performance, it has been removed and replaced with several 'aspects':

• MapCamera.of: for more information, see #some-of-mapcontrollers-responsibilities-have-been-moved-to-mapcamera

• MapOptions.of: use to access the ambient configured MapOptions

• (MapController.of): use to access the ambient MapController, even if one was not explicitly defined by the user

In most cases, migrating will entail replacing FlutterMapState with MapCamera, but another aspect may be required.

See #2.-hooking-into-inherited-state and Programmatic Control for more information.

MapController now only controls the map's position/viewport/camera. The map's position is now described by MapCamera.

You should not read camera data directly from a MapController: these methods have been deprecated.

There are multiple possibilities for migration:

1. If inside the FlutterMap context, prefer using MapCamera.of(context)

2. Otherwise, use MapController in the same way, but use the .camera getter to retrieve the MapCamera.

See Programmatic Control for more information.

The approach to 'mobile' and 'static' layers has been changed. Mobile layers now wrap themselves in a MobileLayerTransformer which uses the inherited state, instead of FlutterMap applying the affects directly to them. Static layers should now ensure they use Align and/or SizedBox.expand.

This has been done to simplify setup, and allow for placing static layers between mobile layers.

The way custom layers are defined has changed. Mobile/moving layers should now use MobileLayerTransformer at the top of their widget tree.

For more information, see #1.-creating-a-layer-widget.

Previously, the retinaMode property enabled/disabled the simulation of retina mode. To request retina tiles from the server, either the {r}placeholder or "@2x" string could be included in the urlTemplate. This behaviour was unclear, did not conform to the norms of other mapping packages, and meant the {r} placeholder was actually redundant.

Now, retinaMode also affects whether the {r} placeholder is filled in. If true, and {r} is present, then that will now be filled in to request retina tiles. If the placeholder is not present, only then will flutter_map simulate retina mode.

Additionally, it is now recommended to use the RetinaMode.isHighDensity method to check whether retinaMode should be enabled.

For more information, see #retina-mode.

This will simplify the developer experience when using multiple overlaid TileLayers, as Colors.transparent will no longer need to be specified. There is no reason that multiple TileLayers would each need to have a different (non-transparent) background colors, as the layers beneath would be invisible and therefore pointless.

Therefore, TileLayers now have transparent backgrounds, and the new MapOptions.backgroundColor property sets the background color of the entire map.

To migrate, move any background colour specified on the bottom-most TileLayer to MapOptions.

TileProvider.templateFunction has been deprecated. It is now preferrable to create a custom TileProvider extension, and override the populateTemplatePlaceholders method. This has been done to reduce the scope of TileLayer.

To migrate, see Creating New Tile Providers.

In order to simplify Markers, the anchor property and AnchorPos/Anchor objects have been removed without replacement.

Marker alignment is now performed with the standard Alignment object through the alignment argument.

Due to the previously named anchor being confusingly (and perhaps incorrectly) named, migration without behaviour change is possible just by taking the Alignment from inside any AnchorPos and passing it directly to alignment.

These properties on Marker have been removed as it is not apparent what any valid use-case could be, and removing them helped simplify the internals significantly.

If these are currently used, try changing alignment, and if that does not give the desired results, use a Transform widget yourself.

This has been done since using the builder pattern offered no significant advantage.

These have been renamed for clarity, as well as to better fit the change into using a documented 'camera' and increasing customizability.

To migrate, rename the properties, and also check the in-code documentation and new objects for information.

This is part of to better fit the change into using a documented 'camera' and increasing customizability.

To migrate, rename the properties, and also check the in-code documentation and new objects for information.

This has been done to improve readability and seperation of responsibilities.

For more information, see Interaction Options.

It is not recommended to implement TileProvider, as there are now two methods of which only one should be implemented (getImage & getImageWithCancelLoadingSupport), as well as other members that should not usually be overridden.

To migrate, use extends instead of implements.

Further panes will refer to implementations that use extends as 'extensions' for clarity, not to be confused with extension methods.

TileLayer behaviour has been modified so that the 'User-Agent' header can be set without copying all user-specified headers. It is now inserted into the Map, so it must be immutable/non-constant.

Note that the headers property is also now final.

To migrate, remove the default value for super.headers: it is not necessary.

The logic previously handled by getTileUrl, invertY, and getSubdomain has been refactored into generateReplacementMap, populateTemplatePlaceholders, and getTileUrl.

To migrate, consider overriding another of those methods, if it is more suitable. This will reduce the amount of code duplicated in your library from flutter_map's implementation.

The framework necessary to support tile providers that can abort in-flight HTTP requests and other processing is now available. For more information about the advantages of cancelling unnecessary tile requests when they are pruned before being fully loaded, see #cancellablenetworktileprovider.

If it is not possible to cancel the loading of a tile, or there is no advantage gained by doing so, you can ignore this.

To migrate, override supportsCancelLoading to true, implement getImageWithCancelLoadingSupport as appropriate, and remove the implementation of getImage.