Class: Plushie::Command

Inherits:
Object
  • Object
show all
Defined in:
lib/plushie/command.rb

Overview

Commands describe side effects that update wants the runtime to perform.

They are pure data -- inspectable, testable, serializable. The runtime interprets them after update returns. Nothing executes inside update.

Examples:

Async work

[model, Command.async(-> { fetch_data }, :data_loaded)]

Focus a widget

[model, Command.focus("input_field")]

Multiple commands

[model, Command.batch([Command.focus("input"), Command.send_after(3000, :auto_save)])]

See Also:

  • (reference: 72+ constructors)

Defined Under Namespace

Classes: Cmd

Class Method Summary collapse

Class Method Details

.advance_frame(timestamp) ⇒ Cmd

Advance the animation clock. For deterministic testing.

Parameters:

  • timestamp (Integer) —

    frame timestamp in milliseconds

Returns:



446
 
# File 'lib/plushie/command.rb', line 446

def self.advance_frame(timestamp) = Cmd.new(type: :advance_frame, payload: {timestamp:})

.allow_automatic_tabbing(enabled) ⇒ Cmd

Parameters:

  • enabled (Boolean)

Returns:



250
 
# File 'lib/plushie/command.rb', line 250

def self.allow_automatic_tabbing(enabled) = Cmd.new(type: :window_op, payload: {op: :allow_automatic_tabbing, window_id: "_global", enabled:})

.announce(text) ⇒ Cmd

Screen reader announcement.

Parameters:

  • text (String)

Returns:



421
 
# File 'lib/plushie/command.rb', line 421

def self.announce(text) = Cmd.new(type: :widget_op, payload: {op: :announce, text:})

.async(callable, tag) ⇒ Cmd

Run a callable asynchronously. Result delivered as Event::Async.

Parameters:

  • callable (Proc, Lambda) —

    the work to run

  • tag (Symbol) —

    event tag for the result

Returns:



34
 
# File 'lib/plushie/command.rb', line 34

def self.async(callable, tag) = Cmd.new(type: :async, payload: {callable:, tag:})

.batch(commands) ⇒ Cmd

Combine multiple commands. Executed sequentially.

Parameters:

  • commands (Array<Cmd>)

Returns:



67
 
# File 'lib/plushie/command.rb', line 67

def self.batch(commands) = Cmd.new(type: :batch, payload: {commands:})

.cancel(tag) ⇒ Cmd

Cancel a running async or stream task by tag.

Parameters:

  • tag (Symbol)

Returns:



46
 
# File 'lib/plushie/command.rb', line 46

def self.cancel(tag) = Cmd.new(type: :cancel, payload: {tag:})

.clear_images ⇒ Cmd

Remove all image handles.

Returns:



389
 
# File 'lib/plushie/command.rb', line 389

def self.clear_images = Cmd.new(type: :widget_op, payload: {op: :clear_images})

.close_window(window_id) ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



141
 
# File 'lib/plushie/command.rb', line 141

def self.close_window(window_id) = Cmd.new(type: :close_window, payload: {window_id:})

.create_image(handle, data = nil, width: nil, height: nil, pixels: nil) ⇒ Cmd

Create an image from encoded data (PNG/JPEG).

Parameters:

  • handle (String) —

    image handle name

  • data (String) (defaults to: nil) —

    encoded image bytes

Returns:



357
358
359
360
361
362
363
 
# File 'lib/plushie/command.rb', line 357

def self.create_image(handle, data = nil, width: nil, height: nil, pixels: nil)
  if pixels
    Cmd.new(type: :image_op, payload: {op: :create_image, handle:, pixels:, width:, height:})
  else
    Cmd.new(type: :image_op, payload: {op: :create_image, handle:, data:})
  end
end

.delete_image(handle) ⇒ Cmd

Delete an image handle.

Parameters:

  • handle (String)

Returns:



380
 
# File 'lib/plushie/command.rb', line 380

def self.delete_image(handle) = Cmd.new(type: :image_op, payload: {op: :delete_image, handle:})

