This update has renewed two of the oldest surviving sections of 'flutter_map' (state/MapController and TileProviders), fixed bugs, and added features!
This is significant progress in our aim to renew the project and bring it up to date. In the long run, this will bring it inline with up-to-date Flutter good practises and techniques, improve its performance and stability, and reduce the maintenance burden.
There are major breaking changes for all users, as well as some things users should check and possibly change.
Some changes have deprecations and messages, some do not. Please refer to the sections below for information on how to migrate your project, as well as in-code documentation and deprecation messages, if your migration is not listed below. Some changes are omitted if they are deemed unlikely to affect implementations.
Changelog & Highlights
There's loads of changes in this release, which will improve performance and reduce costs! Check out these highlights, along with the full changelog:
We've added in-memory caching to the underlying custom ImageProvider. This means that they do not need to be re-requested if they are pruned then re-loaded, reducing tile loading times, and reduce tile requests and costs!
No action is needed to benefit from this.
If you're developing an app for the web, there's an exciting new performance boost available. By aborting in-flight HTTP requests if tiles are pruned before they are fully-loaded, connections can be freed up, reducing tile loading times, and potentially saving you money!
There are also advantages for other platforms, although they may not be quite as visible.
Rotation is now supported on desktop! Simply use the CTRL (or equivalent) keyboard key (customizable in MapOptions) and mouse.
We've added some warning & recommendation logs in-code, that will trigger under certain circumstances. If they trigger, make sure to listen to them to benefit from performance and efficiency improvements!
Migration Instructions
General/Misc
CustomPoint has been replaced by extension methods on Point
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.
"Plugin API" import has been removed
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.
State Management
FlutterMapState 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':
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.
Custom layers need to define their behaviour
The way custom layers are defined has changed. Mobile/moving layers should now use MobileLayerTransformer at the top of their widget tree.
Tile Layer
retinaMode behaviour has changed
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.
backgroundColor has been replaced by MapOptions.backgroundColor
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.
templateFunction has been replaced by TileProvider.populateTemplatePlaceholders
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.
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.
rotateOrigin and rotateAligment have been removed
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.
Marker.builder has been replaced by child
This has been done since using the builder pattern offered no significant advantage.
Map Options
center, bounds, zoom, and rotation have been replaced with initialCenter, initialCameraFit, initialZoom, and initialRotation
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.
maxBounds has been replaced with cameraConstraint
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.
Interactive options (such as interactiveFlags) have been moved into InteractionOptions
This has been done to improve readability and seperation of responsibilities.
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.
Extensions should not provide a constant default value for headers in the constructor
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.
Extensions overriding getTileUrl should consider overriding other methods instead
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.
Extensions implementing getImage should consider overriding getImageWithCancelLoadingSupport instead
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.
Manual action is required to benefit from this. See for more information.
To migrate, simply change to using the child parameter, and use as you would any other widget. If a builder is required, for example to access the inherited states (), use the Builder widget yourself.
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 .
