Struct Ui 

pub struct Ui<'s, 'g, Id> { /* private fields */ }

One frame’s drawing surface and interaction state, together, so a call site names an area/id once and gets both hit-testing and drawing from it: see show.

Why two lifetimes

Surface<'g> holds a &'g mut Grid, which makes Surface invariant in 'g: nothing can shrink or otherwise reinterpret that lifetime once it is fixed. The surface borrow and the grid borrow are therefore kept as two separate lifetime parameters here, 's (how long this Ui itself, and the &'s mut Surface it holds, lives) and 'g (how long the underlying grid is borrowed for). Collapsing them into one, e.g. writing the field as &'a mut Surface<'a>, forces 'a to cover both uses at once: the invariance in 'g then makes the borrow of the surface last exactly as long as the grid borrow it is invariant over, so the surface (and the grid behind it) stay borrowed, and therefore unusable, for the rest of 'a even after the Ui that held them is dropped. Two parameters let 's end (releasing the Ui’s borrow of the surface) while 'g keeps going, which is exactly what Interaction::frame relies on: the surface passed in is usable again once the closure returns.

Implementations

impl<'s, 'g, Id> Ui<'s, 'g, Id>

pub const fn new( surface: &'s mut Surface<'g>, interaction: &'s mut Interaction<Id>, ) -> Self

A Ui pairing surface with interaction for one frame, enabled.

The low-level constructor; prefer Interaction::frame, which builds this and runs the frame lifecycle for you.

pub const fn is_enabled(&self) -> bool

Whether show/show_stateful/region calls through this context report their widgets as enabled: retroglyph#602.

pub const fn surface(&mut self) -> &mut Surface<'g>

The surface, for drawing that no widget in this crate covers.

pub const fn interaction(&mut self) -> &mut Interaction<Id>

The interaction context, for hit-testing/focus queries no method here covers.

pub const fn area(&self) -> Rect

The region this Ui’s surface represents; see Surface::area.

impl<'g, Id: Copy + PartialEq> Ui<'_, 'g, Id>

pub const fn enabled(&mut self, enabled: bool) -> Ui<'_, 'g, Id>

A child context whose show/show_stateful/ region calls report enabled: retroglyph#602.

Nesting only ever tightens: a child of a context already disabled via enabled(false) stays disabled regardless of what enabled this call passes, matching how egui’s and Dear ImGui’s disabled scopes compose.

The returned Ui never inherits an active vertical/ horizontal cursor, even if self has one: call show_sized/draw_sized/etc. directly on the cursor Ui, and reach for enabled on the widget-level show/show_stateful instead if you need both.

pub fn show( &mut self, area: Rect, id: Id, widget: &impl InteractiveWidget<Id, State = ()>, ) -> Response<Id>

Hit-test area for id with widget’s own Sense, then draw widget into area.

This is the one-id-one-area guarantee the InteractiveWidget/Ui split exists for: area is registered for hit-testing and used to scope the surface the widget draws into from the same value, so the two cannot disagree.

If this context is disabled, the returned Response still reports hovered but never an activation: see Sense::DISABLED.

pub fn show_stateful<W: InteractiveWidget<Id> + ?Sized>( &mut self, area: Rect, id: Id, widget: &W, state: &mut W::State, ) -> Response<Id>

Like show, for an InteractiveWidget with externally owned state.

pub fn draw(&mut self, area: Rect, widget: &impl Widget)

Draw a non-interactive widget into area.

pub fn draw_stateful<W: StatefulWidget + ?Sized>( &mut self, area: Rect, widget: &W, state: &mut W::State, )

Like draw, for a StatefulWidget with externally owned state.

pub fn region( &mut self, area: Rect, id: Id, sense: Sense, ) -> (Response<Id>, Surface<'_>)

Register area for id with sense, and hand back both the resolved Response and a surface scoped to area, for drawing this crate has no widget for.

Like show, area is committed once, by this call, for both hit-testing and drawing, so the two cannot disagree.

pub fn modal<R>( &mut self, area: Rect, f: impl FnOnce(&mut Ui<'_, 'g, Id>) -> R, ) -> R

Run f with a Ui whose widgets sit above everything shown so far, and whose pointer hits inside area never reach a widget registered before f (a menu bar, the screen behind a dropdown, …), so an app doesn’t have to answer “is the thing under this overlay still supposed to see this event” with its own bookkeeping. A widget registered after f still wins inside area, so an overlay has to be shown after the content it covers, not before it.

The barrier is scoped to area: a pointer outside it reaches whatever’s registered outside f exactly as if modal hadn’t been called. A modal claims the region it covers, not the whole screen; pass a full-screen area for a blocking overlay. Drawing is unaffected either way, f’s Ui still draws to this Ui’s full surface unless it also narrows with show/draw/scope itself: modal only changes hit-testing.

pub fn vertical<R>(&mut self, f: impl FnOnce(&mut Ui<'_, 'g, Id>) -> R) -> R

Run f with a fresh vertical cursor claiming whatever’s left: the rest of this Ui’s own cursor if it has one (so a vertical nested inside a horizontal row claims that row’s remaining width), or the whole of area if it doesn’t (a vertical called directly inside Interaction::frame, say).

Widgets shown/drawn through the closure’s Ui via show_sized/ draw_sized/show_auto/ draw_auto stack top-to-bottom, each claiming a horizontal strip of the cursor’s remaining area sized by an explicit height or, for show_auto/draw_auto, by Measure::height_for, and advancing the cursor by that strip’s height, so the call site never computes a Rect by hand. Content past the bottom of the cursor’s area clips, the same way split_v clips a pane that overflows area.

Nests with horizontal: the Ui handed to f is a plain Ui, so it can call vertical/horizontal again to start a flow along the other axis, scoped to whatever this cursor has left at that point.

pub fn horizontal<R>(&mut self, f: impl FnOnce(&mut Ui<'_, 'g, Id>) -> R) -> R

Like vertical, stacking left-to-right instead of top-to-bottom.

pub fn vertical_sized<R>( &mut self, height: u16, f: impl FnOnce(&mut Ui<'_, 'g, Id>) -> R, ) -> R

Like vertical, but claims only height rows of this Ui’s own cursor (clipped to whatever’s left) instead of everything remaining, so a fixed-size nested flow (a one-row-tall horizontal button bar inside a vertical column, say) leaves the rest of the outer cursor for whatever comes after it.

Panics

If this Ui has no active cursor: see vertical.

pub fn horizontal_sized<R>( &mut self, width: u16, f: impl FnOnce(&mut Ui<'_, 'g, Id>) -> R, ) -> R

Like vertical_sized, claiming width columns instead of height rows.

Panics

If this Ui has no active cursor: see vertical.

pub fn show_sized( &mut self, id: Id, widget: &impl InteractiveWidget<Id, State = ()>, size: u16, ) -> Response<Id>

Like show, but allocates the area from this Ui’s own cursor instead of taking one explicitly: size is a height on a vertical cursor, a width on a horizontal one, clipped to whatever’s left (like split_v/split_h), and the cursor advances by that amount so the next show_sized/draw_sized/show_auto/draw_auto call claims the space right after it.

Panics

If this Ui has no active cursor: see vertical.

pub fn draw_sized(&mut self, widget: &impl Widget, size: u16)

Like draw, sized from this Ui’s own cursor; see show_sized.

Panics

If this Ui has no active cursor: see vertical.

pub fn show_auto( &mut self, id: Id, widget: &(impl InteractiveWidget<Id, State = ()> + Measure), ) -> Response<Id>

Like show_sized, sized by Measure::height_for instead of an explicit size, for a widget that can report its own height.

Panics

If this Ui has no active cursor, or its cursor is horizontal: Measure::height_for takes a width, so a horizontal cursor has nothing to size a column by.

pub fn draw_auto(&mut self, widget: &(impl Widget + Measure))

Like draw_sized, sized by Measure::height_for instead of an explicit size; see show_auto.

Panics

If this Ui has no active cursor, or its cursor is horizontal.