To cause a widget inside FlutterMap's context to rebuild when the MapCamera, MapOptions, or MapController changes, see #hooking-into-inherited-state.
This page's methods should only be used to listen to events from outside the FlutterMap's context.
When changes happen to FlutterMap's internal state (such as a change to the current MapCamera) it emits a MapEvent, which can be handled by you.
There's two methods to catch all emitted MapEvents. These methods expose the raw MapEvent, and is recommended in cases where multiple events need to be caught, or there's no more specific callback method available in MapOptions (see #catching-specific-events).
Listening to a MapController's mapEventStream, which exposes events via a Stream
Specifying a callback method in MapOptions.onMapEvent
If only a couple of events need to be caught, such as just an onTap handler, it is possible to avoid handling the raw Stream of MapEvents. Instead, MapOptions has callbacks available for the following events:
onTap
onLongPress
onPositionChanged
onPointerDown/onPointerUp/onPointerHover/onPointerCancel
onMapReady
Primarily used for advanced MapController #usage-inside-initstate
The MapEventTap event may be emitted (or the onTap callback called) 250ms after the actual tap occurred, as this is the acceptable delay between the two taps in a double tap zoom gesture.
If this causes noticeable jank or a bad experience (for example, on desktop platforms), disable InteractiveFlag.doubleTapZoom:
This disables the double tap handler, so the MapEventTap is emitted 'instantly' on tap.
To control the map (such as moving it to a new position and zoom level), you'll need a MapController. The controller does not provide access to the current viewport/camera: that is the responsibility of .
FlutterMap ChildTo control the map from within the context of a FlutterMap widget, use MapController.of(context).
FlutterMapTo use a MapController, it must initialised like any other object and then passed to the FlutterMap. This attaches them until the map is disposed.
initState()Instead, use the MapOptions.onMapReady callback. The initialised MapController can be used freely within it.
Using them as a reaction to a map event is still fine.
The example application also includes a page demonstrating a custom animated map movement without the plugin.
Calling this method in a build method will cause the widget to automatically rebuild if the MapController changes. See for more information.
If this throws a StateError, try wrapping the concerned widget in a Builder, to ensure the FlutterMap widget is parenting the BuildContext. If this has no effect, use instead.
Sometimes, it is necessary MapController in initState() before the map has been built, for example to attach an event listener (). This is not directly possible, as the map must be built for the controller to be attached.
MapController methods that change the position of the map should not be used instantly in onMapReady - see .
Whilst animated movements through MapControllers aren't built-in, the provides this, and much more!
The MapCamera object describes the map's current viewport. It does not provide methods to change it: that is the responsibility of a MapController.
The MapCamera object also provides access to some other helpful methods that depend on it, such as pointToLatLng & latLngToPoint.
FlutterMap ChildTo get the camera from within the context of a FlutterMap widget, use MapCamera.of(context).
Calling this method in a build method will cause the widget to automatically rebuild when the MapCamera changes. See #2.-hooking-into-inherited-state for more information.
If this behaviour is unwanted, use #single-time instead.
If this throws a StateError, try wrapping the concerned widget in a Builder, to ensure the FlutterMap widget is parenting the BuildContext. If this has no effect, use #usage-outside-of-fluttermap instead.
FlutterMapTo get the camera from outside the context of the FlutterMap widget, you'll need to setup a MapController first: see Control Camera > #usage-outside-of-fluttermap.
Then, use the .camera getter.
Avoid using MapController.of(context).camera from within the context of FlutterMap, as it is redundant and less performant than using MapCamera.of(context) directly.
There's two ways to interact with the map - that is to control it, as well as receive data from it - and it's current viewport, aka. 'camera'.
The first way is through user interaction, where they perform gestures (such as drags/pans), and the map reacts automatically to those gestures to change the camera view of the map.
These are usually restricted by Options. It is possible to disable all input, either by disabling all gestures, or by wrapping the map with something like IgnorePointer.
When using programmatic means, there's two methods to most things, dependent on whether the context is within a FlutterMap (ie. usually a layer) or not.
If within FlutterMap's context, the methods usually cause automatic rebuilding. As well as the pages below, also see #2.-hooking-into-inherited-state.