plushie/command

Command types returned from update.

Commands describe side effects that the runtime executes after update returns. The lifecycle is: update returns #(model, command), the runtime executes the command, and then calls view with the new model. Batched commands execute in list order. For no side effects, return command.none().

Types

Command

</>

pub type Command(msg) {
  None
  Batch(commands: List(Command(msg)))
  Done(
    value: dynamic.Dynamic,
    mapper: fn(dynamic.Dynamic) -> msg,
  )
  Async(work: fn() -> dynamic.Dynamic, tag: String)
  Stream(
    work: fn(fn(dynamic.Dynamic) -> Nil) -> dynamic.Dynamic,
    tag: String,
  )
  Cancel(tag: String)
  SendAfter(delay_ms: Int, msg: msg)
  Exit
  Focus(widget_id: String)
  FocusNext
  FocusPrevious
  SelectAll(widget_id: String)
  MoveCursorToFront(widget_id: String)
  MoveCursorToEnd(widget_id: String)
  MoveCursorTo(widget_id: String, position: Int)
  SelectRange(widget_id: String, start: Int, end: Int)
  ScrollTo(widget_id: String, offset: dynamic.Dynamic)
  SnapTo(widget_id: String, x: Float, y: Float)
  SnapToEnd(widget_id: String)
  ScrollBy(widget_id: String, x: Float, y: Float)
  CloseWindow(window_id: String)
  ResizeWindow(window_id: String, width: Float, height: Float)
  MoveWindow(window_id: String, x: Float, y: Float)
  MaximizeWindow(window_id: String, maximized: Bool)
  MinimizeWindow(window_id: String, minimized: Bool)
  SetWindowMode(window_id: String, mode: String)
  ToggleMaximize(window_id: String)
  ToggleDecorations(window_id: String)
  GainFocus(window_id: String)
  SetWindowLevel(window_id: String, level: String)
  DragWindow(window_id: String)
  DragResizeWindow(window_id: String, direction: String)
  RequestUserAttention(
    window_id: String,
    urgency: option.Option(String),
  )
  Screenshot(window_id: String, tag: String)
  SetResizable(window_id: String, resizable: Bool)
  SetMinSize(window_id: String, width: Float, height: Float)
  SetMaxSize(window_id: String, width: Float, height: Float)
  EnableMousePassthrough(window_id: String)
  DisableMousePassthrough(window_id: String)
  ShowSystemMenu(window_id: String)
  SetResizeIncrements(
    window_id: String,
    width: option.Option(Float),
    height: option.Option(Float),
  )
  AllowAutomaticTabbing(enabled: Bool)
  SetIcon(
    window_id: String,
    rgba_data: BitArray,
    width: Int,
    height: Int,
  )
  GetWindowSize(window_id: String, tag: String)
  GetWindowPosition(window_id: String, tag: String)
  IsMaximized(window_id: String, tag: String)
  IsMinimized(window_id: String, tag: String)
  GetMode(window_id: String, tag: String)
  GetScaleFactor(window_id: String, tag: String)
  RawWindowId(window_id: String, tag: String)
  MonitorSize(window_id: String, tag: String)
  GetSystemTheme(tag: String)
  GetSystemInfo(tag: String)
  CreateImage(handle: String, data: BitArray)
  CreateImageRgba(
    handle: String,
    width: Int,
    height: Int,
    pixels: BitArray,
  )
  UpdateImage(handle: String, data: BitArray)
  UpdateImageRgba(
    handle: String,
    width: Int,
    height: Int,
    pixels: BitArray,
  )
  DeleteImage(handle: String)
  ListImages(tag: String)
  ClearImages
  Announce(text: String)
  PaneSplit(
    pane_grid_id: String,
    pane_id: dynamic.Dynamic,
    axis: String,
    new_pane_id: dynamic.Dynamic,
  )
  PaneClose(pane_grid_id: String, pane_id: dynamic.Dynamic)
  PaneSwap(
    pane_grid_id: String,
    pane_a: dynamic.Dynamic,
    pane_b: dynamic.Dynamic,
  )
  PaneMaximize(pane_grid_id: String, pane_id: dynamic.Dynamic)
  PaneRestore(pane_grid_id: String)
  TreeHashQuery(tag: String)
  FindFocused(tag: String)
  LoadFont(data: BitArray)
  Effect(
    id: String,
    kind: String,
    payload: dict.Dict(String, node.PropValue),
  )
  ExtensionCommand(
    node_id: String,
    op: String,
    payload: dict.Dict(String, node.PropValue),
  )
  ExtensionCommands(
    commands: List(
      #(String, String, dict.Dict(String, node.PropValue)),
    ),
  )
  AdvanceFrame(timestamp: Int)
}

