Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jonaswanke/debug_overlay
🐛 View debug infos and change settings via a central overlay for your app.
https://github.com/jonaswanke/debug_overlay
dart debugging debugging-tool flutter hacktoberfest package utility widgets
Last synced: 3 months ago
JSON representation
🐛 View debug infos and change settings via a central overlay for your app.
- Host: GitHub
- URL: https://github.com/jonaswanke/debug_overlay
- Owner: JonasWanke
- License: mit
- Created: 2021-03-24T09:05:23.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-10-15T07:21:46.000Z (3 months ago)
- Last Synced: 2024-10-25T00:48:54.288Z (3 months ago)
- Topics: dart, debugging, debugging-tool, flutter, hacktoberfest, package, utility, widgets
- Language: Dart
- Homepage: https://pub.dev/packages/debug_overlay
- Size: 32.7 MB
- Stars: 20
- Watchers: 3
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# debug_overlay
🐛 View debug infos and change settings via a central overlay for your app.
To add a debug overlay to your app, pass `DebugOverlay.builder()` to `MaterialApp`/`CupertinoApp`/`WidgetsApp.builder`:
```dart
MaterialApp(
builder: DebugOverlay.builder(),
// And other customization...
)
```
> The debug overlay only works in debug mode and is not included in your widget tree in profile or release mode unless you pass `enableOnlyInDebugMode: false`.
There are two ways to open the debug overlay:
- Shake your phone!
(You can disable the shake detection by passing `showOnShake: false` to `DebugOverlay.builder`.)
- Call `DebugOverlay.show()`.
By default, this overlay includes `MediaQueryDebugHelper`, `PackageInfoDebugHelper`, and `DeviceInfoDebugHelper`.
## Debug Helpers
To add a debug helper, you have to register it by calling either of the following two (which accept any widget):
- `DebugOverlay.prependHelper(myDebugHelper)` to add it to the front of the list
- `DebugOverlay.appendHelper(myDebugHelper)` to add it to the end of the list
Or, if you want to override all currently registered overlays, set `DebugOverlay.helpers.value` to a list of widgets.
### `DeviceInfoDebugHelper`
Displays information obtained from [device_info_plus](https://pub.dev/packages/device_info_plus).
### `MediaQueryDebugHelper`
Displays information obtained from [`MediaQuery`](https://api.flutter.dev/flutter/widgets/MediaQuery-class.html).
### `LogsDebugHelper`
Displays logs generated by your app. To use it, follow these steps:
1. Store its mutable state, e.g., in a global variable:
```dart
final logs = LogCollection();
```
2. Register the helper and supply its state, e.g., in `main()`:
```dart
void main() {
if (kDebugMode) {
DebugOverlay.appendHelper(LogsDebugHelper(logs));
}
runApp(MyApp());
}
```
3. When you generate logs, add them to the collection.
Except for `message`, all parameters are optional:
```dart
logs.add(Log(
level: DiagnosticLevel.info,
timestamp: DateTime.now(),
message: 'My message',
error: myException,
stackTrace: myStackTrace,
));
```
The `error` field can also hold data for non-error logs.
If it stores JSON data (on an object with a `toJson()` method), the data can be inspected using [json_view](https://pub.dev/packages/json_view).
> By default, this only stores the last 50 logs. You can customize this via the `maximumSize` parameter of `LogCollection`.
>
> Logs are only stored in debug builds.
### `MediaOverridesDebugHelper`
This allows you to override the theme mode and locale of your app. To use it, follow these steps:
1. Store its mutable state, e.g., in a global variable:
```dart
final mediaOverrideState = ValueNotifier(MediaOverrideState());
```
2. Register the helper and supply its state, e.g., in `main()`:
```dart
void main() {
if (kDebugMode) {
DebugOverlay.prependHelper(MediaOverrideDebugHelper(
mediaOverrideState,
// To support overriding locales, this value must be set and should
// contain the same locales as passed to [MaterialApp.supportedLocales],
// [CupertinoApp.supportedLocales] or [WidgetsApp.supportedLocales].
supportedLocales: supportedLocales,
));
}
runApp(MyApp());
}
```
3. When building your `MaterialApp`/`CupertinoApp`/`WidgetsApp`, wrap it in a `ValueListenableBuilder` that uses the state from step 1:
```dart
ValueListenableBuilder(
valueListenable: mediaOverrideState,
builder: (context, overrideState, child) {
return MaterialApp(
// You can access overridden values via [overrideState]:
themeMode: overrideState.themeMode,
locale: overrideState.locale,
builder: DebugOverlay.builder(showOnShake: false),
supportedLocales: supportedLocales,
// And your other customizations...
);
},
);
```
### `PackageInfoDebugHelper`
Displays information obtained from [package_info_plus](https://pub.dev/packages/package_info_plus).
### Custom
To implement your own debug helper, you can use the provided `DebugHelper` class for the layout.
If your information can be represented with Flutter's [`DiagnosticsNode`](https://api.flutter.dev/flutter/foundation/DiagnosticsNode-class.html), you can use `DiagnosticsBasedDebugHelper` which automatically provides filtering.
This is also used internally by `DeviceInfoDebugHelper`, `MediaQueryDebugHelper`, and `PackageInfoDebugHelper`.