Struct NodeSpec 

pub struct NodeSpec {

    pub layout: LayoutSpec,
    pub style: VisualStyle,
    pub hoverable: bool,
    pub animate: bool,
    pub accent: bool,
    pub window: Option<WindowRole>,
    pub transition: Option<Transition>,
    pub slide: bool,
    pub focusable: bool,
    pub initial_focus: bool,
    pub disabled: bool,
    pub cursor: Option<CursorShape>,
    pub events: Option<Box<EventSpec>>,
    pub anim: Option<Box<AnimSpec>>,
    pub access: Option<Box<AccessSpec>>,
    pub interact: Option<Box<InteractSpec>>,
}

Everything one node declares. This, not any Rust trait, is the contract every frontend (Rust builders, Lua, JSX, C) lowers into. Start from NodeSpec::row, NodeSpec::column or NodeSpec::table and chain builders; see the module docs for an example.

Fields

layout: LayoutSpec

style: VisualStyle

hoverable: bool

Track pointer hover for this node (Ui::is_hovered) without making it clickable — tooltips on passive badges. Nodes with on_click / on_key / window are always hover-tracked; clicks on a merely hoverable node emit nothing.

animate: bool

Ask the driver for another frame after this one, every frame this node is declared (animate). What a fragment reading time needs; opt-in, because it takes the loop off input-driven.

accent: bool

Paint this node’s background in the theme’s accent: the OS’s where the host reported one, the app’s where it pinned one, kui’s blue otherwise. A view says that this node is the accented one and the palette says which colour that is. The stock button also repaints its hover, pressed shade and label from the same accent.

window: Option<WindowRole>

Window-chrome role (drag handle / window button). A chrome node’s interactions become WindowCommands for the frame driver instead of UiEvents; on_click is ignored on such nodes.

transition: Option<Transition>

Eases this node’s sizing amounts, colors and radius toward what the view declares instead of snapping (see crate::anim). Keyed by node identity, so the node needs a stable key across frames.

slide: bool

With transition: also ease this node’s laid-out position, moving its whole subtree — reordered siblings slide into their new slots. Opt-in because a node whose position follows an already-easing sibling (a split’s second half) would lag twice.

focusable: bool

Reachable by Tab, and focused by a click or an assistive-technology request, without a click payload or a control role — a list row that opens on Enter, a card. Controls (editors, key sinks, on_click boxes, the control roles) are focusable already.

initial_focus: bool

Where focus lands when the modal scope containing this node is entered: the first node in the modal’s Tab ring declaring it, instead of simply the ring’s first — a destructive confirm opening on its Cancel rather than on whichever control is declared first. Read on entry only, so a Tab press afterwards stands; a node the ring skips (disabled, decoration, not focusable) is not a candidate, and with no candidate the entry is the ring’s first node as before.

disabled: bool

Inert: keeps its hit region (so a tooltip can say why) and loses everything else — no click, drag or key sink, no hover / pressed / focus background, no place in the Tab ring; the access tree reports it disabled.

cursor: Option<CursorShape>

The pointer shape over this node (see crate::cursor). Unset, the pointer is the I-beam over an editor or a selection scope and the plain arrow over everything else — a clickable or draggable node included — so a hand over a button, a grab over a handle (grabbing while its drag runs), a splitter’s resize arrows and a disabled control’s notAllowed are all the view’s to declare. The stock button declares Pointer itself.

events: Option<Box<EventSpec>>

See EventSpec. None when the node declares none of it.

anim: Option<Box<AnimSpec>>

See AnimSpec. None when the node declares none of it.

access: Option<Box<AccessSpec>>

See AccessSpec. None when the node declares none of it.

interact: Option<Box<InteractSpec>>

See InteractSpec. None when the node declares none of it.

Implementations

impl NodeSpec

pub fn events(&self) -> &EventSpec

Event payloads this node declares, empty if it declares none.

pub fn events_mut(&mut self) -> &mut EventSpec

