debug.dart 11.4 KB
Newer Older
1 2 3 4
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'dart:collection';
6
import 'dart:developer' show Timeline; // to disambiguate reference in dartdocs below
7

8
import 'basic.dart';
9
import 'framework.dart';
10
import 'media_query.dart';
11
import 'table.dart';
12

13 14 15
// Any changes to this file should be reflected in the debugAssertAllWidgetVarsUnset()
// function below.

16
/// Log the dirty widgets that are built each frame.
17 18 19 20
///
/// Combined with [debugPrintBuildScope] or [debugPrintBeginFrameBanner], this
/// allows you to distinguish builds triggered by the initial mounting of a
/// widget tree (e.g. in a call to [runApp]) from the regular builds triggered
21
/// by the pipeline.
22 23 24
///
/// Combined with [debugPrintScheduleBuildForStacks], this lets you watch a
/// widget's dirty/clean lifecycle.
25
///
26 27 28 29
/// To get similar information but showing it on the timeline available from the
/// Observatory rather than getting it in the console (where it can be
/// overwhelming), consider [debugProfileBuildsEnabled].
///
30
/// See also the discussion at [WidgetsBinding.drawFrame].
31 32
bool debugPrintRebuildDirtyWidgets = false;

33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
/// Signature for [debugOnRebuildDirtyWidget] implementations.
typedef RebuildDirtyWidgetCallback = void Function(Element e, bool builtOnce);

/// Callback invoked for every dirty widget built each frame.
///
/// This callback is only invoked in debug builds.
///
/// See also:
///
///  * [debugPrintRebuildDirtyWidgets], which does something similar but logs
///    to the console instead of invoking a callback.
///  * [debugOnProfilePaint], which does something similar for [RenderObject]
///    painting.
///  * [WidgetInspectorService], which uses the [debugOnRebuildDirtyWidget]
///    callback to generate aggregate profile statistics describing which widget
///    rebuilds occurred when the
///    `ext.flutter.inspector.trackRebuildDirtyWidgets` service extension is
///    enabled.
RebuildDirtyWidgetCallback debugOnRebuildDirtyWidget;

53 54 55 56 57 58 59 60
/// Log all calls to [BuildOwner.buildScope].
///
/// Combined with [debugPrintScheduleBuildForStacks], this allows you to track
/// when a [State.setState] call gets serviced.
///
/// Combined with [debugPrintRebuildDirtyWidgets] or
/// [debugPrintBeginFrameBanner], this allows you to distinguish builds
/// triggered by the initial mounting of a widget tree (e.g. in a call to
61 62 63
/// [runApp]) from the regular builds triggered by the pipeline.
///
/// See also the discussion at [WidgetsBinding.drawFrame].
64 65 66 67 68 69 70 71 72 73
bool debugPrintBuildScope = false;

/// Log the call stacks that mark widgets as needing to be rebuilt.
///
/// This is called whenever [BuildOwner.scheduleBuildFor] adds an element to the
/// dirty list. Typically this is as a result of [Element.markNeedsBuild] being
/// called, which itself is usually a result of [State.setState] being called.
///
/// To see when a widget is rebuilt, see [debugPrintRebuildDirtyWidgets].
///
74
/// To see when the dirty list is flushed, see [debugPrintBuildScope].
75 76
///
/// To see when a frame is scheduled, see [debugPrintScheduleFrameStacks].
77 78
bool debugPrintScheduleBuildForStacks = false;

79 80 81 82 83 84
/// Log when widgets with global keys are deactivated and log when they are
/// reactivated (retaken).
///
/// This can help track down framework bugs relating to the [GlobalKey] logic.
bool debugPrintGlobalKeyedWidgetLifecycle = false;

85 86 87
/// Adds [Timeline] events for every Widget built.
///
/// For details on how to use [Timeline] events in the Dart Observatory to
88
/// optimize your app, see https://flutter.dev/docs/testing/debugging#tracing-any-dart-code-performance
89
/// and https://fuchsia.googlesource.com/topaz/+/master/shell/docs/performance.md
90 91 92 93
///
/// See also [debugProfilePaintsEnabled], which does something similar but for
/// painting, and [debugPrintRebuildDirtyWidgets], which does something similar
/// but reporting the builds to the console.
94 95
bool debugProfileBuildsEnabled = false;

