Migrating To v6

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:

flutter_map/CHANGELOG.md at master · fleaflet/flutter_mapGitHub

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.

Manual action is required to benefit from this. See CancellableNetworkTileProvider for more information.

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':

• MapCamera.of: for more information, see Some of MapController's 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 Creating New Layers and Programmatic Control for more information.

Some of MapController's responsibilities have been moved to MapCamera

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.

Children/Layers

nonRotatedChildren has been removed

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.

For more information, see Creating New Layers.

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.

For more information, see Retina Mode.

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.

To migrate, see Creating New Tile Providers.

Marker Layer

anchor and all related objects have been removed

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.

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 (Accessing Aspects Within Descendants), use the Builder widget yourself.

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.

For more information, see Interaction Options.

Tile Providers

Implementations should switch to extensions

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

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.