NAME

Selkie::ScreenManager - Named multi-screen management

SYNOPSIS

You rarely use ScreenManager directly — Selkie::App's add-screen and switch-screen methods forward to its add-screen and switch-to methods (the App-level name is switch-screen; the ScreenManager-level name is switch-to). When you do need the underlying object directly (e.g. to enumerate screen names), reach it via $app.screen-manager:

my $sm = $app.screen-manager;

say $sm.active-screen;           # 'main'
say $sm.screen-names;            # ('login', 'main', 'settings')

# Route a keybind based on the active screen
$app.on-key('ctrl+n', -> $ {
    given $app.screen-manager.active-screen {
        when 'tasks' { create-task }
        when 'notes' { create-note }
    }
});

DESCRIPTION

A tiny registry mapping screen names to root containers, with one marked as active at a time. Selkie::App uses it to park inactive screens off-screen while preserving their state.

Switching screens is fast — the inactive roots remain fully built, just repositioned off-screen. Their widgets keep their state (text input buffers, scroll positions, cursor positions) until the screen is reactivated.

EXAMPLES

Checking before registering

unless $app.screen-manager.has-screen('settings') {
    $app.add-screen('settings', build-settings-screen());
}

Cleanup

Remove a screen you no longer need (e.g. after logout). Attempting to remove the active screen throws:

$app.switch-screen('login');
$app.screen-manager.remove-screen('main');

SEE ALSO

• Selkie::App — wraps ScreenManager with higher-level conveniences

method add-screen

method add-screen(
    Str:D $name,
    Selkie::Container $root
) returns Mu

Register a screen under a name. If this is the first screen added, it automatically becomes active. Subsequent screens join the registry but the active screen is unchanged. Idempotent by name: re-adding the same name overwrites the previous root.

method remove-screen

method remove-screen(
    Str:D $name
) returns Mu

Remove a registered screen by name. Fails if the screen is currently active — switch to another screen first. Destroys the screen's root widget tree.

method switch-to

method switch-to(
    Str:D $name
) returns Mu

Make the named screen active. Marks its root dirty so it re-renders. Fails if no screen with that name exists.

method active-screen

method active-screen() returns Str

The name of the currently active screen, or Nil if no screens are registered.

method active-root

method active-root() returns Selkie::Container

The root container of the currently active screen, or the type object Selkie::Container if no screen is active.

method screen-names

method screen-names() returns List

Sorted list of registered screen names.

method screen

method screen(
    Str:D $name
) returns Selkie::Container

Look up a registered screen's root widget by name. Returns the Container type object if no screen with that name exists.

method has-screen

method has-screen(
    Str:D $name
) returns Bool

True if a screen with the given name is registered.

method focusable-descendants

method focusable-descendants() returns Seq

Focusable descendants of the active screen's root. Used by Selkie::App to build the Tab cycle.

method handle-resize

method handle-resize(
    Int $rows where { ... },
    Int $cols where { ... }
) returns Mu

Propagate a terminal resize to every registered screen, not just the active one. Without this, switching to an inactive screen after a resize would render at stale dimensions until a re-layout happens to fire. Each screen's root is a Container, so its handle-resize cascades through its subtree synchronously.

method destroy

method destroy() returns Mu

Destroy every registered screen and clear the active screen reference. Called automatically by Selkie::App.shutdown.