Skip to content

Commit 3c9f3a4

Browse files
authored
Apply view metrics overrides below the framework (flutter#194311)
Part of flutter/devtools#9893 (the DevTools accessibility page). Design: [flutter.dev/go/view-metrics-overrides](https://flutter.dev/go/view-metrics-overrides). flutter#192764 added the `debugViewMetricsOverrides` registry and the `ext.flutter.viewMetricsOverride` service extension. This PR makes those overrides take effect, which the DevTools override controls depend on. Next up: `flutter_test` support for test views with their own ids, and moving `ext.flutter.brightnessOverride` onto the registry. ## What this does In debug mode, `BindingBase.platformDispatcher` wraps `PlatformDispatcher.instance`. The wrapper and its views report overridden metrics, so everything that reads them through the binding (`MediaQuery`, `RenderView`, gestures, semantics, image resolution, accessibility evaluations) sees the overrides without any override-specific code. Changing an override fires the same `dart:ui` callbacks a real platform change would. `RenderView`, `View`, `RawView` and `MediaQueryData.fromView` map a raw engine view to the binding's wrapped one, so overrides apply to it too. Widget tests see overrides through `TestWidgetsFlutterBinding`, and explicit test values still take precedence. Profile and release builds are unchanged. New API: `debugApplyViewMetricsOverrides` wraps a dispatcher, for bindings that supply their own, and `debugViewWithMetricsOverrides` maps a raw engine view to its wrapper. ## Behavior changes and caveats - Debug only: `View.of(context)` and the binding's views are no longer `identical` to the ones `PlatformDispatcher.instance` reports. A view's `platformDispatcher` is a wrapper for that view, not `PlatformDispatcher.instance` or an app binding's dispatcher. Compare views by `viewId`. - Debug only: a `FlutterView` test double passed to `View`, `RawView`, `RenderView` or `MediaQueryData.fromView` must implement `platformDispatcher` and `viewId`. - `TestPlatformDispatcher.scaleFontSize` asks the wrapped dispatcher unless `textScaleFactorTestValue` is set, so non-linear text scaling applies in tests. A fake dispatcher without `scaleFontSize` still gets linear scaling. - An overridden `physicalSize` lays out at that size but still renders into the real surface, anchored top-left. - An ancestor `MediaQuery` still wins over platform-wide overrides, as it does over real platform settings. `debugBrightnessOverride` still wins over an overridden brightness. - `ui.window`, direct `PlatformDispatcher.instance` reads and engine-drawn content (platform views, system UI, keyboard) don't see overrides. - Text scalers compare by `textScaleFactor`, so a new `textScaling` table with the same first-point ratio only reaches already laid-out text when that text lays out again. ## Tests - `foundation/debug_view_metrics_override_test.dart`: the wrappers, per metric and per view, plus view identity, normalization, change notifications and validation. - `widgets/debug_view_metrics_override_test.dart`: end to end through `MediaQuery`, views, layout, pointer events, semantics, images and accessibility evaluations, and precedence of explicit test values. - `service_extensions_test.dart` covers an override set through the extension. `platform_dispatcher_test.dart` covers `scaleFontSize` delegation and its fallback for fakes. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant in-code documentation (doc comments with `///`). - [x] If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in [flutter/website] (or verified none is needed). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/CONTRIBUTING.ai.md [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [flutter/website]: https://github.com/flutter/website [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
1 parent 2accf87 commit 3c9f3a4

13 files changed

Lines changed: 3717 additions & 96 deletions

File tree

‎packages/flutter/lib/src/foundation/binding.dart‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,11 @@ abstract class BindingBase {
212212
/// [FlutterView]s in [PlatformDispatcher.views] to access view-specific
213213
/// functionality without a context.
214214
///
215+
/// Unlike the views [platformDispatcher] reports, this window — like
216+
/// [ui.window] and [ui.PlatformDispatcher.instance] — reports the metrics the
217+
/// platform reports, and does not apply the debug-only
218+
/// [debugViewMetricsOverrides] that tooling such as DevTools installs.
219+
///
215220
/// See also:
216221
///
217222
/// * [View.of] to access view-specific functionality on the [FlutterView]
@@ -247,7 +252,20 @@ abstract class BindingBase {
247252
/// for use by other bindings. A subclass of [BindingBase], such as
248253
/// [TestWidgetsFlutterBinding], can override this accessor to return a
249254
/// different [ui.PlatformDispatcher] implementation.
250-
ui.PlatformDispatcher get platformDispatcher => ui.PlatformDispatcher.instance;
255+
///
256+
/// In debug mode, this is [ui.PlatformDispatcher.instance] wrapped by
257+
/// [debugApplyViewMetricsOverrides], so that it and the views it reports apply
258+
/// [debugViewMetricsOverrides]; see [DebugViewMetricsOverride]. The views it
259+
/// reports are therefore not identical to the ones
260+
/// [ui.PlatformDispatcher.instance] reports; compare views by
261+
/// [FlutterView.viewId] when both are in hand. A subclass that overrides
262+
/// this accessor should build on `super.platformDispatcher`, the way
263+
/// [TestWidgetsFlutterBinding] does, or apply [debugApplyViewMetricsOverrides]
264+
/// to the dispatcher it supplies instead.
265+
ui.PlatformDispatcher get platformDispatcher => _platformDispatcher;
266+
final ui.PlatformDispatcher _platformDispatcher = kDebugMode
267+
? debugApplyViewMetricsOverrides(ui.PlatformDispatcher.instance)
268+
: ui.PlatformDispatcher.instance;
251269

252270
/// The initialization method.
253271
///

‎packages/flutter/lib/src/foundation/debug.dart‎

Lines changed: 876 additions & 38 deletions
Large diffs are not rendered by default.

‎packages/flutter/lib/src/foundation/service_extensions.dart‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,11 @@ enum FoundationServiceExtensions {
105105
///
106106
/// A malformed `viewId` or `overrides` fails the call, and nothing changes.
107107
///
108+
/// A change takes effect before the call returns: the framework is told to
109+
/// re-read the metrics it altered, as it would be if the platform had
110+
/// changed them, so the next frame reflects it. See
111+
/// [DebugViewMetricsOverride] for what is applied, and where.
112+
///
108113
/// Every reply has one key, whatever the call was, so that a client can
109114
/// resynchronize from any reply without remembering which call produced it:
110115
///

‎packages/flutter/lib/src/rendering/view.dart‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,13 @@ class RenderView extends RenderObject with RenderObjectWithChildMixin<RenderBox>
141141
/// [RenderView] object from configuring it. Typically, the object is created
142142
/// by the [View] widget and configured by the [RendererBinding] when the
143143
/// [RenderView] is registered with it by the [View] widget.
144-
RenderView({RenderBox? child, ViewConfiguration? configuration, required this._view}) {
144+
///
145+
/// In debug mode, the `view` is normalized with
146+
/// [debugViewWithMetricsOverrides], so that a view read straight from
147+
/// `dart:ui` renders with the same [debugViewMetricsOverrides] entry as one
148+
/// read from the binding.
149+
RenderView({RenderBox? child, ViewConfiguration? configuration, required ui.FlutterView view})
150+
: _view = kDebugMode ? debugViewWithMetricsOverrides(view) : view {
145151
if (configuration != null) {
146152
this.configuration = configuration;
147153
}

‎packages/flutter/lib/src/widgets/media_query.dart‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,12 +295,30 @@ class MediaQueryData {
295295
/// constructor is primarily for use in the implementation of the framework
296296
/// itself.
297297
///
298+
/// A [debugViewMetricsOverrides] entry for `view` is applied by the view and
299+
/// its [PlatformDispatcher], so it reaches this constructor only through
300+
/// what they report: its geometry always, and its platform-wide values only
301+
/// when `platformData` does not supply them. An ancestor [MediaQuery] that
302+
/// does supply them is not overridden, just as it is not overridden by the
303+
/// real platform settings.
304+
///
298305
/// See also:
299306
///
300307
/// * [MediaQuery.fromView], which constructs [MediaQueryData] from a provided
301308
/// [FlutterView], makes it available to descendant widgets, and sets up
302309
/// the appropriate notification listeners to keep the data updated.
303310
MediaQueryData.fromView(ui.FlutterView view, {MediaQueryData? platformData})
311+
: this._fromView(
312+
kDebugMode ? debugViewWithMetricsOverrides(view) : view,
313+
platformData: platformData,
314+
);
315+
316+
// A hop, so that everything below reads the view that applies the
317+
// [debugViewMetricsOverrides] entry registered for `view`: in debug mode, a
318+
// view read straight from a PlatformDispatcher the framework wrapped applies
319+
// none of its own, and the one [debugViewWithMetricsOverrides] returns for it
320+
// does.
321+
MediaQueryData._fromView(ui.FlutterView view, {required MediaQueryData? platformData})
304322
: size = view.physicalSize / view.devicePixelRatio,
305323
devicePixelRatio = view.devicePixelRatio,
306324
_textScaleFactor = 1.0, // _textScaler is the source of truth.

‎packages/flutter/lib/src/widgets/view.dart‎

Lines changed: 45 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,23 @@ import 'framework.dart';
2222
import 'lookup_boundary.dart';
2323
import 'media_query.dart';
2424

25+
// Whether [renderView], if there is one, renders into the view that [View] and
26+
// [RawView] keep for [view], which is the one [debugViewWithMetricsOverrides]
27+
// returns. That is the same object every time it is asked about the same view,
28+
// so asking again here is the same as reading the field, which an initializer
29+
// list assert cannot do. Only ever called from an assert.
30+
bool _debugRenderViewRendersInto(RenderView? renderView, FlutterView view) {
31+
assert(
32+
renderView == null || identical(renderView.flutterView, debugViewWithMetricsOverrides(view)),
33+
'A RenderView passed to View or RawView must render into the FlutterView '
34+
'passed alongside it. Both are normalized by debugViewWithMetricsOverrides '
35+
'and then compared by identity, so a view that merely compares == to the '
36+
"RenderView's — a test double with an operator == of its own, say — is not "
37+
'the same view for this purpose.',
38+
);
39+
return true;
40+
}
41+
2542
/// Bootstraps a render tree that is rendered into the provided [FlutterView].
2643
///
2744
/// The content rendered into that view is determined by the provided [child].
@@ -80,7 +97,7 @@ class View extends StatefulWidget {
8097
/// widget.
8198
View({
8299
super.key,
83-
required this.view,
100+
required FlutterView view,
84101
@Deprecated(
85102
'Do not use. '
86103
'This parameter only exists to implement the deprecated RendererBinding.pipelineOwner property until it is removed. '
@@ -94,18 +111,22 @@ class View extends StatefulWidget {
94111
)
95112
RenderView? deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView,
96113
required this.child,
97-
}) : _deprecatedPipelineOwner = deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner,
114+
}) : view = kDebugMode ? debugViewWithMetricsOverrides(view) : view,
115+
_deprecatedPipelineOwner = deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner,
98116
_deprecatedRenderView = deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView,
99117
assert(
100118
(deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner == null) ==
101119
(deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView == null),
102120
),
103121
assert(
104-
deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView == null ||
105-
deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView.flutterView == view,
122+
_debugRenderViewRendersInto(deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView, view),
106123
);
107124

108125
/// The [FlutterView] into which [child] is drawn.
126+
///
127+
/// This is the view passed to the constructor, normalized in debug mode with
128+
/// [debugViewWithMetricsOverrides] so that it applies the
129+
/// [debugViewMetricsOverrides] entry registered for its id.
109130
final FlutterView view;
110131

111132
/// The widget below this widget in the tree, which will be drawn into the
@@ -129,6 +150,16 @@ class View extends StatefulWidget {
129150
/// is best practice to use [MediaQuery.maybeOf] instead, which will ensure
130151
/// that the `context` is informed when the view properties change.
131152
///
153+
/// {@template flutter.widgets.View.debugViewMetricsOverrides}
154+
/// In debug mode, a view that [PlatformDispatcher.instance] reports is used
155+
/// through a wrapper that applies [debugViewMetricsOverrides], and this method
156+
/// returns the wrapper. It is not identical to the view that
157+
/// [PlatformDispatcher.instance] reports, and its
158+
/// [FlutterView.platformDispatcher] is not identical to
159+
/// [PlatformDispatcher.instance]. Compare views by [FlutterView.viewId]
160+
/// instead.
161+
/// {@endtemplate}
162+
///
132163
/// See also:
133164
///
134165
/// * [View.of], which throws instead of returning null if no [FlutterView]
@@ -150,6 +181,8 @@ class View extends StatefulWidget {
150181
/// [MediaQuery.sizeOf], which will ensure that the `context` is informed when
151182
/// the view properties change.
152183
///
184+
/// {@macro flutter.widgets.View.debugViewMetricsOverrides}
185+
///
153186
/// See also:
154187
///
155188
/// * [View.maybeOf], which throws instead of returning null if no
@@ -337,7 +370,7 @@ class RawView extends StatelessWidget {
337370
/// Creates a [RawView] widget.
338371
RawView({
339372
super.key,
340-
required this.view,
373+
required FlutterView view,
341374
@Deprecated(
342375
'Do not use. '
343376
'This parameter only exists to implement the deprecated RendererBinding.pipelineOwner property until it is removed. '
@@ -351,18 +384,22 @@ class RawView extends StatelessWidget {
351384
)
352385
RenderView? deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView,
353386
required this.child,
354-
}) : _deprecatedPipelineOwner = deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner,
387+
}) : view = kDebugMode ? debugViewWithMetricsOverrides(view) : view,
388+
_deprecatedPipelineOwner = deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner,
355389
_deprecatedRenderView = deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView,
356390
assert(
357391
(deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner == null) ==
358392
(deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView == null),
359393
),
360394
assert(
361-
deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView == null ||
362-
deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView.flutterView == view,
395+
_debugRenderViewRendersInto(deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView, view),
363396
);
364397

365398
/// The [FlutterView] into which [child] is drawn.
399+
///
400+
/// This is the view passed to the constructor, normalized in debug mode with
401+
/// [debugViewWithMetricsOverrides] so that it applies the
402+
/// [debugViewMetricsOverrides] entry registered for its id.
366403
final FlutterView view;
367404

368405
/// The widget below this widget in the tree, which will be drawn into the

0 commit comments

Comments
 (0)