Update `MediaQuery` documentation by nate-thegrate · Pull Request #183702 · flutter/flutter

nate-thegrate · 2026-03-14T22:13:24Z

This PR covers a couple of things:

The style guide's advice to never use "you" or "we".
A while back, the framework was tweaked so that runApp() creates and updates the MediaQuery instead of MaterialApp or WidgetsApp. The MediaQuery docs have yet to be updated with this information.

This PR is related to #183701, but I haven't added any recommendations regarding whether or not .maybeOf methods should be used; I'll plan on doing that if/when we decide to move forward with deprecating those methods.

gemini-code-assist

Code Review

This pull request updates the documentation for MediaQuery and MediaQueryData. The changes primarily involve rephrasing documentation comments to remove personal pronouns like 'you' and 'we' and to use passive voice, aligning with the repository's style guide. Additionally, the documentation for MediaQuery is updated to correctly state that the runApp function, rather than WidgetsApp or MaterialApp, is responsible for introducing and updating the MediaQuery.

victorsanni

LGTM, thanks for the cleanup!

dkwingsmt

Generally LGTM except for one question.

dkwingsmt · 2026-03-31T01:33:29Z

 /// See also:
 ///
-///  * [WidgetsApp] and [MaterialApp], which introduce a [MediaQuery] and keep
+///  * The [runApp] function, which introduces a [MediaQuery] and keeps


Can you teach me where runApp introduces the MediaQuery?

Sure!

flutter/packages/flutter/lib/src/widgets/binding.dart

Lines 1874 to 1877 in aaa24c3

void runApp(Widget app) {

final WidgetsBinding binding = WidgetsFlutterBinding.ensureInitialized();

_runWidget(binding.wrapWithDefaultView(app), binding, 'runApp');

}

runApp() calls the WidgetsBinding wrapWithDefaultView() method.

flutter/packages/flutter/lib/src/widgets/binding.dart

Lines 1635 to 1640 in aaa24c3

return View(

view: platformDispatcher.implicitView!,

deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner: pipelineOwner,

deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView: renderView,

child: rootWidget,

);

wrapWithDefaultView() returns a View widget.

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

Lines 269 to 288 in aaa24c3

@override

Widget build(BuildContext context) {

return RawView(

view: widget.view,

deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner: widget._deprecatedPipelineOwner,

deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView: widget._deprecatedRenderView,

child: MediaQuery.fromView(

view: widget.view,

child: FocusTraversalGroup(

policy: _policy,

child: FocusScope.withExternalFocusNode(

includeSemantics: false,

focusScopeNode: _scopeNode,

child: widget.child,

),

),

),

);

}

}

The View widget's build method returns a MediaQuery.

Thank you very much! I see why it is now basically impossible to have no MediaQuery in scope any more.

auto-submit · 2026-03-31T22:22:45Z

autosubmit label was removed for flutter/flutter/183702, because The base commit of the PR is older than 7 days and can not be merged. Please merge the latest changes from the main into this branch and resubmit the PR.

nate-thegrate · 2026-04-05T06:19:55Z

The PR has 2 approvals so I'm not sure what's going on. Maybe a rebase will fix it?

auto-submit · 2026-04-07T17:33:22Z

autosubmit label was removed for flutter/flutter/183702, because - The status or check suite Mac_arm64 tool_tests_commands has failed. Please fix the issues identified (or deflake) before re-applying this label.

dkwingsmt · 2026-04-08T20:07:10Z

Thanks for your contribution! This PR has reached completion, however we're not able to merge this PR for the moment due to the Material/Cupertino code freeze (#184093). As soon as the decoupling is complete, we will post a way to port this PR to the new packages to land. In the meantime, I'll convert this PR to a draft and apply a label so that we can quickly find it when the freeze is lifted.

flutter-dashboard · 2026-04-08T20:10:57Z

This pull request has been changed to a draft. The currently pending flutter-gold status will not be able to resolve until a new commit is pushed or the change is marked ready for review again.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

Piinks · 2026-06-24T19:54:03Z

It looks like this PR does not affect cupertino or material so it is not blocked on the code freeze.

