flutter_map Docs
Project Links💝 Support Us
v7
v7
  • flutter_map
  • 🏗️Why Choose flutter_map?
  • 💝Supporters
  • ✏️Credits & Contributing
  • Getting Started
    • How Does It Work?
      • Raster vs Vector Tiles
    • Installation
    • Examples
    • v7 Information
  • Usage
    • Base Widget
    • Options
      • Interaction Options
      • Custom CRSs
    • Layers
    • Programmatic Interaction
      • Controllers & Cameras
      • External Custom Controllers
      • Listen To Events
    • Full API Reference
  • Layers
    • Tile Layer
      • Tile Providers
      • WMS Usage
    • Marker Layer
    • Polygon Layer
    • Polyline Layer
    • Circle Layer
    • Overlay Image Layer
    • Attribution Layer
    • Layer Interactivity
      • Hit Testing Behaviour
  • Tile Servers
    • Using Google Maps
    • Using Mapbox
    • Using Thunderforest
    • Using Tracestrack
    • Using Stadia Maps
    • Using Lima Labs
    • Using Bing Maps
    • Offline Mapping
    • Other Options
  • Plugins
    • Plugins List
    • Creating A Plugin
      • Creating New Tile Providers
      • Creating New Layers
Powered by GitBook

© flutter_map Authors & Maintainers

On this page
  • Basic Setup
  • Usage Before Attachment (eg. Within initState)
  • Usage Within A State System/Model
  • Animation

Was this helpful?

Export as PDF
  1. Usage
  2. Programmatic Interaction

External Custom Controllers

PreviousControllers & CamerasNextListen To Events

Last updated 1 year ago

Was this helpful?

For more information about what a MapController is, and when it is necessary to set one up in this way, see:


Basic Setup

The FlutterMap.controller parameter takes an externally intialised MapController instance, and attaches it to the map.

// Within a widget
final mapController = MapController();

@override
Widget build(BuildContext context) =>
    FlutterMap(
        mapController: mapController,
        // ...
    );

An externally attached controller will be accurately reflected when depending on the MapController aspect.

It is not safe to assume that the MapController is ready to use as soon as an instance has been initialised, for example within initState.

See below for more information.

Usage Before Attachment (eg. Within initState)

It is not safe to assume that the MapController is ready to use as soon as an instance has been initialised, for example within initState.

It must first be attached to the FlutterMap, which could take up to multiple frames to occur (similar to the way a ScrollController is attached to a scrollable view). It helps to avoid errors by thinking of the controller in this way.

Use of the MapController before it has been attached to a FlutterMap will result in an error being thrown, usually a LateInitialisationError.

It is usually safe to use a controller from within a callback manually initiated by the user without further complications.

Instead, use the MapOptions.onMapReady callback. At this point, it is guaranteed that the controller will have been attached. You could also use this method to complete a Completer (and await its Future elsewhere) if you need to use it elsewhere.

final mapController = MapController();

@override
void initState() {
    // Cannot use `mapController` safely here
}

@override
Widget build(BuildContext context) {
    return FlutterMap(
        mapController: mapController,
        options: MapOptions(
            onMapReady: () {
                mapController.mapEventStream.listen((evt) {}); // for example
                // Any* other `MapController` dependent methods
            },
        ),
    );
}

Usage Within A State System/Model

Don't define/intialise the a MapController within a class or widget that doesn't also contain the FlutterMap, such as a state model (eg. ChangeNotifier), then try to use it by querying the state in the FlutterMap.controller parameter.

Instead, some extra care should be taken, which may feel a little backwards at first. The state model should be used AFTER the normal setup.

  1. Setup the controller as in Basic Setup, where the MapController is defined & initialised directly adjacent to the FlutterMap

  2. In your state model, create a nullable (and initially uninitialised) MapController containing field

  3. Follow Usage Before Attachment (eg. Within initState) to setup an onMapReady callback. Then within this callback, set the state model field.

It may then be beneficial to unset the state model field when the controller is disposed: it should be disposed when the FlutterMap is disposed, which should occur just before the widget building the FlutterMap is disposed. Therefore, you can override the dispose method.

Animation

For example, it is sometimes necessary to use a controller in the initState() method (for example to ). However, because this method executes before the widget has been built, a controller defined here will not be ready for use.

MapController methods that change the position of the map should not be used directly (not as a result of another callback) in onMapReady - see . This is an unsupported and usually unnecessary usecase.

Whilst animated movements through MapControllers aren't built-in, the provides this, and much more!

Controllers & Cameras
attach an event listener
issue #1507
community maintained plugin flutter_map_animations