Allocates the group on first write.

pub fn anim(&self) -> &AnimSpec

Animation declarations, empty if this node has none.

pub fn anim_mut(&mut self) -> &mut AnimSpec

Allocates the group on first write.

pub fn access(&self) -> &AccessSpec

Declared accessibility properties, empty if this node declares none.

pub fn access_mut(&mut self) -> &mut AccessSpec

Allocates the group on first write.

pub fn interact(&self) -> &InteractSpec

Hover / pressed / focus styling, empty if this node declares none.

pub fn interact_mut(&mut self) -> &mut InteractSpec

Allocates the group on first write.

pub fn hover_tracked(&self) -> bool

Whether the core registers a hit region for this node (any of the interaction props, or an explicit hoverable).

pub fn hover_group_id(name: &str) -> u64

The group id hover_group(name) assigns — reproducible from any binding (the same FNV mix as Key).

pub fn row() -> Self

A container that lays its children out left to right.

pub fn column() -> Self

A container that lays its children out top to bottom (the default).

pub fn table() -> Self

A table: a column whose rows’ children line up in columns. Its in-flow Row children are the rows and each row’s in-flow children its cells; the nth cell of every row is column n, and a column is as wide as its widest cell, so a label column sits at its longest label with no width picked by hand.

A cell’s width says how its column sizes: Fit (the default) and Fixed are content the column’s fit width is the max of, Grow makes the whole column grow with the table, and a column’s min_width / max_width are the strictest its cells declared. Give the rows width: grow for the columns to grow into; a Fit row sits at the columns’ fit width. Rows keep their own gap, padding, background, click and hover, and never wrap. A bare text or image straight inside a row is a cell too. A text, a column or a table straight under the table is a child with its own width and no cells. Everything else is a column’s: gap is the space between rows, scroll_y scrolls them.

use kui_core::{NodeSpec, Sizing};
let table = NodeSpec::table().gap(4.0).rules(kui_core::Color::hex(0x80808080));
let row = NodeSpec::row().width(Sizing::GROW).gap(12.0);
assert!(table.layout.is_table() && !row.layout.is_table());

pub fn width(self, s: impl Into<Sizing>) -> Self

A Sizing, or a number of px (.width(120.0)).

pub fn height(self, s: impl Into<Sizing>) -> Self

A Sizing, or a number of px (.height(24.0)).

pub fn size(self, w: impl Into<Sizing>, h: impl Into<Sizing>) -> Self

Both axes at once: .size(20.0, 20.0) for a fixed box, .size(Sizing::GROW, 24.0) for a strip.

pub fn grow_width(self) -> Self

An equal share of the leftover width: .width(Sizing::GROW).

pub fn grow_height(self) -> Self

An equal share of the leftover height: .height(Sizing::GROW).

pub fn fill(self) -> Self

Grow along both axes.

pub fn min_width(self, v: impl Into<Bound>) -> Self

A number of px, Min::FIT for the node’s own fit width, or a Bound::Calc.

pub fn max_width(self, v: impl Into<Bound>) -> Self

A number of px, or a Bound::Calc; a max has no fit size, so Bound::Fit is no clamp. A px ceiling below zero, or NaN, is a ceiling of 0 (px_ceiling).

pub fn min_height(self, v: impl Into<Bound>) -> Self

A number of px, Min::FIT for the node’s own fit height, or a Bound::Calc.

pub fn with_bounds( self, min_w: Option<Bound>, max_w: Option<Bound>, min_h: Option<Bound>, max_h: Option<Bound>, ) -> Self

The four clamps where each is given, a transport’s shape (C’s *_size fields): None leaves that clamp as it is.

pub fn clip(self) -> Self

Clip children to this node’s rect without scrolling. A radius on the same node rounds the clip, so children stay inside its corners (see display::Clip).

pub fn scroll_y(self) -> Self

Vertical scrolling (and clipping) for overflowing content.

pub fn scroll_x(self) -> Self

Horizontal scrolling (and clipping) for overflowing content.

pub fn anchor(self) -> Self

Scroll anchoring on this container (see LayoutSpec::anchor): the first child in view stays where it is on screen when the content before it changes size. Needs scroll_y on a column or scroll_x on a row.

pub fn float(self, cfg: FloatConfig) -> Self

Take this node out of flex flow; see FloatConfig.

pub fn overflow_bits(self, bits: u32) -> Self

Apply the overflow bits (OVERFLOW_CLIP and friends). What a bit means is decided here: a binding ORs together whatever its own surface spells (clip, scrollX, overflow) and hands the number over, rather than each one re-deciding that scrolling clips too.

pub fn tooltip(self, hint: &str) -> Self

A tooltip: the node tracks hover, hint is its accessible description, and the core floats the hint below it while it is hovered. On a box or a fragment the float is the node’s last child; on a leaf — an image, an editor, a cells grid, a line, a polygon, a path — which holds no children, it floats beside the leaf, anchored to it (FloatAnchor::Node), and lands below the leaf’s box all the same (backlog RG113).

pub fn apply_tooltip(self, hint: &str) -> Self

The spec half of the tooltip prop: the hint is hover-gated, so the node tracks hover, and it is what assistive technology should say, so it is the accessible description too — and nothing floats. For a caller that floats the hint itself: crate::schema::PropsOut::apply_tooltip for the parsers, kui_close for C, a widget that draws its own. A Rust view wants Self::tooltip, which is all three.

pub fn max_height(self, v: impl Into<Bound>) -> Self

A number of px, or a Bound::Calc; Bound::Fit is no clamp. A px ceiling below zero, or NaN, is a ceiling of 0.

pub fn pad(self, v: f32) -> Self

The same padding on all four edges, logical px.

pub fn pad_xy(self, x: f32, y: f32) -> Self

Padding x on the left and right, y on the top and bottom.

pub fn padding(self, e: Edges) -> Self

Padding per edge.

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

Space between children along the main axis, logical px.

pub fn wrap(self) -> Self

Wrap overflowing children onto more lines; see LayoutSpec::wrap.

pub fn cross_gap(self, v: f32) -> Self

Space between wrap lines (across the main axis).

pub fn main_align(self, a: Align) -> Self

Where children sit along the main axis; the spreads are allowed.

pub fn cross_align(self, a: Align) -> Self

Where children sit across the main axis; Baseline on a row.

pub fn aspect_ratio(self, ratio: f32) -> Self

Width over height (CSS’s aspect-ratio): see LayoutSpec::aspect. 16.0 / 9.0 for a video, 1.0 for a square. A ratio that is not positive and finite clears it.

pub fn center(self) -> Self

Center children on both axes.

pub fn bg(self, c: Color) -> Self

The background colour.

pub fn radius(self, r: f32) -> Self

Rounds all four corners by r. On a node that also clips or scrolls it rounds the clip too, so its children are cut to the same corners rather than poking square out of them.

pub fn radii(self, tl: f32, tr: f32, br: f32, bl: f32) -> Self

Per-corner radii, clockwise from the top-left.

pub fn radius_tl(self, r: f32) -> Self

pub fn radius_tr(self, r: f32) -> Self

pub fn radius_br(self, r: f32) -> Self

pub fn radius_bl(self, r: f32) -> Self

pub fn radius_top(self, r: f32) -> Self

Rounds the two top corners (tabs, headers).

pub fn radius_bottom(self, r: f32) -> Self

Rounds the two bottom corners.

pub fn border(self, w: f32, c: Color) -> Self

A border w px wide in c, inside the node’s box.

pub fn pixel_snap(self) -> Self

Paints this node’s background, border, shadow and fragment on whole pixels (see VisualStyle::pixel_snap).

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

Fades this node and everything under it (see VisualStyle::opacity); clamped to 0..=1.

pub fn shadow(self, shadow: Shadow) -> Self

The whole drop shadow at once: color, offset, blur, spread.

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

The shadow’s color — on its own, a hard shadow exactly behind the node. Nothing else about a shadow draws without it.

pub fn shadow_blur(self, blur: f32) -> Self

pub fn shadow_offset(self, dx: f32, dy: f32) -> Self

pub fn shadow_x(self, dx: f32) -> Self

pub fn shadow_y(self, dy: f32) -> Self

pub fn shadow_spread(self, spread: f32) -> Self

pub fn hoverable(self) -> Self

Hover-track this node without making it clickable; see the hoverable field.

pub fn animate(self) -> Self

Ask for another frame after this one, for as long as this node is declared. See the animate prop.

pub fn accent(self) -> Self

Background from the OS accent colour where the host knows it; see the field.

pub fn on_click(self, payload: impl Into<Value>) -> Self

Makes this node clickable: a click emits payload as a UiEvent, and the node joins the Tab ring and reads as a button to assistive technology.

pub fn hover_bg(self, c: Color) -> Self

Background while hovered (see the hover_bg field).

pub fn drop_bg(self, c: Color) -> Self

Background while dragged files are over this node (see the drop_bg field).

pub fn gradient(self, gradient: Gradient) -> Self

Paints gradient over this node’s bg, under its border and its children (see the gradient field).

pub fn backdrop_blur(self, radius: f32) -> Self

Blurs what was drawn beneath this node, inside its rounded rect, by radius logical px (see the backdrop_blur field). A translucent bg over it makes frosted glass:

let bar = NodeSpec::row().backdrop_blur(16.0).bg(Color::hex(0xffffff40));
assert_eq!(bar.interact().backdrop_blur, 16.0);

pub fn rules(self, c: Color) -> Self

A table’s grid rules in c (see the rules field).

pub fn rule_width(self, w: f32) -> Self

The rules’ width in logical px; 1 when unset (see rules).

pub fn selectable(self) -> Self

Makes this node a selection scope (see the selectable field): the text inside it becomes one selectable run.

pub fn focus_region(self) -> Self

Makes this node’s subtree a focus region (see the focus_region field): a Tab ring of its own, entered on purpose.

pub fn overscroll(self, o: Overscroll) -> Self

Whether a scroll gesture starting over this scroller at its limit goes on to the one around it (see Overscroll): Overscroll::Contain keeps it here.

pub fn scrollbar(self, mode: ScrollbarMode) -> Self

When this node’s scrollbars are drawn (see ScrollbarMode). Scrolling itself is unchanged whatever the mode.

pub fn scrollbar_width(self, w: f32) -> Self

The thumb’s width at rest, logical px (see Scrollbar::width).

pub fn scrollbar_color(self, c: Color) -> Self

The thumb’s colour at rest (see Scrollbar::color).

pub fn scrollbar_active_color(self, c: Color) -> Self

The thumb’s colour under the pointer or dragged (see Scrollbar::active_color).

pub fn pressed_bg(self, c: Color) -> Self

Background while pressed (see the pressed_bg field).

pub fn focus_bg(self, c: Color) -> Self

Background while keyboard-visibly focused (see the focus_bg field); replaces the default focus ring.

pub fn focusable(self) -> Self

Puts this node in the Tab ring (see the focusable field).

pub fn on_focus(self, tag: impl Into<Value>) -> Self

Hears focus entering and leaving this subtree (see the on_focus field).

pub fn keep_focus(self) -> Self

A press here leaves keyboard focus where it was (see the keep_focus field).

pub fn initial_focus(self) -> Self

Makes this node the modal scope’s entry focus (see the initial_focus field).

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

Makes this node inert (see the disabled field).

pub fn modal(self, tag: impl Into<Value>) -> Self

Makes this node the frame’s modal surface (see the modal field).

pub fn hover_group(self, name: &str) -> Self

Joins the hover group name (see the hover_group field).

pub fn on_hover(self, tag: impl Into<Value>) -> Self

