Struct TabBar 

pub struct TabBar {
    pub pending_drag: Option<DragPayload>,
    pub pending_reorder: Option<(usize, usize)>,
    pub pending_close: Option<u64>,
    pub pending_max: Option<u64>,
    pub pending_search: Option<u64>,
    pub pending_new_tab: Option<()>,
    pub pending_detach: Option<(u64, Point)>,
    /* private fields */
}

Fields

pending_drag: Option<DragPayload>

pending_reorder: Option<(usize, usize)>

pending_close: Option<u64>

pending_max: Option<u64>

pending_search: Option<u64>

pending_new_tab: Option<()>

pending_detach: Option<(u64, Point)>

(tab_id, release_point) when a drag is released outside this bar’s rect, for a parent (e.g. GroupRow) to resolve the drop target.

Implementations

impl TabBar

pub fn begin_rename(&mut self, id: u64, name: &str) -> bool

Turn tab id’s title into a field holding it, all of it selected, where the title stands. name is what a reader announces the field as. Returns whether the edit is open; a tab drawn as an icon alone has no title to edit.

pub fn renaming(&self) -> Option<u64>

The tab whose name is being edited in place, if any.

pub fn rename_hit(&self, p: Point) -> bool

Whether p is on the name field: a press there places the caret rather than ending the edit.

pub fn rename_text(&self) -> Option<&str>

The name field’s text while it is edited.

