feat!: added TileUpdateTransformers.debounce & reverted #1840 (#1850)

example/lib/main.dart

@@ -4,6 +4,7 @@ import 'package:flutter_map_example/pages/bundled_offline_map.dart';
 import 'package:flutter_map_example/pages/cancellable_tile_provider.dart';
 import 'package:flutter_map_example/pages/circle.dart';
 import 'package:flutter_map_example/pages/custom_crs/custom_crs.dart';
+import 'package:flutter_map_example/pages/debouncing_tile_update_transformer.dart';
 import 'package:flutter_map_example/pages/epsg3413_crs.dart';
 import 'package:flutter_map_example/pages/epsg4326_crs.dart';
 import 'package:flutter_map_example/pages/fallback_url_page.dart';
@@ -86,6 +87,8 @@ class MyApp extends StatelessWidget {
         FallbackUrlPage.route: (context) => const FallbackUrlPage(),
         SecondaryTapPage.route: (context) => const SecondaryTapPage(),
         RetinaPage.route: (context) => const RetinaPage(),
+        DebouncingTileUpdateTransformerPage.route: (context) =>
+            const DebouncingTileUpdateTransformerPage(),
       },
     );
   }

example/lib/pages/debouncing_tile_update_transformer.dart

@@ -0,0 +1,112 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_map/flutter_map.dart';
+import 'package:flutter_map_example/widgets/drawer/menu_drawer.dart';
+import 'package:flutter_map_example/widgets/notice_banner.dart';
+import 'package:latlong2/latlong.dart';
+
+class DebouncingTileUpdateTransformerPage extends StatefulWidget {
+  static const String route = '/debouncing_tile_update_transformer_page';
+
+  const DebouncingTileUpdateTransformerPage({super.key});
+
+  @override
+  State<DebouncingTileUpdateTransformerPage> createState() =>
+      _DebouncingTileUpdateTransformerPageState();
+}
+
+class _DebouncingTileUpdateTransformerPageState
+    extends State<DebouncingTileUpdateTransformerPage> {
+  int _changeEndKeyRefresher = 0;
+  double _durationInMilliseconds = 20;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('Debouncing Tile Update Transformer')),
+      drawer: const MenuDrawer(DebouncingTileUpdateTransformerPage.route),
+      body: Column(
+        children: [
+          const NoticeBanner.informational(
+            text:
+                'This TileUpdateTransformer debounces TileUpdateEvents so they '
+                "don't occur too frequently, which can improve performance and "
+                'reduce tile requests.\nHowever, this does lead to reduced UX, '
+                'as tiles will not be loaded during long movements or '
+                'animations, resulting in the background grey breaking the '
+                'illusion of a seamless map.',
+            url:
+                'https://docs.fleaflet.dev/layers/tile-layer#tile-update-transformers',
+            sizeTransition: 1360,
+          ),
+          Expanded(
+            child: Stack(
+              children: [
+                FlutterMap(
+                  options: MapOptions(
+                    initialCenter: const LatLng(51.5, -0.09),
+                    initialZoom: 5,
+                    cameraConstraint: CameraConstraint.contain(
+                      bounds: LatLngBounds(
+                        const LatLng(-90, -180),
+                        const LatLng(90, 180),
+                      ),
+                    ),
+                  ),
+                  children: [
+                    TileLayer(
+                      key: ValueKey('TileLayer-$_changeEndKeyRefresher'),
+                      urlTemplate:
+                          'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
+                      userAgentPackageName: 'dev.fleaflet.flutter_map.example',
+                      tileUpdateTransformer: TileUpdateTransformers.debounce(
+                        Duration(milliseconds: _durationInMilliseconds.toInt()),
+                      ),
+                    ),
+                  ],
+                ),
+                Positioned(
+                  left: 16,
+                  top: 16,
+                  right: 16,
+                  child: DecoratedBox(
+                    decoration: BoxDecoration(
+                      color: Theme.of(context).colorScheme.background,
+                      borderRadius: BorderRadius.circular(32),
+                    ),
+                    child: Padding(
+                      padding: const EdgeInsets.only(
+                          left: 16, right: 8, top: 4, bottom: 4),
+                      child: Row(
+                        children: [
+                          const Tooltip(
+                            message: 'Adjust Duration',
+                            child: Icon(Icons.timer),
+                          ),
+                          Expanded(
+                            child: Slider.adaptive(
+                              value: _durationInMilliseconds,
+                              onChanged: (v) =>
+                                  setState(() => _durationInMilliseconds = v),
+                              onChangeEnd: (v) =>
+                                  setState(() => _changeEndKeyRefresher++),
+                              min: 0,
+                              max: 500,
+                              divisions: 100,
+                              label: _durationInMilliseconds == 0
+                                  ? 'Instant/No Debounce'
+                                  : '${_durationInMilliseconds.toInt()} ms',
+                            ),
+                          ),
+                        ],
+                      ),
+                    ),
+                  ),
+                )
+              ],
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}

example/lib/widgets/drawer/menu_drawer.dart

@@ -4,6 +4,7 @@ import 'package:flutter_map_example/pages/bundled_offline_map.dart';
 import 'package:flutter_map_example/pages/cancellable_tile_provider.dart';
 import 'package:flutter_map_example/pages/circle.dart';
 import 'package:flutter_map_example/pages/custom_crs/custom_crs.dart';
+import 'package:flutter_map_example/pages/debouncing_tile_update_transformer.dart';
 import 'package:flutter_map_example/pages/epsg3413_crs.dart';
 import 'package:flutter_map_example/pages/epsg4326_crs.dart';
 import 'package:flutter_map_example/pages/fallback_url_page.dart';
@@ -137,6 +138,11 @@ class MenuDrawer extends StatelessWidget {
             routeName: CancellableTileProviderPage.route,
             currentRoute: currentRoute,
           ),
+          MenuItemWidget(
+            caption: 'Debouncing Tile Update Transformer',
+            routeName: DebouncingTileUpdateTransformerPage.route,
+            currentRoute: currentRoute,
+          ),
           const Divider(),
           MenuItemWidget(
             caption: 'Polygon Stress Test',

example/lib/widgets/notice_banner.dart

@@ -20,6 +20,15 @@ class NoticeBanner extends StatelessWidget {
         foregroundColor = const Color(0xFF072100),
         backgroundColor = const Color(0xFFB8F397);
 
+  const NoticeBanner.informational({
+    super.key,
+    required this.text,
+    required this.url,
+    required this.sizeTransition,
+  })  : icon = Icons.info_outline,
+        foregroundColor = const Color(0xFF072100),
+        backgroundColor = Colors.lightBlueAccent;
+
   final String text;
   final String? url;
   final double sizeTransition;
@@ -33,10 +42,7 @@ class NoticeBanner extends StatelessWidget {
     return LayoutBuilder(
       builder: (context, constraints) {
         return Container(
-          padding: EdgeInsets.symmetric(
-            horizontal: 8,
-            vertical: constraints.maxWidth <= sizeTransition ? 8 : 0,
-          ),
+          padding: const EdgeInsets.all(12),
           width: double.infinity,
           color: backgroundColor,
           child: Flex(
@@ -46,14 +52,14 @@ class NoticeBanner extends StatelessWidget {
             mainAxisAlignment: MainAxisAlignment.center,
             children: [
               Icon(icon, color: foregroundColor, size: 32),
-              const SizedBox(height: 12, width: 16),
+              const SizedBox(height: 8, width: 12),
               Text(
                 text,
                 style: TextStyle(color: foregroundColor),
                 textAlign: TextAlign.center,
               ),
               if (url != null) ...[
-                const SizedBox(height: 0, width: 16),
+                const SizedBox(height: 8, width: 12),
                 TextButton.icon(
                   icon: const Icon(Icons.open_in_new),
                   label: const Text('Learn more'),

lib/src/layer/tile_layer/tile_layer.dart

@@ -197,35 +197,19 @@ class TileLayer extends StatefulWidget {
   /// Only load tiles that are within these bounds
   final LatLngBounds? tileBounds;
 
-  /// This transformer modifies how/when tile updates and pruning are triggered
-  /// based on [MapEvent]s. It is a StreamTransformer and therefore it is
-  /// possible to filter/modify/throttle the [TileUpdateEvent]s. Defaults to
-  /// [TileUpdateTransformers.ignoreTapEvents] which disables loading/pruning
-  /// for map taps, secondary taps and long presses. See TileUpdateTransformers
-  /// for more transformer presets or implement your own.
+  /// Restricts and limits [TileUpdateEvent]s (which are emitted 'by'
+  /// [MapEvent]s), which cause tiles to update.
   ///
-  /// Note: Changing the [tileUpdateTransformer] after TileLayer is created has
-  /// no affect.
-  final TileUpdateTransformer tileUpdateTransformer;
-
-  /// Defines the minimum delay time from last map event before the tile layers
-  /// are updated. This delay acts as a debounce period to prevent frequent
-  /// reloading of tile layers in response to rapid, successive events
-  /// (e.g., zooming or panning).
-  ///
-  /// 16ms could be a good starting point for most applications.
-  /// This at 60fps this will wait one frame after the last event.
+  /// For more information, see [TileUpdateTransformer].
   ///
-  /// By setting this delay, we ensure that map layer updates are performed
-  /// only after a period of inactivity, enhancing performance and user
-  /// experience on lower performance devices.
+  /// Defaults to [TileUpdateTransformers.ignoreTapEvents], which disables
+  /// updates for map taps, secondary taps and long presses, which alone should
+  /// not cause the camera to change position.
   ///
-  /// - If multiple events occur within this delay period, only the last event
-  ///   triggers the tile layer update, reducing unnecessary processing and
-  ///   network requests.
-  /// - If the [loadingDelay] is `Duration.zero`, the delay is completely
-  /// disabled and the tile layer will update as soon as possible.
-  final Duration loadingDelay;
+  /// Note that changing this after the layer has already been built will have
+  /// no effect. If necessary, force a rebuild of the entire layer by changing
+  /// the [key].
+  final TileUpdateTransformer tileUpdateTransformer;
 
   /// Create a new [TileLayer] for the [FlutterMap] widget.
   TileLayer({
@@ -258,7 +242,6 @@ class TileLayer extends StatefulWidget {
     this.evictErrorTileStrategy = EvictErrorTileStrategy.none,
     this.reset,
     this.tileBounds,
-    this.loadingDelay = Duration.zero,
     TileUpdateTransformer? tileUpdateTransformer,
     String userAgentPackageName = 'unknown',
   })  : assert(
@@ -353,9 +336,6 @@ class _TileLayerState extends State<TileLayer> with TickerProviderStateMixin {
       TileRangeCalculator(tileSize: widget.tileSize);
   late TileScaleCalculator _tileScaleCalculator;
 
-  /// Delay Timer for [TileLayer.loadingDelay]
-  Timer? _delayTimer;
-
   // We have to hold on to the mapController hashCode to determine whether we
   // need to reinitialize the listeners. didChangeDependencies is called on
   // every map movement and if we unsubscribe and resubscribe every time we
@@ -370,26 +350,8 @@ class _TileLayerState extends State<TileLayer> with TickerProviderStateMixin {
     _loadAndPruneInVisibleBounds(MapCamera.of(context));
   });
 
-  /// This method is used to delay the execution of a function by the specified
-  /// [TileLayer.loadingDelay]. This is useful to prevent frequent reloading
-  /// of tile layers in response to rapid, successive events (e.g., zooming
-  /// or panning).
-  void _loadingDelay(VoidCallback action) {
-    //execute immediately if delay is zero.
-    if (widget.loadingDelay == Duration.zero) {
-      action();
-      return;
-    }
-
-    // Cancel the previous timer if it is still active.
-    _delayTimer?.cancel();
-
-    // Reset the timer to wait for the debounce duration
-    _delayTimer = Timer(widget.loadingDelay, action);
-  }
-
   // This is called on every map movement so we should avoid expensive logic
-  // where possible.
+  // where possible, or filter as necessary
   @override
   void didChangeDependencies() {
     super.didChangeDependencies();
@@ -404,7 +366,7 @@ class _TileLayerState extends State<TileLayer> with TickerProviderStateMixin {
       _tileUpdateSubscription = mapController.mapEventStream
           .map((mapEvent) => TileUpdateEvent(mapEvent: mapEvent))
           .transform(widget.tileUpdateTransformer)
-          .listen((event) => _loadingDelay(() => _onTileUpdateEvent(event)));
+          .listen(_onTileUpdateEvent);
     }
 
     var reloadTiles = false;
@@ -499,7 +461,6 @@ class _TileLayerState extends State<TileLayer> with TickerProviderStateMixin {
     _resetSub?.cancel();
     _pruneLater?.cancel();
     widget.tileProvider.dispose();
-    _delayTimer?.cancel();
     super.dispose();
   }