Class: Teek::UI::Screens

Inherits:
Object
  • Object
show all
Defined in:
lib/teek/ui/screens.rb

Overview

Push/pop stack for content screens - works directly against ordinary DSL handles (a ui.panel/ui.box, or a ui.window) instead of requiring a bespoke per-screen class with its own show/hide/cleanup protocol. Pushing conceals the current screen (if any) before revealing the new one; popping reverses it, re-revealing whatever is now on top.

A :window handle is revealed/concealed through its own Handle#show/ Handle#hide (deiconify/raise/modal, or grab-release/withdraw); anything else is packed to fill its parent, or pack-forgotten via the plain pack/pack forget primitive.

A screen being pushed/replaced-in can also be a lazy: true node that hasn't been realized yet (see WidgetDSL#append_container) - it's realized on demand, right before being revealed, with nothing extra to call by hand, as long as this stack was constructed with document:. A screen with no opinion on laziness at all (any plain object exposing just type/path/app or type/show/hide, the original "push an already-built Handle" usage) behaves exactly as before either way. Concealing never destroys a screen's widget - see Handle#destroy! for that as a separate, explicit step (typically screens.pop&.destroy!).

Examples:

ui.screens.push(:picker, ui[:picker])
ui.screens.push(:emulator, ui[:emulator])   # picker concealed
ui.screens.pop                              # emulator concealed, picker revealed
ui.screens.replace_current(ui[:emulator])   # in-place swap, same stack depth

Defined Under Namespace

Classes: Entry

Instance Method Summary collapse

Constructor Details

#initialize(document: nil) ⇒ Screens

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.

Returns a new instance of Screens.

Parameters:

  • document (Document, nil) (defaults to: nil) —

    needed only to lazily Handle#realize! a not-yet-realized screen on push - omit if every screen pushed onto this stack is already realized



40
41
42
43
 
# File 'lib/teek/ui/screens.rb', line 40

def initialize(document: nil)
  @stack = []
  @document = document
end

Instance Method Details

#active? ⇒ Boolean

Returns true if any screen is on the stack.

Returns:

  • (Boolean) —

    true if any screen is on the stack



46
47
48
 
# File 'lib/teek/ui/screens.rb', line 46

def active?
  !@stack.empty?
end

#current ⇒ Symbol?

Returns name of the topmost screen.

Returns:

  • (Symbol, nil) —

    name of the topmost screen



51
52
53
 
# File 'lib/teek/ui/screens.rb', line 51

def current
  @stack.last&.name
end

#current_screen ⇒ Handle?

Returns the topmost screen's handle.

Returns:

  • (Handle, nil) —

    the topmost screen's handle



56
57
58
 
# File 'lib/teek/ui/screens.rb', line 56

def current_screen
  @stack.last&.screen
end

#pop ⇒ Object?

Pop the current screen off the stack. The popped screen is concealed (never destroyed - see Handle#destroy! to additionally release it); if a screen remains underneath, it's revealed again.

Returns:

  • (Object, nil) —

    the just-popped screen, or nil if the stack was empty



97
98
99
100
101
102
 
# File 'lib/teek/ui/screens.rb', line 97

def pop
  entry = @stack.pop or return nil
  conceal(entry.screen)
  reveal(@stack.last.screen) if @stack.last
  entry.screen
end

#push(name, screen) ⇒ void

This method returns an undefined value.

Push a screen onto the stack. The previous screen (if any) is concealed before the new one is realized (if it isn't already) and revealed.

Parameters:

  • name (Symbol) —

    identifier (e.g. :picker, :emulator)

  • screen (Handle) —

    a :window handle, or any other container/widget handle



71
72
73
74
75
76
77
 
# File 'lib/teek/ui/screens.rb', line 71

def push(name, screen)
  conceal(@stack.last.screen) if @stack.last
  @stack.push(Entry.new(name: name, screen: screen))
  ensure_realized(screen)
  reveal(screen)
  nil
end

#replace_current(screen) ⇒ void

This method returns an undefined value.

Replace the current screen in-place, without changing stack depth - the existing screen is concealed, the new one takes its name, realizes if needed, and is revealed.

Parameters:



84
85
86
87
88
89
90
91
 
# File 'lib/teek/ui/screens.rb', line 84

def replace_current(screen)
  entry = @stack.last or return
  conceal(entry.screen)
  @stack[-1] = Entry.new(name: entry.name, screen: screen)
  ensure_realized(screen)
  reveal(screen)
  nil
end

#size ⇒ Integer

Returns number of screens on the stack.

Returns:

  • (Integer) —

    number of screens on the stack



61
62
63
 
# File 'lib/teek/ui/screens.rb', line 61

def size
  @stack.length
end