Constructors

```
None
```
No side effect.
```
Batch(commands: List(Command(msg)))
```
Execute multiple commands in list order.

Done(value: dynamic.Dynamic, mapper: fn(dynamic.Dynamic) -> msg)

Deliver an already-resolved value through update via the mapper.

```
Async(work: fn() -> dynamic.Dynamic, tag: String)
```
Run a function on a background process. The result is delivered as an AsyncResult event identified by tag.
```
Stream(
  work: fn(fn(dynamic.Dynamic) -> Nil) -> dynamic.Dynamic,
  tag: String,
)
```
Run a function that can emit multiple values over time. Each value is delivered as a StreamValue event identified by tag.
```
Cancel(tag: String)
```
Cancel a running Async or Stream task by tag.
```
SendAfter(delay_ms: Int, msg: msg)
```
Deliver msg back to update after delay_ms milliseconds. Sending another SendAfter with an identical msg cancels the previous timer (deduplication via stable hashing).
```
Exit
```
Shut down the runtime and close all windows.
```
Focus(widget_id: String)
```
Move keyboard focus to the given widget.
```
FocusNext
```
Move focus to the next focusable widget in tab order.
```
FocusPrevious
```
Move focus to the previous focusable widget in tab order.
```
SelectAll(widget_id: String)
```
Select all text in a text input or text editor widget.
```
MoveCursorToFront(widget_id: String)
```
Move the text cursor to the beginning of the input.
```
MoveCursorToEnd(widget_id: String)
```
Move the text cursor to the end of the input.
```
MoveCursorTo(widget_id: String, position: Int)
```
Move the text cursor to a specific character position.
```
SelectRange(widget_id: String, start: Int, end: Int)
```
Select a range of text between start and end character positions.

ScrollTo(widget_id: String, offset: dynamic.Dynamic)

Scroll a scrollable widget to an absolute offset.

```
SnapTo(widget_id: String, x: Float, y: Float)
```
Snap a scrollable widget to an absolute x/y offset instantly (no smooth scrolling).
```
SnapToEnd(widget_id: String)
```
Snap a scrollable widget to the end of its content.

ScrollBy(widget_id: String, x: Float, y: Float)

Scroll a scrollable widget by a relative x/y delta.

```
CloseWindow(window_id: String)
```
Close the window with the given ID.

ResizeWindow(window_id: String, width: Float, height: Float)

Resize a window to the given dimensions in logical pixels.

```
MoveWindow(window_id: String, x: Float, y: Float)
```
Move a window to the given screen position in logical pixels.

MaximizeWindow(window_id: String, maximized: Bool)

Set whether a window is maximized or restored.

MinimizeWindow(window_id: String, minimized: Bool)

Set whether a window is minimized or restored.

```
SetWindowMode(window_id: String, mode: String)
```
Set window mode (e.g. “windowed”, “fullscreen”).
```
ToggleMaximize(window_id: String)
```
Toggle a window between maximized and restored state.
```
ToggleDecorations(window_id: String)
```
Toggle window decorations (title bar, borders).
```
GainFocus(window_id: String)
```
Give keyboard/input focus to a window, bringing it to the front.
```
SetWindowLevel(window_id: String, level: String)
```
Set window stacking level (“normal”, “always_on_top”, “always_on_bottom”). May be ignored on Wayland.
```
DragWindow(window_id: String)
```
Initiate a window drag operation (user moves the window).
```
DragResizeWindow(window_id: String, direction: String)
```
Initiate a drag-resize from the given edge/corner direction.
```
RequestUserAttention(
  window_id: String,
  urgency: option.Option(String),
)
```
Flash the taskbar/dock icon to request user attention. Urgency is “informational” or “critical”; None clears the request.
```
Screenshot(window_id: String, tag: String)
```
Capture a screenshot of a window. The result arrives as a tagged system event.

SetResizable(window_id: String, resizable: Bool)

Set whether a window can be resized by the user.

SetMinSize(window_id: String, width: Float, height: Float)

Set the minimum allowed size for a window in logical pixels.

SetMaxSize(window_id: String, width: Float, height: Float)

Set the maximum allowed size for a window in logical pixels.