96 97 98
/// Show banners for deprecated widgets.
bool debugHighlightDeprecatedWidgets = false;

99
Key _firstNonUniqueKey(Iterable<Widget> widgets) {
100
  final Set<Key> keySet = HashSet<Key>();
101 102 103 104 105 106 107 108 109 110
  for (Widget widget in widgets) {
    assert(widget != null);
    if (widget.key == null)
      continue;
    if (!keySet.add(widget.key))
      return widget.key;
  }
  return null;
}

111 112 113 114 115 116 117 118 119 120 121 122 123 124
/// Asserts if the given child list contains any duplicate non-null keys.
///
/// To invoke this function, use the following pattern, typically in the
/// relevant Widget's constructor:
///
/// ```dart
/// assert(!debugChildrenHaveDuplicateKeys(this, children));
/// ```
///
/// For a version of this function that can be used in contexts where
/// the list of items does not have a particular parent, see
/// [debugItemsHaveDuplicateKeys].
///
/// Does nothing if asserts are disabled. Always returns true.
125
bool debugChildrenHaveDuplicateKeys(Widget parent, Iterable<Widget> children) {
126
  assert(() {
127 128
    final Key nonUniqueKey = _firstNonUniqueKey(children);
    if (nonUniqueKey != null) {
129
      throw FlutterError(
130 131 132 133
        'Duplicate keys found.\n'
        'If multiple keyed nodes exist as children of another node, they must have unique keys.\n'
        '$parent has multiple children with key $nonUniqueKey.'
      );
134 135
    }
    return true;
136
  }());
137 138
  return false;
}
139

140 141 142 143 144 145 146 147 148 149 150 151
/// Asserts if the given list of items contains any duplicate non-null keys.
///
/// To invoke this function, use the following pattern:
///
/// ```dart
/// assert(!debugItemsHaveDuplicateKeys(items));
/// ```
///
/// For a version of this function specifically intended for parents
/// checking their children lists, see [debugChildrenHaveDuplicateKeys].
///
/// Does nothing if asserts are disabled. Always returns true.
152 153 154 155
bool debugItemsHaveDuplicateKeys(Iterable<Widget> items) {
  assert(() {
    final Key nonUniqueKey = _firstNonUniqueKey(items);
    if (nonUniqueKey != null)
156
      throw FlutterError('Duplicate key found: $nonUniqueKey.');
157
    return true;
158
  }());
159 160
  return false;
}
161 162 163

/// Asserts that the given context has a [Table] ancestor.
///
164
/// Used by [TableRowInkWell] to make sure that it is only used in an appropriate context.
165 166
///
/// To invoke this function, use the following pattern, typically in the
167
/// relevant Widget's build method:
168 169 170 171 172 173 174 175 176
///
/// ```dart
/// assert(debugCheckHasTable(context));
/// ```
///
/// Does nothing if asserts are disabled. Always returns true.
bool debugCheckHasTable(BuildContext context) {
  assert(() {
    if (context.widget is! Table && context.ancestorWidgetOfExactType(Table) == null) {
177
      final Element element = context;
178
      throw FlutterError(
179 180 181 182 183 184 185 186 187
        'No Table widget found.\n'
        '${context.widget.runtimeType} widgets require a Table widget ancestor.\n'
        'The specific widget that could not find a Table ancestor was:\n'
        '  ${context.widget}\n'
        'The ownership chain for the affected widget is:\n'
        '  ${element.debugGetCreatorChain(10)}'
      );
    }
    return true;
188
  }());
189 190
  return true;
}
191

