Skip to content

Commit b7e7a69

Browse files
feat: show a background grid while map tiles load (#2259)
Co-authored-by: JaffaKetchup <github@jaffaketchup.dev>
1 parent 8da9c1e commit b7e7a69

6 files changed

Lines changed: 271 additions & 10 deletions

File tree

‎example/lib/pages/tile_builder.dart‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,10 @@ class TileBuilderPageState extends State<TileBuilderPage> {
8181
onChanged: (v) => setState(() => enableGrid = v),
8282
),
8383
const SizedBox.square(dimension: 12),
84+
const Tooltip(
85+
message: 'Show Background Grid While Tiles Load',
86+
child: Icon(Icons.grid_on),
87+
),
8488
const Tooltip(
8589
message: 'Show Coordinates',
8690
child: Icon(Icons.location_on),
@@ -113,16 +117,19 @@ class TileBuilderPageState extends State<TileBuilderPage> {
113117
),
114118
Expanded(
115119
child: FlutterMap(
116-
options: const MapOptions(
117-
initialCenter: LatLng(51.5, -0.09),
120+
options: MapOptions(
121+
initialCenter: const LatLng(51.5, -0.09),
118122
initialZoom: 5,
123+
backgroundColor:
124+
darkMode ? Colors.grey[900]! : Colors.grey[200]!,
119125
),
120126
children: [
121127
_darkModeContainerIfEnabled(
122128
TileLayer(
123129
urlTemplate:
124130
'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
125-
userAgentPackageName: 'dev.fleaflet.flutter_map.example',
131+
userAgentPackageName: 'dev.fleaflet.flutter_map.demo',
132+
maxNativeZoom: 19,
126133
tileBuilder: tileBuilder,
127134
),
128135
),
@@ -148,7 +155,6 @@ class TileBuilderPageState extends State<TileBuilderPage> {
148155

149156
Widget _darkModeContainerIfEnabled(Widget child) {
150157
if (!darkMode) return child;
151-
152158
return darkModeTilesContainerBuilder(context, child);
153159
}
154160
}

‎lib/flutter_map.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ export 'package:flutter_map/src/layer/attribution_layer/v2/simple/simple_attribu
3131
export 'package:flutter_map/src/layer/circle_layer/circle_layer.dart';
3232
export 'package:flutter_map/src/layer/marker_layer/marker_layer.dart';
3333
export 'package:flutter_map/src/layer/overlay_image_layer/overlay_image_layer.dart';
34+
export 'package:flutter_map/src/layer/placeholder_grid_layer/placeholder_grid_layer.dart';
3435
export 'package:flutter_map/src/layer/polygon_layer/label/deprecated_placements.dart';
3536
export 'package:flutter_map/src/layer/polygon_layer/label/placement_calculators/placement_calculator.dart';
3637
export 'package:flutter_map/src/layer/polygon_layer/polygon_layer.dart';
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
part of 'placeholder_grid_layer.dart';
2+
3+
class _BackgroundGridPainter extends CustomPainter {
4+
const _BackgroundGridPainter({
5+
required this.color,
6+
required this.spacing,
7+
required this.pixelOrigin,
8+
required this.numOfMinors,
9+
required this.majorStrokeWidth,
10+
required this.minorStrokeWidth,
11+
});
12+
13+
final Color color;
14+
final double spacing;
15+
final Offset? pixelOrigin;
16+
final int numOfMinors;
17+
final double majorStrokeWidth;
18+
final double minorStrokeWidth;
19+
20+
@override
21+
void paint(Canvas canvas, Size size) {
22+
if (size.isEmpty || !spacing.isFinite || spacing < 1) return;
23+
24+
final paint = Paint()
25+
..color = color
26+
..strokeWidth = majorStrokeWidth
27+
..style = PaintingStyle.stroke
28+
..isAntiAlias = false;
29+
final path = Path();
30+
31+
double x = -(pixelOrigin == null ? size.width : pixelOrigin!.dx % spacing);
32+
for (; x < size.width; x += spacing) {
33+
path
34+
..moveTo(x, 0)
35+
..lineTo(x, size.height);
36+
}
37+
double y = -(pixelOrigin == null ? size.height : pixelOrigin!.dy % spacing);
38+
for (; y < size.height; y += spacing) {
39+
path
40+
..moveTo(0, y)
41+
..lineTo(size.width, y);
42+
}
43+
44+
canvas.drawPath(path, paint);
45+
46+
if (numOfMinors == 0) return;
47+
48+
path.reset();
49+
50+
final minorSpacing = spacing / (numOfMinors + 1);
51+
52+
x = -(pixelOrigin == null ? size.width : pixelOrigin!.dx % minorSpacing);
53+
for (; x < size.width; x += minorSpacing) {
54+
path
55+
..moveTo(x, 0)
56+
..lineTo(x, size.height);
57+
}
58+
y = -(pixelOrigin == null ? size.height : pixelOrigin!.dy % minorSpacing);
59+
for (; y < size.height; y += minorSpacing) {
60+
path
61+
..moveTo(0, y)
62+
..lineTo(size.width, y);
63+
}
64+
65+
canvas.drawPath(path, paint..strokeWidth = minorStrokeWidth);
66+
}
67+
68+
@override
69+
bool shouldRepaint(_BackgroundGridPainter oldDelegate) =>
70+
color != oldDelegate.color ||
71+
spacing != oldDelegate.spacing ||
72+
pixelOrigin != oldDelegate.pixelOrigin ||
73+
numOfMinors != oldDelegate.numOfMinors ||
74+
majorStrokeWidth != oldDelegate.majorStrokeWidth ||
75+
minorStrokeWidth != oldDelegate.majorStrokeWidth;
76+
}
Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
import 'package:flutter/widgets.dart';
2+
import 'package:flutter_map/flutter_map.dart';
3+
4+
part 'painter.dart';
5+
6+
/// Layer which draws a grid consisting of orthogonal major and minor strokes,
7+
/// configured by a [PlaceholderGridOptions].
8+
///
9+
/// This layer is usually drawn by default on the map background, but can be
10+
/// inserted manually. See [MapOptions.backgroundGridOptions] for info.
11+
///
12+
/// This layer is intended for use in a [FlutterMap]. However, it will work
13+
/// without being placed in one.
14+
class PlaceholderGridLayer extends StatelessWidget {
15+
/// Build a widget which draws a grid consisting of orthogonal major and minor
16+
/// strokes, configured by a [PlaceholderGridOptions].
17+
///
18+
/// The widget does not have to be used within a map context.
19+
const PlaceholderGridLayer({
20+
super.key,
21+
this.gridOptions = const PlaceholderGridOptions(),
22+
});
23+
24+
/// Configuration of the grid drawn.
25+
final PlaceholderGridOptions gridOptions;
26+
27+
@override
28+
Widget build(BuildContext context) {
29+
final camera = MapCamera.maybeOf(context);
30+
31+
late final autoGridColor = () {
32+
const delta = 0.15;
33+
34+
if (MapOptions.maybeOf(context)?.backgroundColor case final color?) {
35+
final hsl = HSLColor.fromColor(color);
36+
return hsl
37+
.withLightness(
38+
((hsl.lightness > 0.5 ? -delta : delta) + hsl.lightness)
39+
.clamp(0, 1),
40+
)
41+
.toColor();
42+
}
43+
}();
44+
final static = gridOptions.static || camera == null;
45+
final spacing = gridOptions.spacing *
46+
(static
47+
? 1
48+
: camera.getZoomScale(camera.zoom, camera.zoom.floorToDouble()));
49+
50+
final painted = CustomPaint(
51+
painter: _BackgroundGridPainter(
52+
color: gridOptions.color ?? autoGridColor ?? const Color(0x14000000),
53+
spacing: spacing,
54+
pixelOrigin: static ? null : camera.pixelOrigin,
55+
numOfMinors: gridOptions.numOfMinors,
56+
majorStrokeWidth: gridOptions.majorStrokeWidth,
57+
minorStrokeWidth: gridOptions.minorStrokeWidth,
58+
),
59+
);
60+
if (static) return painted;
61+
return MobileLayerTransformer(child: painted);
62+
}
63+
}
64+
65+
/// Configuration options for a [PlaceholderGridLayer], which is usually
66+
/// displayed on the map background.
67+
///
68+
/// The grid consists of orthogonal major and minor strokes.
69+
@immutable
70+
class PlaceholderGridOptions {
71+
/// Color of the grid strokes.
72+
///
73+
/// Defaults to a slightly ligher or darker shade of the
74+
/// [MapOptions.backgroundColor], based on if it's dark or light respectively.
75+
///
76+
/// If no inherited [MapOptions] is available, the default color is a
77+
/// translucent black.
78+
final Color? color;
79+
80+
/// Gap between major strokes (at integer zoom levels when [static] is
81+
/// `false`), in logical pixels.
82+
///
83+
/// To ensure a grid is visible while tiles are loading in holes, it's
84+
/// recommended to set this to a smaller value than the tile size.
85+
///
86+
/// Defaults to 64.
87+
final double spacing;
88+
89+
/// Whether the grid should be static and not move or zoom with the map,
90+
/// instead of its default behaviour of moving and scaling with zoom levels.
91+
///
92+
/// If no inherited [MapCamera] is available, the grid is always static.
93+
final bool static;
94+
95+
/// Thickness of major strokes.
96+
///
97+
/// Defaults to 1.5.
98+
final double majorStrokeWidth;
99+
100+
/// Thickness of minor strokes.
101+
///
102+
/// Defaults to 0 (a hairline stroke).
103+
final double minorStrokeWidth;
104+
105+
/// Number of minor strokes to insert between major strokes.
106+
///
107+
/// Defaults to 3. Set to 0 to disable minor strokes.
108+
final int numOfMinors;
109+
110+
/// Configuration options for a grid, usually displayed on the map background.
111+
const PlaceholderGridOptions({
112+
this.color,
113+
this.spacing = 64,
114+
this.static = false,
115+
this.majorStrokeWidth = 1.5,
116+
this.minorStrokeWidth = 0,
117+
this.numOfMinors = 3,
118+
}) : assert(
119+
spacing >= 1 && spacing < double.infinity,
120+
'`spacing` must be equal to or greater than one, and finite',
121+
),
122+
assert(
123+
majorStrokeWidth >= 0,
124+
'`majorStrokeWidth` must be equal to or greater than zero',
125+
),
126+
assert(
127+
minorStrokeWidth >= 0,
128+
'`minorStrokeWidth` must be equal to or greater than zero',
129+
),
130+
assert(
131+
numOfMinors >= 0,
132+
'`numOfMinors` must be equal to or greater than zero',
133+
);
134+
135+
@override
136+
int get hashCode => Object.hash(
137+
color,
138+
spacing,
139+
static,
140+
majorStrokeWidth,
141+
minorStrokeWidth,
142+
numOfMinors,
143+
);
144+
145+
@override
146+
bool operator ==(Object other) =>
147+
identical(this, other) ||
148+
other is PlaceholderGridOptions &&
149+
color == other.color &&
150+
spacing == other.spacing &&
151+
static == other.static &&
152+
majorStrokeWidth == other.majorStrokeWidth &&
153+
minorStrokeWidth == other.minorStrokeWidth &&
154+
numOfMinors == other.numOfMinors;
155+
}

‎lib/src/map/options/options.dart‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -80,10 +80,27 @@ class MapOptions {
8080
/// additional zoom level restrictions.
8181
final double? maxZoom;
8282

83-
/// The background color of the [FlutterMap] widget, defaults to a
84-
/// yellow grey-ish color.
83+
/// Background color of the [FlutterMap] widget.
84+
///
85+
/// It is usually recommended to set this to the background color of the app/
86+
/// screen, such as the scaffold background color held within the inherited
87+
/// theme, or at least a dark color if the app and map run in dark mode.
88+
///
89+
/// Defaults to a light yellow-gray-ish color.
8590
final Color backgroundColor;
8691

92+
/// Configuration of an optional grid to display on the map background.
93+
///
94+
/// By default, a grid is drawn on top of the [backgroundColor] with a stroke
95+
/// color which will automatically work on most backgrounds.
96+
///
97+
/// Set to `null` to disable the grid. The grid is automatically disabled if
98+
/// the [backgroundColor] is fully transparent.
99+
///
100+
/// A grid can be inserted anywhere within the map stack (or outside of the
101+
/// map context) using a [PlaceholderGridLayer] manually.
102+
final PlaceholderGridOptions? backgroundGridOptions;
103+
87104
/// Callback that fires when the map gets tapped or clicked with the
88105
/// primary mouse button. This is normally the left mouse button. This
89106
/// callback does not fire if the gesture is recognized as a double click.
@@ -167,6 +184,7 @@ class MapOptions {
167184
this.minZoom,
168185
this.maxZoom,
169186
this.backgroundColor = const Color(0xFFE0E0E0),
187+
this.backgroundGridOptions = const PlaceholderGridOptions(),
170188
this.onTap,
171189
this.onSecondaryTap,
172190
this.onLongPress,
@@ -204,6 +222,7 @@ class MapOptions {
204222
minZoom == other.minZoom &&
205223
maxZoom == other.maxZoom &&
206224
backgroundColor == other.backgroundColor &&
225+
backgroundGridOptions == other.backgroundGridOptions &&
207226
onTap == other.onTap &&
208227
onSecondaryTap == other.onSecondaryTap &&
209228
onLongPress == other.onLongPress &&
@@ -228,6 +247,7 @@ class MapOptions {
228247
minZoom,
229248
maxZoom,
230249
backgroundColor,
250+
backgroundGridOptions,
231251
onTap,
232252
onSecondaryTap,
233253
onLongPress,

‎lib/src/map/widget.dart‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -81,12 +81,15 @@ class _FlutterMapStateContainer extends State<FlutterMap>
8181
Widget build(BuildContext context) {
8282
super.build(context);
8383

84+
final backgroundColor = widget.options.backgroundColor;
85+
8486
final widgets = ClipRect(
8587
child: Stack(
86-
children: <Widget>[
87-
Positioned.fill(
88-
child: ColoredBox(color: widget.options.backgroundColor),
89-
),
88+
children: [
89+
Positioned.fill(child: ColoredBox(color: backgroundColor)),
90+
if (widget.options.backgroundGridOptions case final options?
91+
when backgroundColor.a != 0)
92+
Positioned.fill(child: PlaceholderGridLayer(gridOptions: options)),
9093
...widget.children,
9194
],
9295
),

0 commit comments

Comments
 (0)