```
EnableMousePassthrough(window_id: String)
```
Enable mouse passthrough so clicks pass through to windows below.
```
DisableMousePassthrough(window_id: String)
```
Disable mouse passthrough, restoring normal click handling.
```
ShowSystemMenu(window_id: String)
```
Show the native system menu (window controls) for a window.

SetResizeIncrements(
  window_id: String,
  width: option.Option(Float),
  height: option.Option(Float),
)

Set the resize increment size. The window will only resize in multiples of the given width/height. Pass None to clear.

```
AllowAutomaticTabbing(enabled: Bool)
```
Set whether the system can automatically organize windows into tabs. macOS-specific; no-op on other platforms.
```
SetIcon(
  window_id: String,
  rgba_data: BitArray,
  width: Int,
  height: Int,
)
```
Set the window icon from raw RGBA pixel data. The BitArray must be width * height * 4 bytes (R, G, B, A per pixel, row-major).
```
GetWindowSize(window_id: String, tag: String)
```
Query the size of a window. Result arrives as a SystemInfo event.
```
GetWindowPosition(window_id: String, tag: String)
```
Query the position of a window. Result arrives as a SystemInfo event.
```
IsMaximized(window_id: String, tag: String)
```
Query whether a window is maximized. Result arrives as a SystemInfo event.
```
IsMinimized(window_id: String, tag: String)
```
Query whether a window is minimized. Result arrives as a SystemInfo event.
```
GetMode(window_id: String, tag: String)
```
Query the current window mode (windowed, fullscreen, hidden). Result arrives as a SystemInfo event.
```
GetScaleFactor(window_id: String, tag: String)
```
Query the window’s DPI scale factor. Result arrives as a SystemInfo event.
```
RawWindowId(window_id: String, tag: String)
```
Query the raw platform window ID (e.g. X11 window ID, HWND). Result arrives as a SystemInfo event.
```
MonitorSize(window_id: String, tag: String)
```
Query the monitor size for the display containing a window. Result arrives as a SystemInfo event. Data is None if the monitor cannot be determined.
```
GetSystemTheme(tag: String)
```
Query the OS light/dark theme preference. Result arrives as a SystemTheme event with “light”, “dark”, or “none”.
```
GetSystemInfo(tag: String)
```
Query system information (OS, CPU, memory, graphics). Result arrives as a SystemInfo event with a map of system fields.
```
CreateImage(handle: String, data: BitArray)
```
Register an image from encoded data (PNG, JPEG, etc.) under the given handle for use in image widgets.

CreateImageRgba(
  handle: String,
  width: Int,
  height: Int,
  pixels: BitArray,
)

```
UpdateImage(handle: String, data: BitArray)
```
Update an existing image handle with new encoded data.

UpdateImageRgba(
  handle: String,
  width: Int,
  height: Int,
  pixels: BitArray,
)

Update an existing image handle with new raw RGBA pixel data.

```
DeleteImage(handle: String)
```
Delete a previously registered image by its handle.
```
ListImages(tag: String)
```
List all registered image handles. Result arrives as an ImageList event.
```
ClearImages
```
Delete all registered images.
```
Announce(text: String)
```
Announce text to screen readers via the accessibility system.

PaneSplit(
  pane_grid_id: String,
  pane_id: dynamic.Dynamic,
  axis: String,
  new_pane_id: dynamic.Dynamic,
)

Split a pane in a pane_grid widget along the given axis (“horizontal” or “vertical”), creating a new pane.

PaneClose(pane_grid_id: String, pane_id: dynamic.Dynamic)

Close a pane in a pane_grid widget.

PaneSwap(
  pane_grid_id: String,
  pane_a: dynamic.Dynamic,
  pane_b: dynamic.Dynamic,
)

Swap two panes in a pane_grid widget.

PaneMaximize(pane_grid_id: String, pane_id: dynamic.Dynamic)

Maximize a single pane to fill the entire pane_grid.

```
PaneRestore(pane_grid_id: String)
```
Restore all panes from maximized state in a pane_grid.
```
TreeHashQuery(tag: String)
```
Compute a SHA-256 hash of the renderer’s current tree state. Result arrives as a TreeHash event.
```
FindFocused(tag: String)
```
Query which widget currently has keyboard focus. Result arrives as a FocusedWidget event.
```
LoadFont(data: BitArray)
```
Load a font at runtime from raw TrueType or OpenType binary data. Once loaded, the font can be referenced by name in widget props.
```
Effect(
  id: String,
  kind: String,
  payload: dict.Dict(String, node.PropValue),
)
```
Request a platform effect (file dialog, clipboard, notification). The result arrives as an EffectResponse event matched by id.

