Struct MediaQuery 

pub struct MediaQuery {
    pub size: Size,
    pub device_pixel_ratio: f32,
    pub density: f32,
    pub padding: Insets,
    pub view_insets: Insets,
    pub text_scaler: f32,
    pub platform_brightness: Brightness,
    pub accessibility: Accessibility,
    pub system_gesture_insets: Insets,
    pub view_padding: Insets,
    pub title_bar: Option<TitleBar>,
}

The surface an interface is being built for.

Every length is in logical pixels, the same unit widget styles use, so a value read here can be handed straight to a padding or a size.

Fields

size: Size

The drawable surface, in logical px — the window’s client area, or the whole screen on a phone.

device_pixel_ratio: f32

Physical pixels per logical pixel: the system’s DPI scale.

density: f32

The application’s own zoom factor on top of the system scale (see Application::density). 1.0 is neutral.

padding: Insets

Occupied edges still worth avoiding: the intrusions, less whatever view_insets already covers.

Zero at the bottom while the keyboard is up, because the navigation bar it hides is not an edge anything needs to stay clear of any more. This is what a crate::SafeArea pads by, and it is why a screen does not keep a strip of nothing between its content and the keys.

view_insets: Insets

Transiently occupied edges — in practice the soft keyboard, at the bottom. Measured from the window edge, so it already includes whatever bar it covers.

text_scaler: f32

How much larger the user has asked text to be — the system’s font-size setting, not the application’s zoom (that is density).

1.0 is the platform’s normal. It is the accessibility setting people actually change: a phone’s Font size slider goes to 1.3 on Android and past 3 with Larger Accessibility Sizes on iOS, and a layout that ignores it is one a great many people cannot read.

The framework scales text by it since milestone 403: installing this surface with MediaQuery::scope puts the factor where TextStyle::resolved reads it, and every size in the framework passes through there. scaled applies it to a number of an application’s own.

Chrome that cannot grow caps it instead of obeying it — see TextStyle::clamp_scale, which is what an app bar does with its title.

platform_brightness: Brightness

Whether the platform is currently showing a dark interface, independently of what this application chose.

The reference’s platformBrightness. An application that follows the system reads it; one that has its own switch ignores it.

accessibility: Accessibility

The accessibility settings the platform reports, which the framework and the application both have a say in honouring.

system_gesture_insets: Insets

The edges a system gesture starts from — a back swipe, a home swipe — which a widget with a horizontal drag of its own has to keep clear of, or the two fight over the same finger.

The reference’s systemGestureInsets. Usually wider than padding at the sides and taller at the bottom.

view_padding: Insets

The intrusions ignoring anything transient: what the notch and the bars take whether or not the keyboard is over them.

The one that does not move when the keyboard opens. A layout with a flexible child would otherwise shift the moment the padding under it went to zero, which is a whole screen twitching because somebody tapped a field — see crate::SafeArea::maintain_bottom_view_padding.

title_bar: Option<TitleBar>

The window’s title bar line, when the application’s content shares it (milestone 640): set by the shell on a desktop whose system allows it, while a WindowMenuBar has a bar. Below the bar it is None again: the line is the bar’s.

Implementations

impl MediaQuery

pub const UNSET: MediaQuery

The value of returns outside any scope: a zero-size surface, no scaling, nothing to avoid.

pub fn new(size: Size) -> MediaQuery

A description of a bare surface of size, with no insets — the desktop case, and the starting point for building one by hand in a test.

pub fn with_device_pixel_ratio(self, ratio: f32) -> MediaQuery

Sets the DPI scale.

pub fn with_density(self, density: f32) -> MediaQuery

Sets the application zoom factor.

pub fn with_text_scaler(self, scaler: f32) -> MediaQuery

Sets the user’s text-size setting. Clamped at zero, since a scale that shrank text to nothing would be a setting nobody could undo.

pub fn with_platform_brightness(self, brightness: Brightness) -> MediaQuery

Sets the platform’s own light/dark preference.

