XU XUv0.13.1
中文

UI / WIDGETS / Feedback

Modal

Complete a focused decision in a dialog

Run the Xu example

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

What to try

Open a confirmation, cancel it and confirm it.

Usage notes

Keep interaction inside the dialog while open and restore focus to its trigger on close. Define confirm, cancel and dismiss behavior explicitly.

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.modal("Apply changes?","Review before confirming.") or >>
    << id
}

($&Screen) modal

XuAPI
pub fn (s $&Screen) modal(title string,message string) int

Purpose

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

Parameters

s $&Screen
The Screen instance used by this call (exclusive borrow).
title string
title (string)
message string
message (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 Modal

XuAPI
pub struct Modal {

}

Purpose

Modal owns the keyboard focus order, while the host owns the actual child controls. Use blocks_input as the dispatch gate, including the closing fade. Cancel background View input before open (cancel_input) to release capture and native editor focus. Apply focused_id after open/input, and restore take_restore_focus after tick reports the closing fade finished. Never dispatch to background while blocks_input first call input, honor consumed even when that input closes the modal, then dispatch only to modal children if allows_content.

Public fields

This type has no public fields.

(&Modal) id

XuAPI
pub fn (m &Modal) id() int

Purpose

Return the unique integer ID of the element or control.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

int — a value of this type

(&Modal) bounds

XuAPI
pub fn (m &Modal) bounds() layout.Rect

Purpose

Return the bounding Rectangle of the control or geometry.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

layout.Rect — a value of this type

(&Modal) is_enabled

XuAPI
pub fn (m &Modal) is_enabled() bool

Purpose

Return whether the control is currently enabled.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

bool — true or false

(&Modal) is_selectable

XuAPI
pub fn (m &Modal) is_selectable() bool

Purpose

Operation on &Modal: whether it is selectable.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

bool — true or false

($&Modal) set_selectable

XuAPI
pub fn (m $&Modal) set_selectable(selectable bool)

Purpose

Operation on $&Modal: set selectable.

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).
selectable bool
selectable (bool)

Returns

This call does not return a value.

($&Modal) set_text

XuAPI
pub fn (m $&Modal) set_text(context &draw.Context,text &string) int

Purpose

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

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).
context &draw.Context
context (read-only borrow; caller keeps the original; type &draw.Context)
text &string
text (read-only borrow; caller keeps the original; type &string)

Returns

int — a value of this type

(&Modal) has_popup_open

XuAPI
pub fn (m &Modal) has_popup_open() bool

Purpose

Operation on &Modal: whether it has popup open.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

bool — true or false

(&Modal) popup_bounds

XuAPI
pub fn (m &Modal) popup_bounds() layout.Rect

Purpose

Operation on &Modal: popup bounds.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

layout.Rect — a value of this type

(&Modal) selected_text

XuAPI
pub fn (m &Modal) selected_text() string

Purpose

Operation on &Modal: selected text.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

string — result string

(&Modal) copy_selection

XuAPI
pub fn (m &Modal) copy_selection() int

Purpose

Operation on &Modal: copy selection.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

int — a value of this type

(&Modal) cursor

XuAPI
pub fn (m &Modal) cursor() int

Purpose

Execute cursor on &Modal.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

int — a value of this type

($&Modal) set_locale

XuAPI
pub fn (m $&Modal) set_locale(locale &Locale) int

Purpose

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

Parameters

m $&Modal
The Modal 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

(&Modal) is_open

XuAPI
pub fn (m &Modal) is_open() bool

Purpose

Return whether the overlay, menu or dialog is currently open.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

bool — true or false

(&Modal) is_visible

XuAPI
pub fn (m &Modal) is_visible() bool

Purpose

Check whether the modal remains visible, including its exit transition.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

true while open or fading out, and false once fully hidden.

(&Modal) blocks_input

XuAPI
pub fn (m &Modal) blocks_input() bool

Purpose

Keep background input blocked throughout the closing fade.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

