Documentation
¶
Overview ¶
Package screen defines a richer navigation model for pkg/app. A Screen owns its own layout tree, lifecycle, help bindings, and (optionally) a focus signal so the surrounding app shell can route global keys correctly.
The Stack manages push/pop with result passing: a child can Pop with a value, and the parent's OnEnter receives it. This makes drilldown flows ("pick something, come back with the pick") trivially composable.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Pop ¶
Pop returns a command that pops the current screen, passing result to whatever screen is uncovered. Pass nil to indicate "no result / cancel".
func Replace ¶
Replace returns a command that swaps the active screen with s. The previous top is discarded and s.Init + s.OnEnter(nil) run, exactly as if it had just been pushed. The screen below is not notified (no OnEnter fires on it), so this is the right tool for a "fresh instance" of the current view (reset filter, reset scroll, refetch from scratch) without the visible flicker or accidental parent-side-effect that pop+push would cause. Pass the new screen with its theme already applied — Replace does not call SetTheme, matching Push's convention.
On a single-screen stack (only the root), Replace swaps the root.
Types ¶
type PopMsg ¶
type PopMsg struct{ Result any }
PopMsg is emitted by Pop; the Stack handles it. Result is delivered to the newly-active screen's OnEnter.
type PushMsg ¶
type PushMsg struct{ Screen Screen }
PushMsg is emitted by Push; the Stack handles it.
type ReplaceMsg ¶
type ReplaceMsg struct{ Screen Screen }
ReplaceMsg is emitted by Replace; the Stack handles it by swapping the active (top) screen with Screen. The previous top is discarded; the screen below it is left undisturbed (no OnEnter fires on it).
type Screen ¶
type Screen interface {
// Title labels the screen in the breadcrumb trail. Free to change over
// the screen's lifetime (e.g., after an item is selected).
Title() string
// Init runs once when the screen is first constructed. Rarely non-nil.
Init() tea.Cmd
// Update handles a single tea.Msg. Return the screen (same pointer for
// pointer-receiver implementations) and any follow-up command.
Update(msg tea.Msg) (Screen, tea.Cmd)
// Layout returns a layout tree. The app shell renders this inside the
// body rect — the screen never sees the breadcrumb/statusbar chrome.
Layout() layout.Node
// Help returns the bindings shown inline in the statusbar footer.
Help() []key.Binding
// OnEnter runs each time the screen becomes the active top of the stack.
// - On the initial push: result == nil
// - When a child popped with a value: result == that value
// Return a tea.Cmd for any activation work (e.g. kick off a fetch).
OnEnter(result any) tea.Cmd
// SetTheme is called when the app swaps themes. Rebuild themed widgets
// here, preserving state through accessors/setters (Cursor, Value, …).
SetTheme(t theme.Theme)
// IsCapturingKeys reports whether an embedded input (filter, textinput,
// …) currently owns the keyboard. The app shell suppresses its global
// keys (quit, theme-swap, …) while this is true.
IsCapturingKeys() bool
}
Screen is the unit the Stack manages. Implementations are typically pointer types so Update/OnEnter/SetTheme can mutate local state.
type Stack ¶
type Stack struct {
// contains filtered or unexported fields
}
Stack is the push/pop navigation stack. The last element is active.
func (Stack) Init ¶
Init returns the root screen's Init + OnEnter(nil), to be run by the surrounding program.
Source Files