nate-thegrate · 2026-06-24T20:16:06Z

Thank you, that was my thought as well!

I suppose we're good to un-draft and land this change, aside from needing to respect the limit of 2 concurrent open PRs.

Piinks · 2026-09-09T21:52:56Z

Greetings from stale PR triage! 👋
Is this change still on your radar?

nate-thegrate · 2026-09-09T23:59:31Z

Thanks for the poke! I think I'm able to un-draft this one, now that #188148 has landed :)

gemini-code-assist

Code Review

This pull request updates the documentation in media_query.dart to rephrase sentences, removing direct references to "you" or "your app" and improving clarity. The review feedback suggests retaining the concrete code example for MediaQuery.sizeOf and the guidance on when to prefer MediaQuery.maybeOf over MediaQuery.of, while still adhering to the style changes.

gemini-code-assist · 2026-09-10T00:00:49Z

+/// For example, [MediaQuery.sizeOf] obtains the size of the current view
+/// using the ancestor MediaQuery's [data].


By removing the concrete code example and the reference to [FlutterView], the documentation becomes less helpful for developers trying to understand how to use MediaQuery.sizeOf. We can rephrase the original text to avoid using "you" or "your app" while still keeping the useful code example and context.

/// For example, [MediaQuery.sizeOf] can be used to obtain the size of the /// current view (e.g., the [FlutterView] containing the app): /// MediaQuery.sizeOf(context).

References

Documentation should be useful and provide sample code. ^(link)

I like this documentation as-is, since it provides useful advice while avoiding unnecessary redundancy.

I removed the reference to FlutterView for a couple of reasons:

FlutterView is a class that developers usually don't need to interact with directly, whereas MediaQuery is used all the time, so I didn't feel that the reference was worth it.

The "e.g." parenthetical didn't make much sense here, since the FlutterView is always the source of truth for the view size.

Dart's function signatures are self-documenting, to some degree. In the case of MediaQuery.sizeOf, the fact that the method takes a BuildContext is obvious.

My guess is that the original reason for the MediaQuery.sizeOf(context) snippet is that in the English language, putting "of" at the end of a sentence feels weird, so the contributor felt like they needed to add something there.

gemini-code-assist · 2026-09-10T00:00:49Z

-  /// Use this function if you want to allow situations where no [MediaQuery] is
-  /// in scope. Prefer using [MediaQuery.of] in situations where a media query
-  /// is always expected to exist.
+  /// Returns `null` if no [MediaQuery] is in scope.


The original documentation contained useful guidance on when to prefer MediaQuery.maybeOf versus MediaQuery.of. Completely removing this guidance makes the documentation less helpful. We can rephrase the guidance to avoid using "you" while keeping the valuable recommendation.

/// This is appropriate when a [MediaQuery] might not be in scope. If a /// [MediaQuery] is expected to always be present, [MediaQuery.of] is preferred. /// /// Returns null if no [MediaQuery] is in scope.

References

Documentation should be useful and explain the why and the how, such as when to prefer one method over another. ^(link)

I feel pretty strongly that the simple "Returns null if no [MediaQuery] is in scope" is fine here, due to the precedent set by documentation for other .maybeOf() methods and the fact that there isn't a realistic scenario where no MediaQuery is in scope.

nate-thegrate · 2026-09-21T20:50:23Z

I believe we're ready to land this PR.

I'll do a rebase to mitigate any potential CI issues, also feel free to read through Gemini's review and let me know if anything should be changed from here.

github-actions Bot added the framework flutter/packages/flutter repository. See also f: labels. label Mar 14, 2026

gemini-code-assist Bot reviewed Mar 14, 2026

View reviewed changes

victorsanni self-requested a review March 23, 2026 17:41

justinmc requested a review from dkwingsmt March 24, 2026 22:13

victorsanni approved these changes Mar 24, 2026

View reviewed changes

victorsanni added the CICD Run CI/CD label Mar 24, 2026

github-actions Bot removed the CICD Run CI/CD label Mar 24, 2026

dkwingsmt reviewed Mar 31, 2026

View reviewed changes

dkwingsmt approved these changes Mar 31, 2026

