What to try
Type to filter the suggestions.
Usage notes
Combine typing and selection. Decide explicitly whether custom values outside the list are accepted; filtering only changes the suggestions.
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.combo_box(&options,"Design") or >>
screen.place(id,24.0,24.0,320.0,80.0) or >>
<< id
}
($&Screen) combo_box
pub fn (s $&Screen) combo_box(options &[]string,value string) int
Purpose
Create ComboBox 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)
value string- value (string)
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.
struct ComboBox
Purpose
Editable choice field. Text is owned by Editor and travels through the native TextInput revision/IME protocol, including composition, clipboard and Unicode. Call event for native events and place_combo_box after each View layout. route receives node-local input; input receives canvas coordinates, which lets the scene intercept an open popup before dispatching an outside press. paint_styled paints locally like Editor; paint_popup_styled is canvas-space.
Public fields
This type has no public fields.
(&ComboBox) id
pub fn (combo &ComboBox) id() int
Purpose
Return the unique integer ID of the element or control.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
int — a value of this type
(&ComboBox) bounds
pub fn (combo &ComboBox) bounds() layout.Rect
Purpose
Return the bounding Rectangle of the control or geometry.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
layout.Rect — a value of this type
(&ComboBox) value
pub fn (combo &ComboBox) value() string
Purpose
Execute value on &ComboBox.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
string — result string
(&ComboBox) selected_text
pub fn (combo &ComboBox) selected_text() string
Purpose
Operation on &ComboBox: selected text.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
string — result string
(&ComboBox) selected
pub fn (combo &ComboBox) selected() int
Purpose
Read the original option index matching the current text, to check whether it corresponds to an existing choice.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
Original matching option index, or -1 when the text matches no option.
(&ComboBox) count
pub fn (combo &ComboBox) count() int
Purpose
Return the number of items in this control.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
int — a value of this type
(&ComboBox) filtered_count
pub fn (combo &ComboBox) filtered_count() int
Purpose
Operation on &ComboBox: filtered count.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
int — a value of this type
(&ComboBox) is_open
pub fn (combo &ComboBox) is_open() bool
Purpose
Return whether the overlay, menu or dialog is currently open.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
bool — true or false
(&ComboBox) is_selectable
pub fn (combo &ComboBox) is_selectable() bool
Purpose
Operation on &ComboBox: whether it is selectable.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
bool — true or false
(&ComboBox) is_focused
pub fn (combo &ComboBox) is_focused() bool
Purpose
Return whether the control currently has input focus.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
bool — true or false
(&ComboBox) is_enabled
pub fn (combo &ComboBox) is_enabled() bool
Purpose
Return whether the control is currently enabled.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
bool — true or false
(&ComboBox) needs_paint
pub fn (combo &ComboBox) needs_paint() bool
Purpose
Return whether the control needs repainting; call painted after painting to clear the flag.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
bool — true or false
($&ComboBox) set_placeholder
pub fn (combo $&ComboBox) set_placeholder(value &string) int
Purpose
Operation on $&ComboBox: set placeholder. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
value &string- value (read-only borrow; caller keeps the original; type &string)
Returns
int — a value of this type
(&ComboBox) style_or
pub fn (combo &ComboBox) style_or(styles &Styles) ControlStyle
Purpose
Operation on &ComboBox: style or.
Parameters
combo &ComboBox- The
ComboBox 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
($&ComboBox) set_style
pub fn (combo $&ComboBox) set_style(style &ControlStyle) int
Purpose
Operation on $&ComboBox: set style. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo $&ComboBox- The
ComboBox 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
($&ComboBox) set_enabled
pub fn (combo $&ComboBox) set_enabled(enabled bool) int
Purpose
Operation on $&ComboBox: set enabled. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
enabled bool- enabled (bool)
Returns
int — a value of this type
($&ComboBox) set_read_only
pub fn (combo $&ComboBox) set_read_only(read_only bool) int
Purpose
Operation on $&ComboBox: set read only. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
read_only bool- read_only (bool)
Returns
int — a value of this type
($&ComboBox) set_selectable
pub fn (combo $&ComboBox) set_selectable(selectable bool) int
Purpose
Operation on $&ComboBox: set selectable. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
selectable bool- selectable (bool)
Returns
int — a value of this type
($&ComboBox) set_viewport
pub fn (combo $&ComboBox) set_viewport(viewport &layout.Rect)
Purpose
Operation on $&ComboBox: set viewport.
Parameters
combo $&ComboBox- The
ComboBox 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.
($&ComboBox) set_invalid
pub fn (combo $&ComboBox) set_invalid(invalid bool)
Purpose
Operation on $&ComboBox: set invalid.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
invalid bool- invalid (bool)
Returns
This call does not return a value.
($&ComboBox) focus_session
pub fn (combo $&ComboBox) focus_session(focused bool) int
Purpose
Operation on $&ComboBox: focus session. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
focused bool- focused (bool)
Returns
int — a value of this type
($&ComboBox) set_bounds
pub fn (combo $&ComboBox) set_bounds(bounds &layout.Rect) int
Purpose
Operation on $&ComboBox: set bounds. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo $&ComboBox- The
ComboBox 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
($&ComboBox) set_value
pub fn (combo $&ComboBox) set_value(value &string) int
Purpose
Programmatically replace editable combo-box text and refresh its query state.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
value &string- Complete new text; an exact option match updates the matching index.
Returns
Returns 0 on success; failure throws rather than returning a nonzero status.
Error handling
- An editor replacement failure, such as active IME composition, propagates.
($&ComboBox) set_selected
pub fn (combo $&ComboBox) set_selected(index int) int
Purpose
Select an existing choice, copy its text into the editor and close the list.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
index int- Zero-based index in the original options, not the filtered visible row.
Returns
Returns 0 on success; failure throws rather than returning a nonzero status.
Error handling
- An invalid index throws
widgets: combo choice out of range; replacing text during IME composition can also throw.
($&ComboBox) set_open
pub fn (combo $&ComboBox) set_open(open bool)
Purpose
Set whether the option list is open.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
open booltrue requests opening and false closes it; disabled or read-only controls remain closed.
Returns
No return value; read the resulting state with is_open().
Usage notes
- Opening and painting are separate: call
paint_popup_styled in an appropriate overlay pass.
- An explicit open shows all options; subsequent editing filters them.
($&ComboBox) apply_styles
pub fn (combo $&ComboBox) 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
combo $&ComboBox- The
ComboBox 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
(&ComboBox) option_bounds
pub fn (combo &ComboBox) option_bounds(index int) layout.Rect
Purpose
Operation on &ComboBox: option bounds. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
index int- index (int)
Returns
layout.Rect — a value of this type
(&ComboBox) toggle_bounds
pub fn (combo &ComboBox) toggle_bounds() layout.Rect
Purpose
Operation on &ComboBox: toggle bounds.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
layout.Rect — a value of this type
($&ComboBox) input
pub fn (combo $&ComboBox) input(event &ui.InputEvent) Action
Purpose
Process editable combo-box choice selection, its toggle and editor input.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
event &ui.InputEvent- Input event for the same window, canvas and generation, with coordinates in the control's canvas space.
Returns
An Action: kind identifies the action, consumed marks a handled event, request_focus requests focus, and needs_paint requests repainting.
Usage notes
- Choosing an item yields
ACTION_CHANGE with its original option index in value; Enter and arrows remain with the editor during IME composition.
($&ComboBox) route
pub fn (combo $&ComboBox) route(kind int,event &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
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
kind int- kind tag (int)
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.
($&ComboBox) event
pub fn (combo $&ComboBox) event(event &ui.Event) Action
Purpose
Receive native window events, routing input to input and other events to the internal editor or base control.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
event &ui.Event- Full native
ui.Event; use this entry point for IME, blur and lifecycle handling.
Returns
An Action: kind identifies the action, consumed marks a handled event, request_focus requests focus, and needs_paint requests repainting.
Usage notes
- The option list closes when its internal control loses focus.
($&ComboBox) tick
pub fn (combo $&ComboBox) 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
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
now time.Instant- now (time.Instant)
reduced_motion bool- reduced_motion (bool)
Returns
bool — true or false
(&ComboBox) next_caret_tick
pub fn (combo &ComboBox) next_caret_tick(now time.Instant,reduced_motion bool) time.Instant
Purpose
Operation on &ComboBox: next caret tick. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
now time.Instant- now (time.Instant)
reduced_motion bool- reduced_motion (bool)
Returns
time.Instant — a value of this type
($&ComboBox) measure_styled
pub fn (combo $&ComboBox) measure_styled(styles &Styles) layout.Size
Purpose
Operation on $&ComboBox: measure styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo $&ComboBox- The
ComboBox 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
($&ComboBox) paint_styled
pub fn (combo $&ComboBox) paint_styled(frame $&draw.Frame,styles &Styles) int
Purpose
Operation on $&ComboBox: paint styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo $&ComboBox- The
ComboBox 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
($&ComboBox) dispose
pub fn (combo $&ComboBox) dispose()
Purpose
Release and dispose native resources and underlying handles.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&ComboBox) set_allow_custom
pub fn (combo $&ComboBox) set_allow_custom(allowed bool)
Purpose
Operation on $&ComboBox: set allow custom.
Parameters
combo $&ComboBox- The
ComboBox instance used by this call (exclusive borrow).
allowed bool- allowed (bool)
Returns
This call does not return a value.
(&ComboBox) is_valid_choice
pub fn (combo &ComboBox) is_valid_choice() bool
Purpose
Operation on &ComboBox: whether it is valid choice.
Parameters
combo &ComboBox- The
ComboBox instance used by this call (borrow).
Returns
bool — true or false
($&ComboBox) set_locale
pub fn (combo $&ComboBox) set_locale(locale &Locale) int
Purpose
Operation on $&ComboBox: set locale. Throws on failure; handle the error or propagate it to the caller.
Parameters
combo $&ComboBox- The
ComboBox 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
Complete native example
Component Workshop · Back to Widgets