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(); // flutter_ignore: stopwatch (see analyze.dart)
79 // Ignore context: The framework does not use this function internally so it will not cause flakes.
80 try {
81 return await action();
82 } finally {
83 stopwatch.stop();
84 debugPrint('Action "$description" took ${stopwatch.elapsed}');
85 }
86 } else {
87 return action();
88 }
89}
90
91/// Configure [debugFormatDouble] using [num.toStringAsPrecision].
92///
93/// Defaults to null, which uses the default logic of [debugFormatDouble].
94int? debugDoublePrecision;
95
96/// Formats a double to have standard formatting.
97///
98/// This behavior can be overridden by [debugDoublePrecision].
99String debugFormatDouble(double? value) {
100 if (value == null) {
101 return 'null';
102 }
103 if (debugDoublePrecision != null) {
104 return value.toStringAsPrecision(debugDoublePrecision!);
105 }
106 return value.toStringAsFixed(1);
107}
108
109/// A setting that can be used to override the platform [Brightness] exposed
110/// from [BindingBase.platformDispatcher].
111///
112/// See also:
113///
114/// * [WidgetsApp], which uses the [debugBrightnessOverride] setting in debug mode
115/// to construct a [MediaQueryData].
116ui.Brightness? debugBrightnessOverride;
117
118/// The address for the active DevTools server used for debugging this
119/// application.
120String? activeDevToolsServerAddress;
121
122/// The uri for the connected vm service protocol.
123String? connectedVmServiceUri;
124