.disable_mouse_passthrough(window_id) ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



229
 
# File 'lib/plushie/command.rb', line 229

def self.disable_mouse_passthrough(window_id) = Cmd.new(type: :window_op, payload: {op: :mouse_passthrough, window_id:, enabled: false})

.done(value, mapper_fn) ⇒ Cmd

Lift an already-resolved value into the command pipeline.

Parameters:

  • value (Object) —

    the resolved value

  • mapper_fn (Proc) —

    function that wraps value into an event

Returns:



52
 
# File 'lib/plushie/command.rb', line 52

def self.done(value, mapper_fn) = Cmd.new(type: :done, payload: {value:, mapper: mapper_fn})

.drag_resize_window(window_id, direction) ⇒ Cmd

Parameters:

  • window_id (String)
  • direction (Symbol)

Returns:



194
 
# File 'lib/plushie/command.rb', line 194

def self.drag_resize_window(window_id, direction) = Cmd.new(type: :window_op, payload: {op: :drag_resize, window_id:, direction: direction.to_s})

.drag_window(window_id) ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



189
 
# File 'lib/plushie/command.rb', line 189

def self.drag_window(window_id) = Cmd.new(type: :window_op, payload: {op: :drag, window_id:})

.enable_mouse_passthrough(window_id) ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



225
 
# File 'lib/plushie/command.rb', line 225

def self.enable_mouse_passthrough(window_id) = Cmd.new(type: :window_op, payload: {op: :mouse_passthrough, window_id:, enabled: true})

.exit ⇒ Cmd

Terminate the application.

Returns:



62
 
# File 'lib/plushie/command.rb', line 62

def self.exit = Cmd.new(type: :exit, payload: {})

.extension_command(node_id, op, payload = {}) ⇒ Cmd

Send a command to a native extension widget.

Parameters:

  • node_id (String)
  • op (String)
  • payload (Hash) (defaults to: {})

Returns:



432
 
# File 'lib/plushie/command.rb', line 432

def self.extension_command(node_id, op, payload = {}) = Cmd.new(type: :extension_command, payload: {node_id:, op:, data: payload})

.extension_commands(commands) ⇒ Cmd

Batch multiple extension commands.

Parameters:

  • commands (Array<Hash>) —

    each with :node_id, :op, :payload

Returns:



437
 
# File 'lib/plushie/command.rb', line 437

def self.extension_commands(commands) = Cmd.new(type: :extension_commands, payload: {commands:})

.find_focused(tag) ⇒ Cmd

Find focused widget. Result via Event::System.

Parameters:

  • tag (Symbol)

Returns:



403
 
# File 'lib/plushie/command.rb', line 403

def self.find_focused(tag) = Cmd.new(type: :widget_op, payload: {op: :find_focused, tag: tag.to_s})

.focus(widget_id) ⇒ Cmd

Parameters:

  • widget_id (String)

Returns:



75
 
# File 'lib/plushie/command.rb', line 75

def self.focus(widget_id) = Cmd.new(type: :focus, payload: {target: widget_id})

.focus_element(canvas_id, element_id) ⇒ Cmd

Focus a specific element within a canvas widget.

Parameters:

  • canvas_id (String)
  • element_id (String)

Returns:



316
 
# File 'lib/plushie/command.rb', line 316

def self.focus_element(canvas_id, element_id) = Cmd.new(type: :widget_op, payload: {op: "focus_element", target: canvas_id, element_id: element_id})

.focus_next ⇒ Cmd

Returns:



78
 
# File 'lib/plushie/command.rb', line 78

def self.focus_next = Cmd.new(type: :focus_next, payload: {})

.focus_previous ⇒ Cmd

Returns:



81
 
# File 'lib/plushie/command.rb', line 81

def self.focus_previous = Cmd.new(type: :focus_previous, payload: {})

.gain_focus(window_id) ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



180
 
# File 'lib/plushie/command.rb', line 180