View reviewed changes

dkwingsmt added the CICD Run CI/CD label Mar 31, 2026

justinmc added the autosubmit Merge PR when tree becomes green via auto submit App label Mar 31, 2026

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Mar 31, 2026

dkwingsmt added the autosubmit Merge PR when tree becomes green via auto submit App label Mar 31, 2026

github-actions Bot removed the CICD Run CI/CD label Mar 31, 2026

victorsanni added the CICD Run CI/CD label Apr 2, 2026

nate-thegrate force-pushed the MediaQuery-docs branch from 53d619e to 605535b Compare April 5, 2026 06:20

github-actions Bot removed the CICD Run CI/CD label Apr 5, 2026

victorsanni added the CICD Run CI/CD label Apr 7, 2026

victorsanni approved these changes Apr 7, 2026

View reviewed changes

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Apr 7, 2026

dkwingsmt marked this pull request as draft April 8, 2026 20:07

dkwingsmt added the waiting for code freeze This PR is waiting for a code freeze to resolve. label Apr 8, 2026

Piinks removed the waiting for code freeze This PR is waiting for a code freeze to resolve. label Jun 24, 2026

nate-thegrate force-pushed the MediaQuery-docs branch from 393ad83 to 58acc26 Compare September 9, 2026 23:59

nate-thegrate marked this pull request as ready for review September 9, 2026 23:59

flutter-dashboard Bot removed the CICD Run CI/CD label Sep 9, 2026

gemini-code-assist Bot reviewed Sep 10, 2026

View reviewed changes

update MediaQuery documentation

a585487

nate-thegrate force-pushed the MediaQuery-docs branch from 58acc26 to a585487 Compare September 21, 2026 20:50

victorsanni added CICD Run CI/CD autosubmit Merge PR when tree becomes green via auto submit App labels Sep 21, 2026

auto-submit Bot added this pull request to the merge queue Sep 21, 2026

Merged via the queue into flutter:master with commit b993ec8 Sep 21, 2026
26 checks passed

flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Sep 21, 2026

nate-thegrate deleted the MediaQuery-docs branch September 22, 2026 01:30

	void runApp(Widget app) {
	final WidgetsBinding binding = WidgetsFlutterBinding.ensureInitialized();
	_runWidget(binding.wrapWithDefaultView(app), binding, 'runApp');
	}

	return View(
	view: platformDispatcher.implicitView!,
	deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner: pipelineOwner,
	deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView: renderView,
	child: rootWidget,
	);

	@override
	Widget build(BuildContext context) {
	return RawView(
	view: widget.view,
	deprecatedDoNotUseWillBeRemovedWithoutNoticePipelineOwner: widget._deprecatedPipelineOwner,
	deprecatedDoNotUseWillBeRemovedWithoutNoticeRenderView: widget._deprecatedRenderView,
	child: MediaQuery.fromView(
	view: widget.view,
	child: FocusTraversalGroup(
	policy: _policy,
	child: FocusScope.withExternalFocusNode(
	includeSemantics: false,
	focusScopeNode: _scopeNode,
	child: widget.child,
	),
	),
	),
	);
	}
	}

		/// For example, [MediaQuery.sizeOf] obtains the size of the current view
		/// using the ancestor MediaQuery's [data].

Conversation

nate-thegrate commented Mar 14, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

victorsanni left a comment

Choose a reason for hiding this comment

Uh oh!

dkwingsmt left a comment

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

nate-thegrate Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

auto-submit Bot commented Mar 31, 2026

Uh oh!

nate-thegrate commented Apr 5, 2026

Uh oh!

auto-submit Bot commented Apr 7, 2026

Uh oh!

dkwingsmt commented Apr 8, 2026

Uh oh!

flutter-dashboard Bot commented Apr 8, 2026

Uh oh!

Piinks commented Jun 24, 2026

Uh oh!

nate-thegrate commented Jun 24, 2026

Uh oh!

Piinks commented Sep 9, 2026

Uh oh!

nate-thegrate commented Sep 9, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

nate-thegrate Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

nate-thegrate Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

nate-thegrate commented Sep 21, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants