UI / WIDGETS / Text input
Input
Edit a single line of text
Run the Xu example ↗The example executes in the browser using the Xu/WASM runtime.
What to try
Enter and clear a project name.
Usage notes
Use for single-line values. Read and update text through application state; choose TextArea for multiple lines or Field for a label and validation feedback.
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.input("Xu workspace") or >>
screen.place(id,24.0,24.0,320.0,80.0) or >>
<< id
}
($&Screen) input
pub fn (s $&Screen) input(value string) int
Purpose
Create Input in Screen and return the component node ID; throw on creation failure.
Parameters
s $&Screen- The
Screen instance used by this call (exclusive borrow).
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 Editor
Purpose
Input and TextArea share one persistent editor. Native TextInput owns edits while focused; this model owns the committed value between focus lifetimes.
Public fields
This type has no public fields.
See usage example
(&Editor) id
pub fn (editor &Editor) id() int
Purpose
Return the unique integer ID of the element or control.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
int — a value of this type
(&Editor) value
pub fn (editor &Editor) value() string
Purpose
Execute value on &Editor.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
string — result string
(&Editor) has_selection
pub fn (editor &Editor) has_selection() bool
Purpose
Operation on &Editor: whether it has selection.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
(&Editor) selection_range
pub fn (editor &Editor) selection_range() TextRange
Purpose
Operation on &Editor: selection range.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
TextRange — a value of this type
(&Editor) selected_text
pub fn (editor &Editor) selected_text() string
Purpose
Operation on &Editor: selected text.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
string — result string
(&Editor) is_password
pub fn (editor &Editor) is_password() bool
Purpose
Operation on &Editor: whether it is password.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
(&Editor) is_password_visible
pub fn (editor &Editor) is_password_visible() bool
Purpose
Operation on &Editor: whether it is password visible.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
($&Editor) set_password
pub fn (editor $&Editor) set_password(on bool) int
Purpose
Operation on $&Editor: set password. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
on bool- on (bool)
Returns
int — a value of this type
($&Editor) set_password_visible
pub fn (editor $&Editor) set_password_visible(visible bool) int
Purpose
Operation on $&Editor: set password visible. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
visible bool- visible (bool)
Returns
int — a value of this type
(&Editor) is_focused
pub fn (editor &Editor) is_focused() bool
Purpose
Return whether the control currently has input focus.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
(&Editor) is_enabled
pub fn (editor &Editor) is_enabled() bool
Purpose
Return whether the control is currently enabled.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
(&Editor) is_selectable
pub fn (editor &Editor) is_selectable() bool
Purpose
Operation on &Editor: whether it is selectable.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
(&Editor) cursor
pub fn (editor &Editor) cursor() int
Purpose
Execute cursor on &Editor.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
int — a value of this type
(&Editor) needs_paint
pub fn (editor &Editor) needs_paint() bool
Purpose
Return whether the control needs repainting; call painted after painting to clear the flag.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
($&Editor) painted
pub fn (editor $&Editor) painted()
Purpose
Acknowledge the painted frame and clear the dirty flag; this is not a query.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&Editor) set_locale
pub fn (editor $&Editor) set_locale(locale &Locale) int
Purpose
Operation on $&Editor: set locale. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor 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
($&Editor) set_viewport
pub fn (editor $&Editor) set_viewport(viewport &layout.Rect)
Purpose
Operation on $&Editor: set viewport.
Parameters
editor $&Editor- The
Editor 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.
($&Editor) set_selectable
pub fn (editor $&Editor) set_selectable(selectable bool) int
Purpose
Operation on $&Editor: set selectable. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
selectable bool- selectable (bool)
Returns
int — a value of this type
($&Editor) set_placeholder
pub fn (editor $&Editor) set_placeholder(value &string) int
Purpose
Operation on $&Editor: set placeholder. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor 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
($&Editor) focus_session
pub fn (editor $&Editor) focus_session(on bool) int
Purpose
Change editing focus and native session lifetime; committed text persists on blur.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
on bool- on (bool)
Returns
0 on success; throws on failure
($&Editor) enable
pub fn (editor $&Editor) enable(on bool) int
Purpose
Execute enable on $&Editor. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
on bool- on (bool)
Returns
int — a value of this type
($&Editor) place
pub fn (editor $&Editor) place(bounds &layout.Rect) int
Purpose
Set canvas-global bounds after layout or ancestor scrolling to synchronize native IME geometry.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
bounds &layout.Rect- bounds (read-only borrow; caller keeps the original; type &layout.Rect)
Returns
0 on success; throws on failure
($&Editor) set_value
pub fn (editor $&Editor) set_value(value &string) int
Purpose
Operation on $&Editor: set value. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor 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
($&Editor) route
pub fn (editor $&Editor) 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
editor $&Editor- The
Editor 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.
($&Editor) event
pub fn (editor $&Editor) 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
editor $&Editor- The
Editor 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.
($&Editor) paint
pub fn (editor $&Editor) paint(frame $&draw.Frame,theme &Theme) int
Purpose
Retain the layout until the containing frame has been accepted. painted acknowledges dirtiness, not native resource ownership. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
frame $&draw.Frame- frame (exclusive borrow; may modify the original; type $&draw.Frame)
theme &Theme- theme (read-only borrow; caller keeps the original; type &Theme)
Returns
int — a value of this type
($&Editor) dispose
pub fn (editor $&Editor) dispose()
Purpose
Release and dispose native resources and underlying handles.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
Returns
This call does not return a value.
(&Editor) caret_opacity
pub fn (editor &Editor) caret_opacity() f64
Purpose
Operation on &Editor: caret opacity.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
f64 — a value of this type
(&Editor) has_caret_animation
pub fn (editor &Editor) has_caret_animation() bool
Purpose
Operation on &Editor: whether it has caret animation.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
(&Editor) next_caret_tick
pub fn (editor &Editor) next_caret_tick(now time.Instant,reduced_motion bool) time.Instant
Purpose
Operation on &Editor: next caret tick. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor &Editor- The
Editor 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
($&Editor) tick
pub fn (editor $&Editor) tick(now time.Instant,reduced_motion bool) bool
Purpose
Call from the owning event loop. Only the short fade phases need new frames editing/selection restarts a full visible interval and IME stays steady. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
now time.Instant- now (time.Instant)
reduced_motion bool- reduced_motion (bool)
Returns
bool — true or false
(&Editor) bounds
pub fn (editor &Editor) bounds() layout.Rect
Purpose
Return the bounding Rectangle of the control or geometry.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
layout.Rect — a value of this type
(&Editor) is_invalid
pub fn (editor &Editor) is_invalid() bool
Purpose
Operation on &Editor: whether it is invalid.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
(&Editor) is_hovered
pub fn (editor &Editor) is_hovered() bool
Purpose
Operation on &Editor: whether it is hovered.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
(&Editor) visual_state
pub fn (editor &Editor) visual_state() int
Purpose
Operation on &Editor: visual state.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
int — a value of this type
(&Editor) has_style
pub fn (editor &Editor) has_style() bool
Purpose
Operation on &Editor: whether it has style.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
(&Editor) style_or
pub fn (editor &Editor) style_or(styles &Styles) ControlStyle
Purpose
Operation on &Editor: style or.
Parameters
editor &Editor- The
Editor 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
($&Editor) set_style
pub fn (editor $&Editor) set_style(style &ControlStyle) int
Purpose
Operation on $&Editor: set style. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor 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
($&Editor) clear_style
pub fn (editor $&Editor) clear_style()
Purpose
Operation on $&Editor: clear style.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&Editor) apply_styles
pub fn (editor $&Editor) apply_styles(styles &Styles) int
Purpose
Validate and apply styles, updating layout / geometry and repainting when metrics change.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
0 on success; throws on failure
($&Editor) paint_motion_styled
pub fn (editor $&Editor) paint_motion_styled(frame $&draw.Frame,styles &Styles,motion $&PaintTransition,now time.Instant,reduced_motion bool) int
Purpose
Operation on $&Editor: paint motion styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
editor $&Editor- The
Editor 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)
motion $&PaintTransition- motion (exclusive borrow; may modify the original; type $&PaintTransition)
now time.Instant- now (time.Instant)
reduced_motion bool- reduced_motion (bool)
Returns
int — a value of this type
($&Editor) set_invalid
pub fn (editor $&Editor) set_invalid(invalid bool)
Purpose
Operation on $&Editor: set invalid.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
invalid bool- invalid (bool)
Returns
This call does not return a value.
(&Editor) is_read_only
pub fn (editor &Editor) is_read_only() bool
Purpose
Operation on &Editor: whether it is read only.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
($&Editor) set_read_only
pub fn (editor $&Editor) set_read_only(on bool) int
Purpose
Switch read-only state, releasing or restarting native input. Preserve selection, navigation and copy; reject edits and late IME commits while read-only.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
on bool- on (bool)
Returns
0 on success; throws on failure
(&Editor) is_copy_enabled
pub fn (editor &Editor) is_copy_enabled() bool
Purpose
Operation on &Editor: whether it is copy enabled.
Parameters
editor &Editor- The
Editor instance used by this call (borrow).
Returns
bool — true or false
($&Editor) set_copy_enabled
pub fn (editor $&Editor) set_copy_enabled(on bool)
Purpose
Operation on $&Editor: set copy enabled.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
on bool- on (bool)
Returns
This call does not return a value.
($&Editor) measure_styled
pub fn (editor $&Editor) measure_styled(styles &Styles) layout.Size
Purpose
Measure Editor with the effective font, density, content and minimum size.
Parameters
editor $&Editor- The
Editor instance used by this call (exclusive borrow).
styles &Styles- styles (read-only borrow; caller keeps the original; type &Styles)
Returns
intrinsic logical size; throws if native shaping fails
($&Editor) paint_styled
pub fn (editor $&Editor) paint_styled(frame $&draw.Frame,styles &Styles) int
Purpose
Paint Editor using the complete theme; control bounds and Frame use the same local coordinates.
Parameters
editor $&Editor- The
Editor 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
0 on success; throws on failure
Complete native example
Component Workshop · Back to Widgets