(⏸︎) Replace TileLayer.errorImage with TileLayer.tilePlaceholder

example/lib/main.dart

@@ -25,7 +25,7 @@ import 'package:flutter_map_example/pages/secondary_tap.dart';
 import 'package:flutter_map_example/pages/sliding_map.dart';
 import 'package:flutter_map_example/pages/stateful_markers.dart';
 import 'package:flutter_map_example/pages/tile_builder_example.dart';
-import 'package:flutter_map_example/pages/tile_loading_error_handle.dart';
+import 'package:flutter_map_example/pages/tile_error_handling.dart';
 import 'package:flutter_map_example/pages/wms_tile_layer.dart';
 import 'package:url_strategy/url_strategy.dart';
 
@@ -62,8 +62,7 @@ class MyApp extends StatelessWidget {
         SlidingMapPage.route: (_) => const SlidingMapPage(),
         WMSLayerPage.route: (context) => const WMSLayerPage(),
         CustomCrsPage.route: (context) => const CustomCrsPage(),
-        TileLoadingErrorHandle.route: (context) =>
-            const TileLoadingErrorHandle(),
+        TileErrorHandling.route: (context) => const TileErrorHandling(),
         TileBuilderPage.route: (context) => const TileBuilderPage(),
         InteractiveTestPage.route: (context) => const InteractiveTestPage(),
         ManyMarkersPage.route: (context) => const ManyMarkersPage(),

example/lib/pages/tile_loading_error_handle.dart → example/lib/pages/tile_error_handling.dart

@@ -6,25 +6,60 @@ import 'package:flutter_map/flutter_map.dart';
 import 'package:flutter_map_example/widgets/drawer.dart';
 import 'package:latlong2/latlong.dart';
 
-class TileLoadingErrorHandle extends StatefulWidget {
-  static const String route = '/tile_loading_error_handle';
+class TileErrorHandling extends StatefulWidget {
+  static const String route = '/tile_error_handling';
 
-  const TileLoadingErrorHandle({Key? key}) : super(key: key);
+  const TileErrorHandling({Key? key}) : super(key: key);
 
   @override
-  _TileLoadingErrorHandleState createState() => _TileLoadingErrorHandleState();
+  _TileErrorHandlingState createState() => _TileErrorHandlingState();
 }
 
-class _TileLoadingErrorHandleState extends State<TileLoadingErrorHandle> {
+class _TileErrorHandlingState extends State<TileErrorHandling> {
   static const _showSnackBarDuration = Duration(seconds: 1);
+
+  late final TileLayerController _tileLayerController;
+
   bool _simulateTileLoadErrors = false;
   DateTime? _lastShowedTileLoadError;
 
+  @override
+  void initState() {
+    super.initState();
+    _tileLayerController = TileLayerController();
+  }
+
+  @override
+  void dispose() {
+    _tileLayerController.dispose();
+    super.dispose();
+  }
+
   @override
   Widget build(BuildContext context) {
     return Scaffold(
-      appBar: AppBar(title: const Text('Tile Loading Error Handle')),
-      drawer: buildDrawer(context, TileLoadingErrorHandle.route),
+      appBar: AppBar(
+        title: const Text('Tile Error Handling'),
+        actions: [
+          IconButton(
+            icon: const Icon(Icons.info),
+            onPressed: () {
+              showDialog<void>(
+                context: context,
+                builder: (context) => const AlertDialog(
+                  title: Text('Tile Error Handling'),
+                  content: Text(
+                    'To trigger tile loading errors enable tile loading error '
+                    'simulation or disable internet access and try to move the '
+                    'map.',
+                  ),
+                ),
+              );
+            },
+          )
+        ],
+      ),
+      drawer: buildDrawer(context, TileErrorHandling.route),
       body: Padding(
         padding: const EdgeInsets.all(8),
         child: Column(
@@ -36,11 +71,11 @@ class _TileLoadingErrorHandleState extends State<TileLoadingErrorHandle> {
                 _simulateTileLoadErrors = newValue;
               }),
             ),
-            const Padding(
-              padding: EdgeInsets.only(top: 8, bottom: 8),
-              child: Text(
-                  'Enable tile load error simulation or disable internet and try to move or zoom map.'),
+            ElevatedButton(
+              onPressed: () => _tileLayerController.reloadErrorTiles(),
+              child: const Text('Reload error tiles'),
             ),
+            const SizedBox(height: 12),
             Flexible(
               child: Builder(builder: (BuildContext context) {
                 return FlutterMap(
@@ -50,6 +85,7 @@ class _TileLoadingErrorHandleState extends State<TileLoadingErrorHandle> {
                   ),
                   children: [
                     TileLayer(
+                      controller: _tileLayerController,
                       urlTemplate:
                           'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
                       userAgentPackageName: 'dev.fleaflet.flutter_map.example',

example/lib/widgets/drawer.dart

@@ -1,5 +1,4 @@
 import 'package:flutter/material.dart';
-
 import 'package:flutter_map_example/pages/animated_map_controller.dart';
 import 'package:flutter_map_example/pages/circle.dart';
 import 'package:flutter_map_example/pages/custom_crs/custom_crs.dart';
@@ -26,7 +25,7 @@ import 'package:flutter_map_example/pages/secondary_tap.dart';
 import 'package:flutter_map_example/pages/sliding_map.dart';
 import 'package:flutter_map_example/pages/stateful_markers.dart';
 import 'package:flutter_map_example/pages/tile_builder_example.dart';
-import 'package:flutter_map_example/pages/tile_loading_error_handle.dart';
+import 'package:flutter_map_example/pages/tile_error_handling.dart';
 import 'package:flutter_map_example/pages/wms_tile_layer.dart';
 
 Widget _buildMenuItem(
@@ -228,8 +227,8 @@ Drawer buildDrawer(BuildContext context, String currentRoute) {
         const Divider(),
         _buildMenuItem(
           context,
-          const Text('Custom Tile Error Handling'),
-          TileLoadingErrorHandle.route,
+          const Text('Tile Error Handling'),
+          TileErrorHandling.route,
           currentRoute,
         ),
         _buildMenuItem(

lib/flutter_map.dart

@@ -14,6 +14,9 @@ export 'package:flutter_map/src/layer/marker_layer.dart';
 export 'package:flutter_map/src/layer/overlay_image_layer.dart';
 export 'package:flutter_map/src/layer/polygon_layer.dart';
 export 'package:flutter_map/src/layer/polyline_layer.dart';
+export 'package:flutter_map/src/layer/tile_layer/controller/tile_layer_controller.dart'
+    hide TileLayerControllerImpl;
+export 'package:flutter_map/src/layer/tile_layer/placeholder_grid_tile.dart';
 export 'package:flutter_map/src/layer/tile_layer/tile_builder.dart';
 export 'package:flutter_map/src/layer/tile_layer/tile_coordinates.dart';
 export 'package:flutter_map/src/layer/tile_layer/tile_display.dart';

lib/src/layer/tile_layer/controller/tile_layer_controller.dart

@@ -0,0 +1,30 @@
+import 'dart:async';
+
+sealed class TileLayerController {
+  factory TileLayerController() => TileLayerControllerImpl();
+
+  /// Trigger reloading of tiles which failed to load.
+  void reloadErrorTiles();
+
+  /// Dispose of this controller, should be called when this TileLayerController
+  /// is no longer used.
+  void dispose();
+}
+
+class TileLayerControllerImpl implements TileLayerController {
+  final StreamController<void> _streamController;
+
+  TileLayerControllerImpl() : _streamController = StreamController.broadcast();
+
+  Stream<void> get stream => _streamController.stream;
+
+  @override
+  void reloadErrorTiles() {
+    _streamController.add(null);
+  }
+
+  @override
+  void dispose() {
+    _streamController.close();
+  }
+}

lib/src/layer/tile_layer/placeholder_grid_tile.dart

@@ -0,0 +1,88 @@
+import 'dart:ui' as ui;
+
+import 'package:flutter/material.dart';
+
+class PlaceholderGridTile extends StatelessWidget {
+  final int cellCount;
+  final Color lineColor;
+  final Color? backgroundColor;
+
+  /// Creates a placeholder tile which is a grid with [cellCount] cells on both
+  /// axis. The cells are have a background of [backgroundColor] (default
+  /// transparent) and are divided by lines with the color [lineColor].
+  const PlaceholderGridTile({
+    super.key,
+    this.cellCount = 8,
+    this.lineColor = Colors.white,
+    this.backgroundColor,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return CustomPaint(
+      painter: _PlaceholderGridTilePainter(
+        lineColor: lineColor,
+        cellCount: cellCount,
+        backgroundColor: backgroundColor,
+      ),
+    );
+  }
+}
+
+class _PlaceholderGridTilePainter extends CustomPainter {
+  final int cellCount;
+  final Color lineColor;
+  final Color? backgroundColor;
+
+  _PlaceholderGridTilePainter({
+    required this.cellCount,
+    required this.lineColor,
+    required this.backgroundColor,
+  });
+
+  @override
+  void paint(ui.Canvas canvas, ui.Size size) {
+    final paint = Paint();
+    if (backgroundColor != null && backgroundColor != Colors.transparent) {
+      paint
+        ..color = backgroundColor!
+        ..style = PaintingStyle.fill;
+      canvas.drawRect(Offset.zero & size, paint);
+    }
+
+    paint
+      ..color = lineColor
+      ..style = PaintingStyle.stroke;
+
+    final tileSize = size.width;
+    final cellOffsetSize = tileSize / cellCount;
+
+    // Draw lines
+    for (int i = 0; i <= cellCount; i++) {
+      if (i % cellCount == 0) {
+        paint.strokeWidth = 1;
+      } else {
+        paint.strokeWidth = 0.5;
+      }
+      final cellOffset = cellOffsetSize * i;
+      // Horizontal line.
+      canvas.drawLine(
+        Offset(0, cellOffset),
+        Offset(tileSize, cellOffset),
+        paint,
+      );
+      // Vertical line.
+      canvas.drawLine(
+        Offset(cellOffset, 0),
+        Offset(cellOffset, tileSize),
+        paint,
+      );
+    }
+  }
+
+  @override
+  bool shouldRepaint(_PlaceholderGridTilePainter oldDelegate) =>
+      lineColor != oldDelegate.lineColor ||
+      cellCount != oldDelegate.cellCount ||
+      backgroundColor != oldDelegate.backgroundColor;
+}

lib/src/layer/tile_layer/positioned_tile.dart

@@ -0,0 +1,30 @@
+import 'dart:math';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_map/flutter_map.dart';
+
+class PositionedTile extends StatelessWidget {
+  final TileCoordinates tileCoordinates;
+  final double scaledTileSize;
+  final Point<double> currentPixelOrigin;
+  final Widget child;
+
+  const PositionedTile({
+    super.key,
+    required this.tileCoordinates,
+    required this.scaledTileSize,
+    required this.currentPixelOrigin,
+    required this.child,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return Positioned(
+      left: tileCoordinates.x * scaledTileSize - currentPixelOrigin.x,
+      top: tileCoordinates.y * scaledTileSize - currentPixelOrigin.y,
+      width: scaledTileSize,
+      height: scaledTileSize,
+      child: child,
+    );
+  }
+}

lib/src/layer/tile_layer/tile.dart

@@ -1,5 +1,3 @@
-import 'dart:math';
-
 import 'package:flutter/widgets.dart';
 import 'package:flutter_map/src/layer/tile_layer/tile_builder.dart';
 import 'package:flutter_map/src/layer/tile_layer/tile_image.dart';
@@ -8,13 +6,9 @@ import 'package:flutter_map/src/layer/tile_layer/tile_image.dart';
 class Tile extends StatefulWidget {
   final TileImage tileImage;
   final TileBuilder? tileBuilder;
-  final double scaledTileSize;
-  final Point<double> currentPixelOrigin;
 
   const Tile({
     super.key,
-    required this.scaledTileSize,
-    required this.currentPixelOrigin,
     required this.tileImage,
     required this.tileBuilder,
   });
@@ -42,27 +36,12 @@ class _TileState extends State<Tile> {
 
   @override
   Widget build(BuildContext context) {
-    return Positioned(
-      left: widget.tileImage.coordinates.x * widget.scaledTileSize -
-          widget.currentPixelOrigin.x,
-      top: widget.tileImage.coordinates.y * widget.scaledTileSize -
-          widget.currentPixelOrigin.y,
-      width: widget.scaledTileSize,
-      height: widget.scaledTileSize,
-      child: widget.tileBuilder?.call(context, _tileImage, widget.tileImage) ??
-          _tileImage,
-    );
+    return widget.tileBuilder?.call(context, _tileImage, widget.tileImage) ??
+        _tileImage;
   }
 
   Widget get _tileImage {
-    if (widget.tileImage.loadError && widget.tileImage.errorImage != null) {
-      return Image(
-        image: widget.tileImage.errorImage!,
-        opacity: widget.tileImage.opacity == 1
-            ? null
-            : AlwaysStoppedAnimation(widget.tileImage.opacity),
-      );
-    } else if (widget.tileImage.animation == null) {
+    if (widget.tileImage.animation == null) {
       return RawImage(
         image: widget.tileImage.imageInfo?.image,
         fit: BoxFit.fill,

lib/src/layer/tile_layer/tile_display.dart

@@ -45,14 +45,14 @@ sealed class TileDisplay {
   }) = FadeInTileDisplay._;
 
   /// Output a value of type [T] dependent on [this] and its type
-  T? when<T>({
-    T? Function(InstantaneousTileDisplay instantaneous)? instantaneous,
-    T? Function(FadeInTileDisplay fadeIn)? fadeIn,
+  T when<T>({
+    required T Function(InstantaneousTileDisplay instantaneous) instantaneous,
+    required T Function(FadeInTileDisplay fadeIn) fadeIn,
   }) {
     final display = this;
     return switch (display) {
-      InstantaneousTileDisplay() => instantaneous?.call(display),
-      FadeInTileDisplay() => fadeIn?.call(display),
+      InstantaneousTileDisplay() => instantaneous(display),
+      FadeInTileDisplay() => fadeIn(display),
     };
   }
 }