UI / WIDGETS / Actions
TaskButton
Show task progress inside an action button
Run the Xu example ↗The example executes in the browser using the Xu/WASM runtime.
What to try
Start a task, wait for completion and run again.
Usage notes
Distinguish idle, running, success and failure. The application performs the task; displaying progress does not start background work.
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.task_button("Export") or >>
screen.place(id,24.0,24.0,320.0,80.0) or >>
<< id
}
($&Screen) task_button
pub fn (s $&Screen) task_button(label string) int
Purpose
Create TaskButton in Screen and return the component node ID; throw on creation failure.
Parameters
s $&Screen- The
Screen instance used by this call (exclusive borrow).
label string- label (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.
($&TaskButton) set_locale
pub fn (task $&TaskButton) set_locale(locale &Locale) int
Purpose
Operation on $&TaskButton: set locale. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton 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
($&TaskButton) use_locale_labels
pub fn (task $&TaskButton) use_locale_labels() int
Purpose
Operation on $&TaskButton: use locale labels. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
Returns
int — a value of this type
(&TaskButton) label_text
pub fn (task &TaskButton) label_text() string
Purpose
Operation on &TaskButton: label text. Throws on failure; handle the error or propagate it to the caller.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
string — result string
struct TaskButton
pub struct TaskButton {
}
Purpose
TaskButton context or state structure.
Public fields
This type has no public fields.
(&TaskButton) id
pub fn (task &TaskButton) id() int
Purpose
Return the unique integer ID of the element or control.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
int — a value of this type
(&TaskButton) bounds
pub fn (task &TaskButton) bounds() layout.Rect
Purpose
Return the bounding Rectangle of the control or geometry.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
layout.Rect — a value of this type
(&TaskButton) state
pub fn (task &TaskButton) state() int
Purpose
Execute state on &TaskButton.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
int — a value of this type
(&TaskButton) task_id
pub fn (task &TaskButton) task_id() int
Purpose
Operation on &TaskButton: task id.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
int — a value of this type
(&TaskButton) is_running
pub fn (task &TaskButton) is_running() bool
Purpose
Operation on &TaskButton: whether it is running.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
bool — true or false
(&TaskButton) is_determinate
pub fn (task &TaskButton) is_determinate() bool
Purpose
Operation on &TaskButton: whether it is determinate.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
bool — true or false
(&TaskButton) progress
pub fn (task &TaskButton) progress() f64
Purpose
Execute progress on &TaskButton.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
f64 — a value of this type
(&TaskButton) is_enabled
pub fn (task &TaskButton) is_enabled() bool
Purpose
Return whether the control is currently enabled.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
bool — true or false
(&TaskButton) is_selectable
pub fn (task &TaskButton) is_selectable() bool
Purpose
Operation on &TaskButton: whether it is selectable.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
bool — true or false
($&TaskButton) set_selectable
pub fn (task $&TaskButton) set_selectable(selectable bool)
Purpose
Operation on $&TaskButton: set selectable.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
selectable bool- selectable (bool)
Returns
This call does not return a value.
(&TaskButton) is_focused
pub fn (task &TaskButton) is_focused() bool
Purpose
Return whether the control currently has input focus.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
bool — true or false
(&TaskButton) needs_paint
pub fn (task &TaskButton) needs_paint() bool
Purpose
Return whether the control needs repainting; call painted after painting to clear the flag.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
Returns
bool — true or false
($&TaskButton) painted
pub fn (task $&TaskButton) painted()
Purpose
Acknowledge the painted frame and clear the dirty flag; this is not a query.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&TaskButton) cancel
pub fn (task $&TaskButton) cancel()
Purpose
Execute cancel on $&TaskButton.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&TaskButton) set_focus
pub fn (task $&TaskButton) set_focus(focused bool)
Purpose
Operation on $&TaskButton: set focus.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
focused bool- focused (bool)
Returns
This call does not return a value.
($&TaskButton) set_enabled
pub fn (task $&TaskButton) set_enabled(enabled bool)
Purpose
Operation on $&TaskButton: set enabled.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
enabled bool- enabled (bool)
Returns
This call does not return a value.
($&TaskButton) set_bounds
pub fn (task $&TaskButton) set_bounds(bounds &layout.Rect) int
Purpose
Operation on $&TaskButton: set bounds. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton 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
($&TaskButton) set_style
pub fn (task $&TaskButton) set_style(style &ControlStyle) int
Purpose
Operation on $&TaskButton: set style. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton 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
($&TaskButton) set_motion
pub fn (task $&TaskButton) set_motion(spec &MotionSpec) int
Purpose
Operation on $&TaskButton: set motion. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton 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
($&TaskButton) set_progress_mode
pub fn (task $&TaskButton) set_progress_mode(mode int) int
Purpose
Operation on $&TaskButton: set progress mode. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
mode int- mode (int)
Returns
int — a value of this type
($&TaskButton) set_labels
pub fn (task $&TaskButton) set_labels(running &string,success &string,error &string,cancelled &string) int
Purpose
Operation on $&TaskButton: set labels. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
running &string- running (read-only borrow; caller keeps the original; type &string)
success &string- success (read-only borrow; caller keeps the original; type &string)
error &string- error (read-only borrow; caller keeps the original; type &string)
cancelled &string- cancelled (read-only borrow; caller keeps the original; type &string)
Returns
int — a value of this type
($&TaskButton) set_cancellable
pub fn (task $&TaskButton) set_cancellable(enabled bool)
Purpose
Operation on $&TaskButton: set cancellable.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
enabled bool- enabled (bool)
Returns
This call does not return a value.
($&TaskButton) begin
pub fn (task $&TaskButton) begin(id int,now time.Instant) int
Purpose
Strictly increasing task IDs prevent a late completion from replacing a retry. The caller owns execution, cancellation and all progress reporting. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
id int- id (int)
now time.Instant- now (time.Instant)
Returns
int — a value of this type
($&TaskButton) set_progress
pub fn (task $&TaskButton) set_progress(id int,value f64) bool
Purpose
Operation on $&TaskButton: set progress. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
id int- id (int)
value f64- value (f64)
Returns
bool — true or false
($&TaskButton) complete
pub fn (task $&TaskButton) complete(id int,state int) bool
Purpose
Execute complete on $&TaskButton. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
id int- id (int)
state int- state (int)
Returns
bool — true or false
($&TaskButton) reset
pub fn (task $&TaskButton) reset() int
Purpose
Operation on $&TaskButton: clear internal state so the value can be reused. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
Returns
int — a value of this type
($&TaskButton) input
pub fn (task $&TaskButton) input(input &ui.InputEvent) Action
Purpose
Process routed mouse, keyboard, or touch input events. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton 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.
($&TaskButton) route
pub fn (task $&TaskButton) 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
task $&TaskButton- The
TaskButton 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.
($&TaskButton) event
pub fn (task $&TaskButton) 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
task $&TaskButton- The
TaskButton 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.
($&TaskButton) tick
pub fn (task $&TaskButton) 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
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
now time.Instant- now (time.Instant)
reduced bool- reduced (bool)
Returns
bool — true or false
(&TaskButton) next_tick
pub fn (task &TaskButton) next_tick(now time.Instant) time.Instant
Purpose
Operation on &TaskButton: next tick. Throws on failure; handle the error or propagate it to the caller.
Parameters
task &TaskButton- The
TaskButton instance used by this call (borrow).
now time.Instant- now (time.Instant)
Returns
time.Instant — a value of this type
($&TaskButton) measure_styled
pub fn (task $&TaskButton) measure_styled(styles &Styles) layout.Size
Purpose
Operation on $&TaskButton: measure styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton 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
($&TaskButton) paint_styled
pub fn (task $&TaskButton) paint_styled(frame $&draw.Frame,styles &Styles) int
Purpose
Operation on $&TaskButton: paint styled. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton 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
($&TaskButton) dispose
pub fn (task $&TaskButton) dispose()
Purpose
Release and dispose native resources and underlying handles.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
Returns
This call does not return a value.
($&TaskButton) set_feedback
pub fn (task $&TaskButton) set_feedback(feedback &TaskFeedback) int
Purpose
Operation on $&TaskButton: set feedback. Throws on failure; handle the error or propagate it to the caller.
Parameters
task $&TaskButton- The
TaskButton instance used by this call (exclusive borrow).
feedback &TaskFeedback- feedback (read-only borrow; caller keeps the original; type &TaskFeedback)
Returns
int — a value of this type
Complete native example
Component Workshop · Back to Widgets