The debug panel
The debug panel is a panel over the running app for whoever builds it. Each tab shows one side of the application: the logs, the frame meter, the configuration with the source of every value, the beans, the themes and the stages of the start. It opens with the action debug.open: ⌘⇧D (Ctrl+Shift+D elsewhere), or four quick taps and a fifth held three seconds, on every platform, phones included.
Why
On a phone or in a browser there is no console at hand, and the question is often "which value did this build get?" or "which profile is active?". The panel answers on the device itself, from the running context. And it costs nothing in what users run: by default the build leaves its code out of release builds.
Example
Nothing to write in a debug build: the panel is there, and ⌘⇧D opens it. To change how it opens, or to have it in every build:
# lib/resources/application.yml
spring:
flutter:
debug:
enabled: true # true: every build; false: none; not set: debug and profile builds
shortcuts:
debug.open: [primary+shift+d, taps:5+hold:2s]
The modules
The panel and each of its tools are separate modules of the build, each with its own property, so a release build can have one and not the others:
| Module | Property | Bean | Action and keys |
|---|---|---|---|
The panel (springBootStarterFlutterDebugAutoConfiguration) |
spring.flutter.debug.enabled |
debugPanel |
debug.open: ⌘⇧D (Ctrl+Shift+D), or taps:4+hold:3s |
The frame meter (springBootStarterFlutterDebugFrameMeterAutoConfiguration) |
spring.flutter.debug.frame-meter.enabled |
debugFrameMeter |
debug.frame-meter: ⌘⇧X (Ctrl+Shift+X), or taps:5+hold:2s (five quick taps and a sixth held two seconds) |
The motion switch (springBootStarterFlutterDebugMotionAutoConfiguration) |
spring.flutter.debug.motion.enabled |
debugMotion |
debug.motion: ⌘⇧M (Ctrl+Shift+M) |
The timeline (springBootStarterFlutterDebugTimelineAutoConfiguration) |
spring.flutter.debug.timeline.enabled |
debugTimeline |
debug.timeline: ⌘⇧L (Ctrl+Shift+L), or taps:6+hold:2s |
Dragging the overlays (springBootStarterFlutterDebugDragAutoConfiguration) |
spring.flutter.debug.drag.enabled (not set: never) |
debugOverlayDrag |
none: drag an overlay |
The keys of the tools are set like the panel's: spring.flutter.shortcuts.debug.frame-meter, spring.flutter.shortcuts.debug.motion, spring.flutter.shortcuts.debug.timeline.
The frame meter and the timeline show small widgets over the app; the dock of the debug overlays puts those of one corner together. While the panel is open they hide: their tabs show the same thing.
For example, a release build with only the frame meter and no panel:
spring:
flutter:
debug:
enabled: false
frame-meter:
enabled: true
motion:
enabled: false
frame-meter:
position: bottom-right
The frame meter then starts in the corner spring.flutter.frame-meter.position, and the action debug.frame-meter shows it or hides it.
When a module is in the app
Each of these properties (spring.flutter.debug.enabled, spring.flutter.debug.frame-meter.enabled, spring.flutter.debug.motion.enabled, spring.flutter.debug.timeline.enabled, spring.flutter.debug.drag.enabled) is read by the generator when it writes main.spring.dart, so it decides what code the app contains:
| Value | The module |
|---|---|
| not set (the default) | In debug and profile builds only. The module is written behind a release-mode condition, so a release build compiles it away |
true |
In every build, release included |
false |
In no build: the module is not written, and the app has none of its code |
Set to false in a profile file, each also turns off its feature in a running app whose build has it. See Modules left out of the build for how a module's build condition works.
The tabs
| Tab | What it shows |
|---|---|
| Logs | The records of the logging system's buffer (logBuffer), newest first and live, filtered by level and text |
| Frames | The frame meter on or off over the app, and its corner, without a new build. It uses the debugFrameMeter bean; when the build left the frame meter out, the tab says it is not in this build |
| Motion | Every animation of the app on, or off as the device's "reduce motion" turns it off (motion.enabled sets it for a build). It uses the debugMotion bean; when the build left the motion switch out, the tab says it is not in this build |
| Configuration | The active profiles and every property with the source that sets it. Values of keys that name a secret (password, secret, token, key, credential) show as ******, as Spring Boot's actuator does |
| Beans | Every bean of the context with its type |
| Theme | The themes the app's own files declare or choose (SpringThemes.ownNames; not the base themes a source file brings) and system; a tap shows one |
| Start | When each stage of the start was reached |
A tab of your own
A tab is a DebugPanelSection bean, in the order of the beans (@Order, Ordered):
// The basket's content, for whoever tests the checkout.
@Component()
@Order(100)
class BasketSection implements DebugPanelSection {
BasketSection(this.basket);
final Basket basket;
@override
String get title => 'Basket';
@override
Widget build(BuildContext context) => Text('${basket.count} books');
}
DebugStyle.of(context), DebugChip and DebugFilter give a tab the panel's look. A tab of your own lives in your code, so keep it out of release builds yourself, for example with @Profile(['debug', 'profile']).
The panel's state
debugPanel (a DebugPanel, a ChangeNotifier) is the panel's state:
| Member | Meaning |
|---|---|
isOpen |
Whether the panel shows |
toggle() |
Opens the panel, or closes it |
close() |
Closes it |
It is also the KeyedShortcutHandler of debug.open, with the default keys primary+shift+d and taps:4+hold:3s. The panel is installed over the app by a FlutterAppCustomizer (debugPanelCustomizer).
The other two modules have a state bean each:
| Bean | Member | Meaning |
|---|---|---|
debugFrameMeter (DebugFrameMeter) |
on |
Whether the frame meter shows over the app (the Frames tab and debug.frame-meter set it) |
position |
The corner of the frame meter | |
debugMotion (DebugMotion) |
animations |
Whether the animations of the app run (the Motion tab and debug.motion set it) |
Each is the KeyedShortcutHandler of its action.
The property
| Key | Type | Default | Meaning |
|---|---|---|---|
spring.flutter.debug.enabled |
true, false |
not set | Read by the generator. true: the panel is in every build. false: in none (no code). Not set: debug and profile builds only |
spring.flutter.debug.frame-meter.enabled |
true, false |
not set | Read by the generator. The same, for the frame meter module |
spring.flutter.debug.motion.enabled |
true, false |
not set | Read by the generator. The same, for the motion switch module |
spring.flutter.shortcuts.debug.open |
keys or taps | [primary+shift+d, taps:4+hold:3s] |
What opens the panel (see Keyboard shortcuts and taps) |
spring.flutter.shortcuts.debug.frame-meter |
keys or taps | [primary+shift+x, taps:5+hold:2s] |
What shows or hides the frame meter |
spring.flutter.shortcuts.debug.motion |
keys or taps | primary+shift+m |
What turns the animations on or off |
spring.flutter.frame-meter.position |
corner | top-right |
The corner the frame meter starts in |
In Spring (Java)
Spring Boot's actuator shows the same facts (/actuator/env, /actuator/beans, /actuator/loggers) over HTTP for a server. The panel shows them on the device, in the app itself.