Struct AppBar 

pub struct AppBar<Msg = Callback> { /* private fields */ }

An adaptive application bar. A fluent builder finished by AppBar::build.

Implementations

impl<Msg: Clone + 'static> AppBar<Msg>

pub fn new() -> Self

Creates a bar with no title, as wide as the surface it is being built for — which is what decides how many actions fit on the line and how many fold into the overflow menu.

The title is AppBar::title, and it is any widget. A bar that has none keeps its leading and its actions where they would be and puts nothing between them.

The width is read from MediaQuery::of, so no caller passes it. Outside any surface description — a unit test that builds a bar on its own — there is no width to fold against and nothing folds, which is what this did before the surface was ambient. A bar that is not the full width of the screen (one beside a rail, say) still says so with AppBar::width.

Breaking: this took the title as a string until milestone 522. AppBar::new().title(Text::new("Inbox")) is AppBar::new().title(Text::new("Inbox")).

pub fn width(self, width: f32) -> Self

The available width for the bar, in logical pixels: what drives the folding. It is a size, not a platform indicator.

An override. AppBar::new already takes the surface’s width from MediaQuery::of; this is for a bar that does not get the whole of it.

pub fn title_style(self, style: TextStyle) -> Self

The text title’s style (size/weight/italic/color). Default: the reference’s title_large at medium weight, in the theme’s colour.

