Class: Plushie::Command

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/plushie/command.rb,
lib/plushie/command/text.rb,
lib/plushie/command/image.rb,
lib/plushie/command/scroll.rb,
lib/plushie/command/window.rb,
lib/plushie/command/window_query.rb,
sig/plushie/command.rbs,
sig/plushie/command/text.rbs,
sig/plushie/command/image.rbs,
sig/plushie/command/scroll.rbs,
sig/plushie/command/window.rbs,
sig/plushie/command/window_query.rbs

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.

Command categories

  • Basic: async, stream, cancel, done, send_after, exit, batch
  • Focus: focus, focus_next, focus_previous
  • Text (Text): select_all, move_cursor_to, select_range, ...
  • Scroll (Scroll): scroll_to, snap_to, scroll_by, ...
  • Window (Window): resize_window, close_window, focus_window, ...
  • Window queries (WindowQuery): window_size, window_mode, ...
  • Image (Image): create_image, create_image_rgba, update_image, update_image_rgba, delete_image, ...
  • Widget command: widget_command for native widget operations

All submodule methods are also available directly on Command via delegation:

Command.scroll_to("list", 0, 100)       # via delegation
Command::Scroll.scroll_to("list", 0, 100)  # directly

Examples:

Async work

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

Focus a widget

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

Native widget command

[model, Command.widget_command("chart-1", "append_data", {values: [1.0, 2.5]})]

Defined Under Namespace

Modules: Image, Scroll, Text, Window, WindowQuery Classes: Cmd

Class Method Summary collapse

Class Method Details

.advance_frame(timestamp) ⇒ Cmd

Test

Parameters:

  • timestamp (Integer)

Returns:



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

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

.allow_automatic_tabbing ⇒ Cmd

Parameters:

  • enabled (Boolean)

Returns:



86
 
# File 'sig/plushie/command.rbs', line 86

def self.allow_automatic_tabbing: (bool enabled) -> Cmd

.announce(text, politeness = :polite) ⇒ Cmd

Accessibility

Parameters:

  • text (String)

Returns:



263
264
265
266
267
268
 
# File 'lib/plushie/command.rb', line 263

def self.announce(text, politeness = :polite)
  unless %i[polite assertive].include?(politeness)
    raise ArgumentError, "politeness must be :polite or :assertive, got #{politeness.inspect}"
  end
  Cmd.new(type: :widget_op, payload: {op: "announce", text:, politeness: politeness.to_s})
end

.async ⇒ Cmd

Parameters:

  • callable (Proc)
  • tag (Symbol)

Returns:



13
 
# File 'sig/plushie/command.rbs', line 13

def self.async: (Proc callable, Symbol tag) -> Cmd

.batch(commands) ⇒ Cmd

Combine multiple commands. Executed sequentially.

Parameters:

  • commands (Array<Cmd>)

Returns:



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

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:



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

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

.clear_images ⇒ Cmd

Returns:



99
 
# File 'sig/plushie/command.rbs', line 99

def self.clear_images: () -> Cmd

.close_window ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



64
 
# File 'sig/plushie/command.rbs', line 64

def self.close_window: (String window_id) -> Cmd

.create_image ⇒ Cmd

Parameters:

  • handle (String)
  • data (String, nil)
  • width: (Integer, nil)
  • height: (Integer, nil)
  • pixels: (String, nil)

Returns:



95
 
# File 'sig/plushie/command.rbs', line 95

def self.create_image: (String handle, ?String? data, ?width: Integer?, ?height: Integer?, ?pixels: String?) -> Cmd

.delete_image ⇒ Cmd

Parameters:

  • handle (String)

Returns:



97
 
# File 'sig/plushie/command.rbs', line 97

def self.delete_image: (String handle) -> Cmd

.disable_mouse_passthrough ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



82
 
# File 'sig/plushie/command.rbs', line 82

def self.disable_mouse_passthrough: (String window_id) -> Cmd