def self.gain_focus(window_id) = Cmd.new(type: :window_op, payload: {op: :gain_focus, window_id:})

.get_mode(window_id, tag) ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



279
 
# File 'lib/plushie/command.rb', line 279

def self.get_mode(window_id, tag) = Cmd.new(type: :window_query, payload: {op: :get_mode, window_id:, tag: tag.to_s})

.get_scale_factor(window_id, tag) ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



284
 
# File 'lib/plushie/command.rb', line 284

def self.get_scale_factor(window_id, tag) = Cmd.new(type: :window_query, payload: {op: :get_scale_factor, window_id:, tag: tag.to_s})

.get_system_info(tag) ⇒ Cmd

Parameters:

  • tag (Symbol)

Returns:



306
 
# File 'lib/plushie/command.rb', line 306

def self.get_system_info(tag) = Cmd.new(type: :window_query, payload: {op: :get_system_info, window_id: "_system", tag: tag.to_s})

.get_system_theme(tag) ⇒ Cmd

Parameters:

  • tag (Symbol)

Returns:



302
 
# File 'lib/plushie/command.rb', line 302

def self.get_system_theme(tag) = Cmd.new(type: :window_query, payload: {op: :get_system_theme, window_id: "_system", tag: tag.to_s})

.get_window_position(window_id, tag) ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



264
 
# File 'lib/plushie/command.rb', line 264

def self.get_window_position(window_id, tag) = Cmd.new(type: :window_query, payload: {op: :get_position, window_id:, tag: tag.to_s})

.get_window_size(window_id, tag) ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



259
 
# File 'lib/plushie/command.rb', line 259

def self.get_window_size(window_id, tag) = Cmd.new(type: :window_query, payload: {op: :get_size, window_id:, tag: tag.to_s})

.is_maximized(window_id, tag) ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



269
 
# File 'lib/plushie/command.rb', line 269

def self.is_maximized(window_id, tag) = Cmd.new(type: :window_query, payload: {op: :is_maximized, window_id:, tag: tag.to_s})

.is_minimized(window_id, tag) ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



274
 
# File 'lib/plushie/command.rb', line 274

def self.is_minimized(window_id, tag) = Cmd.new(type: :window_query, payload: {op: :is_minimized, window_id:, tag: tag.to_s})

.list_images(tag) ⇒ Cmd

List all image handles. Result via Event::System.

Parameters:

  • tag (Symbol)

Returns:



385
 
# File 'lib/plushie/command.rb', line 385

def self.list_images(tag) = Cmd.new(type: :widget_op, payload: {op: :list_images, tag: tag.to_s})

.load_font(data) ⇒ Cmd

Load a font at runtime from TTF/OTF data.

Parameters:

  • data (String) —

    font file bytes

Returns:



412
 
# File 'lib/plushie/command.rb', line 412

def self.load_font(data) = Cmd.new(type: :widget_op, payload: {op: :load_font, data:})

.maximize_window(window_id, maximized = true) ⇒ Cmd

Parameters:

  • window_id (String)
  • maximized (Boolean) (defaults to: true)

Returns:



158
 
# File 'lib/plushie/command.rb', line 158

def self.maximize_window(window_id, maximized = true) = Cmd.new(type: :window_op, payload: {op: :maximize, window_id:, maximized:})

.minimize_window(window_id, minimized = true) ⇒ Cmd

Parameters:

  • window_id (String)
  • minimized (Boolean) (defaults to: true)

Returns:



163
 
# File 'lib/plushie/command.rb', line 163

def self.minimize_window(window_id, minimized = true) = Cmd.new(type: :window_op, payload: {op: :minimize, window_id:, minimized:})

.monitor_size(window_id, tag) ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



294
 
# File 'lib/plushie/command.rb', line 294

def self.monitor_size(window_id, tag) = Cmd.new(type: :window_query, payload: {op: :monitor_size, window_id:, tag: tag.to_s})

.move_cursor_to(widget_id, position) ⇒ Cmd

Parameters:

  • widget_id (String)
  • position (Integer)

