Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Various fixes to the debugging page. #132

Merged
merged 1 commit into from
Jan 11, 2016
Merged

Various fixes to the debugging page. #132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
4 changes: 2 additions & 2 deletions _sass/_base.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,13 +125,13 @@ blockquote {
/**
* Code formatting
*/
pre,
code {
pre {
font-size: 15px;
}

code {
font-family: 'Source Code Pro', monospace;
font-size: 1em;
}

pre {
Expand Down
70 changes: 37 additions & 33 deletions debugging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ The `debugger()` statement takes an optional `when` argument which you
can specify to only break when a certain condition is true, as in:

<!-- import 'dart:developer'; -->
<!-- skip -->
```dart
void someFunction(double offset) {
debugger(when: offset > 30.0);
Expand All @@ -62,7 +63,7 @@ you can view using `flutter logs` (which is basically a wrapper around

If you output too much at once, then Android sometimes discards some
log lines. To avoid this, you can use `debugPrint()`, from Flutter's
"services" library. This is a wrapper around `print` which throttles
`services` library. This is a wrapper around `print` which throttles
the output to a level that avoids being dropped by Android's kernel.

## Checked mode assertions
Expand All @@ -87,8 +88,8 @@ current state to the console (using `debugPrint`).

### Widget layer

To dump the state of the Widget library, call
`[debugDumpApp()](http://docs.flutter.io/flutter/widgets/debugDumpApp.html)`.
To dump the state of the Widgets library, call
[`debugDumpApp()`](http://docs.flutter.io/flutter/widgets/debugDumpApp.html).
You can call this more or less any time that the application is not in
the middle of running a build phase (i.e. anywhere not inside a
`build()` method), so long as the application has built at least once
Expand Down Expand Up @@ -184,16 +185,16 @@ This is the "flattened" tree, showing all the widgets projected
through their various build functions. You'll see a lot of widgets in
there that don't appear in your application's source, because they are
inserted by the framework's widgets' build functions. For example,
`[InkFeatures](http://docs.flutter.io/flutter/material/InkFeatures-class.html)`
[`InkFeatures`](http://docs.flutter.io/flutter/material/InkFeatures-class.html)
is an implementation detail of the
`[Material](http://docs.flutter.io/flutter/material/Material-class.html)`
[`Material`](http://docs.flutter.io/flutter/material/Material-class.html)
widget.

Since the `debugDumpApp()` call is invoked when the button changes
from being pressed to being released, it coincides with the
`[FlatButton](http://docs.flutter.io/flutter/material/FlatButton-class.html)`
[`FlatButton`](http://docs.flutter.io/flutter/material/FlatButton-class.html)
object calling
`[setState()](http://docs.flutter.io/flutter/widgets/State/setState.html)`
[`setState()`](http://docs.flutter.io/flutter/widgets/State/setState.html)
and thus marking itself dirty. That is why if you look at the dump you
will see that specific object marked "dirty". You can also see what
gesture listeners have been registered; in this case, a single
Expand All @@ -209,7 +210,7 @@ Add strings to the method's argument, and call the superclass method.
If you are trying to debug a layout issue, then the Widgets layer's
tree may be insufficiently detailed. In that case, you can dump the
rendering tree by calling
`[debugDumpRenderTree()](http://docs.flutter.io/flutter/rendering/debugDumpRenderTree.html)`.
[`debugDumpRenderTree()`](http://docs.flutter.io/flutter/rendering/debugDumpRenderTree.html).
As with `debugDumpApp()`, you can call this more or less any time
except during a layout or paint phase. As a general rule, calling it
from a [frame
Expand Down Expand Up @@ -369,29 +370,29 @@ sizes flow back up.

For example, in the dump above you can see that the window size,
`Size(411.4, 683.4)`, is used to force all the boxes down to the
`[RenderPositionedBox](http://docs.flutter.io/flutter/rendering/RenderPositionedBox-class.html)`
[`RenderPositionedBox`](http://docs.flutter.io/flutter/rendering/RenderPositionedBox-class.html)
to be the size of the screen, with constraints of
`BoxConstraints(w=411.4, h=683.4)`. The `RenderPositionedBox`, which
the dump says was created by a
`[Center](http://docs.flutter.io/flutter/widgets/Center-class.html)`
[`Center`](http://docs.flutter.io/flutter/widgets/Center-class.html)
widget (as described by the `owner` field), sets its childs
constraints to a loose version of this: `BoxConstraints(0.0<=w<=411.4,
0.0<=h<=683.4)`. The child, a
`[RenderPadding](http://docs.flutter.io/flutter/rendering/RenderPadding-class.html)`,
[`RenderPadding`](http://docs.flutter.io/flutter/rendering/RenderPadding-class.html),
further inserts these constraints to ensure there is room for the
padding, and thus the
`[RenderConstrainedBox](http://docs.flutter.io/flutter/rendering/RenderConstrainedBox-class.html)`
[`RenderConstrainedBox`](http://docs.flutter.io/flutter/rendering/RenderConstrainedBox-class.html)
has a loose constraint of `BoxConstraints(0.0<=w<=395.4,
0.0<=h<=667.4)`. This object, which the `owner` field tells us is
probably part of the
`[FlatButton](http://docs.flutter.io/flutter/material/FlatButton-class.html)`'s
[`FlatButton`](http://docs.flutter.io/flutter/material/FlatButton-class.html)'s
definition, sets a minimum width of 88 pixels on its contents and a
specific height of 36.0. (This is the `FlatButton` class implementing
the Material Design rules regarding button dimensions.)

The inner-most `RenderPositionedBox` loosens the constraints again,
this time to center the text within the button. The
`[RenderParagraph](http://docs.flutter.io/flutter/rendering/RenderParagraph-class.html)`
[`RenderParagraph`](http://docs.flutter.io/flutter/rendering/RenderParagraph-class.html)
picks its size based on its contents. If you now follow the sizes back
up the chain, you'll see how the text's size is what influences the
width of all the boxes that form the button, as they all take their
Expand All @@ -412,7 +413,7 @@ Add strings to the method's argument, and call the superclass method.
### Layers

If you are trying to debug a compositing issue, you can use
`[debugDumpLayerTree()](http://docs.flutter.io/flutter/rendering/debugDumpLayerTree.html)`.
[`debugDumpLayerTree()`](http://docs.flutter.io/flutter/rendering/debugDumpLayerTree.html).
For the example above, it would output:

```
Expand All @@ -437,8 +438,8 @@ android: I/flutter : paintBounds: Rect.fromLTRB(0.0, 0.0, 411.4, 683.4)
## Visual debugging

You can also debug a layout problem visually, by setting
`[debugPaintSizeEnabled](http://docs.flutter.io/flutter/rendering/debugPaintSizeEnabled.html)`
to `true`. This is a boolean from the rendering library. It can be
[`debugPaintSizeEnabled`](http://docs.flutter.io/flutter/rendering/debugPaintSizeEnabled.html)
to `true`. This is a boolean from the `rendering` library. It can be
enabled at any time and affects all painting while it is true. The
easiest way to set it is at the top of your `void main()` entry point.

Expand All @@ -449,13 +450,13 @@ is shown with yellow arrows, and spacers (from widgets like
`Container` when they have no child) are shown in gray.

The
`[debugPaintBaselinesEnabled](http://docs.flutter.io/flutter/rendering/debugPaintBaselinesEnabled.html)`
[`debugPaintBaselinesEnabled`](http://docs.flutter.io/flutter/rendering/debugPaintBaselinesEnabled.html)
does something similar but for objects with baselines. The alphabetic
baseline is shown in bright green and the ideographic baseline in
orange.

The
`[debugPaintPointersEnabled](http://docs.flutter.io/flutter/rendering/debugPaintPointersEnabled.html)`
[`debugPaintPointersEnabled`](http://docs.flutter.io/flutter/rendering/debugPaintPointersEnabled.html)
flag turns on a special mode whereby any objects that are being tapped
get highlighted in teal. This can help you determine whether an object
is somehow failing to correctly hit test (which might happen if, for
Expand All @@ -464,9 +465,9 @@ being considered for hit testing in the first place).

If you're trying to debug compositor layers, for example to determine
whether and where to add `RepaintBoundary` widgets, you can use the
`[debugPaintLayerBordersEnabled](http://docs.flutter.io/flutter/rendering/debugPaintLayerBordersEnabled.html)`
[`debugPaintLayerBordersEnabled`](http://docs.flutter.io/flutter/rendering/debugPaintLayerBordersEnabled.html)
flag, which outlines each layer's bounds in orange, or the
`[debugEnableRepaintRainbox](http://docs.flutter.io/flutter/rendering/debugEnableRepaintRainbox.html)`
[`debugEnableRepaintRainbox`](http://docs.flutter.io/flutter/rendering/debugEnableRepaintRainbox.html)
flag, which causes layers to be overlayed with a rotating set of
colors whenever they are repainted.

Expand All @@ -478,7 +479,7 @@ checked mode.

The easiest way to debug animations is to slow them way down. To do
that, set the
`[timeDilation](http://docs.flutter.io/flutter/scheduler/timeDilation.html)`
[`timeDilation`](http://docs.flutter.io/flutter/scheduler/timeDilation.html)
variable (from the `scheduler` library) to a number greater than 1.0,
for instance, 50.0. It's best to only set this once on app startup. If
you change it on the fly, especially if you reduce it while animations
Expand All @@ -490,22 +491,23 @@ interfere with your efforts.

To see why your application is causing relayouts or repaints, you can
set the
`[debugPrintMarkNeedsLayoutStacks](http://docs.flutter.io/flutter/rendering/debugPrintMarkNeedsLayoutStacks.html)`
[`debugPrintMarkNeedsLayoutStacks`](http://docs.flutter.io/flutter/rendering/debugPrintMarkNeedsLayoutStacks.html)
and
`[debugPrintMarkNeedsPaintStacks](http://docs.flutter.io/flutter/rendering/debugPrintMarkNeedsPaintStacks.html)`
[`debugPrintMarkNeedsPaintStacks`](http://docs.flutter.io/flutter/rendering/debugPrintMarkNeedsPaintStacks.html)
flags respectively. These will log a stack trace to the console any
time a render box is asked to relayout and repaint. You can use the
`debugPrintStack()` method from the `services` library to print your
own stack traces on demand, if this kind of approach is useful to you.

## StatisticsOverlay
## PerformanceOverlay

To get a graphical view of the performance of your application, set
the `showRenderingPerformanceOverlay` argument of the `MaterialApp`
constructor to true. (If you're not using `MaterialApp`, you can get
the same effect by wrapping your application in a stack and putting a
widget on your stack that was created by calling `new
StatisticsOverlay.allEnabled()`.)
the `showPerformanceOverlay` argument of the [`MaterialApp`
constructor](http://docs.flutter.io/flutter/material/MaterialApp/MaterialApp.html)
to true. (If you're not using `MaterialApp`, you can get the same
effect by wrapping your application in a stack and putting a widget on
your stack that was created by calling [`new
PerformanceOverlay.allEnabled()`](http://docs.flutter.io/flutter/widgets/PerformanceOverlay/PerformanceOverlay.allEnabled.html).)

This will show two graphs. The top one is the time spent by the GPU
thread, the bottom one is the time spent by the CPU thread. The white
Expand All @@ -527,10 +529,12 @@ design](https://www.google.com/design/spec/material-design/introduction.html),
it can be helpful to overlay a [Material design baseline
grid](https://www.google.com/design/spec/layout/metrics-keylines.html)
over the application to help verify alignments. To that end, the
`MaterialApp` constructor has a `debugShowGrid` argument which, when
set to `true` in checked mode, will overlay such a grid.
[`MaterialApp`
constructor](http://docs.flutter.io/flutter/material/MaterialApp/MaterialApp.html)
has a `debugShowGrid` argument which, when set to `true` in checked
mode, will overlay such a grid.

You can also overlay such a grid on non-Material applications by using
the
`[GridPaper](http://docs.flutter.io/flutter/widgets/GridPaper-class.html)`
[`GridPaper`](http://docs.flutter.io/flutter/widgets/GridPaper-class.html)
widget directly.