XU XUv0.13.1
中文

UI / WIDGETS / Selection

Switch

Turn a setting on or off immediately

Run the Xu example

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

What to try

Toggle the switch and observe the boolean value.

Usage notes

Use for settings that take effect immediately. Label the setting rather than the action and make both on and off states understandable.

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.switch_control("Live preview",true) or >>
    screen.place(id,24.0,24.0,320.0,80.0) or >>
    << id
}

($&Screen) switch_control

XuAPI
pub fn (s $&Screen) switch_control(text string,checked bool) int

Purpose

Create Switch in Screen and return the component node ID; throw on creation failure.

Parameters

s $&Screen
The Screen instance used by this call (exclusive borrow).
text string
text (string)
checked bool
checked (bool)

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.

(&Switch) clone

XuAPI
pub fn (value &Switch) clone() Switch

Purpose

Copy the control or style snapshot into an independent Switch value.

Parameters

value &Switch
The Switch instance used by this call (borrow).

Returns

Switch — a value of this type

struct Switch

XuAPI
pub struct Switch {

}

Purpose

Switch context or state structure.

Public fields

This type has no public fields.

See usage example

(&Switch) id

XuAPI
pub fn (sw &Switch) id() int

Purpose

Return the unique integer ID of the element or control.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

int — a value of this type

(&Switch) bounds

XuAPI
pub fn (sw &Switch) bounds() layout.Rect

Purpose

Return the bounding Rectangle of the control or geometry.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

layout.Rect — a value of this type

(&Switch) needs_paint

XuAPI
pub fn (sw &Switch) needs_paint() bool

Purpose

Return whether the control needs repainting; call painted after painting to clear the flag.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

($&Switch) painted

XuAPI
pub fn (sw $&Switch) painted()

Purpose

Acknowledge the painted frame and clear the dirty flag; this is not a query.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).

Returns

This call does not return a value.

($&Switch) invalidate

XuAPI
pub fn (sw $&Switch) invalidate()

Purpose

Invalidate the control area, requesting a repaint on next frame.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).

Returns

This call does not return a value.

($&Switch) cancel

XuAPI
pub fn (sw $&Switch) cancel()

Purpose

Execute cancel on $&Switch.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).

Returns

This call does not return a value.

(&Switch) is_enabled

XuAPI
pub fn (sw &Switch) is_enabled() bool

Purpose

Return whether the control is currently enabled.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

(&Switch) is_selectable

XuAPI
pub fn (sw &Switch) is_selectable() bool

Purpose

Operation on &Switch: whether it is selectable.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

($&Switch) set_selectable

XuAPI
pub fn (sw $&Switch) set_selectable(selectable bool)

Purpose

Operation on $&Switch: set selectable.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).
selectable bool
selectable (bool)

Returns

This call does not return a value.

($&Switch) set_enabled

XuAPI
pub fn (sw $&Switch) set_enabled(enabled bool)

Purpose

Operation on $&Switch: set enabled.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).
enabled bool
enabled (bool)

Returns

This call does not return a value.

(&Switch) is_focused

XuAPI
pub fn (sw &Switch) is_focused() bool

Purpose

Return whether the control currently has input focus.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

($&Switch) set_focus

XuAPI
pub fn (sw $&Switch) set_focus(focused bool)

Purpose

Operation on $&Switch: set focus.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).
focused bool
focused (bool)

Returns

This call does not return a value.

(&Switch) is_hovered

XuAPI
pub fn (sw &Switch) is_hovered() bool

Purpose

Operation on &Switch: whether it is hovered.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

(&Switch) is_pressed

XuAPI
pub fn (sw &Switch) is_pressed() bool

Purpose

Operation on &Switch: whether it is pressed.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

(&Switch) is_invalid

XuAPI
pub fn (sw &Switch) is_invalid() bool

Purpose

Operation on &Switch: whether it is invalid.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

($&Switch) set_invalid

XuAPI
pub fn (sw $&Switch) set_invalid(invalid bool)

Purpose

Operation on $&Switch: set invalid.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).
invalid bool
invalid (bool)

Returns

This call does not return a value.

(&Switch) is_read_only

XuAPI
pub fn (sw &Switch) is_read_only() bool

Purpose

Operation on &Switch: whether it is read only.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

($&Switch) set_read_only

XuAPI
pub fn (sw $&Switch) set_read_only(read_only bool)

Purpose

Operation on $&Switch: set read only.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).
read_only bool
read_only (bool)

Returns

This call does not return a value.

($&Switch) set_bounds

XuAPI
pub fn (sw $&Switch) set_bounds(bounds &layout.Rect) int

Purpose

