Expose more declarative arguments to the class MaplibreMap ? Eg. symbols

[T-moz]

Currently to display symbols on the map, we have to use imperative methods of the MaplibreMapController class.

/// Eg.
await controller.addSymbols(options);
await controller.removeSymbols(symbols)

But Flutter is, mostly, a declarative framework where just by giving args to a widget, it updates the UI.

Others flutter map packages (like google_map, or flutter_map) have done it.

/// See: https://github.com/flutter/packages/blob/main/packages/google_maps_flutter/google_maps_flutter/lib/src/google_map.dart
///
/// Eg.
class GoogleMap extends StatefulWidget {
  const GoogleMap({
    super.key,
    this.markers = const <Marker>{},
    ...
  });

  /// Markers to be placed on the map.
  final Set<Marker> markers;
  ...
  /// Creates a [State] for this [GoogleMap].
  @override
  State createState() => _GoogleMapState();
}

class _GoogleMapState extends State<GoogleMap> {

  final Completer<GoogleMapController> _controller =
      Completer<GoogleMapController>();

  Map<MarkerId, Marker> _markers = <MarkerId, Marker>{};

  @override
  Widget build(BuildContext context) {
    return GoogleMapsFlutterPlatform.instance.buildViewWithConfiguration(
      _mapId,
      ...
    );
  }

  @override
  void initState() {
    super.initState();
    _markers = widget.markers;
  }

  @override
  void didUpdateWidget(GoogleMap oldWidget) {
    super.didUpdateWidget(oldWidget);
    _updateMarkers();
  }

  Future<void> _updateMarkers() async {
    final GoogleMapController controller = await _controller.future;
    unawaited(controller._updateMarkers(
        MarkerUpdates.from(_markers.values.toSet(), widget.markers)));
    _markers = widget.markers;
  }
  ...
} 

Should the flutter_maplibre_gl package go in this direction ?

[m0nac0]

I tried doing this in the past.
However, since the underlying plugins we use are imperative, we would need to have code to maintain the previous copy of the arguments, compare them to the new arguments and run an algorithm to detect all changes and then call the imperative methods again to perform these changes.
I understand that it might feel a bit more idiomatic, but I think it would be unnecessary work and code to maintain, and also we would risk performance degradations, especially for huge amounts of annotations, depending on how performant the algorithm we use for comparison is.

[T-moz]

Hey !

Now that we are a few month later, I have more experience to talk about this subject 💡
With my company we built two flutter apps build around map. One with flutter-maplibre-gl, and one with mapbox.

In both project we added a widget called DeclarativeMap around the MapWidget.
The principe is describe above, but simply:

• Detect changes in the didUpdateWidget method.
• Compare the difference between old and new widget.
• Call the right imperative method (add, remove, update).

This package (fast immutable collection) was a great help in achieving the declarative API.

We also write an article that goes deeper into this technique.
https://www.bam.tech/article/build-a-declarative-map-widget-above-the-mapbox-flutter-package-mapbox-maps-flutter

Conclusion, a few month later, I still think that a declarative API to display map features is a cool evolution for this package.

[josxha]

Thanks for looking into this topic and all your research @T-moz. There seems to be a good amount of interest in a declarative API and I understand since it's the way flutter works. I'm not against a declarive layer above the imperative controller too, but I think it should be planned and tested well.

It's correct that flutter_map uses a mostly declarative approach like you mentioned in your initial post. The expense to check if anything has changed in every widget build is not something to underestimate. For example a very recent bug in flutter_map related to this is: fleaflet/flutter_map#1894.
I checked the package fast_immutable_collections and saw that they use a cached hash code for the list content to improve equality checks. This would be a viable solution to avoid the expensive checks on every widget build. If the list content changes however, there might still be one bad frame, or am I wrong?

I had a look at googe maps for flutter and it seems that they just update everything on every widget build. No special checks in place. Maybe the native SDK performs those checks, maybe it is performant without them? I can't tell.

  @override
  void didUpdateWidget(GoogleMap oldWidget) {
    super.didUpdateWidget(oldWidget);
    _updateOptions();
    _updateMarkers();
    _updatePolygons();
    _updatePolylines();
    _updateCircles();
    _updateTileOverlays();
  }

Future<void> _updatePolygons() async {
    final GoogleMapController controller = await _controller.future;
    unawaited(controller._updatePolygons(
        PolygonUpdates.from(_polygons.values.toSet(), widget.polygons)));
    _polygons = keyByPolygonId(widget.polygons);
  }

https://github.com/flutter/packages/blob/02e71b087e76205de8b1576fb5fb3f8a8792d249/packages/google_maps_flutter/google_maps_flutter/lib/src/google_map.dart#L376-L385

In the end, some caveats seem to persist for us:

• the declarative approach has additional cost that imperative doesn't have
• users need to add fast_immutable_collections as a dependency and use it instead of default dart lists.

I red trough your example declarative_mapbox_map and would be interessted how well it performs for bigger Polygons (50k+ points in total), potentially with holes.

[josxha]

Hi @T-moz, not sure if you are aware of it but I started a new maplibre flutter package some time ago. It will add a declarative annotation API for easy use in its next release.
The annotation layers are build on the imperative calls that manipulate the MapLibre Style but handle those calls internally. All the user has to do is calling setState().

https://github.com/josxha/flutter-maplibre/blob/587cdd78dd5b2b4bd874d194d3b34c4ae9667839/example/lib/annotations_mixed_page.dart#L80-L99

As you've been the strongest influence with your article and this thread I'd be really interested to hear some feedback from you. (: