The type for mutable nodes in the UI tree.

The type for render callbacks. render self grid ~delta draws self into grid. delta is the elapsed time in milliseconds since the last frame.

The type for intrinsic size computation callbacks. Called during layout when a node lacks explicit dimensions.

The type for hardware cursor descriptions. Coordinates are absolute terminal cell positions.

equal_cursor a b is true iff all fields of a and b match.

pp_cursor ppf c formats c on ppf for debugging.

create ~parent () is a new node attached as a child of child_target parent. When index is omitted the node is appended last; otherwise it is inserted at the given position, clamped to [0;child_count].

Optional parameters:

• id: unique identifier string. Defaults to "node-N".
• style: flexbox style. Defaults to Toffee.Style.default.
• visible: initial visibility. Defaults to true.
• z_index: rendering order; higher values render on top. Defaults to 0.
• opacity: opacity clamped to [0.0;1.0]. Defaults to 1.0.
• live: continuous rendering every frame. Defaults to false.

Raises Invalid_argument if the layout tree rejects the node.

attach ~parent t attaches t as a child of child_target parent, detaching t from any previous parent first. When index is omitted the node is appended last.

Raises Invalid_argument if parent and t belong to different trees, or if either node is destroyed.

detach t removes t from its parent. The node remains valid and can be reattached with attach. Blurs t if focused. No-op if already detached.

destroy t detaches t, removes all children (clearing their parent pointers and lifecycle registrations), frees its layout node, and clears all handlers. The node becomes unusable. No-op if already destroyed.

Children are removed but not themselves destroyed — they become orphaned nodes that can be reattached elsewhere. Use destroy_recursively to destroy the entire subtree.

destroy_recursively t destroys t and all descendants depth-first. See also destroy.

destroyed t is true iff destroy has been called on t.

id t is t's string identifier.

parent t is t's parent, or None if t is detached or a root.

children t is t's children in insertion order. The list is a snapshot; subsequent mutations are not reflected.

child_target t is the node that receives children on behalf of t. Defaults to t itself. Composite widgets override this to redirect children to an internal container (e.g. a scroll box routes children to its content node).

See also set_child_target.

set_child_target t target sets the node that receives children on behalf of t. None resets to t itself.

set_style t style updates t's flexbox style, marks layout dirty, and schedules a re-render. When explicit dimensions are present and flex_shrink is still at its default 1.0, it is automatically set to 0.0 to match terminal layout conventions.

style t is t's current flexbox style.

set_measure t fn assigns a custom measure function for intrinsic sizing and marks layout dirty. None clears it.

mark_dirty t flags t for re-layout on the next frame.

x t is t's absolute horizontal position in terminal cells.

y t is t's absolute vertical position in terminal cells.

width t is t's layout width in terminal cells. Returns 0 when t is hidden or layout has not yet been computed.

height t is t's layout height in terminal cells. Returns 0 when t is hidden or layout has not yet been computed.

bounds t is { x = x t; y = y t; width = width t; height = height t }.

set_translate t ~x ~y shifts t's rendering position by (x, y) without affecting layout. Useful for scrolling.

translate t is t's current translation offset as (x, y).

set_render t fn replaces t's render callback and schedules a re-render.

request_render t schedules a re-render for t.

set_render_before t hook assigns an optional pre-render hook. None clears it.

set_render_after t hook assigns an optional post-render hook. None clears it.

set_child_clip t fn overrides the clipping rectangle applied to t's children. When set, the renderer calls fn t to obtain a scissor rectangle before rendering children. Useful for scroll containers and bordered boxes. None clears the override.

set_visible t v shows or hides t. Blurs t if it is focused while being hidden.

visible t is true iff t is currently visible.

set_z_index t z sets t's rendering order. Higher values render on top.

z_index t is t's z-index.

set_opacity t v sets t's opacity, clamped to [0.0;1.0]. Values below 1.0 cause the renderer to push an opacity context around t and its descendants.

opacity t is t's opacity in [0.0;1.0].

set_buffered t v enables or disables offscreen buffering. When true, t renders into a private grid that is blitted to the parent grid.

buffered t is true iff offscreen buffering is enabled.

set_live t v enables or disables continuous rendering. When live, the renderer runs t's render callback every frame rather than only on request.

live t is true iff continuous rendering is enabled.

set_focusable t v marks t as focusable or not.

focusable t is true iff t can receive focus.

focused t is true iff t currently holds focus.

focus t requests focus for t. Returns false if t is not focusable. Delegates to the renderer's focus controller.

blur t removes focus from t. No-op if t is not focused.

set_cursor_provider t f registers a hardware cursor provider consulted when t is focused. f is called with t and returns the desired cursor state, or None to hide the cursor.

clear_cursor_provider t removes t's cursor provider.

cursor t is the current hardware cursor state as reported by t's cursor provider, or None if no provider is set.

on_mouse t handler registers a mouse event handler on t. Handlers accumulate and run newest-first. Mouse events bubble to ancestors unless Event.Mouse.stop_propagation is called.

on_key t handler registers a keyboard handler on t. Handlers accumulate and run newest-first until one calls Event.Key.prevent_default.

set_default_key_handler t handler assigns a fallback key handler that runs after on_key handlers. Only one fallback handler per node. None clears it.

set_paste_handler t handler assigns a paste handler on t. Only one paste handler per node. None clears it.

set_selection t ~should_start ~on_change ~clear ~get_text enables text selection on t. The renderer calls these callbacks during mouse interactions and clipboard operations. The contract is:

• should_start ~x ~y is true iff a selection drag starting at (x, y) should be initiated.
• on_change sel is called when the selection changes; returns true to accept the selection.
• clear () discards any active selection state.
• get_text () returns the currently selected text.

unset_selection t disables text selection on t.

selectable t is true iff t has selection callbacks registered.

The type for display line metrics used by line-numbering widgets.

• line_count: number of logical lines.
• display_line_count: number of visual lines after wrapping.
• line_sources.(i): logical line index for display line i.
• line_wrap_indices.(i): sub-line index within the logical line — 0 for the first display line, 1 for the first continuation, and so on.
• scroll_y: vertical scroll offset in display lines.

set_line_info_provider t f registers a function that supplies line metrics for t. Used by composite widgets (e.g. line-number gutters) to read display line information from a content child without coupling to its concrete type. None clears the provider.

line_info t is the current line metrics from t's provider, or None if no provider is registered.

set_on_frame t callback registers a per-frame update hook. callback t ~delta is called every frame with delta as the elapsed milliseconds. None clears the hook.

set_on_resize t callback registers a size-change hook. The callback is called when width or height changes after layout. None clears the hook.

pp ppf t formats t on ppf for debugging.