bool — true or false

(&Modal) opacity

XuAPI
pub fn (m &Modal) opacity() f64

Purpose

Execute opacity on &Modal.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

f64 — a value of this type

(&Modal) needs_paint

XuAPI
pub fn (m &Modal) needs_paint() bool

Purpose

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

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

bool — true or false

($&Modal) painted

XuAPI
pub fn (m $&Modal) painted()

Purpose

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

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).

Returns

This call does not return a value.

($&Modal) set_dismiss_on_outside

XuAPI
pub fn (m $&Modal) set_dismiss_on_outside(enabled bool)

Purpose

Operation on $&Modal: set dismiss on outside.

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).
enabled bool
enabled (bool)

Returns

This call does not return a value.

(&Modal) focused_id

XuAPI
pub fn (m &Modal) focused_id() int

Purpose

Operation on &Modal: focused id.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

int — a value of this type

(&Modal) focus_restore_id

XuAPI
pub fn (m &Modal) focus_restore_id() int

Purpose

Operation on &Modal: focus restore id.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

int — a value of this type

($&Modal) take_restore_focus

XuAPI
pub fn (m $&Modal) take_restore_focus() int

Purpose

Consume the one-time focus restoration target once the modal is fully hidden.

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).

Returns

Control ID to restore, or 0 while visible or without a pending request. Each request is consumed once.

(&Modal) contains_focus

XuAPI
pub fn (m &Modal) contains_focus(id int) bool

Purpose

Operation on &Modal: contains focus.

Parameters

m &Modal
The Modal instance used by this call (borrow).
id int
id (int)

Returns

bool — true or false

($&Modal) set_focus_order

XuAPI
pub fn (m $&Modal) set_focus_order(ids &[]int) int

Purpose

Set the modal's Tab traversal order so keyboard focus cycles through the specified controls.

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).
ids &[]int
Ordered content control IDs, at most 256; IDs must be positive, unique and different from the modal's own ID.

Returns

Returns 0 on success; failure throws rather than returning a nonzero status.

Usage notes

  • Retain the old focus when listed, otherwise select the first target; an empty list has no content focus target.

Error handling

  • An invalid count, ID or duplicate throws.

($&Modal) set_content_focus

XuAPI
pub fn (m $&Modal) set_content_focus(id int) int

Purpose

Operation on $&Modal: set content focus. Throws on failure; handle the error or propagate it to the caller.

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).
id int
id (int)

Returns

int — a value of this type

($&Modal) open

XuAPI
pub fn (m $&Modal) open(now time.Instant,reduced_motion bool,restore_focus int) int

Purpose

Open the modal and remember the focus restoration target.

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).
now time.Instant
Current animation time.Instant; use the same time basis for opening, ticking and closing.
reduced_motion bool
Whether to reduce motion; true moves directly to the target state.
restore_focus int
Control ID to restore after closing; 0 means no target and negative values are invalid.

Returns

Returns 0 on success; failure throws rather than returning a nonzero status.

Usage notes

  • Advance animation with tick each frame and use is_visible to decide whether painting must continue.

Error handling

  • Invalid animation parameters or state throw. A negative focus restoration ID also throws.

($&Modal) close

XuAPI
pub fn (m $&Modal) close(now time.Instant,reduced_motion bool) int

Purpose

Request closing with an exit animation; painting may continue briefly after logical closure.

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).
now time.Instant
Current animation time.Instant; use the same time basis for opening, ticking and closing.
reduced_motion bool
Whether to reduce motion; true moves directly to the target state.

Returns

Returns 0 on success; failure throws rather than returning a nonzero status.

Usage notes

  • is_open() becomes false on the close request; is_visible() becomes false after the exit animation ends.

Error handling

  • Animation failures propagate.

($&Modal) set_enabled

XuAPI
pub fn (m $&Modal) set_enabled(enabled bool) int

Purpose

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

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).
enabled bool
enabled (bool)

Returns

int — a value of this type

