Teek API Documentation

Teek::UI::ModalStack Class

Push/pop stack for modal window handles, so one modal can push another (e.g. Settings -> Replay Player) with the previous modal automatically re-shown once the new one is dismissed.

The reveal/conceal-on-transition bookkeeping - including on-demand Handle#realize! of a not-yet-realized lazy: true modal, given document: (a “child window” opened fresh each time, say) - is exactly what Screens already does, so this wraps one internally rather than re-deriving it. What’s actually different here is the on_enter/on_exit/on_focus_change lifecycle, useful for pause/resume- style hooks (e.g. pausing an emulator while any modal is open). Each window handle pushed here should typically be declared modal: true (as ui.dialog already defaults to) for Handle#show to actually grab input - ModalStack itself does no grabbing of its own.

Inherits: Object

Instance Methods ↑

active?

Returns Boolean — true if any modal is open

View source ▼ 
def active?
  @screens.active?
end
GitHub

current

Returns Symbol, nil — name of the topmost modal

View source ▼ 
def current
  @screens.current
end
GitHub

initialize(on_enter:, on_exit:, on_focus_change: nil, document: nil)

Parameters
  • on_enter Proc — called with (name) when the stack goes empty -> non-empty
  • on_exit Proc — called with no arguments when the stack goes non-empty -> empty
  • on_focus_change Proc, nil — called with (name) whenever the top modal changes - every push, and every pop that leaves a modal underneath (not the final pop, which fires on_exit instead)
  • document Document, nil — forwarded to the internal Screens - see Screens#initialize - needed only to lazily Handle#realize! a not-yet-realized modal on push

Returns ModalStack — a new instance of ModalStack

View source ▼ 
def initialize(on_enter:, on_exit:, on_focus_change: nil, document: nil)
  @screens = Screens.new(document: document)
  @on_enter = on_enter
  @on_exit = on_exit
  @on_focus_change = on_focus_change
end
GitHub

pop

Pop the current modal off the stack. If a modal remains underneath, it’s re-shown (by Screens#pop) and on_focus_change fires for it; otherwise the stack is now empty and on_exit fires instead.

Returns Object, nil — the just-popped window, or nil if the stack was empty

View source ▼ 
def pop
  return nil unless @screens.active?

  popped = @screens.pop

  if @screens.active?
    @on_focus_change&.call(@screens.current)
  else
    @on_exit.call
  end
  popped
end
GitHub

push(name, window)

Push a modal window handle onto the stack. Whatever was on top (if any) is withdrawn first, with no callback of its own - it’s stepping aside, not being dismissed. on_enter fires only if the stack was empty; on_focus_change fires unconditionally.

Parameters
  • name Symbol
  • window Handle — a `:window` handle

Returns void

View source ▼ 
def push(name, window)
  was_empty = !@screens.active?

  @screens.push(name, window)

  @on_enter.call(name) if was_empty
  @on_focus_change&.call(name)
  nil
end
GitHub

size

Returns Integer — number of modals on the stack

View source ▼ 
def size
  @screens.size
end
GitHub