Class: Tuile::Component::Popup

Inherits:
Component
  • Object
show all
Includes:
HasContent
Defined in:
lib/tuile/component/popup.rb,
sig/tuile.rbs

Overview

An overlay that wraps any Tuile::Component as its content. Popup itself paints nothing — it's a transparent host that handles its lifecycle (#open / #close / #open?, ESC/q to close) and holds a top-down #size the Screen applies.

The popup does not size itself to its content. Its box is declared by #size — a Fraction (resolved against the screen every layout pass, so it tracks resize) or an absolute Size (clamped to the screen). The default is Fraction::HALF: half the screen, centered. The wrapped content then fills that box and handles its own overflow by wrapping and scrolling, so use content that can — a TextView or TextArea — for anything longer than fits. A Label only truncates.

Modal by default: it centers on the screen, grabs focus, eats keys, and blocks clicks beneath it. Pass modal: false for a non-modal overlay that floats above the content without taking focus or capturing input — the caller positions it (via #rect=), sizes it, and drives it from app code. That's the building block for an autocomplete/slash-command list anchored to a text field's caret: typing keeps focus in the input while the caller refills and drives the overlay.

The wrapped content fills the popup's full #rect; if you want a frame and caption, wrap a Window (or any subclass — including LogWindow) and let it draw its own border:

window = Component::Window.new("Help")
window.content = Component::List.new.tap { _1.lines = lines }
Component::Popup.new(content: window).open

Bare content also works (a Label, a List…), in which case the popup is borderless.

q and ESC close the popup — handled here, at the top of the popup's own subtree, so the key only arrives after every component on the focus chain declined it (see ScreenPane#handle_key). That's why typing q into a nested TextField doesn't dismiss the popup: the field consumes it first.

Direct Known Subclasses

ListDropdown, Notification

Instance Attribute Summary collapse

Attributes included from HasContent

#content

Instance Method Summary collapse

Constructor Details

#initialize(content: nil, modal: true, size: Fraction::HALF) ⇒ Popup

@param content — initial content; can be set later via HasContent#content=. The content fills the popup's Tuile::Component#rect; it does not determine the popup's size.

@param modal — true (default) for a centered, focus-grabbing, input-capturing modal; false for a non-modal overlay the caller positions and drives (see the class docs).

@param size — the popup's size, applied top-down. A Fraction is resolved against the screen each layout pass; a Size is clamped to the screen. Defaults to Fraction::HALF.

Parameters:

  • content: (Component, nil) (defaults to: nil)
  • modal: (Boolean) (defaults to: true)
  • size: (Size, Fraction) (defaults to: Fraction::HALF) 


55
56
57
58
59
60
61
62
 
# File 'lib/tuile/component/popup.rb', line 55

def initialize(content: nil, modal: true, size: Fraction::HALF)
  super()
  @modal = modal
  @size = size
  @content = nil
  self.content = content unless content.nil?
  reposition
end

Instance Attribute Details

#size ⇒ Size, Fraction

@return — the popup's declared size. See #size=.

Returns:



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

def size
  @size
end

Instance Method Details

#center ⇒ void

This method returns an undefined value.

Recenters the popup on the screen, preserving its current width/height.



146
147
148
 
# File 'lib/tuile/component/popup.rb', line 146

def center
  self.rect = rect.centered(screen.size)
end

#close ⇒ void

This method returns an undefined value.

Removes this popup from the Screen. No-op if not currently open.



116
117
118
 
# File 'lib/tuile/component/popup.rb', line 116

def close
  screen.remove_popup(self)
end

#focusable? ⇒ Boolean

Returns:

  • (Boolean) 


70
 
# File 'lib/tuile/component/popup.rb', line 70

def focusable? = true

#handle_key(key) ⇒ Boolean

q and ESC close the popup. The popup sits on the focus chain of whatever it wraps, so the key reaches here by bubbling up from the focused content after that content declined to handle it.

@param key

@return — true if the key was handled.

Parameters:

  • key (String)

Returns:

  • (Boolean) 


163
164
165
166
167
168
169
170
 
# File 'lib/tuile/component/popup.rb', line 163

def handle_key(key)
  if [Keys::ESC, "q"].include?(key)
    close
    true
  else
    false
  end
end

#handle_mouse ⇒ void

This method returns an undefined value.

@param event

Parameters:



2202
 
# File 'sig/tuile.rbs', line 2202

def handle_mouse: (MouseEvent event) -> void

#keyboard_hint ⇒ String

Hint for the status bar: own "q Close" plus the wrapped content's hint.

Returns:

  • (String) 


152
153
154
155
156
 
# File 'lib/tuile/component/popup.rb', line 152

def keyboard_hint
  prefix = "q #{screen.theme.hint("Close")}"
  child_hint = @content&.keyboard_hint.to_s
  child_hint.empty? ? prefix : "#{prefix}  #{child_hint}"
end

#layout(content) ⇒ void

This method returns an undefined value.

Content fills the popup's full rect — Popup has no border to subtract.

@param content

Parameters:



177
178
179
 
# File 'lib/tuile/component/popup.rb', line 177

def layout(content)
  content.rect = rect
end

#modal? ⇒ Boolean

@return — whether this popup is modal. See #initialize.

Returns:

  • (Boolean) 


68
 
# File 'lib/tuile/component/popup.rb', line 68

def modal? = @modal

#on_focus ⇒ void

This method returns an undefined value.



2204
 
# File 'sig/tuile.rbs', line 2204

def on_focus: () -> void

#open ⇒ self

Mounts this popup on the Screen, re-resolving its #size against the current screen first.

popup = Component::Popup.new(content: window).open   # construct and mount

There is deliberately no class-level Popup.open factory — see DECISIONS.md D-popup-open; returning self is what keeps the one-liner above available without one.

Returns:

  • (self) 


108
109
110
111
112
 
# File 'lib/tuile/component/popup.rb', line 108

def open
  reposition
  screen.add_popup(self)
  self
end

#open? ⇒ Boolean

@return — true if this popup is currently mounted on the screen.

Returns:

  • (Boolean) 


121
122
123
 
# File 'lib/tuile/component/popup.rb', line 121

def open?
  screen.has_popup?(self)
end

#rect=(new_rect) ⇒ void

This method returns an undefined value.

Reassigns the popup's rect, escalating to a full scene repaint when an open popup shrinks or moves so its new rect no longer covers the cells it previously painted. A popup overdraws the scene without clipping and nothing clears underneath it, so Screen#repaint's popup-only fast path would repaint into the new rect and leave the vacated cells showing stale content. When the new rect fully covers the old one (the popup only grew), the fast path is correct and the full repaint is skipped.

@param new_rect

Parameters:



93
94
95
96
97
 
# File 'lib/tuile/component/popup.rb', line 93

def rect=(new_rect)
  old_rect = rect
  super
  screen.needs_full_repaint if open? && !new_rect.contains_rect?(old_rect)
end

#reposition ⇒ void

This method returns an undefined value.

Re-resolves #size against the current screen and repositions the popup itself (this is not laying out content — the popup's own rect): a modal popup recenters; a non-modal overlay keeps its caller-assigned top-left (only its size follows the screen). Called on #open, on #size=, and by the screen's layout pass (so a Fraction size tracks SIGWINCH).

The final rect is computed and assigned in one step rather than sizing at the origin and then centering: the intermediate origin rect rarely covers the previous one, which would make #rect='s shrink/move detection fire a full repaint on every resize.



137
138
139
140
141
142
 
# File 'lib/tuile/component/popup.rb', line 137

def reposition
  size = @size.is_a?(Fraction) ? @size.resolve(screen.size) : @size.clamp(screen.size)
  r = Rect.new(rect.left, rect.top, size.width, size.height)
  r = r.centered(screen.size) if modal?
  self.rect = r
end