What to try
Click a row or use arrow keys after focusing the list to change the selection.
Usage notes
Selection and scrolling are separate states. Make the selected item recognizable and validate its index when the data changes.
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 {
options := ["Design","Develop","Review"]
id := screen.list_box(&options,0) or >>
screen.place(id,24.0,24.0,320.0,80.0) or >>
<< id
}
($&Screen) list_box
pub fn (s $&Screen) list_box(options &[]string,selected int) int
Purpose
Create ListBox in Screen and return the component node ID; throw on creation failure.
Parameters
s $&Screen- The
Screen instance used by this call (exclusive borrow).
options &[]string- options (read-only borrow; caller keeps the original; type &[]string)
selected int- selected (int)
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.
(&ListBox) clone
pub fn (value &ListBox) clone() ListBox
Purpose
Copy the control or style snapshot into an independent ListBox value.
Parameters
value &ListBox- The
ListBox instance used by this call (borrow).
Returns
ListBox — a value of this type
struct ListBox
Purpose
ListBox context or state structure.
Public fields
This type has no public fields.
See usage example
(&ListBox) id
pub fn (lb &ListBox) id() int
Purpose
Return the unique integer ID of the element or control.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
int — a value of this type
(&ListBox) bounds
pub fn (lb &ListBox) bounds() layout.Rect
Purpose
Return the bounding Rectangle of the control or geometry.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
layout.Rect — a value of this type
(&ListBox) count
pub fn (lb &ListBox) count() int
Purpose
Return the number of items in this control.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
int — a value of this type
(&ListBox) selected
pub fn (lb &ListBox) selected() int
Purpose
Get or test the currently selected index, node, or state.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
int — a value of this type
(&ListBox) hovered_item
pub fn (lb &ListBox) hovered_item() int
Purpose
Operation on &ListBox: hovered item.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
int — a value of this type
(&ListBox) scroll_offset
pub fn (lb &ListBox) scroll_offset() f64
Purpose
Operation on &ListBox: scroll offset.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
f64 — a value of this type
(&ListBox) is_selectable
pub fn (lb &ListBox) is_selectable() bool
Purpose
Operation on &ListBox: whether it is selectable.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
bool — true or false
($&ListBox) set_selectable
pub fn (lb $&ListBox) set_selectable(selectable bool)
Purpose
Operation on $&ListBox: set selectable.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
selectable bool- selectable (bool)
Returns
This call does not return a value.
(&ListBox) cursor
pub fn (lb &ListBox) cursor() int
Purpose
Execute cursor on &ListBox.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
int — a value of this type
($&ListBox) set_locale
pub fn (lb $&ListBox) set_locale(locale &Locale) int
Purpose
Operation on $&ListBox: set locale. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb $&ListBox- The
ListBox 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
($&ListBox) set_viewport
pub fn (lb $&ListBox) set_viewport(viewport &layout.Rect,context &draw.Context)
Purpose
Operation on $&ListBox: set viewport.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
viewport &layout.Rect- viewport (read-only borrow; caller keeps the original; type &layout.Rect)
context &draw.Context- context (read-only borrow; caller keeps the original; type &draw.Context)
Returns
This call does not return a value.
($&ListBox) dispose_aux
pub fn (lb $&ListBox) dispose_aux()
Purpose
Operation on $&ListBox: dispose aux.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&ListBox) set_styles_cache
pub fn (lb $&ListBox) set_styles_cache(styles &Styles)
Purpose
Operation on $&ListBox: set styles cache.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
This call does not return a value.
(&ListBox) style_snapshot
pub fn (lb &ListBox) style_snapshot() Styles
Purpose
Operation on &ListBox: style snapshot.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
Styles — a value of this type
(&ListBox) has_selection_for_row
pub fn (lb &ListBox) has_selection_for_row(row int) bool
Purpose
Operation on &ListBox: whether it has selection for row.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
row int- row (int)
Returns
bool — true or false
(&ListBox) row_sel_anchor
pub fn (lb &ListBox) row_sel_anchor() int
Purpose
Operation on &ListBox: row sel anchor.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
int — a value of this type
(&ListBox) row_sel_focus
pub fn (lb &ListBox) row_sel_focus() int
Purpose
Operation on &ListBox: row sel focus.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
int — a value of this type
(&ListBox) selected_text
pub fn (lb &ListBox) selected_text() string
Purpose
Operation on &ListBox: selected text.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
string — result string
($&ListBox) handle_text_key
pub fn (lb $&ListBox) handle_text_key(event &ui.InputEvent) Action
Purpose
Operation on $&ListBox: handle text key.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
event &ui.InputEvent- event (read-only borrow; caller keeps the original; type &ui.InputEvent)
Returns
Action — input result with kind, id, repaint and focus requests.
($&ListBox) ensure_row_text
pub fn (lb $&ListBox) ensure_row_text(row int,col int,text &string,row_text &string)
Purpose
Operation on $&ListBox: ensure row text.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
row int- row (int)
col int- col (int)
text &string- text (read-only borrow; caller keeps the original; type &string)
row_text &string- row_text (read-only borrow; caller keeps the original; type &string)
Returns
This call does not return a value.
($&ListBox) begin_row_pointer
pub fn (lb $&ListBox) begin_row_pointer(text &string,row_text &string,idx int,row int,col int,event &ui.InputEvent) bool
Purpose
Operation on $&ListBox: begin row pointer.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
text &string- text (read-only borrow; caller keeps the original; type &string)
row_text &string- row_text (read-only borrow; caller keeps the original; type &string)
idx int- idx (int)
row int- row (int)
col int- col (int)
event &ui.InputEvent- event (read-only borrow; caller keeps the original; type &ui.InputEvent)
Returns
bool — true or false
($&ListBox) should_begin_row_drag
pub fn (lb $&ListBox) should_begin_row_drag(x f64,y f64,density f64) bool
Purpose
Operation on $&ListBox: should begin row drag.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
x f64- value (f64)
y f64- value (f64)
density f64- density (f64)
Returns
bool — true or false
($&ListBox) drag_row_pointer
pub fn (lb $&ListBox) drag_row_pointer(idx int) bool
Purpose
Operation on $&ListBox: drag row pointer.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
idx int- idx (int)
Returns
bool — true or false
($&ListBox) end_row_pointer
pub fn (lb $&ListBox) end_row_pointer()
Purpose
Operation on $&ListBox: end row pointer.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&ListBox) clear_text_selection
pub fn (lb $&ListBox) clear_text_selection()
Purpose
Operation on $&ListBox: clear text selection.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
Returns
This call does not return a value.
(&ListBox) needs_paint
pub fn (lb &ListBox) needs_paint() bool
Purpose
Return whether the control needs repainting; call painted after painting to clear the flag.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
bool — true or false
($&ListBox) painted
pub fn (lb $&ListBox) painted()
Purpose
Acknowledge the painted frame and clear the dirty flag; this is not a query.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&ListBox) invalidate
pub fn (lb $&ListBox) invalidate()
Purpose
Invalidate the control area, requesting a repaint on next frame.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&ListBox) cancel
pub fn (lb $&ListBox) cancel()
Purpose
Execute cancel on $&ListBox.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
Returns
This call does not return a value.
(&ListBox) is_enabled
pub fn (lb &ListBox) is_enabled() bool
Purpose
Return whether the control is currently enabled.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
bool — true or false
($&ListBox) set_enabled
pub fn (lb $&ListBox) set_enabled(enabled bool)
Purpose
Operation on $&ListBox: set enabled.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
enabled bool- enabled (bool)
Returns
This call does not return a value.
(&ListBox) is_focused
pub fn (lb &ListBox) is_focused() bool
Purpose
Return whether the control currently has input focus.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
bool — true or false
($&ListBox) set_focus
pub fn (lb $&ListBox) set_focus(focused bool)
Purpose
Operation on $&ListBox: set focus.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
focused bool- focused (bool)
Returns
This call does not return a value.
(&ListBox) is_hovered
pub fn (lb &ListBox) is_hovered() bool
Purpose
Operation on &ListBox: whether it is hovered.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
bool — true or false
(&ListBox) is_invalid
pub fn (lb &ListBox) is_invalid() bool
Purpose
Operation on &ListBox: whether it is invalid.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
bool — true or false
($&ListBox) set_invalid
pub fn (lb $&ListBox) set_invalid(invalid bool)
Purpose
Operation on $&ListBox: set invalid.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
invalid bool- invalid (bool)
Returns
This call does not return a value.
(&ListBox) is_read_only
pub fn (lb &ListBox) is_read_only() bool
Purpose
Operation on &ListBox: whether it is read only.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
bool — true or false
($&ListBox) set_read_only
pub fn (lb $&ListBox) set_read_only(read_only bool)
Purpose
Operation on $&ListBox: set read only.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
read_only bool- read_only (bool)
Returns
This call does not return a value.
($&ListBox) set_scroll_offset
pub fn (lb $&ListBox) set_scroll_offset(offset f64) int
Purpose
Operation on $&ListBox: set scroll offset. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
offset f64- offset (f64)
Returns
int — a value of this type
($&ListBox) ensure_visible
pub fn (lb $&ListBox) ensure_visible(index int)
Purpose
Operation on $&ListBox: ensure visible.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
index int- index (int)
Returns
This call does not return a value.
($&ListBox) set_count
pub fn (lb $&ListBox) set_count(count int) int
Purpose
Operation on $&ListBox: set count. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
count int- count (int)
Returns
int — a value of this type
($&ListBox) set_selected
pub fn (lb $&ListBox) set_selected(index int) int
Purpose
Operation on $&ListBox: set selected. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
index int- index (int)
Returns
int — a value of this type
($&ListBox) set_bounds
pub fn (lb $&ListBox) set_bounds(bounds &layout.Rect) int
Purpose
Operation on $&ListBox: set bounds. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb $&ListBox- The
ListBox 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
(&ListBox) visual_state
pub fn (lb &ListBox) visual_state() int
Purpose
Operation on &ListBox: visual state.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
int — a value of this type
(&ListBox) item_visual_state
pub fn (lb &ListBox) item_visual_state(index int) int
Purpose
Operation on &ListBox: item visual state.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
index int- index (int)
Returns
int — a value of this type
(&ListBox) has_style
pub fn (lb &ListBox) has_style() bool
Purpose
Operation on &ListBox: whether it has style.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
Returns
bool — true or false
(&ListBox) style_or
pub fn (lb &ListBox) style_or(styles &Styles) ControlStyle
Purpose
Operation on &ListBox: style or.
Parameters
lb &ListBox- The
ListBox 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
($&ListBox) set_style
pub fn (lb $&ListBox) set_style(style &ControlStyle) int
Purpose
Operation on $&ListBox: set style. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb $&ListBox- The
ListBox 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
($&ListBox) clear_style
pub fn (lb $&ListBox) clear_style()
Purpose
Operation on $&ListBox: clear style.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&ListBox) apply_styles
pub fn (lb $&ListBox) apply_styles(styles &Styles) int
Purpose
Apply resolved metrics before routing input, just as Scroll and Editor do. Painting, scrolling and pointer hit testing must share the same row geometry. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb $&ListBox- The
ListBox 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
(&ListBox) hit_row
pub fn (lb &ListBox) hit_row(x f64,y f64) int
Purpose
Operation on &ListBox: hit row.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
x f64- value (f64)
y f64- value (f64)
Returns
int — a value of this type
($&ListBox) input
pub fn (lb $&ListBox) 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
lb $&ListBox- The
ListBox 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.
($&ListBox) event
pub fn (lb $&ListBox) 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
lb $&ListBox- The
ListBox 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.
(&ListBox) paint
pub fn (lb &ListBox) paint(frame $&draw.Frame,labels &[]draw.TextLayout,theme &Theme) int
Purpose
Paint the control visually onto the target canvas. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
frame $&draw.Frame- frame (exclusive borrow; may modify the original; type $&draw.Frame)
labels &[]draw.TextLayout- labels (read-only borrow; caller keeps the original; type &[]draw.TextLayout)
theme &Theme- theme (read-only borrow; caller keeps the original; type &Theme)
Returns
int — a value of this type
(&ListBox) measure_styled
pub fn (lb &ListBox) measure_styled(label $&StyledLabel,styles &Styles) layout.Size
Purpose
Operation on &ListBox: measure styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
label $&StyledLabel- label (exclusive borrow; may modify the original; type $&StyledLabel)
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
layout.Size — a value of this type
(&ListBox) paint_box_styled
pub fn (lb &ListBox) paint_box_styled(frame $&draw.Frame,styles &Styles) int
Purpose
Operation on &ListBox: paint box styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb &ListBox- The
ListBox instance used by this call (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
(&ListBox) paint_item_styled
pub fn (lb &ListBox) paint_item_styled(frame $&draw.Frame,index int,label $&StyledLabel,styles &Styles) int
Purpose
Operation on &ListBox: paint item styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
frame $&draw.Frame- frame (exclusive borrow; may modify the original; type $&draw.Frame)
index int- index (int)
label $&StyledLabel- label (exclusive borrow; may modify the original; type $&StyledLabel)
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
int — a value of this type
(&ListBox) paint_styled
pub fn (lb &ListBox) paint_styled(frame $&draw.Frame,label $&StyledLabel,styles &Styles) int
Purpose
Operation on &ListBox: paint styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
frame $&draw.Frame- frame (exclusive borrow; may modify the original; type $&draw.Frame)
label $&StyledLabel- label (exclusive borrow; may modify the original; type $&StyledLabel)
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
int — a value of this type
($&ListBox) set_appearance
pub fn (lb $&ListBox) set_appearance(appearance &ListAppearance) int
Purpose
Operation on $&ListBox: set appearance. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb $&ListBox- The
ListBox instance used by this call (exclusive borrow).
appearance &ListAppearance- appearance (read-only borrow; caller keeps the original; type &ListAppearance)
Returns
int — a value of this type
(&ListBox) item_bounds
pub fn (lb &ListBox) item_bounds(index int,styles &Styles) layout.Rect
Purpose
Operation on &ListBox: item bounds. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
index int- index (int)
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
layout.Rect — a value of this type
(&ListBox) hit_item_byte
pub fn (lb &ListBox) hit_item_byte(index int,title $&StyledLabel,styles &Styles,has_row_layout bool,has_description bool,has_detail bool,icon int,x_pos f64,y_pos f64) int
Purpose
Operation on &ListBox: hit item byte.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
index int- index (int)
title $&StyledLabel- title (exclusive borrow; may modify the original; type $&StyledLabel)
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
has_row_layout bool- has_row_layout (bool)
has_description bool- has_description (bool)
has_detail bool- has_detail (bool)
icon int- icon (int)
x_pos f64- x_pos (f64)
y_pos f64- y_pos (f64)
Returns
int — a value of this type
(&ListBox) paint_row_styled
pub fn (lb &ListBox) paint_row_styled(frame $&draw.Frame,index int,title $&StyledLabel,description $&StyledLabel,detail $&StyledLabel,icon int,styles &Styles) int
Purpose
Operation on &ListBox: paint row styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
lb &ListBox- The
ListBox instance used by this call (borrow).
frame $&draw.Frame- frame (exclusive borrow; may modify the original; type $&draw.Frame)
index int- index (int)
title $&StyledLabel- title (exclusive borrow; may modify the original; type $&StyledLabel)
description $&StyledLabel- description (exclusive borrow; may modify the original; type $&StyledLabel)
detail $&StyledLabel- detail (exclusive borrow; may modify the original; type $&StyledLabel)
icon int- icon (int)
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
int — a value of this type
($&ListBox) route
pub fn (lb $&ListBox) 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
lb $&ListBox- The
ListBox 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.
Complete native example
Component Workshop · Back to Widgets