Debug overlays
Some debug features show a small widget over the app: the frame meter, the timeline. The debugDock puts them on screen. Each feature only says which corner and in what order; the dock makes sure they never cover each other.
Why
Two overlays in one corner would be drawn one on the other. A laptop has room to show them one under the other; a phone does not. The dock decides per corner, from the room the screen has, and changes its mind when the window is resized or the phone turned.
Example
spring:
flutter:
debug:
frame-meter:
enabled: true
timeline:
enabled: true
overlays:
layout: auto # auto | stack | pages
max-height: 0.4 # the room of a corner for auto
margin:
top: 64 # under the app's header
Both widgets are in the bottom left with spring.flutter.frame-meter.position: bottom-left: on a laptop one under the other, on a phone one at a time with dots.
The layout
layout |
What a corner shows |
|---|---|
auto (default) |
One under the other when they fit: their heights add up to at most max-height of the screen, and none is wider than half of it. Otherwise one at a time |
stack |
Always one under the other |
pages |
Always one at a time |
One at a time, dots show which; change the page with:
- a horizontal swipe (vertical is the app's scroll);
- a tap on a dot;
- a wheel turn or a trackpad swipe over the widget.
A top corner grows downwards and its dots are under the widget; a bottom corner grows upwards and its dots are above it. So the dots never go under the screen's edge. The order is each feature's (the frame meter first, then the timeline).
The dock keeps out of the screen's safe area (the notch, the clock) by itself; margin adds room past it, in logical pixels: top under a header, bottom above a tab bar.
While the debug panel is open, the overlays hide: each feature's section in the panel shows the same thing, and nothing covers the panel.
Dragging them
Moving an overlay is a debug feature of its own, in the build only when asked for:
spring:
flutter:
debug:
drag:
enabled: true # without it, there is no code to drag
overlays:
drag:
snap: corners # corners | free
remember: true
- With a mouse an overlay is dragged at once; the cursor shows it can be moved.
- On a touch screen it is dragged after a long press, so a tap and a swipe between pages stay what they were.
snap: corners(default): dropped, it joins the nearest corner, with that corner's stack or pages.snap: free: it stays where it was dropped, kept on screen.remember: the place is kept for the next start, where the theme chosen is kept (the browser's storage on the web, a file on a device). The corner of the configuration is the place until the overlay is moved.
Each overlay moves on its own: the frame meter can leave the timeline's corner. The panel's overlays section puts them all back.
An overlay of your own
A debug feature of your own shows in the dock when its bean implements DebugOverlay:
final class QueueOverlay extends ChangeNotifier implements DebugOverlay {
@override
String get id => 'queue';
@override
String get title => 'Queue';
@override
DebugOverlayCorner get corner => DebugOverlayCorner.topLeft;
@override
int get order => 20;
@override
Size get size => const Size(160, 40);
bool _shown = false;
@override
bool get shown => _shown;
@override
set shown(bool value) {
_shown = value;
notifyListeners();
}
@override
Widget build(BuildContext context) => const QueueGauge();
}
size is about how much room it takes: what auto adds up. The dock is in the app when a feature that has an overlay is; a feature of your own declares the debugDock bean the same way, or depends on one that does.
The properties
| Key | Type | Default | Meaning |
|---|---|---|---|
spring.flutter.debug.overlays.layout |
auto, stack, pages |
auto |
How the overlays of a corner are put together |
spring.flutter.debug.overlays.max-height |
fraction | 0.4 |
The room of a corner for auto |
spring.flutter.debug.overlays.margin.top / bottom / left / right |
logical pixels | 0 |
Room past the safe area |
spring.flutter.debug.drag.enabled |
bool | not set: no code | Whether the app can drag its overlays (the build reads it) |
spring.flutter.debug.overlays.drag.snap |
corners, free |
corners |
Where a dropped overlay goes |
spring.flutter.debug.overlays.drag.remember |
bool | true |
Whether a moved overlay is where it was left after a restart |