Skip to content
Kward Search API index

Class: Kward::PromptInterface::InteractiveController

Inherits:
Object
  • Object
show all
Defined in:
lib/kward/prompt_interface/interactive/controller.rb

Overview

Controller object passed to interactive plugin commands. Owns the canvas buffer and exposes the plugin-facing API for drawing colored cells, reading keys, and controlling the loop lifecycle.

Kward manages the actual terminal rendering: the plugin fills the canvas via #put and #clear_frame, then calls #render to mark it dirty. Kward flushes the canvas to the composer region on the next frame write.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(width:, height:, fps:) ⇒ InteractiveController

Creates a controller with the given canvas dimensions and frame rate.

Parameters:

  • width (Integer) —

    canvas width in terminal columns

  • height (Integer) —

    canvas height in terminal rows

  • fps (Numeric) —

    target frame rate for tick callbacks



18
19
20
21
22
23
24
25
26
27
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 18

def initialize(width:, height:, fps:)
  @width = [width.to_i, 1].max
  @height = [height.to_i, 1].max
  @fps = [[fps.to_f, 1].max, 120].min
  @cells = Array.new(@height) { Array.new(@width) { blank_cell } }
  @dirty = true
  @keys = []
  @exited = false
  @on_tick = nil
end

Instance Attribute Details

#fps ⇒ Numeric (readonly)

Returns target frame rate.

Returns:

  • (Numeric) —

    target frame rate



36
37
38
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 36

def fps
  @fps
end

#height ⇒ Integer (readonly)

Returns canvas height in terminal rows.

Returns:

  • (Integer) —

    canvas height in terminal rows



33
34
35
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 33

def height
  @height
end

#width ⇒ Integer (readonly)

Returns canvas width in terminal columns.

Returns:

  • (Integer) —

    canvas width in terminal columns



30
31
32
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 30

def width
  @width
end

Instance Method Details

#cells ⇒ Array<Array<Hash>>

Returns the canvas cells as a 2D array of { char:, colors: } hashes. Kward calls this to render the frame. Resets the dirty flag.

Returns:

  • (Array<Array<Hash>>) 


93
94
95
96
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 93

def cells
  @dirty = false
  @cells
end

#clear_frame ⇒ void

This method returns an undefined value.

Clears all canvas cells to blank.



68
69
70
71
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 68

def clear_frame
  @cells = Array.new(@height) { Array.new(@width) { blank_cell } }
  @dirty = true
end

#dirty? ⇒ Boolean

Whether the canvas has changes pending render. Kward checks this to decide whether to write cells to the terminal.

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 85

def dirty?
  @dirty
end

#exit ⇒ void

This method returns an undefined value.

Requests that the interactive loop exit. Kward detects this and tears down the canvas, restoring the prior composer state.



110
111
112
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 110

def exit
  @exited = true
end

#exited? ⇒ Boolean

Whether exit has been requested by the plugin or forced by Kward.

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 117

def exited?
  @exited
end

#force_exit ⇒ void

This method returns an undefined value.

Marks the controller as exited. Called by Kward on forced exit.



175
176
177
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 175

def force_exit
  @exited = true
end

#invoke_tick ⇒ Object, ...

Invokes the registered tick callback. Kward calls this on each frame. Returns :exit if the callback requests exit.

Returns:

  • (Object, :exit, nil) 


132
133
134
135
136
137
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 132

def invoke_tick
  return nil unless @on_tick

  result = @on_tick.call(self)
  result == :exit ? :exit : nil
end

#on_tick {|ui| ... } ⇒ void

This method returns an undefined value.

Sets the tick callback invoked by Kward on each frame. The block receives this controller. Returning :exit or calling #exit ends the loop.

Yield Parameters:



44
45
46
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 44

def on_tick(&block)
  @on_tick = block
end

#poll_key ⇒ String, ...

Returns the next pending key, or nil if none. Keys are routed by Kward's main input loop via #push_key. Non-blocking.

Returns:

  • (String, Symbol, nil) 


102
103
104
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 102

def poll_key
  @keys.shift
end

#push_key(key) ⇒ void

This method returns an undefined value.

Pushes a key into the internal queue. Called by Kward's input loop.

Parameters:

  • key (String, Symbol) —

    key to enqueue



168
169
170
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 168

def push_key(key)
  @keys << key
end

#put(row, col, char, *colors) ⇒ void

This method returns an undefined value.

Places a character at the given canvas position with optional color.

Parameters:

  • row (Integer) —

    zero-based row

  • col (Integer) —

    zero-based column

  • char (String) —

    single character to display

  • colors (Array<Symbol, String>) —

    ANSI style names or raw SGR codes



55
56
57
58
59
60
61
62
63
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 55

def put(row, col, char, *colors)
  row = row.to_i
  col = col.to_i
  return if row.negative? || row >= @height
  return if col.negative? || col >= @width

  @cells[row][col] = { char: char.to_s[0] || " ", colors: colors.flatten }
  @dirty = true
end

#render ⇒ void

This method returns an undefined value.

Marks the canvas as ready for Kward to render. Called after the plugin has finished drawing a frame via #put and #clear_frame.



77
78
79
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 77

def render
  @dirty = true
end

#resize(width:, height: @height) ⇒ void

This method returns an undefined value.

Resizes the canvas dimensions. Called by Kward when the terminal resizes during interactive mode.

Parameters:

  • width (Integer) —

    new canvas width

  • height (Integer) (defaults to: @height) —

    new canvas height (kept at original row count)



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 145

def resize(width:, height: @height)
  @width = [width.to_i, 1].max
  new_height = [height.to_i, 1].max
  if new_height != @height
    @height = new_height
    clear_frame
    return
  end

  @cells.each do |row|
    if row.length < @width
      row.fill(blank_cell, row.length...@width)
    else
      row.slice!(@width..)
    end
  end
  @dirty = true
end

#tickable? ⇒ Boolean

Whether a tick callback has been registered.

Returns:

  • (Boolean) 


124
125
126
 
# File 'lib/kward/prompt_interface/interactive/controller.rb', line 124

def tickable?
  !@on_tick.nil?
end