pub fn rename_event( &mut self, event: &WindowEvent, ctx: &mut EventCtx<'_>, ) -> bool

Hand an event to the name field while a tab is being named. The keyboard is the field’s whole (typing never reaches the window under it); a press on the field is the field’s, and a press anywhere else commits the name and goes on to what is under it. Returns whether the field took the event.

pub fn commit_rename(&mut self) -> bool

Commit the name being edited, as Enter does. Returns whether a tab was being named.

pub fn cancel_rename(&mut self) -> bool

Put the title back, ending the edit, as Escape does. Returns whether a tab was being named.

pub fn take_rename(&mut self) -> Option<(u64, String)>

A name committed in place since the last call: the tab, and the name (empty when the person cleared it).

impl TabBar

pub fn set_shared(&mut self, id: u64, shared: Option<SharedWith>) -> bool

Mark id as a window shared with its workspace, seen by whom shared names, or clear the mark. true when that changed what the bar shows.

pub fn shared_with(&self, id: u64) -> Option<&SharedWith>

Who can see the window id, while it is shared.

pub fn set_shared_by(&mut self, id: u64, shared: Option<SharedBy>) -> bool

Mark id as a window someone else shared with the workspace, whose shared names, or clear the mark. true when that changed what the bar shows.

pub fn shared_by(&self, id: u64) -> Option<&SharedBy>

Whose the window id is, while someone else shares it here.

pub fn shared_chip( &self, tr: &mut TextRenderer, theme: &Theme, ) -> Option<(Rect, String)>

Where the share mark of the window in front stands, with its label: the chip, then the faces of the people who see the window, or of the person whose it is. After the bar’s other status chips, or, where the window’s app put its slots in the bar, right after its location. None when the window in front is not shared, a tab is being dragged, or there is no room for it.

pub fn set_dev_build(&mut self, id: u64, installer: Option<String>) -> bool

Mark id as running a developer’s build installed by installer, or clear the mark. true when that changed what the bar shows.

pub fn dev_build_chip( &self, tr: &mut TextRenderer, theme: &Theme, ) -> Option<(Rect, String)>

Where the “Dev build by …” mark of the window in front stands, with its label: after the “Controls your desktop” chip when that shows. None when the window in front runs no developer’s build, its app put slots in the row, a tab is being dragged, or the run is too short for it.

pub fn set_desktop_control(&mut self, id: u64, on: bool) -> bool

Mark id as a window whose app may control the desktop, or clear the mark. true when that changed what the bar shows.

pub fn controls_desktop(&self, id: u64) -> bool

pub fn take_desktop_control_press(&mut self) -> Option<(u64, Rect)>

A press on the chip, once: the tab it was on and where the chip stands, for the host’s menu to hang from.

pub fn desktop_control_chip( &self, tr: &mut TextRenderer, theme: &Theme, ) -> Option<(Rect, String)>

Where the “Controls your desktop” chip of the window in front stands, with its label: after the pills, before the window’s controls. None when the window in front holds no grant, its app put slots in the row, a tab is being dragged, or the run is too short for it.

pub fn activate_desktop_control(&mut self) -> bool

The chip activated without a pointer: report it from where it stands. Whether the bar shows it.

impl TabBar

pub const SOURCE_PILL_DIM_ALPHA: f32 = 0.35

Source pill’s opacity while the drag-ghost is visible; low enough to read as inactive but the slot still holds its place (no neighbour reflow).

pub const GHOST_PILL_ALPHA: f32 = 0.5

The handle is visibly lifted but remains translucent enough for a drop target to stay legible beneath it.

pub fn new( group_id_tag: &str, tabs: Vec<TabDescriptor>, active_id: u64, ) -> TabBar

pub fn set_window_controls(&mut self, on: bool)

Make this a window’s bar: the window’s controls stand at its trailing end and act on the active tab, a window of one tab shows it as its title, and the tabs carry no maximize or History chips.

pub fn set_search_control(&mut self, width: Option<f64>)

The window carries its own search control after the tabs, width wide with its gap; the tabs leave it that room and carry no chip of their own. None gives the room back.

pub fn toolbar_search_slot(&self) -> Option<(Rect, f64)>

Where the window’s search control stands when the active tab put its slots in the bar, and how far left an open search may reach; None without slots: it follows the tabs.

pub fn ground_color(&self, theme: &Theme) -> AlphaColor<Srgb>

The colour the bar stands on, for what covers part of it.

pub fn tabs_end(&self) -> f64

Where the tabs end: past the last pill, or past the “+” after them; the window’s search control stands here.

pub fn search_cramped_start(&self) -> f64

How far back over the tabs the window’s search may start when a narrow window leaves its query too narrow: past the first tab’s icon, which keeps naming the window.

pub fn set_maximized(&mut self, maximized: bool)

The window is maximized, so its maximize control offers restore.

pub fn set_toolbar(&mut self, id: u64, toolbar: Option<WindowToolbar>) -> bool

Show the slots id’s app declared for the window’s bar, or none. Returns whether that changed what the bar shows.

pub fn toolbar(&self, id: u64) -> Option<&WindowToolbar>

The slots id’s app declared.

pub fn set_popup_area(&mut self, area: Rect)

What the menus of the active tab’s slots keep inside: the window.

pub fn location_hit(&self, p: Point) -> bool

Whether p is on the edited location or the suggestions under it.

pub fn take_toolbar_events(&mut self) -> Vec<(u64, ToolbarEvent)>

What the person did with the apps’ slots since the last call, by tab.

pub fn take_location_drafts(&mut self) -> Vec<(u64, ToolbarEvent)>

What the edited location held since the last call, by tab, for the app’s suggestions (crate::window_toolbar::ToolbarEvent::Edit).

pub fn editing_location(&self) -> bool

Whether the active tab’s location is being edited in the bar: the bar then takes the keyboard.

pub fn edit_location(&mut self) -> bool

Turn the active tab’s editable location into a field (Ctrl+L). Returns whether it did.

pub fn location_event( &mut self, event: &WindowEvent, ctx: &mut EventCtx<'_>, ) -> bool

Hand a keyboard or text event to the location field while it is edited. Returns whether the field took it.

pub fn cancel_location_edit(&mut self) -> bool

Put the location back, ending its edit. Returns whether it was being edited.

pub fn toolbar_hit(&self, p: Point) -> bool

Where the active tab’s slots stand, for the host’s hit tests.

pub fn location_rect(&self) -> Rect

Where the active tab’s location stands (Rect::ZERO for none).

pub fn toolbar_rects(&self) -> (Rect, Rect, Rect, Vec<Rect>)

Where each of the active tab’s slots stands, for tests and the host: back, forward, location, then the actions.

pub fn bar_height(&self) -> f64

The bar’s height: one row, or two with the active tab’s slots under the tabs, and a compact window’s notice strip under those.

pub fn window_controls(&self) -> &WindowControls

The window controls’ rects, for the host’s hit tests and tests.

pub fn control_pill_hit(&self, p: Point) -> bool

Whether p is on the window’s controls pill, padding included: the window’s own chrome, which no app underneath it receives.

pub fn history_action_rect(&self) -> Rect

Where the window’s History toggle stands this frame: the app’s action, on the window’s ground just before the controls’ pill.

pub fn closable(self, closable: bool) -> TabBar

Whether tabs close from the strip (default true). Without it no close control is drawn, reserved or announced.

pub fn set_closable(&mut self, closable: bool) -> bool

Offer tabs’ close controls, or take them away, on a strip already built (closable). true when that changed what the strip offers.

pub fn closable_for_tests(&self) -> bool

Whether the strip offers its tabs’ close controls.

pub fn without_new_tab(self) -> TabBar

No new-tab control at the end of the strip.

pub fn set_new_tab(&mut self, on: bool) -> bool

Offer the new-tab control, or take it away (for someone who opens nothing here). true when that changed what the bar offers.

pub fn set_mark(&mut self, id: u64, mark: Option<TabMark>)

Mark what tab id’s content is doing, or clear the mark.

pub fn mark(&self, id: u64) -> Option<TabMark>

pub fn mark_rect(&self, id: u64) -> Option<Rect>

Where tab id’s mark is painted, for hit-testing and tests.

pub fn take_mark_click(&mut self) -> Option<(u64, TabMark)>

A click on a tab’s sound mark, once: the host mutes or unmutes it.

pub fn set_group_focused(&mut self, focused: bool)

The host shows which group has keyboard input: the focused group’s active tab carries a keyline in primary ink, the others the lift alone.

pub fn force_settled_for_tests(&mut self)

Pin transient pill geometry at its resting state for deterministic screenshots; production animation is unchanged.

pub fn elapse_hover_dwell(&mut self) -> bool

Test and shot control for the hover dwell: settle the pointer intent as if the dwell had run out. Production arms the dwell only through on_cursor_moved.

pub fn visible_title( &mut self, i: usize, tr: &mut TextRenderer, theme: &Theme, ) -> Option<String>

Elides with an ellipsis when the pill is too narrow — a plain clip-rect used to slice the last glyph in half instead. None for a pinned pill.

pub fn tabs(&self) -> &[TabDescriptor]

pub fn tabs_mut(&mut self) -> &mut Vec<TabDescriptor>

pub fn active_id(&self) -> u64

pub fn set_active(&mut self, id: u64)

pub fn take_activation(&mut self) -> Option<u64>

Drain the tab selected by pointer, keyboard, or accessibility input. Programmatic reconciliation deliberately does not populate this edge.

pub fn is_pinned(&self, id: u64) -> bool

pub fn set_holder(&mut self, id: u64, holder: Option<TabHolder>) -> bool

Mark id as held by someone else (TabHolder), or clear the mark. true when that changed what the tab offers.

pub fn holder(&self, id: u64) -> Option<&TabHolder>

Who holds id, when someone else does.

pub fn is_held(&self, id: u64) -> bool

Whether someone else holds id.

pub fn pin(&mut self, id: u64)

Caller ensures the tab exists; a stale entry is tolerated (filtered at render time) but should be cleaned up via unpin when the tab is removed.

pub fn unpin(&mut self, id: u64)

pub fn toggle_pin(&mut self, id: u64)

pub fn set_icon(&mut self, id: u64, icon: Option<AppImage>) -> bool

Replace tab id’s artwork. true when that changed what it paints.

pub fn set_attention(&mut self, id: u64, attention: bool) -> bool

Mark id as waiting for the person, or not. true when that changed what it paints.

pub fn set_accent(&mut self, id: u64, color: AlphaColor<Srgb>)

Tint id’s leading marker: a tab with no app_kind paints a filled dot, one with both tints its app glyph. Pass a colour read off the Theme.

pub fn clear_accent(&mut self, id: u64)

Drop id’s leading accent, giving the pill its leading zone back.

pub fn accent(&self, id: u64) -> Option<AlphaColor<Srgb>>

pub fn set_modified(&mut self, id: u64, modified: bool)

Mark id as holding unsaved changes, or clear the mark.

pub fn is_modified(&self, id: u64) -> bool

True if id is currently marked as holding unsaved changes.

pub fn set_show_maximize(&mut self, show: bool)

Offer, or withhold, the hover-reveal maximize chip. Defaults to offered — see Self::show_maximize for when to turn it off.

pub fn remove_tab(&mut self, id: u64) -> Option<usize>

pub fn start_closing(&mut self, id: u64) -> bool

Active-id shifts to the neighbour at once, so no “ghost active” frame shows during the fade; idempotent on a tab already closing, since restarting the curve would pop it back to full.

pub fn cancel_close(&mut self, id: u64) -> bool

Restore a requested close whose host still owns the live tab. No metadata or focus is lost while the client asks for a save decision.

pub fn finalize_close(&mut self, id: u64) -> bool

Called by WindowGroup once its own fade-out has elapsed.

pub fn has_closing(&self) -> bool

pub fn is_closing(&self, id: u64) -> bool

True if id is mid close-fade: gone from the live list but still rendering. Callers reconciling against their own model check it before re-inserting a still-open item, so cancelling a close does not pop a duplicate pill.

pub fn reorder(&mut self, from: usize, to: usize)

pub fn cancel_drag(&mut self) -> bool

Abandon a pending or lifted tab without turning its release into a drop.

pub fn set_carriable(&mut self, carriable: bool)

Whether the window can be carried by its bar from anywhere that is not a control (it stands on a canvas): its title and location carry it, and a click still does what it does.

pub fn control_hit(&self, p: Point) -> bool

Whether p is on one of the bar’s controls: the window’s own, the toolbar’s (not its location), a tab’s close or action chip, the new-tab button, the desktop chip.

pub fn cancel_press_for_carry(&mut self)

The press under way became a carry of the whole window: whatever it was going to do on the bar it no longer does.

pub fn popup_open(&self) -> bool

Whether the bar has a menu, the emoji picker or the location’s suggestions open over the window.

pub fn close_popups(&mut self) -> bool

Close what the bar has open over the window. Whether anything was.

pub fn drag_in_flight(&self) -> bool

pub fn dragged_tab(&self) -> Option<u64>

The tab this bar is dragging, while it drags one.

pub fn take_reorder(&mut self) -> Option<(usize, usize)>

pub fn take_close(&mut self) -> Option<u64>

pub fn close_rect_for_tests(&self, tab_id: u64) -> Option<Rect>

pub fn take_context_menu(&mut self) -> Option<(u64, Point)>

pub fn take_max(&mut self) -> Option<u64>

pub fn take_search(&mut self) -> Option<u64>

pub fn take_history(&mut self) -> Option<(u64, HistoryControl)>

A press on a pill’s History chip since the last call: the tab, and the control it showed (open History, or close it).

pub fn set_history_control(&mut self, id: u64, control: Option<HistoryControl>)

The History control tab id’s window offers, or None where it has no History: one more chip in the pill’s cluster, left of search.

pub fn history_control(&self, id: u64) -> Option<HistoryControl>

pub fn take_new_tab(&mut self) -> Option<()>

pub fn new_tab_rect(&self) -> Rect

Rect::ZERO when the pills have filled the bar and the chip is suppressed.

pub fn take_detach(&mut self) -> Option<(u64, Point)>

pub fn bar_rect(&self) -> Rect

pub fn tab_rects(&self) -> &[Rect]

pub fn max_rects(&self) -> &[Rect]

Gated cfg(any(test, debug_assertions)) rather than cfg(test), so integration tests in other crates can resolve the chip from live geometry.

pub fn search_rects(&self) -> &[Rect]

pub fn history_rects(&self) -> &[Rect]

pub fn action_hit_rect(&self, chip: Rect) -> Rect

A chip’s pointer target: at least the theme’s minimum on a side, centred on the glyph, never outside the bar. The painted chip keeps its width, so neighbouring targets overlap, resolved close, then maximize, then search.

pub fn drop_index_for(&self, release_point: Point) -> usize

Insert before the first pill whose horizontal midpoint is past release_point.x; append if past every midpoint.

pub fn insert_tab(&mut self, idx: usize, desc: TabDescriptor)

Used by cross-group drag routing in GroupRow::handle_event to splice a detached tab into the target bar without forcing a full rebuild.

pub fn set_external_drag_hover(&mut self, cursor: Option<Point>)

Called for every sibling bar while another group’s tab drag is in flight; a no-op while this bar has its own drag, whose moves already drive the hover.

pub fn set_on_strip(&mut self, on_strip: bool)

Stand the bar on a docked strip of its own instead of the window ground: its tabs then lift off the strip’s ground.

Trait Implementations

impl Widget for TabBar

fn needs_redraw(&self) -> bool

An undrawn bar repaints, and so does one whose own state moved since it drew (every route that changes it says so through TabBar::touch) or whose people are not the people it drew. Presence comes from the frame the host lends, so the answer is right before an event or a peek reaches the bar, not only after a draw.

fn draw( &mut self, scene: &mut Scene, transform: Affine, tr: &mut TextRenderer, theme: &Theme, presence: &PresenceCtx, )

A bar at rest whose own state, theme, placement and the people on its tabs are as when it was last drawn shows that drawing again (TabBar::replays); anything else draws it afresh.

fn tooltip_target_at(&self, point: Point) -> Option<(Rect, String)>

Every button in the bar names its outcome: the slots’ buttons and the window’s controls. See [tips::TabBar::tip_at].

fn draw_overlay( &mut self, scene: &mut Scene, transform: Affine, text_renderer: &mut TextRenderer, theme: &Theme, presence: &PresenceCtx, )

The slots’ menus (overflow, suggestions) float in the window’s top layer, over the content.

fn test_rects(&self) -> Vec<(String, Rect)>

So a scenario clicks the rect the renderer actually painted, not a guessed coordinate. The zero-area case (chip suppressed) is filtered out by the registry.

fn is_layout_dirty(&self) -> bool

A fixed-height strip sized by its parent: only its first layout is a size change. Tab additions and removals are structural; peers arriving on or leaving a tab resize its pill for their faces.

fn next_wake_deadline(&self) -> Option<Instant>

A dwell or an aim hold still to run out is a wait, not motion: the host sleeps until it is due and Widget::update settles it.

fn update( &mut self, _state: &(dyn Any + 'static), _path: &(dyn Any + 'static), ) -> bool

A dwell or aim hold that came due opens (or hands over) its pill; the relayout this asks for starts the reveal.

fn needs_animation_frame(&self) -> bool

The bar’s curves while they run, and busy arcs while they turn (TabBar::busy_needs_frame).

fn build_layout( &mut self, taffy: &mut TaffyTree, theme: &Theme, node_map: &mut HashMap<NodeId, *mut dyn Widget>, ) -> NodeId

fn apply_layout(&mut self, taffy: &TaffyTree, node: NodeId, origin: Point)

Take the geometry layout gave this node. The default keeps none, for widgets that neither draw nor hit-test.

fn handle_event(&mut self, event: &WindowEvent, ctx: &mut EventCtx<'_>)

Handle one input event with the runtime services for this retained node.

fn name(&self) -> &'static str

fn test_id(&self) -> Option<&str>

Stable id for the e2e test harness; None falls back to a path-based key. Must be unique across the live tree — the registry resolves on first match, so a duplicate shadows the second occurrence.

fn accessibility(&self) -> Option<AccessNode>

Role, name/description/value, and AccessState. Default None means presentational: the node is skipped and children reparent onto the parent. State must be derived, not stored so it can’t drift from draw; names must already be i18n!-resolved.

fn perform_semantic_action( &mut self, target: &str, action: &Action, _state: &mut Edits<'_>, _path: &(dyn Any + 'static), ) -> bool

Handle an action addressed to a synthetic accessibility child created by this widget. target is the opaque stable value supplied through AccessNode::with_action_target.

fn get_rect(&self) -> Rect

The rectangle this widget occupies. The default, for widgets that keep no geometry, is empty.

fn is_focusable(&self) -> bool

fn set_focus(&mut self, focused: bool)

fn is_focused(&self) -> bool

fn wants_pointer_capture(&self) -> bool

fn set_interaction_environment(&mut self, environment: InteractionEnvironment)

Receive the host’s current input capabilities. The default propagates through retained containers, so app code does not need device branches.

fn set_motion_reduced(&mut self, reduced: bool)

Apply the effective reduced-motion preference before the host asks this subtree whether it needs another animation frame. The default forwards recursively, making the preference a framework policy instead of an optional convention that every container has to remember to implement.

fn native_input_snapshot( &self, _state: &(dyn Any + 'static), _path: &(dyn Any + 'static), ) -> Option<Value>

Read-only state evidence for opt-in scheduled native input diagnostics. Called only around diagnostic inputs, never during ordinary input or paint. Keep this inexpensive and root-local; snapshots may be logged verbatim. This verifies widget state, not rendered pixels or display presentation.

fn view_only_scroll(&self, _event: &WindowEvent) -> bool

Opt in only when this wheel event changes scroll geometry and nothing else: no document edit, focus or selection, action availability, resource declaration, pending command or work that requires sync. The runner still lays out, paints and refreshes accessibility geometry; unknown handlers stay on the full path.

fn primary_vertical_scroll(&self) -> Option<PrimaryScrollRegion>

Explicit app-owned region; never search secondary children implicitly.

fn apply_primary_vertical_scroll( &mut self, _action: PrimaryScrollAction, ) -> PrimaryScrollResult

fn callback_binding(&self) -> Option<CallbackBinding>

Runtime binding inherited by descendants in a matching layout topology.

fn has_separate_document_owner(&self) -> bool

Whether this widget introduces a document owner distinct from the runner’s outer State. This is a compatibility check, never identity or authority for history access or restore.

fn history_owner(&self) -> Option<HistoryOwner>

Opaque actual custody for framework History source registration.

fn record_owners(&self) -> Vec<HistoryOwner>

Records this widget keeps open beside the document it shows, each synced on its own route: a framework app’s records in the person’s own workspace (crate::record::person). They take no part in this widget’s history or controls.

fn provide<'a>(&'a self, _request: &mut Request<'a, '_>)

Answer a request for a capability this widget takes part in (see capability). Declare capabilities with crate::provides!.

fn provide_mut<'a>(&'a mut self, _request: &mut RequestMut<'a, '_>)

