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/// @docImport 'dart:developer';
6/// @docImport 'package:flutter/foundation.dart';
7/// @docImport 'package:flutter/rendering.dart';
8///
9/// @docImport 'app.dart';
10/// @docImport 'binding.dart';
11/// @docImport 'debug.dart';
12/// @docImport 'framework.dart';
13/// @docImport 'widget_inspector.dart';
14library;
15
16/// Service extension constants for the widgets library.
17///
18/// These constants will be used when registering service extensions in the
19/// framework, and they will also be used by tools and services that call these
20/// service extensions.
21///
22/// The String value for each of these extension names should be accessed by
23/// calling the `.name` property on the enum value.
24enum WidgetsServiceExtensions {
25 /// Name of service extension that, when called, will output a string
26 /// representation of this app's widget tree to console.
27 ///
28 /// See also:
29 ///
30 /// * [WidgetsBinding.initServiceExtensions], where the service extension is
31 /// registered.
32 debugDumpApp,
33
34 /// Name of service extension that, when called, will output a string
35 /// representation of the focus tree to the console.
36 ///
37 /// See also:
38 ///
39 /// * [WidgetsBinding.initServiceExtensions], where the service extension is
40 /// registered.
41 debugDumpFocusTree,
42
43 /// Name of service extension that, when called, will overlay a performance
44 /// graph on top of this app.
45 ///
46 /// See also:
47 ///
48 /// * [WidgetsApp.showPerformanceOverlayOverride], which is the flag
49 /// that this service extension exposes.
50 /// * [WidgetsBinding.initServiceExtensions], where the service extension is
51 /// registered.
52 showPerformanceOverlay,
53
54 /// Name of service extension that, when called, will return whether the first
55 /// 'Flutter.Frame' event has been reported on the Extension stream.
56 ///
57 /// See also:
58 ///
59 /// * [WidgetsBinding.initServiceExtensions], where the service extension is
60 /// registered.
61 didSendFirstFrameEvent,
62
63 /// Name of service extension that, when called, will return whether the first
64 /// frame has been rasterized and the trace event 'Rasterized first useful
65 /// frame' has been sent out.
66 ///
67 /// See also:
68 ///
69 /// * [WidgetsBinding.initServiceExtensions], where the service extension is
70 /// registered.
71 didSendFirstFrameRasterizedEvent,
72
73 /// Name of service extension that, when called, will reassemble the
74 /// application.
75 ///
76 /// See also:
77 ///
78 /// * [WidgetsBinding.initServiceExtensions], where the service extension is
79 /// registered.
80 fastReassemble,
81
82 /// Name of service extension that, when called, will change the value of
83 /// [debugProfileBuildsEnabled], which adds [Timeline] events for every widget
84 /// built.
85 ///
86 /// See also:
87 ///
88 /// * [debugProfileBuildsEnabled], which is the flag that this service extension
89 /// exposes.
90 /// * [WidgetsBinding.initServiceExtensions], where the service extension is
91 /// registered.
92 profileWidgetBuilds,
93
94 /// Name of service extension that, when called, will change the value of
95 /// [debugProfileBuildsEnabledUserWidgets], which adds [Timeline] events for
96 /// every user-created widget built.
97 ///
98 /// See also:
99 /// * [debugProfileBuildsEnabledUserWidgets], which is the flag that this
100 /// service extension exposes.
101 /// * [WidgetsBinding.initServiceExtensions], where the service extension is
102 /// registered.
103 profileUserWidgetBuilds,
104
105 /// Name of service extension that, when called, will change the value of
106 /// [WidgetsApp.debugAllowBannerOverride], which controls the visibility of the
107 /// debug banner for debug mode apps.
108 ///
109 /// See also:
110 ///
111 /// * [WidgetsApp.debugAllowBannerOverride], which is the flag that this service
112 /// extension exposes.
113 /// * [WidgetsBinding.initServiceExtensions], where the service extension is
114 /// registered.
115 debugAllowBanner,
116}
117
118/// Service extension constants for the Widget Inspector.
119///
120/// These constants will be used when registering service extensions in the
121/// framework, and they will also be used by tools and services that call these
122/// service extensions.
123///
124/// The String value for each of these extension names should be accessed by
125/// calling the `.name` property on the enum value.
126enum WidgetInspectorServiceExtensions {
127 /// Name of service extension that, when called, will determine whether
128 /// [FlutterError] messages will be presented using a structured format.
129 ///
130 /// See also:
131 ///
132 /// * [WidgetInspectorService.initServiceExtensions], where the service
133 /// extension is registered.
134 structuredErrors,
135
136 /// Name of service extension that, when called, will change the value of
137 /// [WidgetsBinding.debugShowWidgetInspectorOverride], which controls whether the
138 /// on-device widget inspector is visible.
139 ///
140 /// See also:
141 /// * [WidgetsBinding.debugShowWidgetInspectorOverride], which is the flag that
142 /// this service extension exposes.
143 /// * [WidgetInspectorService.initServiceExtensions], where the service
144 /// extension is registered.
145 show,
146
147 /// Name of service extension that, when called, determines
148 /// whether a callback is invoked for every dirty [Widget] built each frame.
149 ///
150 /// See also:
151 ///
152 /// * [debugOnRebuildDirtyWidget], which is the nullable callback that is
153 /// called for every dirty widget built per frame
154 /// * [WidgetInspectorService.initServiceExtensions], where the service
155 /// extension is registered.
156 trackRebuildDirtyWidgets,
157
158 /// Name of service extension that, when called, returns the mapping of
159 /// widget locations to ids.
160 ///
161 /// This service extension is only supported if
162 /// [WidgetInspectorService._widgetCreationTracked] is true.
163 ///
164 /// See also:
165 ///
166 /// * [trackRebuildDirtyWidgets], which toggles dispatching events that use
167 /// these ids to efficiently indicate the locations of widgets.
168 /// * [WidgetInspectorService.initServiceExtensions], where the service
169 /// extension is registered.
170 widgetLocationIdMap,
171
172 /// Name of service extension that, when called, determines whether
173 /// [WidgetInspectorService._trackRepaintWidgets], which determines whether
174 /// a callback is invoked for every [RenderObject] painted each frame.
175 ///
176 /// See also:
177 ///
178 /// * [debugOnProfilePaint], which is the nullable callback that is called for
179 /// every dirty widget built per frame
180 /// * [WidgetInspectorService.initServiceExtensions], where the service
181 /// extension is registered.
182 trackRepaintWidgets,
183
184 /// Name of service extension that, when called, will clear all
185 /// [WidgetInspectorService] object references in all groups.
186 ///
187 /// See also:
188 ///
189 /// * [WidgetInspectorService.disposeAllGroups], the method that this service
190 /// extension calls.
191 /// * [WidgetInspectorService.initServiceExtensions], where the service
192 /// extension is registered.
193 disposeAllGroups,
194
195 /// Name of service extension that, when called, will clear all
196 /// [WidgetInspectorService] object references in a group.
197 ///
198 /// See also:
199 ///
200 /// * [WidgetInspectorService.disposeGroup], the method that this service
201 /// extension calls.
202 /// * [WidgetInspectorService.initServiceExtensions], where the service
203 /// extension is registered.
204 disposeGroup,
205
206 /// Name of service extension that, when called, returns whether it is
207 /// appropriate to display the Widget tree in the inspector, which is only
208 /// true after the application has rendered its first frame.
209 ///
210 /// See also:
211 ///
212 /// * [WidgetInspectorService.isWidgetTreeReady], the method that this service
213 /// extension calls.
214 /// * [WidgetsBinding.debugDidSendFirstFrameEvent], which stores the
215 /// value of whether the first frame has been rendered.
216 /// * [WidgetInspectorService.initServiceExtensions], where the service
217 /// extension is registered.
218 isWidgetTreeReady,
219
220 /// Name of service extension that, when called, will remove the object with
221 /// the specified `id` from the specified object group.
222 ///
223 /// See also:
224 ///
225 /// * [WidgetInspectorService.disposeId], the method that this service
226 /// extension calls.
227 /// * [WidgetInspectorService.initServiceExtensions], where the service
228 /// extension is registered.
229 disposeId,
230
231 /// Name of service extension that, when called, will set the list of
232 /// directories that should be considered part of the local project for the
233 /// Widget inspector summary tree.
234 ///
235 /// See also:
236 ///
237 /// * [WidgetInspectorService.addPubRootDirectories], which should be used in
238 /// place of this method to add directories.
239 /// * [WidgetInspectorService.removePubRootDirectories], which should be used
240 /// in place of this method to remove directories.
241 /// * [WidgetInspectorService.initServiceExtensions], where the service
242 /// extension is registered.
243 @Deprecated(
244 'Use addPubRootDirectories instead. '
245 'This feature was deprecated after v3.18.0-2.0.pre.',
246 )
247 setPubRootDirectories,
248
249 /// Name of service extension that, when called, will add a list of
250 /// directories that should be considered part of the local project for the
251 /// Widget inspector summary tree.
252 ///
253 /// See also:
254 ///
255 /// * [WidgetInspectorService.addPubRootDirectories], the method that this
256 /// service extension calls.
257 /// * [WidgetInspectorService.removePubRootDirectories], which should be used
258 /// to remove directories.
259 /// * [WidgetInspectorService.pubRootDirectories], which should be used
260 /// to return the active list of directories.
261 /// * [WidgetInspectorService.initServiceExtensions], where the service
262 /// extension is registered.
263 addPubRootDirectories,
264
265 /// Name of service extension that, when called, will remove a list of
266 /// directories that should no longer be considered part of the local project
267 /// for the Widget inspector summary tree.
268 ///
269 /// See also:
270 ///
271 /// * [WidgetInspectorService.removePubRootDirectories], the method that this
272 /// service extension calls.
273 /// * [WidgetInspectorService.addPubRootDirectories], which should be used
274 /// to add directories.
275 /// * [WidgetInspectorService.pubRootDirectories], which should be used
276 /// to return the active list of directories.
277 /// * [WidgetInspectorService.initServiceExtensions], where the service
278 /// extension is registered.
279 removePubRootDirectories,
280
281 /// Name of service extension that, when called, will return the list of
282 /// directories that are considered part of the local project
283 /// for the Widget inspector summary tree.
284 ///
285 /// See also:
286 ///
287 /// * [WidgetInspectorService.pubRootDirectories], the method that this
288 /// service extension calls.
289 /// * [WidgetInspectorService.addPubRootDirectories], which should be used
290 /// to add directories.
291 /// * [WidgetInspectorService.removePubRootDirectories], which should be used
292 /// to remove directories.
293 /// * [WidgetInspectorService.initServiceExtensions], where the service
294 /// extension is registered.
295 getPubRootDirectories,
296
297 /// Name of service extension that, when called, will set the
298 /// [WidgetInspector] selection to the object matching the specified id and
299 /// will return whether the selection was changed.
300 ///
301 /// See also:
302 ///
303 /// * [WidgetInspectorService.setSelectionById], the method that this service
304 /// extension calls.
305 /// * [WidgetInspectorService.initServiceExtensions], where the service
306 /// extension is registered.
307 setSelectionById,
308
309 /// Name of service extension that, when called, will retrieve the chain of
310 /// [DiagnosticsNode] instances form the root of the tree to the [Element] or
311 /// [RenderObject] matching the specified id, passed as an argument.
312 ///
313 /// See also:
314 ///
315 /// * [WidgetInspectorService.getParentChain], which returns a json encoded
316 /// String representation of this data.
317 /// * [WidgetInspectorService.initServiceExtensions], where the service
318 /// extension is registered.
319 getParentChain,
320
321 /// Name of service extension that, when called, will return the properties
322 /// for the [DiagnosticsNode] object matching the specified id, passed as an
323 /// argument.
324 ///
325 /// See also:
326 ///
327 /// * [WidgetInspectorService.getProperties], which returns a json encoded
328 /// String representation of this data.
329 /// * [WidgetInspectorService.initServiceExtensions], where the service
330 /// extension is registered.
331 getProperties,
332
333 /// Name of service extension that, when called, will return the children
334 /// for the [DiagnosticsNode] object matching the specified id, passed as an
335 /// argument.
336 ///
337 /// See also:
338 ///
339 /// * [WidgetInspectorService.getChildren], which returns a json encoded
340 /// String representation of this data.
341 /// * [WidgetInspectorService.initServiceExtensions], where the service
342 /// extension is registered.
343 getChildren,
344
345 /// Name of service extension that, when called, will return the children
346 /// created by user code for the [DiagnosticsNode] object matching the
347 /// specified id, passed as an argument.
348 ///
349 /// See also:
350 ///
351 /// * [WidgetInspectorService.getChildrenSummaryTree], which returns a json
352 /// encoded String representation of this data.
353 /// * [WidgetInspectorService.initServiceExtensions], where the service
354 /// extension is registered.
355 getChildrenSummaryTree,
356
357 /// Name of service extension that, when called, will return all children and
358 /// their properties for the [DiagnosticsNode] object matching the specified
359 /// id, passed as an argument.
360 ///
361 /// See also:
362 ///
363 /// * [WidgetInspectorService.getChildrenDetailsSubtree], which returns a json
364 /// encoded String representation of this data.
365 /// * [WidgetInspectorService.initServiceExtensions], where the service
366 /// extension is registered.
367 getChildrenDetailsSubtree,
368
369 /// Name of service extension that, when called, will return the
370 /// [DiagnosticsNode] data for the root [Element].
371 ///
372 /// See also:
373 ///
374 /// * [WidgetInspectorService.getRootWidget], which returns a json encoded
375 /// String representation of this data.
376 /// * [WidgetInspectorService.initServiceExtensions], where the service
377 /// extension is registered.
378 getRootWidget,
379
380 /// Name of service extension that, when called, will return the
381 /// [DiagnosticsNode] data for the root [Element] of the widget tree.
382 ///
383 /// If the parameter `isSummaryTree` is true, the tree will only include
384 /// [Element]s that were created by user code.
385 ///
386 /// If the parameter `withPreviews` is true, text previews will be included
387 /// for [Element]s with a corresponding [RenderObject] of type
388 /// [RenderParagraph].
389 ///
390 /// See also:
391 ///
392 /// * [WidgetInspectorService.initServiceExtensions], where the service
393 /// extension is registered.
394 getRootWidgetTree,
395
396 /// Name of service extension that, when called, will return the
397 /// [DiagnosticsNode] data for the root [Element] of the summary tree, which
398 /// only includes [Element]s that were created by user code.
399 ///
400 /// See also:
401 ///
402 /// * [WidgetInspectorService.getRootWidgetSummaryTree], which returns a json
403 /// encoded String representation of this data.
404 /// * [WidgetInspectorService.initServiceExtensions], where the service
405 /// extension is registered.
406 getRootWidgetSummaryTree,
407
408 /// Name of service extension that, when called, will return the
409 /// [DiagnosticsNode] data for the root [Element] of the summary tree with
410 /// text previews included.
411 ///
412 /// The summary tree only includes [Element]s that were created by user code.
413 /// Text previews will only be available for [Element]s with a corresponding
414 /// [RenderObject] of type [RenderParagraph].
415 ///
416 /// See also:
417 ///
418 /// * [WidgetInspectorService.initServiceExtensions], where the service
419 /// extension is registered.
420 getRootWidgetSummaryTreeWithPreviews,
421
422 /// Name of service extension that, when called, will return the details
423 /// subtree, which includes properties, rooted at the [DiagnosticsNode] object
424 /// matching the specified id and the having a size matching the specified
425 /// subtree depth, both passed as arguments.
426 ///
427 /// See also:
428 ///
429 /// * [WidgetInspectorService.getDetailsSubtree], the method that this service
430 /// extension calls.
431 /// * [WidgetInspectorService.getDetailsSubtree], which returns a json
432 /// encoded String representation of this data.
433 /// * [WidgetInspectorService.initServiceExtensions], where the service
434 /// extension is registered.
435 getDetailsSubtree,
436
437 /// Name of service extension that, when called, will return the
438 /// [DiagnosticsNode] data for the currently selected [Element].
439 ///
440 /// See also:
441 ///
442 /// * [WidgetInspectorService.getSelectedWidget], which returns a json
443 /// encoded String representation of this data.
444 /// * [WidgetInspectorService.initServiceExtensions], where the service
445 /// extension is registered.
446 getSelectedWidget,
447
448 /// Name of service extension that, when called, will return the
449 /// [DiagnosticsNode] data for the currently selected [Element] in the summary
450 /// tree, which only includes [Element]s created in user code.
451 ///
452 /// If the selected [Element] does not exist in the summary tree, the first
453 /// ancestor in the summary tree for the currently selected [Element] will be
454 /// returned.
455 ///
456 /// See also:
457 ///
458 /// * [WidgetInspectorService.getSelectedSummaryWidget], which returns a json
459 /// encoded String representation of this data.
460 /// * [WidgetInspectorService.initServiceExtensions], where the service
461 /// extension is registered.
462 getSelectedSummaryWidget,
463
464 /// Name of service extension that, when called, will return whether [Widget]
465 /// creation locations are available.
466 ///
467 /// See also:
468 ///
469 /// * [WidgetInspectorService.isWidgetCreationTracked], the method that this
470 /// service extension calls.
471 /// * [WidgetInspectorService.initServiceExtensions], where the service
472 /// extension is registered.
473 isWidgetCreationTracked,
474
475 /// Name of service extension that, when called, will return a base64 encoded
476 /// image of the [RenderObject] or [Element] matching the specified 'id`,
477 /// passed as an argument, and sized at the specified 'width' and 'height'
478 /// values, also passed as arguments.
479 ///
480 /// See also:
481 ///
482 /// * [WidgetInspectorService.screenshot], the method that this service
483 /// extension calls.
484 /// * [WidgetInspectorService.initServiceExtensions], where the service
485 /// extension is registered.
486 screenshot,
487
488 /// Name of service extension that, when called, will return the
489 /// [DiagnosticsNode] data for the currently selected [Element] and will
490 /// include information about the [Element]'s layout properties.
491 ///
492 /// See also:
493 ///
494 /// * [WidgetInspectorService.initServiceExtensions], where the service
495 /// extension is registered.
496 getLayoutExplorerNode,
497
498 /// Name of service extension that, when called, will set the [FlexFit] value
499 /// for the [FlexParentData] of the [RenderObject] matching the specified
500 /// `id`, passed as an argument.
501 ///
502 /// See also:
503 ///
504 /// * [WidgetInspectorService.initServiceExtensions], where the service
505 /// extension is registered.
506 setFlexFit,
507
508 /// Name of service extension that, when called, will set the flex value
509 /// for the [FlexParentData] of the [RenderObject] matching the specified
510 /// `id`, passed as an argument.
511 ///
512 /// See also:
513 ///
514 /// * [WidgetInspectorService.initServiceExtensions], where the service
515 /// extension is registered.
516 setFlexFactor,
517
518 /// Name of service extension that, when called, will set the
519 /// [MainAxisAlignment] and [CrossAxisAlignment] values for the [RenderFlex]
520 /// matching the specified `id`, passed as an argument.
521 ///
522 /// The [MainAxisAlignment] and [CrossAxisAlignment] values will be passed as
523 /// arguments `mainAxisAlignment` and `crossAxisAlignment`, respectively.
524 ///
525 /// See also:
526 ///
527 /// * [WidgetInspectorService.initServiceExtensions], where the service
528 /// extension is registered.
529 setFlexProperties,
530}
531