Class: Tuile::Screen

Inherits:
Object
  • Object
show all
Defined in:
lib/tuile/screen.rb

Overview

The TTY screen. There is exactly one screen per app.

A screen runs the event loop; call #run_event_loop to do that.

A screen holds the screen lock; any UI modifications must be called from the event queue.

All UI lives under a single ScreenPane owned by the screen. Set tiled content via #content=; the pane fills the entire terminal and is responsible for laying out its children.

Modal popups are supported too, via Component::Popup#open. They auto-size to their wrapped content and are drawn centered over the tiled content.

The drawing procedure is very simple: when a window needs repaint, it invalidates itself, but won’t draw immediately. After the keyboard press event processing is done in the event loop, #repaint is called which then repaints all invalidated windows. This prevents repeated paintings.

Direct Known Subclasses

FakeScreen

Constant Summary collapse

@@instance =

Class variable (not class instance var) so the singleton survives subclassing — ‘FakeScreen < Screen` and `Screen.instance` see the same slot.

nil

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Screen

rubocop:disable Style/ClassVars



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/tuile/screen.rb', line 28

def initialize
  @@instance = self # rubocop:disable Style/ClassVars
  @event_queue = EventQueue.new
  @size = EventQueue::TTYSizeEvent.create.size
  @invalidated = Set.new
  # Components being repainted right now. A component may invalidate its
  # children during its repaint phase; this prevents double-draw.
  @repainting = Set.new
  # Until the event loop is run, we pretend we're in the UI thread.
  @pretend_ui_lock = true
  # Structural root of the component tree: holds tiled content, popup
  # stack and status bar.
  @pane = ScreenPane.new
  @on_error = ->(e) { raise e }
end

Instance Attribute Details

#event_queue ⇒ EventQueue (readonly)

Returns the event queue.

Returns:



92
93
94
 
# File 'lib/tuile/screen.rb', line 92

def event_queue
  @event_queue
end

#focused ⇒ Component?

Returns currently focused component.

Returns:

  • (Component, nil) —

    currently focused component.



123
124
125
 
# File 'lib/tuile/screen.rb', line 123

def focused
  @focused
end

#on_error ⇒ Proc

Handler invoked when a StandardError escapes an event handler inside the event loop (e.g. a Component::TextField‘s `on_change` raises).

The default re-raises, so the exception propagates out of #run_event_loop and crashes the script with a stacktrace — unhandled exceptions are bugs and should be surfaced loudly.

Replace it when the host has somewhere visible to put errors, e.g. a Component::LogWindow wired to Tuile.logger:

screen.on_error = lambda do |e|
  Tuile.logger.error("#{e.class}: #{e.message}\n#{e.backtrace&.join("\n")}")
end

The handler runs on the event-loop thread with the UI lock held. Returning normally keeps the loop alive; raising from within the handler tears the loop down and propagates out of #run_event_loop.

Returns:

  • (Proc) —

    one-arg callable receiving the StandardError instance.



65
66
67
 
# File 'lib/tuile/screen.rb', line 65

def on_error
  @on_error
end

#pane ⇒ ScreenPane (readonly)

Returns the structural root of the component tree.

Returns:

  • (ScreenPane) —

    the structural root of the component tree.



45
46
47
 
# File 'lib/tuile/screen.rb', line 45

def pane
  @pane
end

#size ⇒ Size (readonly)

Returns current screen size.

Returns:

  • (Size) —

    current screen size.



85
86
87
 
# File 'lib/tuile/screen.rb', line 85

def size
  @size
end

Class Method Details

.close ⇒ void

This method returns an undefined value.



234
235
236
 
# File 'lib/tuile/screen.rb', line 234

def self.close
  @@instance&.close
end

.fake ⇒ FakeScreen

Testing only — creates new screen, locks the UI, and prevents any redraws, so that test TTY is not painted over. FakeScreen#initialize self-installs as the singleton, so subsequent instance calls return the same object.

Returns:



224
 
# File 'lib/tuile/screen.rb', line 224

def self.fake = FakeScreen.new

.instance ⇒ Screen

Returns the singleton instance.

Returns:

  • (Screen) —

    the singleton instance.

Raises:



68
69
70
71
72
 
# File 'lib/tuile/screen.rb', line 68

def self.instance
  raise Tuile::Error, "Screen not initialized; call Screen.new first" if @@instance.nil?

  @@instance
end

Instance Method Details

#active_window ⇒ Component?

Returns current active tiled component.

Returns:

  • (Component, nil) —

    current active tiled component.



190
191
192
193
194
195
 
# File 'lib/tuile/screen.rb', line 190

def active_window
  check_locked
  result = nil
  @pane.content&.on_tree { result = it if it.is_a?(Component::Window) && it.active? }
  result
end

#add_popup(window) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Internal — use Component::Popup#open instead. Adds the popup to #pane, centers and focuses it.

Parameters:



166
167
168
169
170
171
 
# File 'lib/tuile/screen.rb', line 166

def add_popup(window)
  check_locked
  @pane.add_popup(window)
  # No need to fully repaint the scene: a popup simply paints over the
  # current screen contents.
end

#check_locked ⇒ void

This method returns an undefined value.

Checks that the UI lock is held and the current code runs in the “UI thread”.

Raises:



97
98
99
100
101
102
103
 
# File 'lib/tuile/screen.rb', line 97

def check_locked
  return if @pretend_ui_lock || @event_queue.locked?

  raise Tuile::Error,
        "UI lock not held: UI mutations must run on the event-loop thread; " \
        "marshal via screen.event_queue.submit { ... }"
end

#clear ⇒ void

This method returns an undefined value.

Clears the TTY screen.



107
108
109
 
# File 'lib/tuile/screen.rb', line 107

def clear
  print TTY::Cursor.move_to(0, 0), TTY::Cursor.clear_screen
end

#close ⇒ void

This method returns an undefined value.



227
228
229
230
231
 
# File 'lib/tuile/screen.rb', line 227

def close
  clear
  @pane = nil
  @@instance = nil # rubocop:disable Style/ClassVars
end

#content ⇒ Component?

Returns tiled content (forwarded to Tuile::ScreenPane).

Returns:



75
 
# File 'lib/tuile/screen.rb', line 75

def content = @pane.content

#content=(content) ⇒ void

This method returns an undefined value.

Parameters:



79
80
81
82
 
# File 'lib/tuile/screen.rb', line 79

def content=(content)
  @pane.content = content
  layout
end

#cursor_position ⇒ Point?

Returns the absolute screen coordinates where the hardware cursor should sit, or nil if it should be hidden. Only the #focused component owns the cursor: there can be multiple active components (the focus path), but only one focused.

Returns:



302
 
# File 'lib/tuile/screen.rb', line 302

def cursor_position = @focused&.cursor_position

#has_popup?(window) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Internal — use Component::Popup#open? instead.

Parameters:

Returns:

  • (Boolean) —

    true if this popup is currently mounted.



214
215
216
217
 
# File 'lib/tuile/screen.rb', line 214

def has_popup?(window) # rubocop:disable Naming/PredicatePrefix
  check_locked
  @pane.has_popup?(window)
end

#invalidate(component) ⇒ void

This method returns an undefined value.

Invalidates a component: causes the component to be repainted on next call to #repaint.

Parameters:

Raises:

  • (TypeError) 


115
116
117
118
119
120
 
# File 'lib/tuile/screen.rb', line 115

def invalidate(component)
  check_locked
  raise TypeError, "expected Component, got #{component.inspect}" unless component.is_a? Component

  @invalidated << component unless @repainting.include? component
end

#popups ⇒ Array<Component>

Returns currently active popup components (forwarded to Tuile::ScreenPane). The array must not be modified!.

Returns:



89
 
# File 'lib/tuile/screen.rb', line 89

def popups = @pane.popups

#print(*args) ⇒ void

This method returns an undefined value.

Prints given strings.

Parameters:

  • args (String) —

    stuff to print.



241
242
243
 
# File 'lib/tuile/screen.rb', line 241

def print(*args)
  Kernel.print(*args)
end

#remove_popup(window) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Internal — use Component::Popup#close instead. Removes the popup from #pane, repairs focus, and repaints the scene.

Does nothing if the window is not open on this screen.

Parameters:



204
205
206
207
208
 
# File 'lib/tuile/screen.rb', line 204

def remove_popup(window)
  check_locked
  @pane.remove_popup(window)
  needs_full_repaint
end

#repaint ⇒ void

This method returns an undefined value.

Repaints the screen; tries to be as effective as possible, by only considering invalidated windows.



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/tuile/screen.rb', line 248

def repaint
  check_locked
  # This simple TUI framework doesn't support window clipping since tiled
  # windows are not expected to overlap. If there rarely is a popup, we
  # just repaint all windows in correct order — sure they will paint over
  # other windows, but if this is done in the right order, the final
  # drawing will look okay. Not the most effective algorithm, but very
  # simple and very fast in common cases.

  did_paint = false
  until @invalidated.empty?
    did_paint = true
    popups = @pane.popups

    # Partition invalidated components into tiled vs popup-tree. Sorting
    # by depth across the whole tree would interleave them: a tiled
    # grandchild (depth 3) sorts after a popup's content (depth 2) and
    # overdraws it.
    popup_tree = Set.new
    popups.each { |p| p.on_tree { popup_tree << it } }
    tiled, popup_invalidated = @invalidated.to_a.partition { !popup_tree.include?(it) }

    # Within the tiled tree, paint parents before children.
    tiled.sort_by!(&:depth)

    repaint = if tiled.empty?
                # Only popups need repaint — paint just their invalidated
                # components in depth order.
                popup_invalidated.sort_by(&:depth)
              else
                # Tiled components may overdraw popups; repaint each open
                # popup's full subtree on top, in stacking order
                # (parent-before-child within each popup).
                tiled + popups.flat_map { |p| collect_subtree(p) }
              end

    @repainting = repaint.to_set
    @invalidated.clear

    # Don't call {#clear} before repaint — causes flickering, and only
    # needed when @content doesn't cover the entire screen.
    repaint.each(&:repaint)

    # Repaint done, mark all components as up-to-date.
    @repainting.clear
  end
  position_cursor if did_paint
end

#run_event_loop ⇒ void

This method returns an undefined value.

Runs event loop – waits for keys and sends them to active window. The function exits when the ‘ESC’ or ‘q’ key is pressed.



176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/tuile/screen.rb', line 176

def run_event_loop
  @pretend_ui_lock = false
  $stdin.echo = false
  print MouseEvent.start_tracking
  $stdin.raw do
    event_loop
  end
ensure
  print MouseEvent.stop_tracking
  print TTY::Cursor.show
  $stdin.echo = true
end