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 | |
5 | import 'dart:ui' as ui show Brightness; |
6 | |
7 | import 'assertions.dart'; |
8 | import 'platform.dart'; |
9 | import 'print.dart'; |
10 | |
11 | export 'dart:ui' show Brightness; |
12 | |
13 | export '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. |
28 | bool 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. |
55 | bool 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. |
71 | Future<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]. |
94 | int? debugDoublePrecision; |
95 | |
96 | /// Formats a double to have standard formatting. |
97 | /// |
98 | /// This behavior can be overridden by [debugDoublePrecision]. |
99 | String 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]. |
116 | ui.Brightness? debugBrightnessOverride; |
117 | |
118 | /// The address for the active DevTools server used for debugging this |
119 | /// application. |
120 | String? activeDevToolsServerAddress; |
121 | |
122 | /// The uri for the connected vm service protocol. |
123 | String? connectedVmServiceUri; |
124 | |