.dispatch(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:



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

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

.done ⇒ Cmd

Parameters:

  • value (Object)
  • mapper_fn (Proc)

Returns:



16
 
# File 'sig/plushie/command.rbs', line 16

def self.done: (untyped value, Proc mapper_fn) -> Cmd

.drag_resize_window ⇒ Cmd

Parameters:

  • window_id (String)
  • direction (Symbol)

Returns:



75
 
# File 'sig/plushie/command.rbs', line 75

def self.drag_resize_window: (String window_id, Symbol direction) -> Cmd

.drag_window ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



74
 
# File 'sig/plushie/command.rbs', line 74

def self.drag_window: (String window_id) -> Cmd

.enable_mouse_passthrough ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



81
 
# File 'sig/plushie/command.rbs', line 81

def self.enable_mouse_passthrough: (String window_id) -> Cmd

.exit ⇒ Cmd

Terminate the application.

Returns:



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

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

.find_focused(tag) ⇒ Cmd

Find focused widget. Result via Event::System.

Parameters:

  • tag (Symbol)

Returns:



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

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

.focus(widget_id) ⇒ Cmd

Focus

Parameters:

  • widget_id (String)

Returns:



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

def self.focus(widget_id)
  widget_command(widget_id, "focus")
end

.focus_next ⇒ Cmd

Move focus to the next focusable widget.

Returns:



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

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

.focus_next_within(scope) ⇒ Cmd

Move focus to the next focusable widget within the subtree rooted at scope. Focus wraps at the subtree boundary. Useful for menus, pane grids, and other keyboard containers that want a bounded Tab cycle without leaking focus to siblings.

Parameters:

  • scope (String) —

    the widget ID of the subtree root

Returns:



149
150
151
 
# File 'lib/plushie/command.rb', line 149

def self.focus_next_within(scope)
  Cmd.new(type: :widget_op, payload: {op: "focus_next_within", scope: scope})
end

.focus_previous ⇒ Cmd

Move focus to the previous focusable widget.

Returns:



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

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

.focus_previous_within(scope) ⇒ Cmd

Move focus to the previous focusable widget within the subtree rooted at scope. See focus_next_within for semantics.

Parameters:

  • scope (String) —

    the widget ID of the subtree root

Returns:



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

def self.focus_previous_within(scope)
  Cmd.new(type: :widget_op, payload: {op: "focus_previous_within", scope: scope})
end

.focus_window ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



72
 
# File 'sig/plushie/command.rbs', line 72

def self.focus_window: (String window_id) -> Cmd

.get_mode ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



91
 
# File 'sig/plushie/command.rbs', line 91

def self.get_mode: (String window_id, Symbol tag) -> Cmd

.get_scale_factor ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



92
 
# File 'sig/plushie/command.rbs', line 92

def self.get_scale_factor: (String window_id, Symbol tag) -> Cmd

.get_system_info ⇒ Cmd

Parameters:

  • tag (Symbol)

Returns:



39
 
# File 'sig/plushie/command.rbs', line 39

def self.get_system_info: (Symbol tag) -> Cmd

.get_system_theme ⇒ Cmd

System queries

Parameters:

  • tag (Symbol)

Returns:



38
 
# File 'sig/plushie/command.rbs', line 38

def self.get_system_theme: (Symbol tag) -> Cmd

.get_window_position ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



88
 
# File 'sig/plushie/command.rbs', line 88

def self.get_window_position: (String window_id, Symbol tag) -> Cmd

.get_window_size ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



87
 
# File 'sig/plushie/command.rbs', line 87

def self.get_window_size: (String window_id, Symbol tag) -> Cmd

.is_maximized ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



89
 
# File 'sig/plushie/command.rbs', line 89

def self.is_maximized: (String window_id, Symbol tag) -> Cmd

.is_minimized ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



90
 
# File 'sig/plushie/command.rbs', line 90

def self.is_minimized: (String window_id, Symbol tag) -> Cmd

.list_images ⇒ Cmd

Parameters:

  • tag (Symbol)

Returns:



98
 
# File 'sig/plushie/command.rbs', line 98

def self.list_images: (Symbol tag) -> Cmd

.load_font(family, data) ⇒ Cmd

Font

Parameters:

  • family (String)
  • data (String)

Returns:



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

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

.maximize_window ⇒ Cmd

Parameters:

  • window_id (String)
  • maximized (Boolean)

Returns:



67
 
# File 'sig/plushie/command.rbs', line 67

def self.maximize_window: (String window_id, ?bool maximized) -> Cmd

.minimize_window ⇒ Cmd

Parameters:

  • window_id (String)
  • minimized (Boolean)

Returns:



68
 
# File 'sig/plushie/command.rbs', line 68

def self.minimize_window: (String window_id, ?bool minimized) -> Cmd

.monitor_size ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



94
 
# File 'sig/plushie/command.rbs', line 94

def self.monitor_size: (String window_id, Symbol tag) -> Cmd

.move_cursor_to ⇒ Cmd

Parameters:

  • widget_id (String)
  • position (Integer)

Returns:



58
 
# File 'sig/plushie/command.rbs', line 58

def self.move_cursor_to: (String widget_id, Integer position) -> Cmd

.move_cursor_to_end ⇒ Cmd

Parameters:

  • widget_id (String)

Returns:



57
 
# File 'sig/plushie/command.rbs', line 57

def self.move_cursor_to_end: (String widget_id) -> Cmd

.move_cursor_to_front ⇒ Cmd

Parameters:

  • widget_id (String)

Returns:



56
 
# File 'sig/plushie/command.rbs', line 56

def self.move_cursor_to_front: (String widget_id) -> Cmd

.move_window ⇒ Cmd

Parameters:

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

Returns:



66
 
# File 'sig/plushie/command.rbs', line 66

def self.move_window: (String window_id, Integer x, Integer y) -> Cmd

.none ⇒ Cmd

Basic

Returns:



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

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

.pane_close(grid_id, pane_id) ⇒ Cmd

Close a pane in the pane grid.

Parameters:

  • grid_id (String)
  • pane_id (String)

Returns:



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

def self.pane_close(grid_id, pane_id)
  widget_command(grid_id, "pane_close", {pane: pane_id})
end

.pane_maximize(grid_id, pane_id) ⇒ Cmd

Maximize a pane in the pane grid.

Parameters:

  • grid_id (String)
  • pane_id (String)

Returns:



196
197
198
 
# File 'lib/plushie/command.rb', line 196

def self.pane_maximize(grid_id, pane_id)
  widget_command(grid_id, "pane_maximize", {pane: pane_id})
end

.pane_restore(grid_id) ⇒ Cmd

Restore all panes from maximized state.

Parameters:

  • grid_id (String)

Returns:



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

def self.pane_restore(grid_id)
  widget_command(grid_id, "pane_restore")
end

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

PaneGrid

Parameters:

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

Returns:



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

def self.pane_split(grid_id, pane_id, axis, new_pane_id)
  widget_command(grid_id, "pane_split", {pane: pane_id, axis: axis.to_s, new_pane_id: new_pane_id})
end

.pane_swap(grid_id, pane_a, pane_b) ⇒ Cmd

Swap two panes in the pane grid.

Parameters:

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

Returns:



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

def self.pane_swap(grid_id, pane_a, pane_b)
  widget_command(grid_id, "pane_swap", {a: pane_a, b: pane_b})
end

.raw_id ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



93
 
# File 'sig/plushie/command.rbs', line 93

def self.raw_id: (String window_id, Symbol tag) -> Cmd

.request_user_attention ⇒ Cmd

Parameters:

  • window_id (String)
  • urgency (Symbol)

Returns:



76
 
# File 'sig/plushie/command.rbs', line 76

def self.request_user_attention: (String window_id, Symbol urgency) -> Cmd

.resize_window ⇒ Cmd

Parameters:

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

Returns:



65
 
# File 'sig/plushie/command.rbs', line 65

def self.resize_window: (String window_id, Integer width, Integer height) -> Cmd

.screenshot ⇒ Cmd

Parameters:

  • window_id (String)
  • tag (Symbol)

Returns:



77
 
# File 'sig/plushie/command.rbs', line 77

def self.screenshot: (String window_id, Symbol tag) -> Cmd

.scroll_by ⇒ Cmd

Parameters:

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

Returns:



63
 
# File 'sig/plushie/command.rbs', line 63

def self.scroll_by: (String widget_id, Numeric x, Numeric y) -> Cmd

.scroll_to ⇒ Cmd

Parameters:

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

Returns:



60
 
# File 'sig/plushie/command.rbs', line 60

def self.scroll_to: (String widget_id, Numeric x, Numeric y) -> Cmd

.select_all ⇒ Cmd

Delegated from submodules (also available on each submodule)

Parameters:

  • widget_id (String)

Returns:



55
 
# File 'sig/plushie/command.rbs', line 55

def self.select_all: (String widget_id) -> Cmd

.select_range ⇒ Cmd

Parameters:

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

Returns:



59
 
# File 'sig/plushie/command.rbs', line 59

def self.select_range: (String widget_id, Integer start_pos, Integer end_pos) -> Cmd

.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:



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

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

.set_icon ⇒ Cmd

Parameters:

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

Returns:



84
 
# File 'sig/plushie/command.rbs', line 84

def self.set_icon: (String window_id, String rgba_data, Integer width, Integer height) -> Cmd

.set_max_size ⇒ Cmd

Parameters:

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

Returns:



80
 
# File 'sig/plushie/command.rbs', line 80

def self.set_max_size: (String window_id, Integer width, Integer height) -> Cmd

.set_min_size ⇒ Cmd

Parameters:

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

Returns:



79
 
# File 'sig/plushie/command.rbs', line 79

def self.set_min_size: (String window_id, Integer width, Integer height) -> Cmd

.set_resizable ⇒ Cmd

Parameters:

  • window_id (String)
  • resizable (Boolean)

Returns:



78
 
# File 'sig/plushie/command.rbs', line 78

def self.set_resizable: (String window_id, bool resizable) -> Cmd

.set_resize_increments ⇒ Cmd

Parameters:

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

Returns:



85
 
# File 'sig/plushie/command.rbs', line 85

def self.set_resize_increments: (String window_id, Integer width, Integer height) -> Cmd

.set_window_level ⇒ Cmd

Parameters:

  • window_id (String)
  • level (Symbol)

Returns:



73
 
# File 'sig/plushie/command.rbs', line 73

def self.set_window_level: (String window_id, Symbol level) -> Cmd

.set_window_mode ⇒ Cmd

Parameters:

  • window_id (String)
  • mode (Symbol)

Returns:



69
 
# File 'sig/plushie/command.rbs', line 69

def self.set_window_mode: (String window_id, Symbol mode) -> Cmd

.show_system_menu ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



83
 
# File 'sig/plushie/command.rbs', line 83

def self.show_system_menu: (String window_id) -> Cmd

.snap_to ⇒ Cmd

Parameters:

  • widget_id (String)
  • x (Float)
  • y (Float)

Returns:



61
 
# File 'sig/plushie/command.rbs', line 61

def self.snap_to: (String widget_id, Float x, Float y) -> Cmd

.snap_to_end ⇒ Cmd

Parameters:

  • widget_id (String)

Returns:



62
 
# File 'sig/plushie/command.rbs', line 62

def self.snap_to_end: (String widget_id) -> Cmd

.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:



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

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

.system_info(tag) ⇒ Cmd

Parameters:

  • tag (Symbol)

Returns:



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

def self.system_info(tag) = Cmd.new(type: :system_query, payload: {op: "get_system_info", tag: tag.to_s})

.system_theme(tag) ⇒ Cmd

Parameters:

  • tag (Symbol)

Returns:



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

def self.system_theme(tag) = Cmd.new(type: :system_query, payload: {op: "get_system_theme", tag: tag.to_s})

.task(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:



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

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

.toggle_decorations ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



71
 
# File 'sig/plushie/command.rbs', line 71

def self.toggle_decorations: (String window_id) -> Cmd

.toggle_maximize ⇒ Cmd

Parameters:

  • window_id (String)

Returns:



70
 
# File 'sig/plushie/command.rbs', line 70

def self.toggle_maximize: (String window_id) -> Cmd

.tree_hash(tag) ⇒ Cmd

Widget queries (global)

Parameters:

  • tag (Symbol)

Returns:



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

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

.update_image ⇒ Cmd

Parameters:

  • handle (String)
  • data (String, nil)
  • width: (Integer, nil)
  • height: (Integer, nil)
  • pixels: (String, nil)

Returns:



96
 
# File 'sig/plushie/command.rbs', line 96

def self.update_image: (String handle, ?String? data, ?width: Integer?, ?height: Integer?, ?pixels: String?) -> Cmd

.widget_batch(commands) ⇒ Cmd

Send a batch of widget commands processed atomically in one cycle.

Each command in the list is a {id:, family:, value:} Hash. All commands are applied before any resulting events are emitted.

Parameters:

  • commands (Array<Hash>) —

    each with :id, :family, :value keys

Returns:



119
120
121
 
# File 'lib/plushie/command.rb', line 119

def self.widget_batch(commands)
  Cmd.new(type: :commands, payload: {commands: commands})
end

.widget_command(id, family, value = nil) ⇒ Cmd

Widget command (unified)

Parameters:

  • id (String)
  • family (String)
  • value (Object) (defaults to: nil)

Returns:



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

def self.widget_command(id, family, value = nil)
  Cmd.new(type: :command, payload: {id: id, family: family.to_s, value: value})
end

.widget_commands ⇒ Cmd

Parameters:

  • commands (Array[Hash[Symbol, untyped]])

Returns:



23
 
# File 'sig/plushie/command.rbs', line 23

def self.widget_commands: (Array[Hash[Symbol, untyped]] commands) -> Cmd