192 193 194 195 196 197
/// Asserts that the given context has a [MediaQuery] ancestor.
///
/// Used by various widgets to make sure that they are only used in an
/// appropriate context.
///
/// To invoke this function, use the following pattern, typically in the
198
/// relevant Widget's build method:
199 200 201 202 203 204 205 206 207 208
///
/// ```dart
/// assert(debugCheckHasMediaQuery(context));
/// ```
///
/// Does nothing if asserts are disabled. Always returns true.
bool debugCheckHasMediaQuery(BuildContext context) {
  assert(() {
    if (context.widget is! MediaQuery && context.ancestorWidgetOfExactType(MediaQuery) == null) {
      final Element element = context;
209
      throw FlutterError(
210 211 212 213 214 215 216 217 218 219 220
        'No MediaQuery widget found.\n'
        '${context.widget.runtimeType} widgets require a MediaQuery widget ancestor.\n'
        'The specific widget that could not find a MediaQuery ancestor was:\n'
        '  ${context.widget}\n'
        'The ownership chain for the affected widget is:\n'
        '  ${element.debugGetCreatorChain(10)}\n'
        'Typically, the MediaQuery widget is introduced by the MaterialApp or '
        'WidgetsApp widget at the top of your application widget tree.'
      );
    }
    return true;
221
  }());
222 223 224
  return true;
}

225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241
/// Asserts that the given context has a [Directionality] ancestor.
///
/// Used by various widgets to make sure that they are only used in an
/// appropriate context.
///
/// To invoke this function, use the following pattern, typically in the
/// relevant Widget's build method:
///
/// ```dart
/// assert(debugCheckHasDirectionality(context));
/// ```
///
/// Does nothing if asserts are disabled. Always returns true.
bool debugCheckHasDirectionality(BuildContext context) {
  assert(() {
    if (context.widget is! Directionality && context.ancestorWidgetOfExactType(Directionality) == null) {
      final Element element = context;
242
      throw FlutterError(
243 244 245 246 247 248 249 250 251 252 253
        'No Directionality widget found.\n'
        '${context.widget.runtimeType} widgets require a Directionality widget ancestor.\n'
        'The specific widget that could not find a Directionality ancestor was:\n'
        '  ${context.widget}\n'
        'The ownership chain for the affected widget is:\n'
        '  ${element.debugGetCreatorChain(10)}\n'
        'Typically, the Directionality widget is introduced by the MaterialApp '
        'or WidgetsApp widget at the top of your application widget tree. It '
        'determines the ambient reading direction and is used, for example, to '
        'determine how to lay out text, how to interpret "start" and "end" '
        'values, and to resolve EdgeInsetsDirectional, '
254
        'AlignmentDirectional, and other *Directional objects.'
255 256 257 258 259 260 261
      );
    }
    return true;
  }());
  return true;
}

262 263 264 265 266 267
/// Asserts that the `built` widget is not null.
///
/// Used when the given `widget` calls a builder function to check that the
/// function returned a non-null value, as typically required.
///
/// Does nothing when asserts are disabled.
268 269 270
void debugWidgetBuilderValue(Widget widget, Widget built) {
  assert(() {
    if (built == null) {
271
      throw FlutterError(
272 273 274 275 276 277 278
        'A build function returned null.\n'
        'The offending widget is: $widget\n'
        'Build functions must never return null. '
        'To return an empty space that causes the building widget to fill available room, return "new Container()". '
        'To return an empty space that takes as little room as possible, return "new Container(width: 0.0, height: 0.0)".'
      );
    }
279 280 281 282 283 284 285 286
    if (widget == built) {
      throw FlutterError(
        'A build function returned context.widget.\n'
        'The offending widget is: $widget\n'
        'Build functions must never return their BuildContext parameter\'s widget or a child that contains "context.widget". '
        'Doing so introduces a loop in the widget tree that can cause the app to crash.'
      );
    }
287
    return true;
288
  }());
289
}
290 291 292 293 294 295

/// Returns true if none of the widget library debug variables have been changed.
///
/// This function is used by the test framework to ensure that debug variables
/// haven't been inadvertently changed.
///
296
/// See [the widgets library](widgets/widgets-library.html) for a complete list.
297 298 299 300 301 302
bool debugAssertAllWidgetVarsUnset(String reason) {
  assert(() {
    if (debugPrintRebuildDirtyWidgets ||
        debugPrintBuildScope ||
        debugPrintScheduleBuildForStacks ||
        debugPrintGlobalKeyedWidgetLifecycle ||
303 304
        debugProfileBuildsEnabled ||
        debugHighlightDeprecatedWidgets) {
305
      throw FlutterError(reason);
306 307
    }
    return true;
308
  }());
309 310
  return true;
}