Exclusive counterpart to Widget::provide.

fn mount_native_views(&mut self, host: &NativeViewHost<'_>)

Attach native child views through this owner’s retained lifecycle topology. Presentation containers with inactive or hidden live descendants override this traversal so lifecycle ownership stays independent of drawing and input visibility.

fn unmount_native_views(&mut self)

Tear native children down while their parent window still exists.

fn native_view_frame_start(&mut self)

Begin a native-view frame through this owner’s retained lifecycle topology.

fn set_platform_conventions(&mut self, conventions: PlatformConventions)

Receive host-selected platform conventions. The default propagates to retained children, keeping target-OS branches out of app code.

fn set_window_bar_control(&mut self, in_bar: bool)

Tell this widget whether it stands in a window bar. A bar’s controls are drawn at the bar’s control height whatever the pointer; the target a finger needs reaches beyond the drawn shape, invisibly. The default propagates to children.

fn sync(&mut self, state: &(dyn Any + 'static), path: &(dyn Any + 'static))

Pull model state into this widget before layout. The default syncs the children Widget::children_mut returns; a widget overrides it only to read state of its own, or to sync children it does not expose there.

fn settle(&mut self, edits: &mut Edits<'_>, path: &ExId)

Apply, after the sync pass, what the widget took up there and must write: a worker’s answer, a chooser’s file, an event a child queued. Writes go only through typed actions on edits; the host syncs again when the document changed. The default settles the returned children.

fn measure( &mut self, _known: Size<Option<f32>>, _available: Size<AvailableSpace>, _text_renderer: &mut TextRenderer, ) -> Size<f32>

fn layout_info(&self) -> Option<LayoutInfo>

Read-only resolved decisions for widgets with an explicit layout policy. None means the widget has no such policy; ordinary manual widgets remain valid. Values are available after build/settlement and carry real origins.

fn adjust_layout_style( &mut self, _taffy: &mut TaffyTree, _node: NodeId, _text: &mut TextRenderer, ) -> bool

Adjust this node’s style using its allocated size, before final geometry is applied. Return true only when the style changed (or an inherited decision child hooks read). An override may measure its owned children through ordinary references, entering their callback binding when present. Never reenter descendants through the raw node map while borrowing their parent, change topology, or build another layout tree. The shared host solver visits every registered widget, repeats layout at most eight times and skips a frame that does not settle.

fn observe_physical_input(&mut self, _input: PhysicalInput)

Observe this app’s ordinary foreground physical input before framework shortcuts consume it. Keep feedback ephemeral; this is not an input grant.

fn children(&self) -> Vec<&dyn Widget>

fn for_each_child(&self, visitor: &mut dyn FnMut(&dyn Widget))

Allocation-free read-only child traversal. Existing custom containers inherit a compatibility adapter over Self::children; toolkit containers override this to walk their retained storage directly.

fn for_each_child_in_clip(&self, visitor: &mut dyn FnMut(&dyn Widget))

The children of Self::for_each_child that may paint inside the layout_clip in effect: what a scroll view’s damage and copy plan need. Every child by default; a long column visits only those near the clip, so a frame costs what is shown, not what the column holds.

fn for_each_hosted_child(&self, _visitor: &mut dyn FnMut(&dyn Widget))

Children this widget keeps in the retained tree but does not route input to: a subtree it does not own and answers the person’s events for itself, like a host drawing another widget’s card over the windows. Inspection, named controls and the accessibility tree walk these after the children Self::children lists, so what is walked there keeps the paths, sibling indices and registry entries it had.

fn for_each_layout_child(&self, _visitor: &mut dyn FnMut(&dyn Widget)) -> bool

Every child this widget’s Self::build_layout gives a layout node, also those Self::for_each_child keeps from routing (a hidden pane, a title, a spacer). A retained layout is checked against this walk before it is called through again, so a widget that replaced a child without reporting it gets a new layout instead of a call into freed memory. A child missing here cannot be checked, so debug builds stop on it. A wrapper that stands for its inner widget’s node visits the inner widget itself.

fn children_mut(&mut self) -> Vec<&mut dyn Widget>

fn window_slot(&self, _id: String) -> Option<ToolbarAction>

This control as an action of the window’s bar, sent back as id (crate::window_toolbar::ToolbarAction): a button’s icon and name. None for anything that is not a button.

fn as_any(&self) -> Option<&(dyn Any + 'static)>

Downcast to the concrete widget, for hosts and tests that reach a known widget through dyn Widget. Default None (a widget may borrow and so not be 'static); a widget opts in with Some(self), and a Decorator answers itself.

fn as_any_mut(&mut self) -> Option<&mut (dyn Any + 'static)>

fn stands_for(&self, address: *const ()) -> bool

Whether this widget is the one at address, or stands in the tree for it: a Decorator stands for every widget it wraps, so a scroller drawn inside one is found where the decorator is (crate::scroll_copy::offer).

fn focus_reveal_context(&self) -> Option<Rect>

Context that should remain visible with a focused descendant, such as a form control and its validation message. Opt-in scroll containers use this block when it fits; otherwise they prioritise the control.

fn reveal_descendant(&mut self, target: *const dyn Widget) -> bool

Reveal a newly keyboard-focused descendant inside any enclosing viewport. Containers override this to scroll; ordinary widgets simply recurse toward the target and report whether it was found.

fn child_clip_rect(&self) -> Option<Rect>

Absolute logical clip applied to ordinary children during painting and pointer routing. Inspectors and enclosing scroll regions must respect this boundary instead of treating clipped descendants as visible extent.

fn snap_points(&self, axis: ScrollAxis, out: &mut Vec<f32>)

Offsets along axis that this widget, as a scroll view’s content, offers it to settle on, measured from its own leading edge: a board’s lanes (crate::widget::Board). None leaves a scroller stopping wherever the hand left it.

fn take_action_palette_request(&mut self) -> Option<ActionAddress>

One-shot request to open the host’s action palette directly at a typed resource action. Parameter collection and permission checks remain host policy; widgets only name an address already present in resources().

fn take_search_request(&mut self) -> bool

One-shot request to open the host’s search palette, the same one the platform search shortcut opens. An app’s own search button latches it so search stays one shared host surface rather than an app overlay.

fn cursor_shape(&self, _point: Point) -> Option<CursorIcon>

point is logical coords, same space as Widget::get_rect; None defers to the default arrow. The host hit-tests the whole tree via node_map and picks the smallest-area claim, so containers need not override this.

fn claims_raw_touch(&self, _point: Point) -> bool

Opt out of touch-to-pointer emulation for contacts that begin at point (logical coords, same space as Widget::get_rect).

fn touch_claim(&self, _point: Point) -> TouchClaim

What a one-finger contact that begins at point (logical coords) means here, when a drag moves something rather than scrolling.

fn tooltip(&self) -> Option<&str>

Revealed after a dwell over the widget’s rect, via the toolkit’s one tooltip mechanism (crate::widget::tooltip::TooltipHost), hit-tested like cursor_shape so containers need not forward it. An icon-only control should also use this as its accessible name.

fn tooltip_side(&self) -> TooltipSide

Which side of the control its tooltip goes: below by default, beside it for a control in a vertical rail.

fn is_default_keyboard_focus(&self) -> bool

Preferred control when its app is explicitly activated without a valid saved control. Hosts still enforce visibility, enabled state and scope.

fn keyboard_input_scope(&self) -> Option<u64>

Exact app instance whose non-text shortcuts this subtree owns when activation has no control target. Unbound desktop chrome may declare the active tab; component boundaries default to their captured owner.

fn set_full_bleed(&mut self, _full_bleed: bool)

The window holding this content fills its display (a maximized window): it has nothing beside it to round its corners against or to set it apart from, so content that frames or clips itself to the window’s shape draws edge to edge instead. A client surface drawn that way, last and unclipped, is one the display can scan out directly. Content that frames nothing ignores it.

fn set_invalid(&mut self, _invalid: bool)

The form’s validation verdict for this control, set by Field::with_error: an invalid control edges itself in danger ink and reports invalid to assistive technology. Controls without a field face ignore it.

fn focus_requested(&mut self, target: Option<NodeId>, tree: &TaffyTree)

An explicit runner focus request, after resolving the actual keyboard owner. Retained flags and layout restoration are not user gestures. Containers can observe this to reveal the owning viewport.

fn context_menu_anchor(&self) -> Option<Rect>

The box a context menu opened from the keyboard stands against: the item that has the keyboard, so the menu opens under it rather than under the whole widget. A widget that holds items (a list) answers for the one with the keyboard; None leaves the menu to stand under the focused widget’s own box.

fn wants_tab_input(&self) -> bool

Whether a focused widget owns Tab instead of the host’s focus traversal. This is deliberately opt-in: ordinary form fields and controls retain platform-standard Tab/Shift+Tab navigation, while a code editor or terminal can receive the key for indentation or completion. A widget around the focus may claim it too: a sheet that walks its own controls with Tab.

fn ime_cursor_rect(&self) -> Option<Rect>

Caret rectangle for the platform input method, in window-logical coordinates. Returning Some enables IME for the focused widget and positions its candidate window; non-text controls keep the default None and therefore disable IME.

fn traps_focus(&self) -> bool

While any widget answers true, the host restricts Tab/directional focus to this subtree (wrapping at the ends) and restores the prior focus once it goes back to false. Default false.

fn scopes_keyboard_focus(&self) -> bool

Whether Tab and directional focus travel stay inside this subtree while no trap holds focus: the content of the focused desktop window, so keyboard travel cycles through the app the person is in and never wanders onto the desktop’s chrome (its bars, menus and window titles), which the keyboard reaches through its own shortcuts. Unlike Self::traps_focus it moves no focus when it starts or ends, and pointer input is unaffected. Default false.

fn take_app_activation(&mut self) -> Option<u64>

One-shot (reading MUST clear it): the app instance the person just brought forward (a window they opened, clicked or switched to), whose keyboard focus the host restores, or puts on its default control, so what they type next reaches it. Default forwards the first request found among the children.

fn take_focus_request(&mut self) -> Option<String>

One-shot (reading MUST clear it): the test id of the control this subtree asks to take the keyboard once the runner laid it out, such as the first field of a view a person’s press just opened, so what they type next lands there. The runner focuses it as a press focuses a control, blurring any other; a control it does not find (or that takes no focus) leaves focus where it is. Default forwards the first request found among the children.

fn accessibility_shared(&self) -> Option<SharedAccessNode>

Self::accessibility with its synthetic children shared, for a widget that keeps them between frames: each child it did not change is handed over as the very Arc of the last frame, which the semantic tree takes as unchanged without copying or comparing it.

fn accessibility_hidden(&self) -> bool

Whether Self::accessibility reports this subtree hidden, for a host that asks it of every node to prune focus traversal. Widgets whose node is costly to build (text values, per-block children, a translated name) answer without building it: the focus walk asks every widget in the window on every recomputation. Any override must agree with accessibility(); debug builds check it in the walk.

fn accessibility_root(&self) -> Option<AccessNode>

Self::accessibility’s own node with its children left empty: its role, identity (semantic_key) and state. Focus capture and focus order read only these, for every node on every frame, so a widget whose node carries a large subtree (a document exporting its every block) answers without building it. An override must equal accessibility() with children cleared.

fn synthetic_accessibility_rect(&self, _path: &[usize]) -> Option<Rect>

Geometry for an immediate-mode semantic child from AccessNode::children. The path is its child-index path beneath this widget’s accessibility node. Returning a rect lets AccessKit activation inject the same click as pointer input.

fn focus_synthetic_accessibility(&mut self, _path: &[usize]) -> bool

Move this widget’s own immediate-mode focus to a synthetic semantic child. Retained widgets continue to use the ordinary taffy focus path.

fn accessibility_child_parent(&self, _child_index: usize) -> Option<usize>

Reparent one retained children entry beneath a synthetic child returned by accessibility. The returned index addresses AccessNode::children for this frame. Collections use this to place a real interactive row delegate inside its virtual ListItem/TreeItem instead of exporting a duplicate.

fn accessibility_child_path(&self, child_index: usize) -> Option<Vec<usize>>

Reparent one retained children entry beneath a nested path of synthetic children returned by accessibility.

fn accessibility_represents_child(&self, _child_index: usize) -> bool

Whether one retained children entry is already represented in this widget’s own synthetic accessibility tree, so the bridge must not export it a second time. A host that publishes a child’s semantics itself (to add its own controls inside the same dialog) answers true for that child; assistive technology then sees one copy, not two.

fn lays_out_child(&self, _child_index: usize) -> bool

Whether this widget lays one retained children entry out itself (an Embedded part of a painted page) rather than through the window’s layout, which then gives it no node. The accessibility walk reaches such a child, and every widget inside it, through this widget’s node.

fn accessibility_child_description(&self, _child_index: usize) -> Option<String>

What describes one retained children entry to assistive technology, when this widget holds the words for it: a row’s secondary line is its trailing switch’s description. The bridge sets it as that child’s node’s description unless the child describes itself.

fn perform_action( &mut self, _action: &Action, _key_path: &[u64], _state: &mut Edits<'_>, _path: &(dyn Any + 'static), ) -> bool

Perform an accessibility Action on this widget, or on one of its synthetic accessibility nodes. May mutate the CRDT like handle_event.

fn is_enabled(&self) -> bool

A disabled (false) widget is excluded from focus traversal, must reject input in handle_event, and renders dimmed (see DISABLED_ALPHA).

fn ime_requires_deferred_ack(&self) -> bool

This field needs a host that consumes deferred receipts. Ordinary native Wayland windows must not advertise it until they have that delivery path.

fn ime_refuses_ordinary_commits(&self) -> bool

Ordinary input-method commits (a composing keyboard IME, the on-screen keyboard) cannot reach this field: its text arrives only through deferred receipts (a browser page field), so hosts keep standard text input closed outside a dictation session. A field that needs deferred receipts for dictation but turns an ordinary commit into its own acknowledged edit (Terminal’s native editor) does not refuse them.

fn start_deferred_text(&mut self) -> Option<Receipt>

Begin one bounded deferred session after explicit host consent, preserving the existing original-field fingerprint. This grants no microphone access.

fn commit_deferred_text(&mut self, text: &str) -> Option<Receipt>

A private asynchronous final. None leaves ordinary synchronous IME dispatch to the host. A receipt binds this original field and must be acknowledged before the host releases its private recovery transcript.

fn ime_content(&self) -> Option<InputContent>

The focused widget wants platform text input (Wayland text-input-v3, native IMEs elsewhere). None is intentionally the default: enabling an IME for buttons, canvas tools or games makes the compositor raise an on-screen keyboard over content that cannot accept the committed text.

fn ime_multiline(&self) -> bool

Whether the original focused editor accepts line feeds as text. This is field policy, never inferred from a multiline accessibility presentation. Wrappers inherit only one unambiguous child at their active IME caret.

fn ime_edit_fingerprint(&self, key: &[u8; 32]) -> Option<[u8; 32]>

Opaque local invalidation of deferred input, including selection edits that leave the caret rectangle unchanged. The host supplies an ephemeral secret key; no text or selection is retained in the resulting digest. The default shares the accessibility door and excludes protected or read-only controls. Text controls can override it to avoid cloning text.

fn presented(&self) -> bool

Default true; false only for a widget standing in for a window’s content whose first frame has not drawn. Must latch: once true, never false again for the same content.

fn arrives_from(&self) -> Source

Where this content’s first frame comes from while it has not presented: this device (an app starting here), another device or a host. A frame from this device may hold the window’s first frame up to one frame budget; any other reserves the window’s place and says where it comes from after a while.

fn arrival_progress(&self) -> Option<Progress>

How much of what this content’s first frame waits on has come, when that measures itself (its app downloaded before it starts).

fn arrival_shape(&self) -> SkeletonShape

The shape this content declares for the placeholder standing in for its first frame. Undeclared, the placeholder is the ground alone: nothing guesses what a window will show.

fn text_review(&self) -> Option<(usize, String)>

(caret_byte, text), byte offset on a char boundary. The host diffs this before/after an event so caret-only moves (arrows, Home/End) get announced, not just typing.

fn on_external_event( &mut self, _payload: &str, _state: &mut Edits<'_>, _root: &(dyn Any + 'static), )

Delivers an out-of-band string payload from crate::app::UserEvent::External (e.g. a worker thread streaming output into a status log). Default no-op; the App redraws and re-syncs after dispatch, so mutating state here is enough.

fn on_nav_gesture( &mut self, dir: NavDirection, state: &(dyn Any + 'static), path: &(dyn Any + 'static), ) -> bool

Global back/forward gesture (swipe/edge-pull), recognised by crate::gesture::NavGestureRecognizer and delivered to the whole tree; return true once consumed. Default forwards to children, so a widget that owns history becomes swipe-navigable for free.

fn nav_availability(&self) -> NavAvailability

Which directions Self::on_nav_gesture would consume now. A widget that owns history overrides this beside on_nav_gesture.

fn take_focus_reset(&mut self) -> bool

One-shot (reading MUST clear it) signal to move focus to this subtree’s first focusable widget after the next rebuild. Only consulted under crate::app::App::autofocus_on_structure_change; a wizard raises it on step transitions.

fn take_accessibility_request(&mut self) -> Option<AccessibilityRequest>

One-shot (reading MUST clear it) request to change the window’s accessibility preferences, raised by a control the person used. The host applies it before the next frame. Default forwards the first request found among the children.

fn dev_route(&self) -> Option<RouteSnapshot>

Route history when this widget, or one it contains, is a Router.

fn restore_dev_route(&mut self, route: &RouteSnapshot) -> bool

Put route back. Returns whether a router in this subtree accepted it.

fn appearance_intent(&self) -> Option<AppearanceIntent>

Theme/high-contrast/reduced-motion/scale, polled under crate::app::App::appearance_reconcile — how a settings pane re-themes the running app live without a back-channel. Level-triggered; the App recurses Self::children itself, so containers need not forward it. First Some wins.

fn minimum_window_width(&self) -> Option<f64>

The narrowest this window still works at, in logical pixels: the minimum of its compact layout (a NavShell answers with one column at a time). The host states it to the window system, so the desktop stops a resize there. None: no opinion. The host walks the tree itself (minimum_window_width), so containers need not forward it; the first Some wins.

fn preferred_window_size(&self) -> Option<(f64, f64)>

The whole size this window wants, in logical pixels, when the app is the window’s only content and knows how big it must be: the on-screen keyboard parked to a strip. The host states it as the window’s minimum and maximum, so the desktop shapes the surface to it. None: the window is the user’s and the app lays itself out in whatever it gets.

fn needs_idle_sync(&self) -> bool

Whether sync still needs to run on idle frames without input or collab events — e.g. waiting out a document-adoption grace window.

fn disclosing(&self) -> Option<Disclosing>

While this widget is a band on its way in or out (motion::Disclosure: an in-window banner arriving or leaving), or a content-sized container one moves in, how far what follows it is drawn from where it is laid out. A moving band stands out of the layout; its container places it (Self::place_disclosing) and draws the widgets after it lower by transform, so they move with the band’s edge instead of being laid out again every frame. None at rest (the default).

fn place_disclosing(&mut self, _slot: Rect)

Where a band on its way (Disclosing::Band) stands while it is out of the layout: its slot’s top and width (slot’s height is zero), set by its container after each layout.

fn is_band(&self) -> bool

A band that comes and goes (an in-window banner): when its view stops building it, its column draws it leaving (widget::Disclosing). Its column leaves it out of its identity across rebuilds.

fn note_placement(&mut self, _placement: Placement)

Where a band stands in its column, set by the column after each layout: what it leaves when dropped, so the column a rebuild makes can draw it leaving.

fn animation_detail(&self) -> Option<String>

Why this widget itself asks for animation frames, for diagnostics that name a desktop which keeps painting. None when it has nothing to add to its name and geometry.

fn holds_frame_until(&self, now: Instant) -> Option<Instant>

Until when the frame that would show this subtree waits for data it reads from this device (crate::arriving): a local read that has not answered and is still inside its frame budget. The host keeps the frame on screen until then, or until the data lands, so the person never sees the space empty and then filled. Containers forward (the default does).

fn serve_deadline(&mut self, _now: Instant) -> bool

A deadline this subtree asked for (Self::next_wake_deadline) is due at now: do the work it was for, and say whether anything changed. The default says it did.

fn modal_capture(&self) -> Option<Rect>

Some(rect) when this subtree holds an open modal, its panel box. While any widget reports Some, the host suppresses its own global focus shortcuts and swallows unhandled pointer presses so nothing behind the modal is clickable. Containers MUST forward (the default does, via first Some among children).

fn dismiss_presented_modal(&mut self) -> bool

Close every modal this subtree presents, as its own way out does (a host whose surface is a modal sheet calls it when the shell takes the sheet down). Whether any was presented; containers forward.

fn presents_modal(&self) -> bool

Whether this subtree presents a modal still drawn (arriving, open or leaving): the counterpart of Widget::dismiss_presented_modal.

fn take_structure_dirty(&mut self) -> bool

True if this subtree’s structural composition changed since the last frame; reading clears it. The default drains every retained child and reports whether any was dirty.

fn take_structure_change(&mut self) -> StructureChange

Self::take_structure_dirty, saying whether the frame’s damage can still describe the rebuild (StructureChange::Described). Reading clears what take_structure_dirty clears; the two must agree on whether there is a change. The default is the flag, as a StructureChange::Rebuild: only a widget that knows every pixel its change touches lands in its own damage says less, and a container forwards a child’s StructureChange::Described only by overriding this.

fn remount_children(&mut self, remount: &mut Remount<'_>) -> bool

Carry out a StructureChange::Children this widget or one under it reported, in the retained layout tree, through remount (see remount). Returns false when it cannot be carried out in place: the host then rebuilds its tree, and the change is carried out by Self::build_layout. A widget reports such a change until either has carried it out. The default carries out its children’s.

fn has_pending_visual_work(&self) -> bool

Work already requested by this view whose completion will replace a placeholder. Unlike animations, this can be awaited by still captures.

fn has_transient_feedback(&self) -> bool

Temporary feedback currently presented, such as a save acknowledgement. Captures may intentionally include it; scene-invariance checks can wait for it to disappear separately from unfinished placeholder work.

fn collect_damage(&self, regions: &mut Vec<Rect>)

Logical-pixel bounds whose visual output differs from the last frame.

fn damage_covers_own_box(&self) -> bool

Whether, after this frame’s draw, this widget’s own Self::collect_damage covers every pixel a relayout changed by moving or resizing its layout box: a host that repaints where moved widgets were and are may then leave this widget’s box to it (its children’s boxes still count). A block editor that grew by a paragraph says where its blocks were and are; the default does not claim it.

fn mark_drawn(&mut self)

Called after this widget’s scene lands in the composed frame, to clear a dirty flag. Default forwards to children.

fn mark_children_drawn(&mut self)

Rest this widget’s children after a frame drew them, for a widget that keeps its own dirty flag: it clears the flag itself, then calls this.

fn release_scene_cache(&mut self)

Release retained encoded-scene storage in this subtree without marking its visual/model state dirty. Outer caches call this after a successful reuse: while the outer display list is authoritative, keeping byte-for-byte descendant encodings only duplicates memory. A later outer rebuild causes descendants to record/cache normally.

fn composition_follows_allocation(&self) -> bool

Whether this widget composes its children from the size it was last allocated (it reads its own rect while building its layout: a compact layout under a width, a count of columns, an inset from a drawer). A window resize then needs a second composition against the new allocation, as well as the re-solve every resize gets. Widgets that compose independently of their allocation, or that report take_structure_dirty themselves when a new allocation changes what they show, keep the default: a resize re-solves the retained tree in place instead of recomposing all of it.

fn layout_needs_measure(&self) -> bool

Whether a layout_dirty frame needs taffy to re-solve sizes (compute_layout) rather than just reposition already-solved boxes. Scrollable is the motivating override: it translates its origin in apply_layout without changing any taffy size, so re-solving on every scroll frame is pure waste.

fn paint_bounds(&self) -> Rect

Everything this widget paints, children included; draw_child skips the draw when it misses the viewport. Override for widgets that paint past their own rect.