XU XUv0.13.1
中文

UI / WIDGETS / Text input

TextArea

Edit multiple lines of text

Run the Xu example

The example executes in the browser using the Xu/WASM runtime.

What to try

Write a description with line breaks.

Usage notes

Use for longer text and line breaks. Reserve enough height and distinguish editor scrolling from the outer page scroll.

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.text_area("Project description") or >>
    screen.place(id,24.0,24.0,320.0,80.0) or >>
    << id
}

($&Screen) text_area

XuAPI
pub fn (s $&Screen) text_area(value string) int

Purpose

Create TextArea 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

XuAPI
pub 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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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) has_popup_open

XuAPI
pub fn (editor &Editor) has_popup_open() bool

Purpose

Operation on &Editor: whether it has popup open.

Parameters

editor &Editor
The Editor instance used by this call (borrow).

Returns

bool — true or false

(&Editor) popup_bounds

XuAPI
pub fn (editor &Editor) popup_bounds() layout.Rect

Purpose

Operation on &Editor: popup bounds.

Parameters

editor &Editor
The Editor instance used by this call (borrow).

Returns

layout.Rect — a value of this type

(&Editor) cursor

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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) paint_popup_styled

XuAPI
pub fn (editor $&Editor) paint_popup_styled(frame $&draw.Frame,styles &Styles) int

Purpose

Operation on $&Editor: paint popup 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)

Returns

int — a value of this type

($&Editor) set_placeholder

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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

XuAPI
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