pub fn title(self, widget: impl Widget<Msg> + 'static) -> Self

The title, as any widget — a text, a logo, a composed row.

This is the title in the reference, where title is a Widget? and there is no string form at all. Unset, the bar has none: nothing is laid out, painted or announced between the leading and the actions.

No style is put on it. It takes the resolved title type from the DefaultTextStyle the bar hands down, which is what the reference does at app_bar.dart:1084, so a Text that chose nothing wears the bar’s type and one that chose its own size keeps it. And it is announced as the screen’s heading unless AppBar::exclude_header_semantics says otherwise.

It was called title_widget while the bar had two kinds of title, and AppBar::new took a string until milestone 522. There is one kind, and it is optional.

pub fn leading(self, widget: impl Widget<Msg> + 'static) -> Self

The leading element (a menu or back button…), optional.

pub fn automatically_imply_leading(self, imply: bool) -> Self

Whether a bar with no leading of its own may take one from the shell it stands in. true unless said otherwise, as in the reference.

A bar on a screen that has a drawer then grows the button that opens it, and a bar on a screen that has none stays as it was — the shell is what knows, and until milestone 422 it had no way to say so to a slot handed to it already built.

The reference’s other branch has no counterpart here. There a bar also implies a back button when the route it is in can be popped; frus’s Navigator is controlled — the application holds the stack — so the framework does not know a depth to imply anything from. A screen that can be left says so with AppBar::leading.

false is for a bar that wants its leading slot empty on a screen that has a drawer: a logo where the button would be, and some other way in.

pub fn automatically_imply_actions(self, imply: bool) -> Self

Whether a bar with no actions of its own may take one from the shell it stands in. true unless said otherwise, as in the reference (app_bar.dart:1113).

A bar with nothing at its trailing end, on a screen that has an end drawer, grows the button that opens it. One action of its own and it does not: the reference’s test is the same — the implied button is what fills an empty end, never something added beside what the caller put there.

pub fn overflow(self, open: bool, toggle: Msg) -> Self

Enables the overflow menu: its open state (controlled by the app) and the toggle message (emitted by the ⋯ button and on an outside click).

pub fn action(self, widget: impl Widget<Msg> + 'static) -> Self

Adds an action: any widget, at the bar’s trailing end, after those already added. Typically an IconButton, or a PopupMenuButton for a menu of its own.

The reference’s actions is a list of widgets, and this is one more of them. The actions sit side by side, centred across the bar, inset by AppBar::actions_padding, their glyphs in AppBar::actions_icon_theme. A widget is never folded into the overflow menu: an arbitrary widget cannot become a menu row. An action that may fold is a AppBar::foldable_action.

Breaking: until milestone 613 this took a label and a message and made the foldable button; that is now foldable_action, and this is what action_widget was.

pub fn actions( self, actions: impl IntoIterator<Item = Box<dyn Widget<Msg>>>, ) -> Self

Adds every action of an iterator, already boxed, for actions built in a loop: the reference’s actions: [...] in one call. The same as AppBar::action for each, in order.

pub fn foldable_action(self, label: impl Into<String>, message: Msg) -> Self

Adds an action that folds: a text button with label, shown inline while it fits and moved into the overflow menu (AppBar::overflow) when the bar is too narrow for it. The last ones fold first.

This is frus’s own, beside the reference’s list of widgets: a bar that adapts to its width without the application measuring anything. It was action until milestone 613.

pub fn action_widget(self, widget: impl Widget<Msg> + 'static) -> Self

👎Deprecated since 0.3.0:

an action is any widget: use AppBar::action

Adds a widget action: AppBar::action, under its former name.

pub fn action_size(self, size: f32) -> Self

The foldable actions’ font size (the theme’s label_large by default).

pub fn primary(self, primary: bool) -> Self

Whether this bar sits at the top of the screen, and so has to keep its content out of the status bar. true unless said otherwise, as in the reference.

The bar pads itself: its surface still runs behind the status bar — that is what a Material bar looks like — and only its toolbar and its bottom are held clear. The two things this separates are the shell’s job and the bar’s: a Scaffold makes the slot tall enough, and the bar decides whether to use the room. Until milestone 417 the shell insetted the bar from outside, which is one switch where the reference has two — and why a bar used without a shell drew under the status bar.

Turn it off for a bar that is not at the top: one nested in a page, or a second bar under the first.

pub fn gap(self, gap: f32) -> Self

The space between the bar’s elements (8 px by default).

pub fn background(self, color: Color) -> Self

The bar’s background color (transparent by default: the parent decides).

pub fn height(self, height: f32) -> Self

An imposed bar height (by default, the content’s natural height).

pub fn center_title(self, centered: bool) -> Self

Centres the title in the space left between the leading and the actions, rather than starting it flush after the leading.

Overrides the platform’s convention, which is what a bar that has not been told anything follows: centred where the system centres its own titles, flush after the leading everywhere else. See platform_centers_title.

Centred, the title still yields to the actions first: it is centred in what is left, not in the window.

pub fn bottom(self, widget: impl Widget<Msg> + 'static) -> Self

A widget under the bar, spanning its width — a row of tabs, a search field, a progress bar. It belongs to the bar, so it sits inside the background.

pub fn leading_width(self, width: f32) -> Self

The width reserved for the leading slot. Unset, it is the Material slot width; a leading wider than that would otherwise push the title without the folding budget knowing, and the actions would run off the edge.

pub fn title_spacing(self, spacing: f32) -> Self

The gap between the leading and the title.

pub fn foreground(self, color: Color) -> Self

The colour of the bar’s own text — the title, and the labelled actions. Unset, each follows the theme.

pub fn elevation(self, elevation: f32) -> Self

How far off the page the bar sits. 0 — the default — is flat, which is what a bar sitting on a surface of the same colour wants.

A height casts a shadow only where a shadow_color is named, and tints only where a surface_tint is: the reference’s Material 3 bar makes both transparent (its app bar defaults, lines 2542 and 2545).

pub fn shape(self, shape: ShapeBorder) -> Self

What shape the bar is — the reference’s shape (app_bar.dart:209), and a whole ShapeBorder since milestone 455. Square by default, as the reference’s is.

The bar clips to it, so a coloured surface and anything drawn on it stop at the curve rather than squaring off the corner the shadow already rounded.

A bar is a rectangle, so what a shape contributes here is the corners it resolves to in the bar’s own box — a stadium rounds to half the bar’s height, which is what a stadium means on a wide, short box. A shape with no rounded form at all leaves the bar square rather than clipping it to something it is not.

Breaking: this took a BorderRadius under the same name until milestone 455. A caller passing a number says radius instead.

pub fn radius(self, radius: impl Into<BorderRadius>) -> Self

The corner radii — the shorthand for a rounded rectangle, writing into the same one field shape does. The last of the two called is the one that counts.

pub fn shadow_color(self, color: Color) -> Self

The colour of the shadow the bar casts. Only visible with an elevation.

The reference’s shadowColor, alpha included. Left unset it is transparent, as the reference’s Material 3 bar is (its app bar defaults, line 2542), and an elevated bar casts nothing.

pub fn surface_tint(self, color: Color) -> Self

The colour laid over the bar’s surface in proportion to its elevation — the reference’s surfaceTintColor, and Material 3’s way of showing height.

A shadow says a thing is above the page; the tint says how far, and it is what still reads on a dark background where a shadow shows nothing. The strength comes from the specification’s table (see surface_tint_opacity), so an elevation of 3 tints at 8% whoever asks.

Nothing is tinted at elevation zero, which is the default: a flat bar is the surface it was given.

pub fn force_material_transparency(self, force: bool) -> Self

Draws the bar with no surface at all: no background, no tint, no shadow — only what it holds.

The reference’s forceMaterialTransparency, and it exists for the same case: a bar over an image or a video, where the chrome should be the controls and nothing else. It overrides the background, the tint and the elevation rather than arguing with them, because a caller asking for transparency has already decided.

pub fn toolbar_opacity(self, opacity: f32) -> Self

The opacity of the toolbar row — the leading, the title and the actions — without touching the bar’s surface. 1.0 by default.

The reference’s toolbarOpacity. It is what fades a collapsing header’s contents out while its background stays, and it is a group opacity: overlapping children do not darken where they overlap.

pub fn bottom_opacity(self, opacity: f32) -> Self

The opacity of the bottom slot, independently of the toolbar. 1.0 by default. The reference’s bottomOpacity.

pub fn actions_padding(self, padding: f32) -> Self

Padding across the actions as a group, at its two ends, on top of the gap between them.

The reference’s actionsPadding, added in its 3.27 line for the same reason: an icon button’s own hit area already reaches the bar’s edge, so a design that wants the glyphs inset has nowhere else to say so.

pub fn exclude_header_semantics(self, exclude: bool) -> Self

Stops the title being announced as a heading. false by default, as the reference’s excludeHeaderSemantics is.

A screen reader’s user moves through a screen by its headings, and the bar’s title is the one every screen has. Excluding it is for a bar whose title is decorative, or one of two bars on a page where only the outer one names it — announcing both as headings gives the user two landmarks where there is one screen.

pub fn flexible_space(self, widget: impl Widget<Msg> + 'static) -> Self

A widget stacked behind the toolbar and the bottom, filling the bar’s whole box.

The reference’s flexibleSpace, and it is what makes a collapsing header possible at all: an image, a gradient, a photograph that the title sits on. The bar’s height is unchanged — this is a layer, not a slot — so the space is exactly as tall as the bar however tall the widget would rather be.

The bar’s own background is drawn first and this over it, so a translucent surface still tints what is behind, and a caller who wants only the image says force_material_transparency.

pub fn icon_theme(self, icons: IconTheme) -> Self

The colour and the size of the glyphs in the bar — the reference’s iconTheme.

It reaches every icon in the leading slot and, unless actions_icon_theme says otherwise, in the actions too. It is delivered as a theme for that subtree rather than as an argument to each widget, so it reaches an icon nested inside a button the bar never sees — which is what the reference’s inherited IconTheme does and why it is one.

An icon that names its own colour still wins: caller ?? this ?? the scheme.

pub fn actions_icon_theme(self, icons: IconTheme) -> Self

The same, for the actions alone — the reference’s actionsIconTheme.

Unset, the actions follow icon_theme. Set, they part company with the leading slot, which is the case it exists for: a back arrow in the foreground colour beside actions in a muted one.

pub fn toolbar_text_style(self, style: TextStyle) -> Self

The type worn by the words in the bar that are not the title — a label beside the back arrow, a “Save” in the actions, anything a caller handed over already assembled.

Not the title: the title has title_style, and the reference keeps the same two apart for the same reason. A bar’s title is one line the bar itself lays out and can measure; the rest is other people’s widgets, and the only way to reach a Text nested three levels inside one of them is to hand the style down rather than pass it in.

It is handed down field by field: setting a size leaves the colours alone, and a Text that chose its own size keeps it. See DefaultTextStyle for the rule in full.

pub fn build(self) -> Box<dyn Widget<Msg>>

Assembles the bar into a widget ready to display (the row leading . title . spring . inline actions . overflow, over an optional bottom).

The order in which space is handed out is worth stating, because it is a decision and not an accident: the actions are served first and the title yields. A title cut short is still a title; an action pushed off the edge is gone. So the folding budget is computed against the title’s floor, and whatever is left afterwards is what the title gets - with an ellipsis if it does not fit. Finishes the bar.

The composition is deferred until the theme is known (ThemeBuilder): center_title decides which children exist and in what order, so it cannot be resolved by a hook that runs after the row has been assembled. Everything the theme has a say in — the title’s centring, its type, the bar’s colours — is resolved inside, caller ?? theme ?? framework.

Trait Implementations

impl<Msg: Clone + 'static> Default for AppBar<Msg>

fn default() -> Self

The same as AppBar::new: a bar with no title, as wide as the surface.