Emits enter/leave events for this node (see the on_hover field). Pass a tag the handler can match on; Value::Null if the node key is identification enough.

pub fn on_drop(self, tag: impl Into<Value>) -> Self

Makes this node a drop zone for files dragged in from the OS (see the on_drop field).

pub fn click_sound(self, sound: SoundId) -> Self

Plays a registered sound when this node is clicked (see the click_sound field).

pub fn hover_sound(self, sound: SoundId) -> Self

Plays a registered sound when the pointer enters this node (see the hover_sound field).

pub fn on_drag(self, tag: impl Into<Value>) -> Self

Makes this node draggable (see the on_drag field). Pass a tag the handler can match on; Value::Null if the node key is enough.

pub fn on_layout(self, tag: impl Into<Value>) -> Self

Reports this node’s laid-out rect as an event whenever it changes (see the on_layout field). Pass a tag the handler can match on; Value::Null if the node key is identification enough.

pub fn role(self, role: Role) -> Self

What this node is to assistive technology (see the role field).

pub fn label(self, label: impl Into<Label>) -> Self

The accessible name (see the label field). Takes an Arc<str> as well as a &str, so a view can keep one and hand it out every frame without allocating.

pub fn description(self, description: impl Into<Label>) -> Self

The accessible description (see the description field).

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

The on state for a checkbox / radio / switch role.

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

A checkbox that is neither on nor off (see the mixed field).

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

The current one of a set (see the selected field).

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

A disclosure’s state (see the expanded field).

pub fn live(self, live: Live) -> Self

Marks this node a live region (see the live field).

pub fn value_now(self, v: f32) -> Self

A slider role’s current value.

pub fn value_min(self, v: f32) -> Self

pub fn value_max(self, v: f32) -> Self

pub fn value_step(self, v: f32) -> Self

How far one arrow key moves a slider (see the value_step field). A step that is not positive and finite clears it.

pub fn on_change(self, tag: impl Into<Value>) -> Self

Asks the core for a slider’s changes (see the on_change field).

pub fn value_text(self, text: impl Into<Label>) -> Self

What a slider’s position reads as (see the value_text field).

pub fn caret(self, offset: u32) -> Self

On a Role::Line of a custom editor: the caret’s byte offset into this line’s text (see the caret field).

pub fn selection_anchor(self, offset: u32) -> Self

On a Role::Line of a custom editor: the byte offset where the selection’s other end sits (see the selection_anchor field).

pub fn caret_solid(self) -> Self

On a Role::Line declaring caret: the caret is solid, not a caret to blink (see the caret_solid field). A block caret in a modal editor’s normal mode — the one thing that otherwise asks an idle app for a frame twice a second.

pub fn on_key(self, tag: impl Into<Value>) -> Self

Makes this node a key sink (see NodeSpec::on_key field). Pass a tag the handler can match on; Value::Null if the node key is identification enough.

pub fn key_sink(self) -> Self

A key sink with no tag — on_key(Value::Null), for a handler that knows the node by its key.

pub fn key_up(self) -> Self

Delivers releases to this key sink as well as presses (see the key_up field). Meaningless without on_key.

pub fn modifier_keys(self) -> Self

Delivers the modifier and lock keys to this key sink as keys of their own (see the modifier_keys field). Meaningless without on_key.

pub fn on_force_click(self, tag: impl Into<Value>) -> Self

Asks for force-click events on this node (see the on_force_click field).

pub fn on_button(self, tag: impl Into<Value>) -> Self

Asks for the non-primary buttons pressed over this node as events, each captured by it until its release (see the on_button field): {kind="button", phase, button, x, y, tag}. Every such button unless NodeSpec::buttons narrows it.

pub fn buttons(self, buttons: Buttons) -> Self

Which non-primary buttons on_button claims (see the buttons field): Buttons::MIDDLE, Buttons::SECONDARY | Buttons::MIDDLE. Meaningless without on_button.

