Struct Ui 

pub struct Ui { /* private fields */ }

A tree of widgets: their layout, painting and events.

The Ui owns its widgets and lays them out with flexbox when their styles, contents or the viewport change. Every frame, paint draws them onto a Canvas, and the window layer feeds input through pointer, key and ime. Painting, hit-testing and delivering events do not allocate. Coordinates are physical pixels; Style lengths are logical pixels, multiplied by scale.

Implementations

impl Ui

pub fn access_id(&self, id: WidgetId) -> Option<AccessId>

The accessibility node id of widget id, if it lives.

pub fn access_tree(&mut self) -> AccessTree

The accessibility tree of the shown widgets, laid out first if needed. It allocates: build it only while assistive technology is listening.

pub fn access_action( &mut self, target: AccessId, action: AccessAction, value: Option<&str>, ) -> bool

Carries out assistive technology’s request to do action to node target, with value for AccessAction::SetValue; false if nothing did it: the widget is gone or not shown (a hidden widget is never acted on), or neither it nor, for scrolling, a parent handles it.

impl Ui

pub fn pointer(&mut self, event: PointerEvent) -> Handled

Delivers a pointer event.

A press goes to the topmost widget under the pointer, then up its parents until one handles it; that widget then holds the pointer: it alone gets the moves, any other press and the release, which ends the hold. A release no widget holds goes nowhere, so a press elsewhere never ends in another widget’s click. Moves and scrolls without a holder go to the widget under the pointer, then up. A press first focuses the nearest widget (from the one under the pointer up) that accepts focus. Hover follows the pointer, except while a widget holds it: Enter and Leave go to the topmost widget the pointer comes over and leaves (its parents see PaintCx::is_hovered).

Open popups are over everything. A press or a scroll outside all of them closes them and goes no further, unless it is on the widget that opened them: that widget gets it with the popups still open (a menu bar closing its menu, or switching to another), and they close only if it does not handle it. A secondary press also reports ActionKind::ContextMenu, except inside a popup (outside them it closes them and reports it for the widget under the pointer).

pub fn pointer_left(&mut self, position: Point)

The pointer left the window: nothing is hovered any more (unless a widget holds the pointer, which keeps it until the release).

pub fn cancel_pointer(&mut self)

The press in progress was cancelled, say because the window lost focus: the widget holding the pointer gets PointerKind::Cancel and lets it go, and nothing is hovered.