pub fn with_accessibility(self, accessibility: Accessibility) -> MediaQuery

Sets the accessibility settings the platform reports.

pub fn with_system_gesture_insets(self, insets: Insets) -> MediaQuery

Sets the edges a system gesture starts from.

pub fn scaled(&self, size: f32) -> f32

A font size with the user’s text-size setting applied.

The reference calls this TextScaler.scale, and it is a function there rather than a multiplication because a platform may scale non-linearly — large sizes growing less than small ones, so a heading does not run off the screen when body text is made readable. Ours is linear; the shape of the call is the one that can become non-linear without every caller changing.

pub fn with_title_bar(self, title_bar: Option<TitleBar>) -> MediaQuery

The title bar’s line, shared with the application (milestone 640).

pub fn with_insets(self, insets: WindowInsets) -> MediaQuery

Sets both kinds of inset at once, from what the shell reports.

pub fn safe(&self) -> Insets

The area to keep content out of: the per-side maximum of the two kinds of inset. The keyboard covers the navigation bar rather than stacking on top of it, so they are combined with max and not with +.

pub fn orientation(&self) -> Orientation

Which way round the surface is.

pub fn size_class(&self) -> SizeClass

The width breakpoint the surface falls into.

pub fn measure_hash<H>(&self, hasher: &mut H)

where H: Hasher,

The same description with the selected edges’ padding zeroed — what a widget that has just consumed that padding hands to its descendants, so they do not inset for the same notch a second time. Mixes into hasher everything about this surface that can change a measurement.

The relayout cache fingerprints the walk, and a scoped surface is part of that walk (milestone 417): two subtrees given different descriptions must not share a fingerprint, or the second would keep the first’s geometry.

The colours are left out on purpose — platform_brightness and the accessibility flags change how a frame is painted, and paint is not what this cache stores.

pub fn remove_padding(self, edges: Edges) -> MediaQuery

The query as a descendant sees it once edges of the padding have been consumed by a widget that already made room for them — an app bar takes the top, say. What was consumed is taken off the padding and off the view padding (floored at zero), so nothing below insets for it a second time.

pub fn remove_view_insets(self, edges: Edges) -> MediaQuery

The same description with the selected edges’ view_insets zeroed — the keyboard equivalent of remove_padding.

pub fn of() -> MediaQuery

The description currently in force, or UNSET outside any scope.

pub fn is_described(&self) -> bool

Is a surface actually described? False outside every scope, where of answers UNSET — a surface of no size.

Any widget that sizes itself from the ambient description needs this, because a width of zero is not a narrow screen: it is the absence of one, and the two want opposite answers. A bar folds everything into its menu at zero and nothing at all when there is no screen to fold against.

pub fn scope<R>(self, f: impl FnOnce() -> R) -> R

Runs f with self as the ambient description, and restores whatever was in force before — including when f panics, so one bad frame cannot leave a stale surface installed for every frame after it.

For a subtree, where a closure is the right shape: a widget changing the description its children see. A frame wants install instead, because a frame does not fit in a closure — see there for why that matters.

pub fn install(self) -> SurfaceGuard

Installs self as the ambient description until the returned guard is dropped, and restores whatever was in force before — panic or not.

Why this exists as well as scope

A closure bounds the description to one call, and a frame is not one call. The widgets are built, then measured and laid out, then painted, and all three resolve sizes. The shell wrapped only the build for four milestones: the reader’s font size reached a real device and moved not one pixel, because the two steps that decide how big text actually is ran outside the closure (milestone 407).

The description and the reader’s font size are installed together, by this one call, and that is the point. They were briefly two guards that had to agree with each other, which is the same bug with an extra step: whoever holds one and forgets the other gets a layout measured at one size and painted at another, with nothing to say so.

Trait Implementations

impl Clone for MediaQuery

fn clone(&self) -> MediaQuery

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for MediaQuery

impl Debug for MediaQuery

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for MediaQuery

fn eq(&self, other: &MediaQuery) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for MediaQuery