pub fn on_scroll(self, tag: impl Into<Value>) -> Self

Asks for the wheel over this node as events (see the on_scroll field): {kind="scroll", x, y, dx, dy, lines, tag}.

pub fn scroll_axes(self, axes: ScrollAxes) -> Self

Which axes on_scroll takes (see the scroll_axes field): ScrollAxes::Y for a terminal’s history, so a sideways gesture passes it by. Meaningless without on_scroll.

pub fn scroll_mods(self, mods: KeyMods) -> Self

The modifiers on_scroll is for (see the scroll_mods field): KeyMods::NONE.with_ctrl().with_super() hears a wheel turned with Ctrl or ⌘ held, ahead of every scroller under the pointer, and no other wheel. Meaningless without on_scroll.

pub fn on_context_menu(self, tag: impl Into<Value>) -> Self

Asks for a context menu on this node (see the on_context_menu field). Pass a tag the handler can match on; Value::Null if the node key is identification enough.

pub fn transition(self, duration_ms: f32) -> Self

Animates changes to this node’s sizing amounts, colors and radius over duration_ms (cubic ease-out); see crate::anim. Only the duration: an easing or repeat already declared survives, so the transition props compose in any order.

On a scroll container it also eases the offset a reveal or a set_scroll moves it to; the wheel, the thumb and a drag past the edge still land whole.

use kui_core::{Easing, NodeSpec, Sizing};
// Eases toward whatever width the view declares next frame.
let pane = NodeSpec::column().width(Sizing::Fixed(240.0)).transition(180.0).easing(Easing::Smooth);
assert_eq!(pane.transition.unwrap().duration_ms, 180.0);

pub fn transition_with(self, t: Transition) -> Self

The whole Transition at once, replacing any declared so far.

pub fn slide(self) -> Self

Also ease this node’s position (see the slide field); sets a default 200ms transition if none was declared yet.

pub fn easing(self, easing: Easing) -> Self

Easing for the node’s transition (sets a default 200ms one if none was declared yet).

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

How far the node’s spring overshoots, 0 (glides in) to crate::anim::MAX_BOUNCE — in place of the spring easing’s own bounce, and on a timed easing in place of the curve, making it a spring (see Transition::bounce). Sets a default 200ms transition if none was declared yet.

pub fn repeat(self, repeat: Repeat) -> Self

How this node’s keyframes cycle (CSS’s animation-direction); sets a default 200ms transition if none was declared yet.

pub fn delay(self, delay_ms: f32) -> Self

Holds this node’s keyframe cycle back by delay_ms (CSS’s animation-delay), so siblings given different delays run out of phase — a cascade, a chase light. Sets a default 200ms transition if none was declared yet.

pub fn keyframes(self, stops: Vec<Keyframe>) -> Self

Cycles the slots these stops name (see the keyframes field); sets a default 200ms transition if none was declared yet.

pub fn enter(self, enter: Enter) -> Self

Eases this node in from enter on its first sight (see the enter field); sets a default 200ms transition if none was declared yet.

pub fn exit(self, exit: Enter) -> Self

Eases this node out to exit after the view stops declaring it (see the exit field); sets a default 200ms transition if none was declared yet.

pub fn window_drag(self) -> Self

Pressing this node starts an OS window drag (drivers promote a quick second press to a maximize toggle).

pub fn window_button(self, button: WindowButton) -> Self

Clicking this node emits the button’s WindowCommand.

pub fn cursor(self, shape: CursorShape) -> Self

The pointer shape over this node (see the cursor field).

Trait Implementations

impl Clone for NodeSpec

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NodeSpec

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

Formats the value using the given formatter.

impl Default for NodeSpec

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for NodeSpec

Hand-written so that a group whose box was allocated but left at its defaults — .checked(false) on a fresh spec — equals one whose box was never allocated at all. The derived version compared None against Some(EMPTY) and called them different, which is a difference the boxing introduced rather than one a caller declared.

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.