ExtensionCommand(
  node_id: String,
  op: String,
  payload: dict.Dict(String, node.PropValue),
)

Send a command directly to a native extension widget, bypassing the normal tree diff/patch cycle.

ExtensionCommands(
  commands: List(
    #(String, String, dict.Dict(String, node.PropValue)),
  ),
)

Send a batch of extension commands processed in one cycle.

```
AdvanceFrame(timestamp: Int)
```
Advance the renderer by one frame in test/headless mode. The timestamp is monotonic milliseconds. In normal mode the renderer drives frames from display vsync.

Values

advance_frame

</>

pub fn advance_frame(timestamp: Int) -> Command(msg)

Advance the renderer by one frame in test/headless mode.

announce

</>

pub fn announce(text: String) -> Command(msg)

Announce text to screen readers via the accessibility system.

async

</>

pub fn async(
  work: fn() -> dynamic.Dynamic,
  tag: String,
) -> Command(msg)

Run a function asynchronously on a background process. The result is delivered as an AsyncResult event identified by the tag.

batch

</>

pub fn batch(commands: List(Command(msg))) -> Command(msg)

Execute multiple commands in list order.

cancel

</>

pub fn cancel(tag: String) -> Command(msg)

Cancel a running async or stream task by its tag.

clear_images

</>

pub fn clear_images() -> Command(msg)

Delete all registered images.

close_window

</>

pub fn close_window(window_id: String) -> Command(msg)

Close the window with the given ID.

create_image

</>

pub fn create_image(
  handle: String,
  data: BitArray,
) -> Command(msg)

delete_image

</>

pub fn delete_image(handle: String) -> Command(msg)

Delete a previously registered image by its handle.

done

</>

pub fn done(
  value: dynamic.Dynamic,
  mapper: fn(dynamic.Dynamic) -> msg,
) -> Command(msg)

Wrap an already-resolved value and deliver it through update via the mapper function. Useful for lifting pure values into the command pipeline.

exit

</>

pub fn exit() -> Command(msg)

Shut down the runtime and close all windows.

find_focused

</>

pub fn find_focused(tag: String) -> Command(msg)

Query which widget currently has focus. The result arrives as a tagged event.

focus

</>

pub fn focus(widget_id: String) -> Command(msg)

Move keyboard focus to the given widget.

focus_next

</>

pub fn focus_next() -> Command(msg)

Move focus to the next focusable widget.

focus_previous

</>

pub fn focus_previous() -> Command(msg)

Move focus to the previous focusable widget.

gain_focus

</>

pub fn gain_focus(window_id: String) -> Command(msg)

Give focus to a window, bringing it to the front.

maximize_window

</>

pub fn maximize_window(window_id: String) -> Command(msg)

Maximize a window.

minimize_window

</>

pub fn minimize_window(window_id: String) -> Command(msg)

Minimize a window.

move_window

</>

pub fn move_window(
  window_id: String,
  x: Float,
  y: Float,
) -> Command(msg)

Move a window to the given screen position.

none

</>

pub fn none() -> Command(msg)

No side effect. Return this from update when no command is needed.

resize_window

</>

pub fn resize_window(
  window_id: String,
  width: Float,
  height: Float,
) -> Command(msg)

Resize a window to the given dimensions in logical pixels.

screenshot

</>

pub fn screenshot(window_id: String, tag: String) -> Command(msg)

Take a screenshot of a window. The result arrives as a tagged event.

select_all

</>

pub fn select_all(widget_id: String) -> Command(msg)

Select all text in the given text input widget.

send_after

</>

pub fn send_after(delay_ms: Int, msg: msg) -> Command(msg)

Deliver a message back to update after a delay in milliseconds. Sending another SendAfter with an identical msg replaces the previous timer.

stream

</>

pub fn stream(
  work: fn(fn(dynamic.Dynamic) -> Nil) -> dynamic.Dynamic,
  tag: String,
) -> Command(msg)

Run a function that can emit multiple values over time. Each value is delivered as a StreamValue event identified by the tag.

toggle_decorations

</>

pub fn toggle_decorations(window_id: String) -> Command(msg)

Toggle window decorations (title bar, borders).

toggle_maximize

</>

pub fn toggle_maximize(window_id: String) -> Command(msg)

Toggle a window between maximized and restored state.

tree_hash

</>

pub fn tree_hash(tag: String) -> Command(msg)

Query the current tree hash from the renderer. The result arrives as a tagged event.