Returns:



102
 
# File 'lib/plushie/command.rb', line 102

def self.move_cursor_to(widget_id, position) = Cmd.new(type: :move_cursor_to, payload: {target: widget_id, position:})

.move_cursor_to_end(widget_id) ⇒ Cmd

Parameters:

  • widget_id (String)

Returns:



97
 
# File 'lib/plushie/command.rb', line 97

def self.move_cursor_to_end(widget_id) = Cmd.new(type: :move_cursor_to_end, payload: {target: widget_id})

.move_cursor_to_front(widget_id) ⇒ Cmd

Parameters:

  • widget_id (String)

Returns:



93
 
# File 'lib/plushie/command.rb', line 93

def self.move_cursor_to_front(widget_id) = Cmd.new(type: :move_cursor_to_front, payload: {target: widget_id})

.move_window(window_id, x, y) ⇒ Cmd

Parameters:

  • window_id (String)
  • x (Integer)
  • y (Integer)

Returns:



153
 
# File 'lib/plushie/command.rb', line 153

def self.move_window(window_id, x, y) = Cmd.new(type: :window_op, payload: {op: :move, window_id:, x:, y:})

.none ⇒ Cmd

Returns no-op command.

Returns:

  • (Cmd) —

    no-op command



28
 
# File 'lib/plushie/command.rb', line 28

def self.none = Cmd.new(type: :none, payload: {})

.pane_close(grid_id, pane_id) ⇒ Cmd

Parameters:

  • grid_id (String)
  • pane_id (String)

Returns:



332
 
# File 'lib/plushie/command.rb', line 332

def self.pane_close(grid_id, pane_id) = Cmd.new(type: :widget_op, payload: {op: :pane_close, target: grid_id, pane: pane_id})

.pane_maximize(grid_id, pane_id) ⇒ Cmd

Parameters:

  • grid_id (String)
  • pane_id (String)

Returns:



343
 
# File 'lib/plushie/command.rb', line 343

def self.pane_maximize(grid_id, pane_id) = Cmd.new(type: :widget_op, payload: {op: :pane_maximize, target: grid_id, pane: pane_id})

.pane_restore(grid_id) ⇒ Cmd

Parameters:

  • grid_id (String)

Returns:



347
 
# File 'lib/plushie/command.rb', line 347

def self.pane_restore(grid_id) = Cmd.new(type: :widget_op, payload: {op: :pane_restore, target: grid_id})

.pane_split(grid_id, pane_id, axis, new_pane_id) ⇒ Cmd

Parameters:

  • grid_id (String)
  • pane_id (String)
  • axis (Symbol) —

    :horizontal, :vertical

  • new_pane_id (String)

Returns:



327
 
# File 'lib/plushie/command.rb', line 327

def self.pane_split(grid_id, pane_id, axis, new_pane_id) = Cmd.new(type: :widget_op, payload: {op: :pane_split, target: grid_id, pane: pane_id, axis: axis.to_s, new_pane_id:})

.pane_swap(grid_id, pane_a, pane_b) ⇒ Cmd

Parameters:

  • grid_id (String)
  • pane_a (String)
  • pane_b (String)

Returns:



338
 
# File 'lib/plushie/command.rb', line 338

def self.pane_swap(grid_id, pane_a, pane_b) = Cmd.new(type: :widget_op, payload: {op: :pane_swap, target: grid_id, a: pane_a, b: pane_b})

.raw_id(window_id, tag) ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



289
 
# File 'lib/plushie/command.rb', line 289

def self.raw_id(window_id, tag) = Cmd.new(type: :window_query, payload: {op: :raw_id, window_id:, tag: tag.to_s})

.request_user_attention(window_id, urgency) ⇒ Cmd

Parameters:

  • window_id (String)
  • urgency (Symbol) —

    :informational, :critical

Returns:



199
 
# File 'lib/plushie/command.rb', line 199

def self.request_user_attention(window_id, urgency) = Cmd.new(type: :window_op, payload: {op: :request_attention, window_id:, urgency: urgency&.to_s})