Operation on $&Switch: set bounds. Throws on failure; handle the error or propagate it to the caller.

Parameters

sw $&Switch
The Switch 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

(&Switch) value

XuAPI
pub fn (sw &Switch) value() bool

Purpose

Execute value on &Switch.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

($&Switch) set_value

XuAPI
pub fn (sw $&Switch) set_value(checked bool)

Purpose

Operation on $&Switch: set value.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).
checked bool
checked (bool)

Returns

This call does not return a value.

(&Switch) visual_state

XuAPI
pub fn (sw &Switch) visual_state() int

Purpose

Operation on &Switch: visual state.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

int — a value of this type

(&Switch) has_style

XuAPI
pub fn (sw &Switch) has_style() bool

Purpose

Operation on &Switch: whether it has style.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

(&Switch) style_or

XuAPI
pub fn (sw &Switch) style_or(styles &Styles) ControlStyle

Purpose

Operation on &Switch: style or.

Parameters

sw &Switch
The Switch 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

($&Switch) set_style

XuAPI
pub fn (sw $&Switch) set_style(style &ControlStyle) int

Purpose

Operation on $&Switch: set style. Throws on failure; handle the error or propagate it to the caller.

Parameters

sw $&Switch
The Switch 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

($&Switch) clear_style

XuAPI
pub fn (sw $&Switch) clear_style()

Purpose

Operation on $&Switch: clear style.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).

Returns

This call does not return a value.

($&Switch) input

XuAPI
pub fn (sw $&Switch) input(input &ui.InputEvent) Action

Purpose

Process routed mouse, keyboard, or touch input events.

Parameters

sw $&Switch
The Switch 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.

($&Switch) event

XuAPI
pub fn (sw $&Switch) 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

sw $&Switch
The Switch 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.

(&Switch) paint

XuAPI
pub fn (sw &Switch) paint(frame $&draw.Frame,label &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

sw &Switch
The Switch instance used by this call (borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)
label &draw.TextLayout
label (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

(&Switch) measure_styled

XuAPI
pub fn (sw &Switch) measure_styled(label $&StyledLabel,styles &Styles) layout.Size

Purpose

Operation on &Switch: measure styled. Throws on failure; handle the error or propagate it to the caller.

Parameters

sw &Switch
The Switch 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

(&Switch) paint_styled

XuAPI
pub fn (sw &Switch) paint_styled(frame $&draw.Frame,label $&StyledLabel,styles &Styles) int

Purpose

Operation on &Switch: paint styled. Throws on failure; handle the error or propagate it to the caller.

Parameters

sw &Switch
The Switch 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

(&Switch) paint_position_styled

XuAPI
pub fn (sw &Switch) paint_position_styled(frame $&draw.Frame,label $&StyledLabel,styles &Styles,position f64) int

Purpose

Operation on &Switch: paint position styled. Throws on failure; handle the error or propagate it to the caller.

Parameters

sw &Switch
The Switch 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)
position f64
position (f64)

Returns

int — a value of this type

($&Switch) set_motion

XuAPI
pub fn (sw $&Switch) set_motion(spec &MotionSpec) int

Purpose

Operation on $&Switch: set motion. Throws on failure; handle the error or propagate it to the caller.

Parameters

sw $&Switch
The Switch 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

($&Switch) tick

XuAPI
pub fn (sw $&Switch) 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

sw $&Switch
The Switch instance used by this call (exclusive borrow).
now time.Instant
now (time.Instant)
reduced bool
reduced (bool)

Returns

bool — true or false

(&Switch) next_tick

XuAPI
pub fn (sw &Switch) next_tick(now time.Instant) time.Instant

Purpose

Operation on &Switch: next tick. Throws on failure; handle the error or propagate it to the caller.

Parameters

sw &Switch
The Switch instance used by this call (borrow).
now time.Instant
now (time.Instant)

Returns

time.Instant — a value of this type

(&Switch) is_pending

XuAPI
pub fn (sw &Switch) is_pending() bool

Purpose

Operation on &Switch: whether it is pending.

Parameters

sw &Switch
The Switch instance used by this call (borrow).

Returns

bool — true or false

($&Switch) set_pending

XuAPI
pub fn (sw $&Switch) set_pending(pending bool)

Purpose

Business code completes or rolls back the value and then clears pending. The switch keeps keyboard focus while suppressing repeated submissions.

Parameters

sw $&Switch
The Switch instance used by this call (exclusive borrow).
pending bool
pending (bool)

Returns

This call does not return a value.

($&Switch) route

XuAPI
pub fn (sw $&Switch) 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

sw $&Switch
The Switch 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