Struct PaintCx 

pub struct PaintCx<'a> { /* private fields */ }

Painting context: draws into the frame, clipped to the widget’s visible area.

Implementations

impl PaintCx<'_>

pub fn animation( &mut self, name: &str, style: CellStyle, since: Option<Duration>, ) -> AnimatedCell

The cell the animation name shows now, drawn in style: frames without a colour, and $fg in colour expressions, take style.fg. Draw it with PaintCx::text in one cell.

since is when the animation started on the PaintCx::now clock; looping indicators pass Some(Duration::ZERO) so they turn in step with every other one, and None shows the rest frame. With reduced motion the rest frame always shows. Schedules the next frame exactly when the frame changes, and smooth frames while a colour pulses or blends. An unknown name draws ⟦name⟧, cut to the cell, like a missing icon.

fn paint_busy_mark(cx: &mut PaintCx<'_>, area: Rect) {
    let style = cx.style("spinner", None, &[]).text();
    let cell = cx.animation("spinner-pulse", style, Some(Duration::ZERO));
    cx.text(area.x, area.y, &cell.glyph, cell.style, 1);
}

impl PaintCx<'_>

pub fn floating(&mut self, rect: Rect, paint: impl FnOnce(&mut Self))

Paints a floating surface such as a menu, popover or tooltip over rect with paint, and keeps it apart from what lies around it.

Before paint runs, the ring of cells just outside rect is read; every background covering at least a quarter of it is a ground. After paint, when the background most cells of rect show sits closer to a ground than a barely visible step (0.05 in OKLab), every background inside rect is blended by the same small amount towards the theme’s text or canvas colour, whichever clears every ground sooner, at most 30%. Text colours are kept, and the surface’s own ladder (a highlighted row, a checked row) moves with it, so it stays as distinct as before. A surface over the screen ground keeps its tone; one opened over a panel of nearly the same tone steps lighter on a dark theme and darker on a light one. Nothing moves in 256 and 16 colours, where the screen holds only palette entries.

Overlays paint after the view (see PaintCx::request_overlay), so call this from Widget::paint_overlay, where the cells around rect already show what the surface floats over.

impl PaintCx<'_>

pub fn id(&self) -> WidgetId

The id of the widget being painted.

pub fn env(&self) -> &Env

The environment.

pub fn layout(&self) -> LayoutProps

Layout properties of the widget being painted.

pub fn now(&self) -> Duration

Time since the runtime started; drives animations.

pub fn is_hovered(&self) -> bool

Whether the pointer is over this widget.

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

The widget that has keyboard focus, if any.

pub fn pointer_anywhere(&self) -> Option<(i32, i32)>

The pointer cell wherever it is on screen, unlike PaintCx::pointer.

pub fn request_focus_within(&mut self, ancestor: WidgetId)

Once this frame is painted, moves keyboard focus to the first focusable widget inside ancestor, unless focus is already inside. Used by layers that take focus when they open.

pub fn request_focus(&mut self, id: WidgetId)

Once this frame is painted, moves keyboard focus to id if that widget is focusable. Used by layers to give focus back when they close.

pub fn register_dismissable(&mut self)

Makes this widget a dismissable layer for this frame: a pointer press outside it and its descendants sends it Event::PointerOutside and then still reaches what was pressed, unless that is the widget whose press opened the layer (then the press only closes it); an Esc key no focused widget used is sent to it. Layers registered later are on top and are asked first. Dismissable layers share the layer stack with modal layers (PaintCx::open_layer): a press on a modal layer above a dismissable one lands inside the modal layer, so the dismissable layer beneath stays.

pub fn is_focused(&self) -> bool

Whether this widget has keyboard focus.

pub fn is_focus_visible(&self) -> bool

Whether this widget has focus that should be shown loudly: it was reached with the keyboard rather than clicked. Buttons and cards breathe their pillar only then, so a clicked button stays calm under the pointer.

pub fn pointer(&self) -> Option<(i32, i32)>

The pointer cell, when the pointer is over this widget.

pub fn is_pressed(&mut self) -> bool

Whether this widget is flashing after being activated. Schedules the frame that ends the flash.

pub fn pressable_states(&mut self) -> Vec<State>

Hover, focus and pressed states of a pressable widget such as a button, card, tab or toggle: like states, but focus counts only when it is visible, so a clicked control stays calm under the pointer.

pub fn states(&mut self) -> Vec<State>

Hover, focus and pressed states of this widget.

pub fn style( &mut self, widget: &str, variant: Option<&str>, states: &[State], ) -> WidgetStyle

The theme style of widget.variant in states, evaluated for this frame. Animated styles schedule the next frame.

pub fn color(&self, token: &str) -> Rgb

A theme colour token such as "accent"; black when the token does not exist.

pub fn request_frame_in(&mut self, delay: Duration)

Asks for another frame after delay.

pub fn reduced_motion(&self) -> bool

Whether the user asked for reduced motion; animations should show their end state.

pub fn animate( &mut self, name: &'static str, target: f32, duration: Duration, easing: Easing, ) -> f32

A value of this widget that moves towards target over duration. The value named name starts at its first target without animating; later target changes animate from wherever the value is. Schedules frames while it moves; returns target at once when motion is reduced.

pub fn progress_since( &mut self, start: Duration, duration: Duration, easing: Easing, ) -> f32

Eased progress from 0 to 1 of something that started at start (a time from PaintCx::now or EventCx::now) and takes duration. Schedules frames until it completes; is 1 at once when motion is reduced.

pub fn cycle(&mut self, period: Duration) -> f32

Where a repeating animation of length period is, 0.0..1.0. Schedules smooth frames; always 0 when motion is reduced.

pub fn ticks(&mut self, interval: Duration) -> u128

How many whole intervals have passed, for animations that jump between frames such as spinners. Schedules a frame exactly at the next step; always 0 when motion is reduced.

pub fn pulse_phase(&self) -> f32

Where the theme pulse is, 0.0..1.0; always 0 when motion is reduced.

pub fn clip(&self) -> Rect

The visible area of this widget.

pub fn register_hit(&mut self, rect: Rect)

Makes rect clickable for this widget. Later registrations are on top.

pub fn unselectable(&mut self, rect: Rect)

Keeps mouse text selection from starting in rect, even inside a selectable area, e.g. for a secret shown in a selectable log.

pub fn selectable(&mut self, rect: Rect)

Makes the visible part of rect a text selection region of this widget: a mouse drag that starts inside it, and that no widget uses, selects text, and the selection stays within this widget. Nothing is selectable unless a widget or NodeMut::selectable asks; widgets whose text is content to copy (code, documents, terminal output) call this while painting. The innermost region under a press wins.

pub fn decoration(&mut self, rect: Rect)

Marks the cells of rect as decoration rather than content, such as a scrollbar a widget draws itself: a clean copy of a text selection leaves them out, a raw copy keeps them. PaintCx::pillar marks its cell by itself.

pub fn track_pointer_moves(&mut self)

Asks for MouseKind::Moved events in this frame: the pointer moving with no button held over this widget’s hit area, or over a child of it. Other widgets never see plain moves. Widgets that follow the pointer without a button, such as an embedded terminal whose program asked for every motion, call this while painting, and only while they need it.

pub fn register_focusable(&mut self)

Adds this widget to the keyboard focus order.

pub fn request_overlay(&mut self, anchor: Rect)

Paints this widget’s overlay after the rest of the view.

pub fn open_layer(&mut self) -> Duration

Makes this widget a modal layer for this frame and returns the time the layer opened.

Call it from Widget::paint_overlay every frame the layer is shown, before painting what is inside it. Modal and dismissable layers (PaintCx::register_dismissable) share one stack in paint order; the rules of a modal layer are:

• Focus stays inside. Each frame the layer asks, like PaintCx::request_focus_within, for focus to be inside it; a request made later in the frame by a widget inside the layer (a popover opening) wins. Tab and Shift+Tab cycle only through the layer’s widgets.
• Input stops at the layer. Keys and pointer events bubble from their target up to the topmost modal layer and no further; a press outside it lands on the layer itself. Paint a hit area over the whole screen and use presses on it, so nothing beneath reacts and no text selection starts there.
• Shortcuts pause. Application keymap actions (and global ones the runtime passes to the application) do not run; quit, focus moves, debug, copy and paste still do. Key listeners outside the layer are not heard.
• Above it: dismissable layers opened inside it, later modal layers, and the runtime’s toasts, which stay clickable.
• Focus comes back. When the layer is no longer painted, the runtime requests focus for the widget that had it when the layer opened.

The opening time stays the same for as long as the layer is shown, which makes it the start of an entrance animation, even for layers inside persistent pages.

pub fn listen_key(&mut self, chord: KeyChord)

Delivers chord to this widget even when it is not focused, for as long as the widget is painted: after the focused widgets had their chance and before the keymap. Repeats and releases of the key (which keyboards report while it is held) are delivered too, including repeats of Enter and Space that focused widgets never see. Inside a modal layer only listeners within the topmost layer hear keys.

pub fn reveal(&mut self, rect: Rect)

Asks the nearest ScrollView around this widget to scroll just enough to show rect, a part of this widget’s area, e.g. a line a code view jumps to. The view glides there, or jumps when motion is reduced. Ask once when what should be shown changes, not every frame, or the user could not scroll away from it.

pub fn tint(&mut self, rect: Rect, color: Rgb, amount: f32)

Blends the text and background colours already drawn in rect towards color by amount (0 keeps them, 1 replaces them), e.g. to dim the screen behind a dialog. Cells drawn with reduced colour depth take color once amount passes one half.

pub fn memory<T: Default + 'static>(&mut self) -> &mut T

This widget’s state of type T.

pub fn fill(&mut self, rect: Rect, color: Rgb)

Fills rect with color, keeping text.

pub fn clear(&mut self, rect: Rect, color: Rgb)

Clears rect to spaces on color.

pub fn pillar(&mut self, x: i32, y: i32, color: Rgb)

Draws the theme’s pillar ([icons] pillar, e.g. ▌) at (x, y) in color, over whatever surface is already there. A blank glyph, as in ASCII mode, becomes a cell of color. The cell is decoration: clean copies of a text selection skip it.

pub fn text( &mut self, x: i32, y: i32, text: &str, style: CellStyle, max: u16, ) -> u16

Draws text starting at (x, y), at most max cells wide, clipped to the visible area. Returns the number of cells the text occupies (before clipping).

pub fn paint_child<M: 'static>(&mut self, node: &Node<M>, rect: Rect)

Paints a child node into rect, applying its padding.

pub fn paint_child_unfocusable<M: 'static>( &mut self, node: &Node<M>, rect: Rect, )

Paints a child node that does not take keyboard focus itself, not even when it is normally focusable. For composite widgets that take focus as one control and pass keys on to the child with EventCx::forward, such as a settings row’s switch.

pub fn pointer_within(&self) -> Option<(i32, i32)>

The pointer cell, when the pointer is over this widget or over a widget inside it, for containers whose rows light up while the pointer is on a control within them.

pub fn has_focus_within(&self) -> bool

Whether keyboard focus is on this widget or on a widget painted inside it so far in this frame. Paint children before asking, e.g. to brighten a field label while its control has focus.

pub fn measure_child<M: 'static>( &mut self, node: &Node<M>, available: Size, ) -> Size

Measures a child node with the same rules as layout.

pub fn with_clip(&mut self, rect: Rect, paint: impl FnOnce(&mut Self))

Runs paint with drawing limited to rect (and the current visible area).