Python API

A quick reference to everything import tre gives you: each class with its properties, methods and events, short descriptions, and what it inherits. The Rust API is what these classes sit on. The Details link on a class goes to its longer page (behavior, examples, edge cases).

Node and Window take most of their properties by name through set, get and (for the animatable ones) animate, and their events by name through on; those names are listed with the class. None of these classes can be subclassed.

Class	Purpose
App	Opens and drives one or more windows together in one blocking run().
LoopHandle	The one thread-safe object: queues a callable onto a running App's loop.
StatsHandle	Reads a window's frame statistics from any thread, without waiting for the loop.
TimerHandle	Cancels a timer set with Window.after or Window.every.
Window	Owns a node tree and its size and title; creates nodes, shows layers, docks panels.
Node	A handle to one node in a window's tree: properties, animation, events, structure.
Event	What a listener receives when it takes one argument; never constructed directly.
Painter	The drawing surface a canvas node's draw callback receives.
Gradient	A linear, radial or sweep gradient to give a box as its fill.
CursorImage	A pointer shape drawn from pixels, for a node's cursor.
Shader	WGSL that paints a node (a fill) or transforms its rendered content (an effect).
ShaderError	A shader's source or names are wrong, positioned in the WGSL you gave.

App

Opens and drives one or more windows together in one blocking run().

Inherits: object · Details: App reference

Constructor: App()

Methods:

Method	Description
add_window(window: Window) -> None	Adds a window to open when run() is called.
run(max_frames: int \| None=None) -> None	Opens every added window and runs the event loop until they all close, or max_frames.
thread_handle() -> LoopHandle	A thread-safe handle to this App's event loop.

Events: none.

LoopHandle

The one thread-safe object: queues a callable onto a running App's loop.

Inherits: object · Details: Threading guide

Methods:

Method	Description
call_soon(callback: Callable[[], object]) -> None	Queues callback (called with no arguments) to run on the App's event-loop thread, and wakes the loop.

Events: none.

StatsHandle

Reads a window's frame statistics from any thread, without waiting for the loop.

Inherits: object · Details: StatsHandle reference

Methods:

Method	Description
read(reset: bool=False) -> dict[str, Any]	The dict Window.frame_stats() returns, except that profile is always None (it names Nodes, which belong to the loop's…

Events: none.

TimerHandle

Cancels a timer set with Window.after or Window.every.

Inherits: object · Details: TimerHandle reference

Properties:

Property	Type	Description
active	bool	Whether the timer is still pending: an every until cancelled, an after until it has run.

Methods:

Method	Description
cancel() -> bool	Stops the timer.

Events: none.

Window

Owns a node tree and its size and title; creates nodes, shows layers, docks panels.

Inherits: object · Details: Window reference

Constructor: Window(width: int=480, height: int=200, title: str='tre v2', decorations: bool=True)

Properties:

Property	Type	Description
root	Node	The window's root node — a flex row with 16px padding and gaps, sized to the window.

Settable and readable properties (window.set(...), window.get(name)):

Property	Access	Description
width, height	get	The client area's size (change it with resize).
title	set, get	The window title, live if open.
scale_factor	get	Display scale; 1.0 until App.run() opens the window.
dark	get	The OS appearance: True, False, or None when it can't say.
partial_redraw, partial_redraw_active	set, get	Redraw only what changed; whether that is in effect.
show_damage	set, get	Tint what each frame redrew.
decorations	set, get	Whether the OS draws the title bar and borders.
fullscreen	set, get	Borderless fullscreen.
min_width, min_height	set, get	The smallest size the user can resize to.
icon	set	(rgba, width, height) or None.
maximized, minimized, active	get	Window state; use the methods to change it.
platform	get	"wayland", "x11", "windows" or "macos".
resize_border, system_menu	set, get	Border width for undecorated windows; the OS window menu.
titlebar_inset, native_controls	get	macOS traffic-light area; whether the OS shows its controls.
gpu_watchdog	set, get	Seconds before a stuck frame fires gpu_stalled; None is off.
present_mode	set, get	"vsync" (default) paces frames to the display; "low_latency" shows the newest frame at once.
dpi_scaling	set, get	Layout in logical pixels, drawn at the display's scale (0.5.4); off by default.
glyph_cache	set, get	Draw text from the glyph cache: about 4x cheaper, edge pixels differ slightly (0.5.4); off by default.
profile_nodes	set, get	Time each node the paint walk reaches, for frame_stats() (0.5.4).
transparent, transparent_active	set, get / get	A see-through window background, and whether it took effect (0.5.4).
blur_behind, click_through	set, get	Ask the compositor to blur behind a transparent window; ignore the pointer entirely (0.5.4).
reduced_motion, high_contrast	get	The OS's motion and contrast preferences (0.5.4).

Methods:

Method	Description
add_dock_zone(side: str, container: Node, size: float) -> None	Registers container as the dock zone for side.
advance(ms: float) -> None	Moves the window's clock forward by ms, running animations, callbacks and layout.
after(ms: float, fn: Callable[[], object]) -> TimerHandle	Calls fn once, ms milliseconds from now, on the loop's thread.
center() -> bool	Centres the open window on its monitor.
close() -> None	Closes the window as if the user had: close_requested fires first, and a listener that cancels it keeps the window open.
create(kind: str, **props: Any) -> Node	Makes a detached node of a kind; attach it with add_child.
dock_panel(side: str, panel: Node) -> None	Docks panel into side's zone and shows it.
every(ms: float, fn: Callable[[], object]) -> TimerHandle	Calls fn every ms milliseconds (at least 1) until the handle is cancelled.
frame_stats(reset: bool=False) -> dict[str, Any]	What this window's frames cost, as a dict: frames (drawn since the window opened), skipped (passes that found nothing to…
hide_layer(node: Node) -> None	Hides a layer, detaching it, and returns focus to where it was.
maximize() -> None	Maximizes the window — or opens it maximized.
measure_text(text, font_family, font_size, font_weight, font_style, letter_spacing, line_height, max_width, wrap, max_lines, overflow) -> tuple[float, float]	Returns the (width, height) a text node with these properties would take.
minimize() -> None	Minimizes the window — or, before App.run(), opens it minimized.
off(event: str) -> None	Removes the window's listener for event, if any.
on(event: str, handler: Callable[..., object]) -> None	Registers handler for a window event.
read_clipboard() -> str \| None	Returns the OS clipboard's text, or None when there is none or it can't be reached.
resize(width: int, height: int) -> None	Sets the window's size from code; the root's layout box follows.
restore() -> None	Restores a minimized or maximized window to its normal size; before App.run(), undoes minimize()/maximize().
set(*, title, partial_redraw, show_damage, profile_nodes, glyph_cache, decorations, fullscreen, min_width, min_height, icon, resize_border, system_menu, gpu_watchdog, present_mode, dpi_scaling, transparent, blur_behind, click_through, x, y, always_on_top, resizable, skip_taskbar) -> None	Sets window properties by name, all at once; a bad value raises and changes nothing.
set_active_panel(side: str, index: int) -> None	Shows the indexth panel docked in side's zone (was set_active_tab).
show_layer(node, anchor, placement, modal, dismissible, offset, flip) -> None	Shows node over the window's content, above every layer already open.
simulate(event: str, node: Node \| None=None, **fields: Any) -> None	Delivers a synthetic event as real input would, for tests with no display.
snapshot(width, height, scale, time) -> tuple[bytes, int, int]	What the window draws, as (rgba, width, height): straight-alpha RGBA8 bytes, width * height * 4 of them, top row first.
start_panel_drag(panel: Node) -> None	Starts dragging panel, a docked panel.
start_trace(path: str) -> None	Writes every frame this window draws from now on to path as a Chrome / Perfetto trace (open it at ui.perfetto.dev or…
stats_handle() -> StatsHandle	A handle any thread can use to read this window's frame statistics (handle.read()) without waiting for the event loop.
stop_trace() -> int	Closes the trace start_trace opened and returns how many frames it holds (0 if none is running).
undock_panel(panel: Node) -> None	Takes panel out of docking.
write_clipboard(text: str) -> bool	Puts text on the OS clipboard; False when it can't be reached (logged, never raised).

Events (window.on(event, handler); a window event has no node):

Event	Payload	Fires when
resize	width, height	The client area changed size.
color_scheme	dark	The OS switched between light and dark.
scale_factor	scale_factor	The window moved to a display with a different scale.
close_requested	—	The user asked to close; event.cancel() keeps it open.
closed	—	The window closed.
dock_target, dock_drop	side, panel	A docking drag moved into a zone / ended.
maximized, active	maximized, active	The window was maximized or restored / gained or lost focus.
titlebar_inset	titlebar_inset	The OS controls' area over the content changed.
gpu_lost	reason, message	The GPU was lost; the run is ending.
gpu_error	message	The GPU reported an error; the draw was skipped.
gpu_stalled	seconds	A submitted frame has not completed after gpu_watchdog seconds.
file_hover, file_hover_cancel, file_drop	paths, path	Files dragged over, away from, or dropped on the window (0.5.4).
reduced_motion, high_contrast	reduced_motion, high_contrast	The OS's motion or contrast preference changed (0.5.4).
frame	stats	A frame was drawn and presented; stats holds its costs (0.5.4).

Node

A handle to one node in a window's tree: properties, animation, events, structure.

Inherits: object · Details: Node reference

Kinds (window.create(kind, **props)):

Kind	Required	What it is
"box"	—	A layout container with fill, stroke, corners and shadows.
"text"	text	Shaped, non-editable text.
"text_input"	—	Editable text: selection, clipboard, IME, obscuring.
"image"	rgba, pixel_width, pixel_height	RGBA8 pixels; video is repeated set(rgba=…).
"path"	data	A vector path.
"canvas"	draw	Immediate-mode drawing through a Painter.
"scroll_view"	—	Clips and scrolls one child.
"virtual_list"	item_count, materialize	Builds only the rows its viewport shows.
"terminal"	shell, cols, rows	A PTY-backed terminal emulator.
"svg"	svg, svg_color, svg_images	A whole SVG document, fitted into the node's box (0.5.4).

Settable properties (node.set(...), node.get(name); node.animate(...) for the animatable ones):

Size and position

Property	Value	Description
width, height, min_width, min_height, max_width, max_height	pixels, "auto", or "50%"	Box size and limits.
aspect_ratio	number or None	Width over height.
position	"relative" or "absolute"	In the flow, or placed by x/y.
x, y	pixels, percentage, "auto"	Left and top offset.

Flex layout

Property	Value	Description
flex_direction	"horizontal" or "vertical"	Main axis.
flex_wrap	"no_wrap" or "wrap"	Whether children wrap.
align_items, justify_content	alignment names	Cross- and main-axis alignment of children.
gap	pixels or percentage	Space between children.
padding, padding_top/_right/_bottom/_left	pixels or percentage	Inset; a node's own content draws inside it.
flex_grow, flex_shrink, flex_basis	numbers / like width	How a flex child grows, shrinks and starts.
align_self	an align_items value or None	Overrides the parent's alignment for this child.
margin, margin_top/_right/_bottom/_left	pixels, percentage, "auto"	Outer space.

Grid layout

Property	Value	Description
display	"flex" or "grid"	Which layout a node's children use.
grid_template_columns, grid_template_rows	track list	The grid's tracks.
grid_auto_columns, grid_auto_rows, grid_auto_flow	track list / flow name	Implicit tracks and auto-placement.
row_gap, column_gap	pixels or percentage	Space between rows or columns.
justify_items, align_content, justify_self	alignment names	Cell and track alignment.
grid_column, grid_row	line, "span 2", "1 / 3"	A grid child's placement.

Transform, visibility and order

Property	Value	Description
translate_x, translate_y	pixels (animatable)	Offset from the laid-out position.
scale, rotation_deg	number (animatable)	Scale and clockwise rotation about the center.
visible	bool	False hides the node and its subtree.
z_index	int	Paint and hit order among siblings.
clip_children	bool	Clips children to the rounded box.
cursor	cursor name or None	Pointer shape over the node.
hit_testable	bool	Whether the node can be a pointer target.
window_region	"drag", "none", None	Makes a node a title bar that moves the window.

Paint (every kind)

Property	Value	Description
fill	(r, g, b, a) (animatable)	Background; glyph color on text; a path's fill.
stroke_color, stroke_width	color / pixels (animatable)	Border inside the box; a path's outline.
corner_radius	number or 4-tuple (animatable)	Rounds background, border and image.
opacity	0.0–1.0 (animatable)	Group opacity of the node and its subtree.
shadows	list of (color, dx, dy, blur, spread)	CSS box-shadow model.
shader	Shader or None	WGSL that paints or transforms the node.

Text and text input

Property	Value	Description
text	str	The content (read-only on a terminal).
font_family, font_weight, font_size	name / 1–1000 / pixels	Font.
line_height, text_align, font_style, letter_spacing, wrap, max_lines, overflow	see the text guide	Text layout (text nodes).
multiline, selection, show_whitespace, syntax_spans, folded_ranges	—	Text input editing and decoration.
placeholder, placeholder_fill, caret_color, selection_fill, obscured	—	Text input colors and password mode.

Image, path and canvas

Property	Value	Description
rgba, pixel_width, pixel_height, fit	bytes / ints / "fill", "contain", "cover"	Image pixels and how they fit the box.
data, view_box, trim_start, trim_end	SVG path / tuple / 0.0–1.0	A path's shape, viewport and drawn part.
draw	draw(painter)	A canvas's drawing callback.

Scrolling, lists and terminals

Property	Value	Description
orientation, scroll_offset, scrollbar_fill, scrollbar_width	—	A scroll view's direction, position and bar.
item_count, item_extent, size_hint, materialize	—	A virtual list's rows.
cols, rows, shell, scrollback_lines, palette	—	A terminal's grid, process and colors.

Accessibility and focus

Property	Value	Description
role, label, value, value_min, value_max, value_step	—	What assistive technology reads.
checked, selected, expanded, disabled, level, live, a11y_hidden	—	State announced to assistive technology.
focusable, tab_index	bool / int	Whether and where Tab reaches the node.

Read-only

Property	Value	Description
kind, focused, layer_placement	—	The node's kind, focus state, and a shown layer's side.
layout_x, layout_y, layout_width, layout_height	pixels	Where the node is, as laid out (runs pending layout).

Methods:

Method	Description
add_child(child: Node) -> None	Appends child under this node, moving it if it's attached elsewhere.
animate(property, to, duration_ms, easing, on_complete) -> None	Eases a property from its current value to a target, retargeting mid-flight.
capture_pointer() -> None	Routes every later pointer event to this node until the button is released or release_pointer() is called.
caret_rect() -> tuple[float, float, float, float]	A text input's caret as (x, y, width, height) in the node's coordinates, padding and scrolling included; at the end of the…
children() -> list[Node]	This node's children, in order.
destroy() -> None	Frees this node and its whole subtree now, with their listeners; focus inside it gets unfocus first.
focus() -> None	Moves keyboard focus to this node, firing unfocus/focus.
get(name: str) -> Any	Reads one property: any property set accepts.
get_target(name: str) -> Any	The value name's running animation is heading to.
insert_child(index: int, child: Node) -> None	Attaches child at index, moving it if it is attached elsewhere.
off(event: str) -> None	Removes this node's listener for event, if any.
on(event: str, handler: Callable[..., object]) -> None	Registers handler for event, replacing any earlier listener for it.
parent() -> Node \| None	This node's parent, or None for the root or a detached node.
redraw() -> None	Runs this canvas's draw callback now, replacing what it shows with what the callback draws.
release_pointer() -> None	Ends this node's pointer capture, if it holds it.
remove() -> None	Detaches this node from its parent.
scroll_into_view() -> None	Scrolls every scroll view around this node just enough to show it, innermost first, at once.
set(**props: Any) -> None	Sets properties atomically: every value is checked first, and a bad one raises ValueError without changing anything.
stop_animation(name: str) -> None	Stops name's running animation where it is.
text_rects(start: int, end: int) -> list[tuple[float, float, float, float]]	The rectangles covering bytes start..end of a text input's text, one per line, as (x, y, width, height) in the node's…

Events (node.on(event, handler); a bubbling event runs the target's listener, then each ancestor's):

Event	Bubbles	Fires when
pointer_enter, pointer_leave	no	The pointer enters or leaves the node's subtree.
pointer_down, pointer_move, pointer_up	yes	A button is pressed, the pointer moves, a button is released.
pointer_cancel	yes	The OS took a press (window move, maximize, menu); no pointer_up follows.
click, secondary_click	yes	Primary or secondary press and release on the same node, or keyboard activation.
wheel	yes	A wheel or trackpad scroll.
key_down, key_up	yes	A key is pressed or released while the node or a descendant has focus.
input	yes	Committed text arrives for the focused text input.
focus, unfocus	yes	A node gains or loses keyboard focus.
change	no	A text input's text was changed by the user.
scroll	no	A scroll view's offset changed, once a frame.
dismiss	no	An outside press or Escape asked a layer to close.
a11y_action	yes	Assistive technology asked for an action (increment, expand, set value…).
touch_start, touch_move, touch_end, touch_cancel	yes	A finger touches, moves, lifts or is taken away (0.5.4); pointer_id.
tap, long_press	yes	A quick touch and release in place (count), or one held half a second (0.5.4).
pan, pinch	yes	A dragging or pinching gesture (0.5.4); phase, deltas, scale.
file_hover, file_hover_cancel, file_drop	yes	Files dragged from the OS over, away from, or dropped on the node (0.5.4); paths.
link	yes	A click on a text span that has a link (0.5.4); href.

Event

What a listener receives when it takes one argument; never constructed directly.

Inherits: object · Details: Event reference

Properties (each is None when the event has nothing to say about it):

Property	Type	Description
button	str \| None	"primary", "secondary", "middle", "back" or "forward".
old_value	Any \| None	The previous text (change) or offset (scroll).
new_value	Any \| None	The new text (change) or offset (scroll).
type	str	The event's name; on every event.
target	Node \| None	The node the event happened on; every node event.
current	Node \| None	The node whose listener is running.
x	float \| None	Pointer position, local to current.
y	float \| None	Pointer position, local to current.
window_x	float \| None	Pointer position in the window.
window_y	float \| None	Pointer position in the window.
delta_x	float \| None	Wheel scroll in pixels, positive right.
delta_y	float \| None	Wheel scroll in pixels, positive down.
key	str \| None	A snake_case key name, or the produced character.
repeat	bool \| None	Whether a key event is an auto-repeat.
shift	bool \| None	Modifier held during pointer, wheel, key and click events.
ctrl	bool \| None	Modifier held during pointer, wheel, key and click events.
alt	bool \| None	Modifier held during pointer, wheel, key and click events.
meta	bool \| None	Modifier held during pointer, wheel, key and click events.
text	str \| None	The committed text of an input event.
action	str \| None	The requested action of an a11y_action.
value	Any \| None	The value of an a11y_action such as set_value.
width	float \| None	New size on resize.
height	float \| None	New size on resize.
dark	bool \| None	New appearance on color_scheme.
stats	dict[str, Any] \| None
reduced_motion	bool \| None
high_contrast	bool \| None
maximized	bool \| None	New state on maximized.
active	bool \| None	New state on active.
titlebar_inset	tuple[float, float] \| None	New (height, width) on titlebar_inset.
reason	str \| None	"unknown" or "destroyed" on gpu_lost.
message	str \| None	The driver's or GPU's message on gpu_lost and gpu_error.
seconds	float \| None	How long the frame has run on gpu_stalled.
scale_factor	float \| None	New scale on scale_factor.
related_target	Node \| None	The node on the other side of a focus / unfocus move.
focus_visible	bool \| None	Whether focus arrived by keyboard.
side	str \| None	The dock zone under the pointer, or None.
path	str \| None
paths	list[str] \| None
href	str \| None
preedit_cursor	tuple[int, int] \| None
caret	tuple[float, float, float, float] \| None
inserted	tuple[int, int] \| None
property	str \| None
finished	bool \| None
pointer_id	int \| None
phase	str \| None
count	int \| None
scale	float \| None
scale_delta	float \| None
total_x	float \| None
total_y	float \| None
velocity_x	float \| None
velocity_y	float \| None
panel	Node \| None	The dragged panel on dock_drop.

Methods:

Method	Description
cancel() -> None	Keeps a window open: prevents close_requested's default.
stop() -> None	Ends propagation: no listener on a further ancestor runs.

Events: this is what the events above deliver. stop() ends propagation; cancel() keeps a window open on close_requested.

Painter

The drawing surface a canvas node's draw callback receives.

Inherits: object · Details: Painter reference

Methods:

Method	Description
fill_circle(cx: float, cy: float, radius: float, color: Color \| Gradient) -> None	Fills a circle in canvas-local coordinates.
fill_rect(x: float, y: float, width: float, height: float, color: Color \| Gradient) -> None	Fills a rectangle in canvas-local coordinates.
set_hit_test_circle(cx: float, cy: float, radius: float) -> None	Replaces this canvas's default rectangular hit test with a circular one.
set_hit_test_path(points: Sequence[Sequence[float]], tolerance: float) -> None	Replaces this canvas's default rectangular hit test with a stroke-shaped one.
stroke_path(points: Sequence[Sequence[float]], color: Color \| Gradient, width: float) -> None	Strokes a path in canvas-local coordinates.

Events: none.

Gradient

A linear, radial or sweep gradient to give a box as its fill.

Inherits: object · Details: Gradient reference

Properties:

Property	Type	Description
kind	str	"linear", "radial" or "sweep".
stops	list[tuple[float, Color]]
angle	float \| None
center	tuple[float, float] \| None
radius	float \| None
start	float \| None

Methods:

Method	Description
linear(stops: Sequence[Color] \| Sequence[tuple[float, Color]], angle: float=180.0) -> Gradient	Along a line through the box's centre at angle degrees (0 up, 90 right, 180 down), spanning the box.
radial(stops, center, radius) -> Gradient	Outward from center (fractions of the box; None is (0.5, 0.5), the middle).
sweep(stops, center, start) -> Gradient	Around center (None is the middle), starting start degrees clockwise from up.

Events: none.

CursorImage

A pointer shape drawn from pixels, for a node's cursor.

Inherits: object · Details: CursorImage reference

Constructor: CursorImage(rgba: bytes, width: int, height: int, hotspot: tuple[int, int]=...)

Properties:

Property	Type	Description
size	tuple[int, int]
hotspot	tuple[int, int]
ready	bool	Whether the OS cursor has been made.

Events: none.

Shader

WGSL that paints a node (a fill) or transforms its rendered content (an effect).

Inherits: object · Details: Shader reference

Constructor: Shader(wgsl: str, uniforms: dict[str, float | tuple[float, ...]] | None=None, inputs: dict[str, Node] | None=None, mode: str='fill', animated: bool=False)

Properties:

Property	Type	Description
wgsl	str	The WGSL source, as given.
mode	str	"fill" or "effect".
animated	bool	Whether the node is repainted every frame.
uniforms	dict[str, float \| tuple[float, ...]]	The uniforms and their current values, as a new dict.
inputs	dict[str, Node]	The input nodes by name, as a new dict.

Methods:

Method	Description
filter(*, saturate, brightness, contrast, grayscale, hue_rotate, invert, sepia) -> Shader	A ready-made effect shader that applies CSS colour filters to a node and its subtree…
set(*, uniforms: dict[str, float \| tuple[float, ...]]) -> None	Replaces the uniforms all at once; a mistake raises and changes nothing.

Events: none.

ShaderError

A shader's source or names are wrong, positioned in the WGSL you gave.

Inherits: ValueError → Exception → BaseException → object

Properties:

Property	Type	Description
line	int \| None	The 1-based line in your WGSL, or None when the problem has no position.
column	int \| None	The 1-based column in that line, or None.
source_line	str \| None	The text of that line, or None.

Events: none.

Module functions and constants

Name	Description
register_font(data: bytes) -> list[str]	Registers a font the caller already loaded.
set_system_fonts(enabled: bool) -> None	Lets text use the fonts installed on this machine: for the glyphs the bundled and registered fonts lack (CJK, Hebrew, Indic…
system_fonts() -> bool	Whether system fonts are on (set_system_fonts).
MONOSPACE_FONT_FAMILY	The bundled monospace family a terminal always shapes with.
Color	A type alias: an (r, g, b, a) tuple of ints, 0–255, straight alpha.