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
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
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
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
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
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
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
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
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) selected_text
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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) set_style
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
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