What to try
Expand a folder and select a file.
Usage notes
Trees express parent-child relationships. Manage expansion separately from selection, retain node identity when filtering, and handle leaf actions in the application.
Create through Screen
The Screen constructor returns a node ID. Pass that ID to Screen layout, state and event APIs. It is separate from the standalone control object documented below.
Native Xu setup fragment: call configure during initialization of an existing Screen. See the complete example for window creation, event dispatch and cleanup.
#ui/widgets
fn configure(screen $&widgets.Screen) int {
id := screen.tree() or >>
screen.place(id,24.0,24.0,320.0,80.0) or >>
<< id
}
($&Screen) tree
pub fn (s $&Screen) tree() int
Purpose
Create TreeView in Screen and return the component node ID; throw on creation failure.
Parameters
s $&Screen- The
Screen instance used by this call (exclusive borrow).
Returns
int — component node ID for place and other Screen methods.
Placement, state and events
The application owns the component. Screen.place positions nodes; Screen.set_enabled and Screen.set_visible control availability and visibility. Present again after state changes, handle or errors, and keep topology changes outside paint callbacks. ToastHost uses its own queue API.
Action · Styles · UI lifecycle and styling guide
Screen.place · Screen.set_enabled · Screen.set_visible
Standalone control object API
These types and methods support applications that manage control objects, input and painting directly. Their receiver is a control object, not a Screen node ID. For Screen usage, use the constructor above and the Screen methods in the Widgets module.
($&TreeView) set_appearance
pub fn (t $&TreeView) set_appearance(a &TreeAppearance) int
Purpose
Operation on $&TreeView: set appearance. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
a &TreeAppearance- value (read-only borrow; caller keeps the original; type &TreeAppearance)
Returns
int — a value of this type
($&TreeView) set_motion
pub fn (t $&TreeView) set_motion(spec &MotionSpec) int
Purpose
Operation on $&TreeView: set motion. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
spec &MotionSpec- spec (read-only borrow; caller keeps the original; type &MotionSpec)
Returns
int — a value of this type
($&TreeView) set_metadata
pub fn (t $&TreeView) set_metadata(node int,text &string) int
Purpose
Operation on $&TreeView: set metadata. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
node int- node (int)
text &string- text (read-only borrow; caller keeps the original; type &string)
Returns
int — a value of this type
($&TreeView) set_icon
pub fn (t $&TreeView) set_icon(node int,icon int) int
Purpose
Operation on $&TreeView: set icon. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
node int- node (int)
icon int- icon (int)
Returns
int — a value of this type
($&TreeView) set_action
pub fn (t $&TreeView) set_action(node int,enabled bool) int
Purpose
Operation on $&TreeView: set action. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
node int- node (int)
enabled bool- enabled (bool)
Returns
int — a value of this type
($&TreeView) begin_update
pub fn (t $&TreeView) begin_update() int
Purpose
Operation on $&TreeView: begin update. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
Returns
int — a value of this type
($&TreeView) end_update
pub fn (t $&TreeView) end_update() int
Purpose
Operation on $&TreeView: end update. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
Returns
int — a value of this type
($&TreeView) set_filter
pub fn (t $&TreeView) set_filter(query &string) int
Purpose
Operation on $&TreeView: set filter. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
query &string- query (read-only borrow; caller keeps the original; type &string)
Returns
int — a value of this type
($&TreeView) reveal_selected
pub fn (t $&TreeView) reveal_selected() int
Purpose
Operation on $&TreeView: reveal selected. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
Returns
int — a value of this type
($&TreeView) find_next
pub fn (t $&TreeView) find_next(prefix &string) bool
Purpose
Unicode committed text can be passed by the application; raw key events are used only for ASCII type-ahead, never for IME composition. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
prefix &string- prefix (read-only borrow; caller keeps the original; type &string)
Returns
bool — true or false
($&TreeView) tick
pub fn (t $&TreeView) tick(now time.Instant,reduced_motion bool) bool
Purpose
Advance animation clock and state transition step. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
now time.Instant- now (time.Instant)
reduced_motion bool- reduced_motion (bool)
Returns
bool — true or false
(&TreeView) next_tick
pub fn (t &TreeView) next_tick(now time.Instant) time.Instant
Purpose
Operation on &TreeView: next tick. Throws on failure; handle the error or propagate it to the caller.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
now time.Instant- now (time.Instant)
Returns
time.Instant — a value of this type
(&TreeView) action_bounds
pub fn (t &TreeView) action_bounds(row int) layout.Rect
Purpose
Operation on &TreeView: action bounds.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
row int- row (int)
Returns
layout.Rect — a value of this type
($&TreeView) row_label_rect
pub fn (t $&TreeView) row_label_rect(row int,c &ControlStyle,styles &Styles) layout.Rect
Purpose
Operation on $&TreeView: row label rectangle.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
row int- row (int)
c &ControlStyle- byte or character code (read-only borrow; caller keeps the original; type &ControlStyle)
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
layout.Rect — a value of this type
($&TreeView) paint_styled
pub fn (t $&TreeView) paint_styled(frame $&draw.Frame,styles &Styles) int
Purpose
Operation on $&TreeView: paint styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
frame $&draw.Frame- frame (exclusive borrow; may modify the original; type $&draw.Frame)
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
int — a value of this type
struct TreeView
Purpose
Up to 512 nodes, depth <= 32. add(-1, label) appends a root; other parents must be an earlier node index. Indices stay stable until clear. Children are shown in insertion order, even when they are appended after siblings.
Public fields
This type has no public fields.
(&TreeView) id
pub fn (t &TreeView) id() int
Purpose
Return the unique integer ID of the element or control.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
int — a value of this type
(&TreeView) bounds
pub fn (t &TreeView) bounds() layout.Rect
Purpose
Return the bounding Rectangle of the control or geometry.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
layout.Rect — a value of this type
(&TreeView) count
pub fn (t &TreeView) count() int
Purpose
Return the number of items in this control.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
int — a value of this type
(&TreeView) visible_count
pub fn (t &TreeView) visible_count() int
Purpose
Operation on &TreeView: visible count.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
int — a value of this type
(&TreeView) selected
pub fn (t &TreeView) selected() int
Purpose
Get or test the currently selected index, node, or state.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
int — a value of this type
(&TreeView) is_expanded
pub fn (t &TreeView) is_expanded(node int) bool
Purpose
Operation on &TreeView: whether it is expanded. Throws on failure; handle the error or propagate it to the caller.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
node int- node (int)
Returns
bool — true or false
(&TreeView) parent
pub fn (t &TreeView) parent(node int) int
Purpose
Execute parent on &TreeView. Throws on failure; handle the error or propagate it to the caller.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
node int- node (int)
Returns
int — a value of this type
(&TreeView) text
pub fn (t &TreeView) text(node int) string
Purpose
Operation on &TreeView: return the current text. Throws on failure; handle the error or propagate it to the caller.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
node int- node (int)
Returns
string — result string
(&TreeView) visible_node
pub fn (t &TreeView) visible_node(index int) int
Purpose
Operation on &TreeView: visible node. Throws on failure; handle the error or propagate it to the caller.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
index int- index (int)
Returns
int — a value of this type
(&TreeView) needs_paint
pub fn (t &TreeView) needs_paint() bool
Purpose
Return whether the control needs repainting; call painted after painting to clear the flag.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
bool — true or false
($&TreeView) painted
pub fn (t $&TreeView) painted()
Purpose
Acknowledge the painted frame and clear the dirty flag; this is not a query.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
Returns
This call does not return a value.
(&TreeView) is_selectable
pub fn (t &TreeView) is_selectable() bool
Purpose
Operation on &TreeView: whether it is selectable.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
bool — true or false
($&TreeView) set_selectable
pub fn (t $&TreeView) set_selectable(selectable bool)
Purpose
Operation on $&TreeView: set selectable.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
selectable bool- selectable (bool)
Returns
This call does not return a value.
(&TreeView) selected_text
pub fn (t &TreeView) selected_text() string
Purpose
Operation on &TreeView: selected text.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
string — result string
($&TreeView) set_locale
pub fn (t $&TreeView) set_locale(locale &Locale) int
Purpose
Operation on $&TreeView: set locale. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
locale &Locale- locale (read-only borrow; caller keeps the original; type &Locale)
Returns
int — a value of this type
($&TreeView) set_viewport
pub fn (t $&TreeView) set_viewport(viewport &layout.Rect)
Purpose
Operation on $&TreeView: set viewport.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
viewport &layout.Rect- viewport (read-only borrow; caller keeps the original; type &layout.Rect)
Returns
This call does not return a value.
(&TreeView) cursor
pub fn (t &TreeView) cursor() int
Purpose
Execute cursor on &TreeView.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
int — a value of this type
(&TreeView) is_enabled
pub fn (t &TreeView) is_enabled() bool
Purpose
Return whether the control is currently enabled.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
bool — true or false
(&TreeView) is_focused
pub fn (t &TreeView) is_focused() bool
Purpose
Return whether the control currently has input focus.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
bool — true or false
(&TreeView) is_read_only
pub fn (t &TreeView) is_read_only() bool
Purpose
Operation on &TreeView: whether it is read only.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
bool — true or false
(&TreeView) scroll_offset
pub fn (t &TreeView) scroll_offset() f64
Purpose
Operation on &TreeView: scroll offset.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
Returns
f64 — a value of this type
($&TreeView) cancel
pub fn (t $&TreeView) cancel()
Purpose
Execute cancel on $&TreeView.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&TreeView) set_focus
pub fn (t $&TreeView) set_focus(focused bool)
Purpose
Operation on $&TreeView: set focus.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
focused bool- focused (bool)
Returns
This call does not return a value.
($&TreeView) set_enabled
pub fn (t $&TreeView) set_enabled(enabled bool)
Purpose
Operation on $&TreeView: set enabled.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
enabled bool- enabled (bool)
Returns
This call does not return a value.
($&TreeView) set_read_only
pub fn (t $&TreeView) set_read_only(value bool) int
Purpose
Operation on $&TreeView: set read only. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
value bool- value (bool)
Returns
int — a value of this type
($&TreeView) add
pub fn (t $&TreeView) add(parent int,text &string) int
Purpose
Operation on $&TreeView: add. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
parent int- parent (int)
text &string- text (read-only borrow; caller keeps the original; type &string)
Returns
int — a value of this type
($&TreeView) set_text
pub fn (t $&TreeView) set_text(node int,text &string) int
Purpose
Operation on $&TreeView: set text. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
node int- node (int)
text &string- text (read-only borrow; caller keeps the original; type &string)
Returns
int — a value of this type
($&TreeView) set_expanded
pub fn (t $&TreeView) set_expanded(node int,expanded bool) int
Purpose
Operation on $&TreeView: set expanded. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
node int- node (int)
expanded bool- expanded (bool)
Returns
int — a value of this type
($&TreeView) set_selected
pub fn (t $&TreeView) set_selected(node int) int
Purpose
Operation on $&TreeView: set selected. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
node int- node (int)
Returns
int — a value of this type
($&TreeView) clear
pub fn (t $&TreeView) clear() int
Purpose
Clear all buffered or stored entries and internal state. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
Returns
int — a value of this type
($&TreeView) set_bounds
pub fn (t $&TreeView) set_bounds(bounds &layout.Rect) int
Purpose
Operation on $&TreeView: set bounds. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
bounds &layout.Rect- bounds (read-only borrow; caller keeps the original; type &layout.Rect)
Returns
int — a value of this type
($&TreeView) set_scroll_offset
pub fn (t $&TreeView) set_scroll_offset(offset f64) int
Purpose
Operation on $&TreeView: set scroll offset. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
offset f64- offset (f64)
Returns
int — a value of this type
(&TreeView) style_or
pub fn (t &TreeView) style_or(styles &Styles) ControlStyle
Purpose
Operation on &TreeView: style or.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
ControlStyle — a value of this type
($&TreeView) set_style
pub fn (t $&TreeView) set_style(style &ControlStyle) int
Purpose
Operation on $&TreeView: set style. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
style &ControlStyle- style (read-only borrow; caller keeps the original; type &ControlStyle)
Returns
int — a value of this type
($&TreeView) clear_style
pub fn (t $&TreeView) clear_style()
Purpose
Operation on $&TreeView: clear style.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&TreeView) apply_styles
pub fn (t $&TreeView) apply_styles(styles &Styles) int
Purpose
Resolve and apply theme metrics to the control. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
int — a value of this type
(&TreeView) row_bounds
pub fn (t &TreeView) row_bounds(index int) layout.Rect
Purpose
Operation on &TreeView: row bounds.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
index int- index (int)
Returns
layout.Rect — a value of this type
(&TreeView) node_row_text
pub fn (t &TreeView) node_row_text(node int) string
Purpose
Operation on &TreeView: node row text.
Parameters
t &TreeView- The
TreeView instance used by this call (borrow).
node int- node (int)
Returns
string — result string
($&TreeView) input
pub fn (t $&TreeView) input(input &ui.InputEvent) Action
Purpose
Process routed mouse, keyboard, or touch input events. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
input &ui.InputEvent- input (read-only borrow; caller keeps the original; type &ui.InputEvent)
Returns
Action — input result with kind, id, repaint and focus requests.
($&TreeView) route
pub fn (t $&TreeView) route(kind int,input &ui.InputEvent) Action
Purpose
Route and dispatch the input event to matching targets. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
kind int- kind tag (int)
input &ui.InputEvent- input (read-only borrow; caller keeps the original; type &ui.InputEvent)
Returns
Action — input result with kind, id, repaint and focus requests.
($&TreeView) event
pub fn (t $&TreeView) event(event &ui.Event) Action
Purpose
Handle and respond to window or system lifecycle and interaction events. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
event &ui.Event- event (read-only borrow; caller keeps the original; type &ui.Event)
Returns
Action — input result with kind, id, repaint and focus requests.
($&TreeView) measure_styled
pub fn (t $&TreeView) measure_styled(styles &Styles) layout.Size
Purpose
Operation on $&TreeView: measure styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
layout.Size — a value of this type
($&TreeView) dispose
pub fn (t $&TreeView) dispose()
Purpose
Release and dispose native resources and underlying handles.
Parameters
t $&TreeView- The
TreeView instance used by this call (exclusive borrow).
Returns
This call does not return a value.
Complete native example
Component Workshop · Back to Widgets