.resize_window(window_id, width, height) ⇒ Cmd

Parameters:

  • window_id (String)
  • width (Integer)
  • height (Integer)

Returns:



147
 
# File 'lib/plushie/command.rb', line 147

def self.resize_window(window_id, width, height) = Cmd.new(type: :window_op, payload: {op: :resize, window_id:, width:, height:})

.screenshot(window_id, tag) ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



204
 
# File 'lib/plushie/command.rb', line 204

def self.screenshot(window_id, tag) = Cmd.new(type: :window_query, payload: {op: :screenshot, window_id:, tag: tag.to_s})

.scroll_by(widget_id, x, y) ⇒ Cmd

Parameters:

  • widget_id (String)
  • x (Numeric)
  • y (Numeric)

Returns:



133
 
# File 'lib/plushie/command.rb', line 133

def self.scroll_by(widget_id, x, y) = Cmd.new(type: :scroll_by, payload: {target: widget_id, x:, y:})

.scroll_to(widget_id, offset_y) ⇒ Cmd

Parameters:

  • widget_id (String)
  • offset_y (Numeric)

Returns:



117
 
# File 'lib/plushie/command.rb', line 117

def self.scroll_to(widget_id, offset_y) = Cmd.new(type: :scroll_to, payload: {target: widget_id, offset_y:})

.select_all(widget_id) ⇒ Cmd

Parameters:

  • widget_id (String)

Returns:



89
 
# File 'lib/plushie/command.rb', line 89

def self.select_all(widget_id) = Cmd.new(type: :select_all, payload: {target: widget_id})

.select_range(widget_id, start_pos, end_pos) ⇒ Cmd

Parameters:

  • widget_id (String)
  • start_pos (Integer)
  • end_pos (Integer)

Returns:



108
 
# File 'lib/plushie/command.rb', line 108

def self.select_range(widget_id, start_pos, end_pos) = Cmd.new(type: :select_range, payload: {target: widget_id, start: start_pos, end: end_pos})

.send_after(delay_ms, event) ⇒ Cmd

Send an event to update after a delay.

Parameters:

  • delay_ms (Integer) —

    delay in milliseconds

  • event (Object) —

    event to deliver

Returns:



58
 
# File 'lib/plushie/command.rb', line 58

def self.send_after(delay_ms, event) = Cmd.new(type: :send_after, payload: {delay: delay_ms, event:})

.set_icon(window_id, rgba_data, width, height) ⇒ Cmd

Parameters:

  • window_id (String)
  • rgba_data (String) —

    raw RGBA pixel data

  • width (Integer)
  • height (Integer)

Returns:



240
 
# File 'lib/plushie/command.rb', line 240

def self.set_icon(window_id, rgba_data, width, height) = Cmd.new(type: :window_op, payload: {op: :set_icon, window_id:, icon_data: rgba_data, width:, height:})

.set_max_size(window_id, width, height) ⇒ Cmd

Parameters:

  • window_id (String)
  • width (Integer)
  • height (Integer)

Returns:



221
 
# File 'lib/plushie/command.rb', line 221

def self.set_max_size(window_id, width, height) = Cmd.new(type: :window_op, payload: {op: :set_max_size, window_id:, width:, height:})

.set_min_size(window_id, width, height) ⇒ Cmd

Parameters:

  • window_id (String)
  • width (Integer)
  • height (Integer)

Returns:



215
 
# File 'lib/plushie/command.rb', line 215

def self.set_min_size(window_id, width, height) = Cmd.new(type: :window_op, payload: {op: :set_min_size, window_id:, width:, height:})

.set_resizable(window_id, resizable) ⇒ Cmd

Parameters:

  • window_id (String)
  • resizable (Boolean)

Returns:



209
 
# File 'lib/plushie/command.rb', line 209

def self.set_resizable(window_id, resizable) = Cmd.new(type: :window_op, payload: {op: :set_resizable, window_id:, resizable:})