($&Modal) set_geometry

XuAPI
pub fn (m $&Modal) set_geometry(bounds &layout.Rect,viewport &layout.Rect) int

Purpose

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

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).
bounds &layout.Rect
bounds (read-only borrow; caller keeps the original; type &layout.Rect)
viewport &layout.Rect
viewport (read-only borrow; caller keeps the original; type &layout.Rect)

Returns

int — a value of this type

(&Modal) close_bounds

XuAPI
pub fn (m &Modal) close_bounds() layout.Rect

Purpose

Operation on &Modal: close bounds.

Parameters

m &Modal
The Modal instance used by this call (borrow).

Returns

layout.Rect — a value of this type

(&Modal) allows_content

XuAPI
pub fn (m &Modal) allows_content(event &ui.InputEvent) bool

Purpose

Decide whether input may reach modal content after modal-first dispatch.

Parameters

m &Modal
The Modal instance used by this call (borrow).
event &ui.InputEvent
Input event for the same window, canvas and generation, with coordinates in the control's canvas space.

Returns

true when allowed; false when closed, mismatched, handling Tab/Escape, or hitting the close button.

Usage notes

  • Keyboard input also requires a content focus target; pointer input must be inside the panel.

($&Modal) input

XuAPI
pub fn (m $&Modal) input(event &ui.InputEvent) Action

Purpose

Handle modal dismissal and Tab focus cycling before deciding whether content can receive input.

Parameters

m $&Modal
The Modal 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

  • Dispatch before background controls and use allows_content for content input. The modal continues blocking background input during its exit animation.

($&Modal) route

XuAPI
pub fn (m $&Modal) 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

m $&Modal
The Modal 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.

($&Modal) tick

XuAPI
pub fn (m $&Modal) tick(now time.Instant,reduced_motion bool) bool

Purpose

Advance the fade animation to the current time and use the result to schedule repainting.

Parameters

m $&Modal
The Modal instance used by this call (exclusive borrow).
now time.Instant
Current animation time.Instant; use the same time basis for opening, ticking and closing.
reduced_motion bool
Whether to reduce motion; true moves directly to the target state.

Returns

true when opacity changes, otherwise false.

Error handling

  • Invalid time or animation state throws.

(&Modal) next_tick

XuAPI
pub fn (m &Modal) next_tick(now time.Instant) time.Instant

Purpose

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

Parameters

m &Modal
The Modal instance used by this call (borrow).
now time.Instant
now (time.Instant)

Returns

time.Instant — a value of this type

(&Modal) paint_styled

XuAPI
pub fn (m &Modal) paint_styled(frame $&draw.Frame,styles &Styles) int

Purpose

Paint the modal backdrop, panel and close button.

Parameters

m &Modal
The Modal instance used by this call (borrow).
frame $&draw.Frame
Current frame to receive drawing commands.
styles &Styles
Effective styles supplying colors, spacing, fonts and state appearance.

Returns

Returns 0 on success; failure throws rather than returning a nonzero status.

Usage notes

  • The backdrop uses Styles.overlay_scrim() with alpha scaled by the modal animation.
  • The caller paints panel content; this call does not create, lay out or dispatch content controls.

Error handling

  • Drawing failures propagate.

($&Modal) paint_content_styled

XuAPI
pub fn (m $&Modal) paint_content_styled(frame $&draw.Frame,styles &Styles) int

Purpose

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

Parameters

m $&Modal
The Modal 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

($&Modal) paint_popup_styled

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

Purpose

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

Parameters

m $&Modal
The Modal 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

($&Modal) set_style

XuAPI
pub fn (m $&Modal) set_style(style &ControlStyle) int

Purpose

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

Parameters

m $&Modal
The Modal 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

($&Modal) set_motion

XuAPI
pub fn (m $&Modal) set_motion(spec &MotionSpec) int

Purpose

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

Parameters

m $&Modal
The Modal 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

Complete native example

Component Workshop · Back to Widgets