UI / WIDGETS / Text input
Field
Combine a label, help and validation with an input
Run the Xu example ↗The example executes in the browser using the Xu/WASM runtime.
What to try
Submit an empty name, then correct it.
Usage notes
Labels, help and errors serve different purposes. Validate in the application before setting the error state; a red border does not validate data.
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 {
decoration := widgets.field_decoration(&"Project name")
id := screen.field("",&decoration) or >>
screen.place(id,24.0,24.0,320.0,80.0) or >>
<< id
}
($&Screen) field
pub fn (s $&Screen) field(value string,decoration &FieldDecoration) int
Purpose
Create Field 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)
decoration &FieldDecoration- decoration (read-only borrow; caller keeps the original; type &FieldDecoration)
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.
($&Field) set_locale
pub fn (field $&Field) set_locale(locale &Locale) int
Purpose
Operation on $&Field: set locale. Throws on failure; handle the error or propagate it to the caller.
Parameters
field $&Field- The
Field 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
struct Field
Purpose
The decorator owns an ordinary Editor. Its content geometry is independent of label animation, preserving selection, native IME and candidate placement.
Public fields
This type has no public fields.
(&Field) id
pub fn (f &Field) id() int
Purpose
Return the unique integer ID of the element or control.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
int — a value of this type
(&Field) bounds
pub fn (f &Field) bounds() layout.Rect
Purpose
Return the bounding Rectangle of the control or geometry.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
layout.Rect — a value of this type
(&Field) value
pub fn (f &Field) value() string
Purpose
Execute value on &Field.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
string — result string
(&Field) has_selection
pub fn (f &Field) has_selection() bool
Purpose
Operation on &Field: whether it has selection.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
bool — true or false
(&Field) is_copy_enabled
pub fn (f &Field) is_copy_enabled() bool
Purpose
Operation on &Field: whether it is copy enabled.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
bool — true or false
(&Field) selected_text
pub fn (f &Field) selected_text() string
Purpose
Operation on &Field: selected text.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
string — result string
(&Field) is_enabled
pub fn (f &Field) is_enabled() bool
Purpose
Return whether the control is currently enabled.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
bool — true or false
(&Field) is_focused
pub fn (f &Field) is_focused() bool
Purpose
Return whether the control currently has input focus.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
bool — true or false
(&Field) is_read_only
pub fn (f &Field) is_read_only() bool
Purpose
Operation on &Field: whether it is read only.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
bool — true or false
(&Field) is_invalid
pub fn (f &Field) is_invalid() bool
Purpose
Operation on &Field: whether it is invalid.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
bool — true or false
(&Field) is_selectable
pub fn (f &Field) is_selectable() bool
Purpose
Operation on &Field: whether it is selectable.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
bool — true or false
(&Field) cursor
pub fn (f &Field) cursor() int
Purpose
Execute cursor on &Field.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
int — a value of this type
(&Field) needs_paint
pub fn (f &Field) needs_paint() bool
Purpose
Return whether the control needs repainting; call painted after painting to clear the flag.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
bool — true or false
($&Field) painted
pub fn (f $&Field) painted()
Purpose
Acknowledge the painted frame and clear the dirty flag; this is not a query.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
Returns
This call does not return a value.
(&Field) style_or
pub fn (f &Field) style_or(styles &Styles) ControlStyle
Purpose
Operation on &Field: style or.
Parameters
f &Field- The
Field 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
($&Field) set_style
pub fn (f $&Field) set_style(style &ControlStyle) int
Purpose
Operation on $&Field: set style. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field 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
($&Field) set_decoration
pub fn (f $&Field) set_decoration(decoration &FieldDecoration) int
Purpose
Operation on $&Field: set decoration. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
decoration &FieldDecoration- decoration (read-only borrow; caller keeps the original; type &FieldDecoration)
Returns
int — a value of this type
($&Field) set_motion
pub fn (f $&Field) set_motion(spec &MotionSpec) int
Purpose
Operation on $&Field: set motion. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field 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
($&Field) set_invalid
pub fn (f $&Field) set_invalid(invalid bool)
Purpose
Operation on $&Field: set invalid.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
invalid bool- invalid (bool)
Returns
This call does not return a value.
($&Field) set_value
pub fn (f $&Field) set_value(value &string) int
Purpose
Operation on $&Field: set value. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field 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
($&Field) set_read_only
pub fn (f $&Field) set_read_only(read_only bool) int
Purpose
Operation on $&Field: set read only. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
read_only bool- read_only (bool)
Returns
int — a value of this type
($&Field) set_selectable
pub fn (f $&Field) set_selectable(selectable bool) int
Purpose
Operation on $&Field: set selectable. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
selectable bool- selectable (bool)
Returns
int — a value of this type
($&Field) set_copy_enabled
pub fn (f $&Field) set_copy_enabled(on bool)
Purpose
Operation on $&Field: set copy enabled.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
on bool- on (bool)
Returns
This call does not return a value.
($&Field) set_viewport
pub fn (f $&Field) set_viewport(viewport &layout.Rect)
Purpose
Operation on $&Field: set viewport.
Parameters
f $&Field- The
Field 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.
($&Field) focus_session
pub fn (f $&Field) focus_session(focused bool) int
Purpose
Operation on $&Field: focus session. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
focused bool- focused (bool)
Returns
int — a value of this type
($&Field) enable
pub fn (f $&Field) enable(enabled bool) int
Purpose
Execute enable on $&Field. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
enabled bool- enabled (bool)
Returns
int — a value of this type
($&Field) place
pub fn (f $&Field) place(bounds &layout.Rect) int
Purpose
Compute and place control bounds within canvas layout. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field 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
($&Field) apply_styles
pub fn (f $&Field) 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
f $&Field- The
Field 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
($&Field) input
pub fn (f $&Field) input(input &ui.InputEvent) Action
Purpose
Like Editor.route, pointer coordinates are local to bounds; input offers the canvas-coordinate entry point used by Screen and immediate applications. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field 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.
($&Field) route
pub fn (f $&Field) 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
f $&Field- The
Field 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.
($&Field) event
pub fn (f $&Field) 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
f $&Field- The
Field 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.
($&Field) tick
pub fn (f $&Field) tick(now time.Instant,reduced bool) bool
Purpose
Advance animation clock and state transition step. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
now time.Instant- now (time.Instant)
reduced bool- reduced (bool)
Returns
bool — true or false
(&Field) next_caret_tick
pub fn (f &Field) next_caret_tick(now time.Instant,reduced bool) time.Instant
Purpose
Operation on &Field: next caret tick. Throws on failure; handle the error or propagate it to the caller.
Parameters
f &Field- The
Field instance used by this call (borrow).
now time.Instant- now (time.Instant)
reduced bool- reduced (bool)
Returns
time.Instant — a value of this type
($&Field) measure_styled
pub fn (f $&Field) measure_styled(styles &Styles) layout.Size
Purpose
Operation on $&Field: measure styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field 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
($&Field) dispose
pub fn (f $&Field) dispose()
Purpose
Release and dispose native resources and underlying handles.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&Field) paint_styled
pub fn (f $&Field) paint_styled(frame $&draw.Frame,styles &Styles) int
Purpose
Paint in local coordinates, matching Editor and View. The Editor still retains its canvas-global bounds for the native text session. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field 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
($&Field) set_text_options
pub fn (f $&Field) set_text_options(options &FieldTextOptions) int
Purpose
Operation on $&Field: set text options. Throws on failure; handle the error or propagate it to the caller.
Parameters
f $&Field- The
Field instance used by this call (exclusive borrow).
options &FieldTextOptions- options (read-only borrow; caller keeps the original; type &FieldTextOptions)
Returns
int — a value of this type
(&Field) text_options
pub fn (f &Field) text_options() FieldTextOptions
Purpose
Operation on &Field: text options.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
FieldTextOptions — a value of this type
(&Field) character_count
pub fn (f &Field) character_count() int
Purpose
Counts Unicode scalars without truncating text or touching IME composition. This is a soft counter; application validation decides when to reject input.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
int — a value of this type
(&Field) is_over_limit
pub fn (f &Field) is_over_limit() bool
Purpose
Operation on &Field: whether it is over limit.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
bool — true or false
(&Field) preferred_rows
pub fn (f &Field) preferred_rows() int
Purpose
Operation on &Field: preferred rows.
Parameters
f &Field- The
Field instance used by this call (borrow).
Returns
int — a value of this type
Complete native example
Component Workshop · Back to Widgets