.set_resize_increments(window_id, width, height) ⇒ Cmd

Parameters:

  • window_id (String)
  • width (Integer)
  • height (Integer)

Returns:



246
 
# File 'lib/plushie/command.rb', line 246

def self.set_resize_increments(window_id, width, height) = Cmd.new(type: :window_op, payload: {op: :set_resize_increments, window_id:, width:, height:})

.set_window_level(window_id, level) ⇒ Cmd

Parameters:

  • window_id (String)
  • level (Symbol) —

    :normal, :always_on_top, :always_on_bottom

Returns:



185
 
# File 'lib/plushie/command.rb', line 185

def self.set_window_level(window_id, level) = Cmd.new(type: :window_op, payload: {op: :set_level, window_id:, level: level.to_s})

.set_window_mode(window_id, mode) ⇒ Cmd

Parameters:

  • window_id (String)
  • mode (Symbol) —

    :fullscreen, :windowed, :hidden

Returns:



168
 
# File 'lib/plushie/command.rb', line 168

def self.set_window_mode(window_id, mode) = Cmd.new(type: :window_op, payload: {op: :set_mode, window_id:, mode: mode.to_s})

.show_system_menu(window_id) ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



233
 
# File 'lib/plushie/command.rb', line 233

def self.show_system_menu(window_id) = Cmd.new(type: :window_op, payload: {op: :show_system_menu, window_id:})

.snap_to(widget_id, x, y) ⇒ Cmd

Parameters:

  • widget_id (String)
  • x (Float) —

    relative position 0.0-1.0

  • y (Float) —

    relative position 0.0-1.0

Returns:



123
 
# File 'lib/plushie/command.rb', line 123

def self.snap_to(widget_id, x, y) = Cmd.new(type: :snap_to, payload: {target: widget_id, x:, y:})

.snap_to_end(widget_id) ⇒ Cmd

Parameters:

  • widget_id (String)

Returns:



127
 
# File 'lib/plushie/command.rb', line 127

def self.snap_to_end(widget_id) = Cmd.new(type: :snap_to_end, payload: {target: widget_id})

.stream(callable, tag) ⇒ Cmd

Run a callable that emits multiple values via an emit callback. Each emit delivers Event::Stream; the final return delivers Event::Async.

Parameters:

  • callable (Proc) —

    receives an emit proc as argument

  • tag (Symbol) —

    event tag

Returns:



41
 
# File 'lib/plushie/command.rb', line 41

def self.stream(callable, tag) = Cmd.new(type: :stream, payload: {callable:, tag:})

.toggle_decorations(window_id) ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



176
 
# File 'lib/plushie/command.rb', line 176

def self.toggle_decorations(window_id) = Cmd.new(type: :window_op, payload: {op: :toggle_decorations, window_id:})

.toggle_maximize(window_id) ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



172
 
# File 'lib/plushie/command.rb', line 172

def self.toggle_maximize(window_id) = Cmd.new(type: :window_op, payload: {op: :toggle_maximize, window_id:})

.tree_hash(tag) ⇒ Cmd

Compute tree hash. Result via Event::System.

Parameters:

  • tag (Symbol)

Returns:



398
 
# File 'lib/plushie/command.rb', line 398

def self.tree_hash(tag) = Cmd.new(type: :widget_op, payload: {op: :tree_hash, tag: tag.to_s})

.update_image(handle, data = nil, width: nil, height: nil, pixels: nil) ⇒ Cmd

Update an existing image handle.

Parameters:

  • handle (String)
  • data (String, nil) (defaults to: nil) —

    encoded image bytes

Returns:



369
370
371
372
373
374
375
 
# File 'lib/plushie/command.rb', line 369

def self.update_image(handle, data = nil, width: nil, height: nil, pixels: nil)
  if pixels
    Cmd.new(type: :image_op, payload: {op: :update_image, handle:, pixels:, width:, height:})
  else
    Cmd.new(type: :image_op, payload: {op: :update_image, handle:, data:})
  end
end