Class: Tuile::Screen

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

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
43
44
45
46
47
48
49
50
51
52
 
# 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
  @color_scheme = detect_scheme
  @theme_def = ThemeDef.default
  @theme = @theme_def.for(@color_scheme)
  # Structural root of the component tree: holds tiled content, popup
  # stack and status bar.
  @pane = ScreenPane.new
  @on_error = ->(e) { raise e }
  # App-level keyboard shortcuts dispatched by {#handle_key} before keys
  # reach the pane. See {#register_global_shortcut}.
  @global_shortcuts = {}
  # The back buffer components paint into. {#repaint} flushes its diff to
  # the terminal, so only changed cells are emitted (flicker-free on any
  # terminal). Sized to the current viewport; {#layout} resizes it.
  @buffer = Buffer.new(@size)
end

Instance Attribute Details

#buffer ⇒ Buffer (readonly)

@return — the back buffer components paint into (Buffer#set_line / Buffer#fill / Buffer#set_char).

Returns:



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

def buffer
  @buffer
end

#color_scheme ⇒ Symbol (readonly)

@return — :light or :dark

Returns:

  • (Symbol) 


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

def color_scheme
  @color_scheme
end

#event_queue ⇒ EventQueue (readonly)

@return — the event queue.

Returns:



175
176
177
 
# File 'lib/tuile/screen.rb', line 175

def event_queue
  @event_queue
end

#focused ⇒ Component?

@return — currently focused component.

Returns:



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

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.

@return — one-arg callable receiving the StandardError instance.

Returns:

  • (Proc) 


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

def on_error
  @on_error
end

#pane ⇒ ScreenPane (readonly)

@return — the structural root of the component tree.

Returns:



61
62
63
 
# File 'lib/tuile/screen.rb', line 61

def pane
  @pane
end

#size ⇒ Size (readonly)

@return — current screen size.

Returns:



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

def size
  @size
end

#theme ⇒ Theme

The color Theme built-in components read at paint time: the member of #theme_def matching the terminal background detected at construction (see TerminalBackground.detect; inconclusive means dark). While the event loop runs, terminals supporting mode 2031 push OS appearance changes (EventQueue::ColorSchemeEvent) and the screen re-picks from #theme_def.

Returns:



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

def theme
  @theme
end

#theme_def ⇒ ThemeDef

The app's ThemeDef — the dark/light Theme pair the screen picks #theme from, at startup and on every OS appearance flip. Starts as ThemeDef.default (ThemeDef::DEFAULT unless reassigned — tests do, see ThemeDef.default=). Assigning a custom definition is the durable way to theme an app: unlike a bare #theme=, it survives the user toggling the OS appearance.

Returns:



126
127
128
 
# File 'lib/tuile/screen.rb', line 126

def theme_def
  @theme_def
end

Class Method Details

.close ⇒ void

This method returns an undefined value.



459
460
461
 
# File 'lib/tuile/screen.rb', line 459

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:



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

def self.fake = FakeScreen.new

.instance ⇒ Screen

@return — the singleton instance.

Returns:



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

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

  @@instance
end

Instance Method Details

#active_window ⇒ Component?

@return — current active tiled component.

Returns:



400
401
402
403
404
405
 
# File 'lib/tuile/screen.rb', line 400

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

#add_popup(window) ⇒ void

This method returns an undefined value.

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

@param window

Parameters:



279
280
281
282
283
284
 
# File 'lib/tuile/screen.rb', line 279

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



180
181
182
183
184
185
186
 
# File 'lib/tuile/screen.rb', line 180

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.



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

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

#close ⇒ void

This method returns an undefined value.



452
453
454
455
456
 
# File 'lib/tuile/screen.rb', line 452

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

#content ⇒ Component?

@return — tiled content (forwarded to Tuile::ScreenPane).

Returns:



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

def content = @pane.content

#content=(content) ⇒ void

This method returns an undefined value.

@param content

Parameters:



102
103
104
105
 
# File 'lib/tuile/screen.rb', line 102

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:



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

def cursor_position = @focused&.cursor_position

#cursor_sequence ⇒ String

The escape sequence positioning the hardware cursor for the current focus state: hidden when nothing owns it, else moved to the focused component's Component#cursor_position and shown. Appended to each frame's flush.

Returns:

  • (String) 


607
608
609
610
 
# File 'lib/tuile/screen.rb', line 607

def cursor_sequence
  pos = cursor_position
  pos.nil? ? TTY::Cursor.hide : "#{TTY::Cursor.move_to(pos.x, pos.y)}#{TTY::Cursor.show}"
end

#cycle_focus(forward:) ⇒ Boolean

Walks the current modal scope in pre-order, collects tab stops, and advances focus by one (wrapping). When the focused component isn't in the tab order (e.g. focus is parked on a popup/window chrome with no interactable widgets), Tab goes to the first stop and Shift+Tab to the last.

@param forward

@return — true if focus moved.

Parameters:

  • forward: (Boolean)

Returns:

  • (Boolean) 


582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
 
# File 'lib/tuile/screen.rb', line 582

def cycle_focus(forward:)
  check_locked
  scope = @pane.modal_popup || @pane.content
  return false if scope.nil?

  stops = []
  scope.on_tree { |c| stops << c if c.tab_stop? }
  return false if stops.empty?

  idx = @focused.nil? ? nil : stops.index(@focused)
  target = if idx.nil?
             forward ? stops.first : stops.last
           else
             stops[(idx + (forward ? 1 : -1)) % stops.size]
           end
  return false if target.equal?(@focused)

  self.focused = target
  true
end

#detect_scheme ⇒ Symbol

Startup color scheme: :light when TerminalBackground.detect reports a light terminal background, :dark otherwise (including when detection is inconclusive). Runs in the constructor — the OSC 11 reply arrives on stdin, which is only safe to read before EventQueue#start_key_thread owns it. FakeScreen overrides this to pin :dark, keeping specs deterministic and off the test runner's TTY.

@return — :dark or :light.

Returns:

  • (Symbol) 


562
563
564
 
# File 'lib/tuile/screen.rb', line 562

def detect_scheme
  TerminalBackground.detect == :light ? :light : :dark
end

#emit(str) ⇒ void

This method returns an undefined value.

Writes an assembled frame (escape string) to the terminal. The single sink for repaint output; FakeScreen overrides it to capture instead.

@param str

Parameters:

  • str (String) 


616
617
618
619
 
# File 'lib/tuile/screen.rb', line 616

def emit(str)
  $stdout.write(str)
  $stdout.flush
end

#event_loop ⇒ void

This method returns an undefined value.



676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
 
# File 'lib/tuile/screen.rb', line 676

def event_loop
  @event_queue.run_loop do |event|
    case event
    when EventQueue::KeyEvent
      key = event.key
      handled = handle_key(key)
      @event_queue.stop if !handled && ["q", Keys::ESC].include?(key)
    when MouseEvent
      handle_mouse(event)
    when EventQueue::TTYSizeEvent
      @size = event.size
      layout
    when EventQueue::ColorSchemeEvent
      on_color_scheme(event.scheme)
    when EventQueue::EmptyQueueEvent
      repaint
    when Proc
      event.call
    end
  rescue StandardError => e
    @on_error.call(e)
  end
end

#focus_next ⇒ Boolean

Advances focus to the next Component#tab_stop? in tree order, wrapping around. Scope is the topmost popup if one is open, otherwise #content — this keeps Tab confined inside a modal popup. No-op (returns false) if the modal scope has no tab stops or no content at all.

@return — true if focus moved.

Returns:

  • (Boolean) 


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

def focus_next = cycle_focus(forward: true)

#focus_previous ⇒ Boolean

Mirror of #focus_next that walks backwards through the tab order.

@return — true if focus moved.

Returns:

  • (Boolean) 


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

def focus_previous = cycle_focus(forward: false)

#global_shortcut_hints(popup_open:) ⇒ ::Array[String]

Status-bar hints from currently-registered global shortcuts. When a popup is open, only over_popups: true shortcuts contribute — the rest don't fire in that context, so showing them would be a lie. Insertion order is preserved (Hash iteration order).

@param popup_open

Parameters:

  • popup_open: (Boolean)

Returns:

  • (::Array[String]) 


264
265
266
267
268
269
270
271
 
# File 'lib/tuile/screen.rb', line 264

def global_shortcut_hints(popup_open:)
  @global_shortcuts.each_value.filter_map do |s|
    next if s.hint.nil? || s.hint.empty?
    next if popup_open && !s.over_popups

    s.hint
  end
end

#handle_key(key) ⇒ Boolean

A key has been pressed on the keyboard. Handle it, or forward to active window.

Dispatch order:

1. Tab / Shift+Tab — reserved focus navigation, intercepted before
 anything else so a focused {Component::TextField} (which would
 otherwise swallow printable keys via cursor-owner suppression)
 doesn't trap them.
2. App-level shortcuts from {#register_global_shortcut}. An entry
 registered with `over_popups: true` always fires; one with the
 default `over_popups: false` fires only when no modal popup is open
 (otherwise the modal popup receives the key normally). A non-modal
 overlay doesn't suppress global shortcuts.
3. {ScreenPane#handle_key}, which captures a matching {#key_shortcut}
 in the active scope, then delivers the key to {#focused} and bubbles
 it up the focus chain.

@param key

@return — true if the key was handled by some window.

Parameters:

  • key (String)

Returns:

  • (Boolean) 


651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
 
# File 'lib/tuile/screen.rb', line 651

def handle_key(key)
  case key
  when Keys::TAB
    focus_next
    true
  when Keys::SHIFT_TAB
    focus_previous
    true
  else
    shortcut = @global_shortcuts[key]
    if !shortcut.nil? && (shortcut.over_popups || @pane.modal_popup.nil?)
      shortcut.block.call
      true
    else
      @pane.handle_key(key)
    end
  end
end

#handle_mouse(event) ⇒ void

This method returns an undefined value.

Finds target window and calls Component::Window#handle_mouse.

@param event

Parameters:



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

def handle_mouse(event) = @pane.handle_mouse(event)

#has_popup?(window) ⇒ Boolean

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

@param window

@return — true if this popup is currently mounted.

Parameters:

Returns:

  • (Boolean) 


439
440
441
442
 
# File 'lib/tuile/screen.rb', line 439

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.

@param component

Parameters:



198
199
200
201
202
203
 
# File 'lib/tuile/screen.rb', line 198

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

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

#layout ⇒ void

This method returns an undefined value.

Recalculates positions of all windows, and repaints the scene. Automatically called whenever terminal size changes. Call when the app starts. #size provides correct size of the terminal.



625
626
627
628
629
630
631
 
# File 'lib/tuile/screen.rb', line 625

def layout
  check_locked
  @buffer.resize(size) unless @buffer.size == size
  needs_full_repaint
  @pane.rect = Rect.new(0, 0, size.width, size.height)
  repaint
end

#needs_full_repaint ⇒ void

This method returns an undefined value.

Invalidates the entire attached tree, forcing every component to repaint on the next cycle. Needed whenever something overdraws the scene without clipping and then exposes what was underneath — a closing popup (#remove_popup), or a popup that shrinks or moves so its new #rect no longer covers the cells it previously painted (Component::Popup#rect=). The popup-only fast path in #repaint can't clear those vacated cells on its own, so we accept the cost of a full repaint.



431
432
433
 
# File 'lib/tuile/screen.rb', line 431

def needs_full_repaint
  @pane&.on_tree { invalidate _1 }
end

#on_color_scheme(scheme) ⇒ void

This method returns an undefined value.

An OS appearance flip arrived (mode-2031 report): remember the scheme and apply the matching member of #theme_def.

@param scheme — :dark or :light.

Parameters:

  • scheme (Symbol) 


570
571
572
573
 
# File 'lib/tuile/screen.rb', line 570

def on_color_scheme(scheme)
  @color_scheme = scheme
  self.theme = @theme_def.for(@color_scheme)
end

#popups ⇒ ::Array[Component]

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

Returns:



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

def popups = @pane.popups

#print(*args) ⇒ void

This method returns an undefined value.

Writes terminal-housekeeping escapes straight to stdout: #clear, mouse-tracking start/stop, the color-scheme notify toggles, cursor-show on teardown. Component painting does not go through here anymore — it writes into #buffer, which #repaint diffs and #emits. FakeScreen overrides this (and #emit) to capture into @prints instead of the test runner's stdout.

@param args — stuff to print.

Parameters:

  • args (String) 


471
472
473
 
# File 'lib/tuile/screen.rb', line 471

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

#refresh_status_bar ⇒ void

This method returns an undefined value.

Rebuild the status-bar text from the current focus and global-shortcut registry. Called from #focused= and whenever the global registry changes. Popups own their own "q Close" prefix in #keyboard_hint; for the tiled case Screen tacks on the global "q quit" instead. Global-shortcut hints get spliced in too — see #global_shortcut_hints for the over_popups filter rule.



245
246
247
248
249
250
251
252
253
254
 
# File 'lib/tuile/screen.rb', line 245

def refresh_status_bar
  top_popup = @pane.modal_popup
  globals = global_shortcut_hints(popup_open: !top_popup.nil?)
  @pane.status_bar.text = if top_popup.nil?
                            ["q #{@theme.hint("quit")}", *globals,
                             active_window&.keyboard_hint].compact.reject(&:empty?).join("  ")
                          else
                            [*globals, top_popup.keyboard_hint].reject(&:empty?).join("  ")
                          end
end

#register_global_shortcut(key, over_popups: false, hint: nil, &block) ⇒ void

This method returns an undefined value.

Registers an app-level keyboard shortcut. When key arrives, the block is invoked on the event-loop thread (so it may freely mutate UI) before the key reaches any component. Re-registering the same key replaces the previous binding; use #unregister_global_shortcut to remove one.

Only unprintable keys are accepted — control characters (Ctrl+letter, ESC, BACKSPACE, ENTER, …) and multi-character escape sequences (arrows, F-keys, …). Printable keys raise ArgumentError: they'd hijack typing into a Component::TextField and should be expressed as Component#key_shortcut instead, which the dispatcher suppresses while a text widget owns the hardware cursor. TAB and SHIFT_TAB are also rejected because #handle_key intercepts them for focus navigation before the global registry is consulted, so a binding on them would silently never fire.

Pass hint: to surface the shortcut in the status bar. It's a preformatted string the caller fully owns (so colors and the key label style stay consistent with whatever the host app uses elsewhere). The framework splices it in like any other status hint: in the tiled case, right after q quit and before the active window's own hint; while a popup is open, only hints from over_popups: true shortcuts are shown, and they're prepended before the popup's q Close.

Example — open a log popup with Ctrl+L from anywhere, even while a popup is already on screen:

screen.register_global_shortcut(Keys::CTRL_L,
                              over_popups: true,
                              hint: "^L #{screen.theme.hint("log")}") do
log_popup.open
end

@param key — unprintable key (e.g. Keys::CTRL_L, Keys::ESC, Keys::PAGE_UP).

@param over_popups — when true, fires even while a modal popup is open (pre-empting the popup's own key handling). When false (default), the shortcut is suppressed while any popup is open and the popup gets the key instead.

@param hint — preformatted status-bar hint (e.g. "^L #{screen.theme.hint("log")}"). When nil (default) the shortcut is silent in the status bar. The colors are baked into the string, so a later #theme= does not restyle it — re-register if needed.

Parameters:

  • key (String)
  • over_popups: (Boolean) (defaults to: false)
  • hint: (String, nil) (defaults to: nil) 


370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/tuile/screen.rb', line 370

def register_global_shortcut(key, over_popups: false, hint: nil, &block)
  raise ArgumentError, "block required" if block.nil?
  raise ArgumentError, "key must be a String, got #{key.inspect}" unless key.is_a?(String)
  raise ArgumentError, "key cannot be empty" if key.empty?
  if Keys.printable?(key)
    raise ArgumentError,
          "global shortcut key must be unprintable; got #{key.inspect}. " \
          "Use Component#key_shortcut for printable keys (it's suppressed " \
          "while a text widget owns the cursor, so it won't hijack typing)."
  end
  if [Keys::TAB, Keys::SHIFT_TAB].include?(key)
    raise ArgumentError,
          "#{key == Keys::TAB ? "TAB" : "SHIFT_TAB"} is reserved for focus navigation"
  end
  raise ArgumentError, "hint must be a String or nil, got #{hint.inspect}" unless hint.nil? || hint.is_a?(String)

  @global_shortcuts[key] = Shortcut.new(block: block, over_popups: over_popups, hint: hint)
  refresh_status_bar
end

#remove_popup(window) ⇒ void

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.

@param window

Parameters:



414
415
416
417
418
419
420
 
# File 'lib/tuile/screen.rb', line 414

def remove_popup(window)
  check_locked
  return unless @pane.has_popup?(window)

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



478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
 
# File 'lib/tuile/screen.rb', line 478

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?
    # Defensive filter: a component can become detached between enqueue
    # and drain (popup close, sibling removed mid-event-handling, focus
    # repair). Detached components have no place on the screen and must
    # never paint, even though Component#invalidate already gates them
    # out — this catches the case where attachment changed since.
    @invalidated.delete_if { |c| !c.attached? }
    break if @invalidated.empty?

    did_paint = true
    popups = @pane.popups

    # Build the repaint list in z-order, leaning on the tree itself rather
    # than a depth sort. The pane's pre-order traversal already orders the
    # tiled layer (content subtree + status bar) parent-before-child; the
    # popups are the top layer and must paint last. The status bar is a
    # *late* pane child yet sits under the popups, so a single pane.on_tree
    # walk won't do — we collect the tiled layer first, then append popups.
    popup_members = Set.new
    popups.each { |p| p.on_tree { popup_members << _1 } }

    # Tiled layer: invalidated non-popup components, in tree order.
    repaint = []
    tiled_invalidated = false
    @pane.on_tree do |c|
      next if popup_members.include?(c)
      next unless @invalidated.include?(c)

      repaint << c
      tiled_invalidated = true
    end

    # Popups on top: the whole stack when a tiled repaint may have clobbered
    # cells they share in the buffer, else just the invalidated popup
    # components. Overdraw into the buffer is free (only net-visible cell
    # changes reach the terminal), so reasserting the stack is cheap.
    popups.each do |p|
      p.on_tree { |c| repaint << c if tiled_invalidated || @invalidated.include?(c) }
    end

    @repainting = repaint.to_set
    @invalidated.clear

    # Components write into @buffer; overdraw is free and correct here
    # because the buffer only diffs net-visible changes to the terminal.
    repaint.each(&:repaint)

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

  # Flush only the changed cells, then reposition the cursor — all inside
  # one synchronized-output batch so the terminal composites it atomically.
  emit("#{Ansi::SYNC_BEGIN}#{@buffer.flush}#{cursor_sequence}#{Ansi::SYNC_END}")
end

#run_event_loop(capture_mouse: true) ⇒ 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.

@param capture_mouse — when true (default), enables xterm mouse tracking so clicks and scroll wheel arrive as MouseEvents and feed Component#handle_mouse. When false, no tracking escape sequence is written: the terminal keeps its native click handling, which is what you want if the app benefits more from select-to-copy than from click-to-focus. Components' handle_mouse is simply never invoked from the loop in that mode (the terminal stops sending the bytes).

Parameters:

  • capture_mouse: (Boolean) (defaults to: true) 


297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/tuile/screen.rb', line 297

def run_event_loop(capture_mouse: true)
  @pretend_ui_lock = false
  $stdin.echo = false
  print MouseEvent.start_tracking if capture_mouse
  # Follow OS light/dark flips live: terminals supporting mode 2031
  # push color-scheme reports that the key thread turns into
  # {EventQueue::ColorSchemeEvent}s.
  print TerminalBackground::NOTIFY_ON
  $stdin.raw do
    event_loop
  end
ensure
  print TerminalBackground::NOTIFY_OFF
  print MouseEvent.stop_tracking if capture_mouse
  print TTY::Cursor.show
  $stdin.echo = true
end

#unregister_global_shortcut(key) ⇒ void

This method returns an undefined value.

Removes a shortcut previously installed by #register_global_shortcut. No-op if key was not registered.

@param key

Parameters:

  • key (String) 


394
395
396
397
 
# File 'lib/tuile/screen.rb', line 394

def unregister_global_shortcut(key)
  @global_shortcuts.delete(key)
  refresh_status_bar
end