1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5import 'dart:ui' as ui show Brightness;
6
7import 'assertions.dart';
8import 'platform.dart';
9import 'print.dart';
10
11export 'dart:ui' show Brightness;
12
13export 'print.dart' show DebugPrintCallback;
14
15/// Returns true if none of the foundation library debug variables have been
16/// changed.
17///
18/// This function is used by the test framework to ensure that debug variables
19/// haven't been inadvertently changed.
20///
21/// The `debugPrintOverride` argument can be specified to indicate the expected
22/// value of the [debugPrint] variable. This is useful for test frameworks that
23/// override [debugPrint] themselves and want to check that their own custom
24/// value wasn't overridden by a test.
25///
26/// See [the foundation library](foundation/foundation-library.html)
27/// for a complete list.
28bool debugAssertAllFoundationVarsUnset(String reason, { DebugPrintCallback debugPrintOverride = debugPrintThrottled }) {
29 assert(() {
30 if (debugPrint != debugPrintOverride ||
31 debugDefaultTargetPlatformOverride != null ||
32 debugDoublePrecision != null ||
33 debugBrightnessOverride != null) {
34 throw FlutterError(reason);
35 }
36 return true;
37 }());
38 return true;
39}
40
41/// Boolean value indicating whether [debugInstrumentAction] will instrument
42/// actions in debug builds.
43///
44/// The framework does not use [debugInstrumentAction] internally, so this
45/// does not enable any additional instrumentation for the framework itself.
46///
47/// See also:
48///
49/// * [debugProfileBuildsEnabled], which enables additional tracing of builds
50/// in [Widget]s.
51/// * [debugProfileLayoutsEnabled], which enables additional tracing of layout
52/// events in [RenderObject]s.
53/// * [debugProfilePaintsEnabled], which enables additional tracing of paint
54/// events in [RenderObject]s.
55bool debugInstrumentationEnabled = false;
56
57/// Runs the specified [action], timing how long the action takes in debug
58/// builds when [debugInstrumentationEnabled] is true.
59///
60/// The instrumentation will be printed to the logs using [debugPrint]. In
61/// non-debug builds, or when [debugInstrumentationEnabled] is false, this will
62/// run [action] without any instrumentation.
63///
64/// Returns the result of running [action].
65///
66/// See also:
67///
68/// * [Timeline], which is used to record synchronous tracing events for
69/// visualization in Chrome's tracing format. This method does not
70/// implicitly add any timeline events.
71Future<T> debugInstrumentAction<T>(String description, Future<T> Function() action) async {
72 bool instrument = false;
73 assert(() {
74 instrument = debugInstrumentationEnabled;
75 return true;
76 }());
77 if (instrument) {
78 final Stopwatch stopwatch = Stopwatch()..start();
79 try {
80 return await action();
81 } finally {
82 stopwatch.stop();
83 debugPrint('Action "$description" took ${stopwatch.elapsed}');
84 }
85 } else {
86 return action();
87 }
88}
89
90/// Configure [debugFormatDouble] using [num.toStringAsPrecision].
91///
92/// Defaults to null, which uses the default logic of [debugFormatDouble].
93int? debugDoublePrecision;
94
95/// Formats a double to have standard formatting.
96///
97/// This behavior can be overridden by [debugDoublePrecision].
98String debugFormatDouble(double? value) {
99 if (value == null) {
100 return 'null';
101 }
102 if (debugDoublePrecision != null) {
103 return value.toStringAsPrecision(debugDoublePrecision!);
104 }
105 return value.toStringAsFixed(1);
106}
107
108/// A setting that can be used to override the platform [Brightness] exposed
109/// from [BindingBase.platformDispatcher].
110///
111/// See also:
112///
113/// * [WidgetsApp], which uses the [debugBrightnessOverride] setting in debug mode
114/// to construct a [MediaQueryData].
115ui.Brightness? debugBrightnessOverride;
116
117/// The address for the active DevTools server used for debugging this
118/// application.
119String? activeDevToolsServerAddress;
120
121/// The uri for the connected vm service protocol.
122String? connectedVmServiceUri;
123