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 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

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

See also