pub fn key(&mut self, event: &KeyEvent<'_>) -> Handled

Delivers a key event to the focused widget (the root if none), then up its parents until one handles it. An unhandled Tab moves focus to the next widget that accepts it (Shift+Tab to the previous), in tree order (within the topmost popup while popups are open). An unhandled context menu key (or Shift+F10) reports ActionKind::ContextMenu for the focused widget.

pub fn ime(&mut self, ime: &Ime<'_>) -> Handled

Delivers an input method event to the focused widget, then up its parents.

pub fn focus(&self) -> Option<WidgetId>

The widget with keyboard focus.

pub fn set_focus(&mut self, id: Option<WidgetId>)

Gives keyboard focus to id (None: to nobody), sending FocusLost and FocusGained. A removed or hidden widget gets nothing.

pub fn hovered(&self) -> Option<WidgetId>

The widget under the pointer, deepest first.

pub fn hit_test(&mut self, at: Point) -> Option<WidgetId>

The topmost visible widget at at: later children are over earlier ones, and a widget that clips hides its children outside it.

impl Ui

pub fn open_popup( &mut self, widget: impl Widget, anchor: Anchor, style: Style, ) -> Result<WidgetId, UiError>

Opens widget as a popup next to anchor, above every other widget, laid out by style (its position is made absolute: the anchor places it). It takes keyboard focus if it accepts it, and gives it back when it closes.

While popups are open, a press or a scroll outside all of them closes them all and goes no further; moves still reach the widgets under the pointer.

Errors

UiError::TooManyWidgets.

pub fn close_popup(&mut self, id: WidgetId) -> bool

Closes popup id and every popup opened after it. false if id is not open.

pub fn close_popups(&mut self)

Closes every popup (the window lost focus, or was resized).

pub fn popups(&self) -> impl Iterator<Item = WidgetId> + '_

The open popups, oldest first.

pub fn is_popup_open(&self, id: WidgetId) -> bool

Whether id is an open popup.

impl Ui

pub fn new(text: TextSystem) -> Self

An empty interface with the dark theme at scale 1, its root a column filling the viewport. text shapes every widget’s text.

pub fn root(&self) -> WidgetId

The root: a column filling the viewport, painted with the theme’s background.

pub fn add( &mut self, parent: WidgetId, widget: impl Widget, style: Style, ) -> Result<WidgetId, UiError>

Adds widget as the last child of parent, laid out by style.

Errors

UiError::NoSuchWidget if parent was removed, UiError::TooManyWidgets.

pub fn insert( &mut self, parent: WidgetId, index: usize, widget: impl Widget, style: Style, ) -> Result<WidgetId, UiError>

Adds widget as child number index of parent (past the end: the last), laid out by style.

Errors

UiError::NoSuchWidget if parent was removed, UiError::TooManyWidgets.

pub fn remove(&mut self, id: WidgetId) -> bool

Removes id and everything inside it; false if it was already gone, or is the root. An open popup is closed as close_popup closes it: with the popups opened after it, focus going back.

pub fn set_style(&mut self, id: WidgetId, style: Style) -> bool

Changes id’s style; false if it was removed.

pub fn style(&self, id: WidgetId) -> Option<&Style>

id’s style.

pub fn parent(&self, id: WidgetId) -> Option<WidgetId>

id’s parent; None for the root or a removed widget.

pub fn children(&self, id: WidgetId) -> &[WidgetId]

id’s children, first painted first; empty for a removed widget.

pub fn rect(&self, id: WidgetId) -> Option<Rect>

Where id is, in physical pixels from the window’s top-left corner, as of the last layout.

pub fn widget<T: Widget>(&self, id: WidgetId) -> Option<&T>

The widget id, if it is a T.

pub fn update<T: Widget, R>( &mut self, id: WidgetId, update: impl FnOnce(&mut T, &mut EventCx<'_>) -> R, ) -> Option<R>

Runs update on the widget id, if it is a T, with a context to request layout, paint or focus as an event handler would.

pub fn theme(&self) -> &Theme

The theme.

pub fn set_theme(&mut self, theme: Theme)

Changes the theme; widgets are measured again (sizes may differ).

pub fn clipboard(&mut self) -> &mut dyn Clipboard

The clipboard widgets copy to and paste from.

pub fn set_clipboard(&mut self, clipboard: impl Clipboard + 'static)

Gives widgets clipboard (the system’s, from a window) in place of the MemoryClipboard a Ui starts with.

pub fn scale(&self) -> f32

Physical pixels per logical pixel.

pub fn set_scale(&mut self, scale: f32)

Changes the scale factor (the window moved to a screen of another density).

pub fn viewport(&self) -> Size

The area the root fills, in physical pixels.

pub fn resize(&mut self, viewport: Size)

Changes the area the root fills (the window was resized).

pub fn text_system(&mut self) -> &mut TextSystem

The text system widgets shape their text with.

pub fn needs_paint(&self) -> bool

Whether something changed since the last paint.

pub fn cursor(&self) -> Cursor

The cursor to show: the one set by the widget under the pointer (or holding it), or its nearest parent that set one.

pub fn ime_area(&self) -> Option<Rect>

Where the focused widget wants input method candidates, if it does.

pub fn actions(&mut self) -> impl Iterator<Item = Action> + '_

The actions widgets reported and not yet read, oldest first, taken out.

pub fn next_action(&mut self) -> Option<Action>

The oldest action not yet read, taken out: lets the application act on each with the Ui at hand.

pub fn layout(&mut self)

Lays the widgets out if anything changed. paint and the event methods call it first; call it to read rects before painting.

pub fn paint(&mut self, canvas: &mut Canvas<'_>)

Paints every visible widget onto canvas, laying them out first if needed.

Trait Implementations

impl Debug for Ui

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

Formats the value using the given formatter.