Screen

Phui\Screen configures the terminal and runs the render loop. Every setter returns the screen, so calls chain.

Mounting and running

static mount(Component|string $component): static

Creates a screen with $component as the root of the tree.

Screen::mount(App::class)->run();

run(
    int $targetFps = 60,
    bool $installErrorHandler = true,
): mixed

Runs the loop until the app completes or quits, and returns the value passed to complete().

start(bool $installErrorHandler = true): static

Takes over the terminal without entering a loop, for driving frames yourself.

frame(): bool

Processes input and renders one frame. Returns whether the app is still running.

stop(): void

Restores the terminal and ends the run.

Terminal options

mouse(
    bool $enabled = true,
    MouseTracking $tracking = MouseTracking::DRAG,
): static

Sets mouse reporting and how much movement is tracked.

focusTracking(bool $enabled = true): static

Sets whether the terminal reports window focus changes as a FocusEvent.

bracketedPaste(bool $enabled = true): static

Sets whether pastes arrive as a single PasteEvent rather than as keypresses.

cursor(bool $visible = true): static

Sets whether the terminal cursor is shown.

inline(int $height = 15): static

Renders into a region of $height rows in the current terminal rather than taking over the whole screen.

captureOutput(bool $enabled = true): static

Sets whether output written outside the renderer is captured and reported as a StrayOutputEvent.

colours(ColourMode $mode): static

Forces a ColourMode instead of detecting one.

Application setup

theme(Theme $theme): static

Sets the active Theme.

service(string $class, object $instance): static

Registers a service, retrieved in a component with get().

bindings(
    ?Binding $focusNext = null,
    ?Binding $focusPrevious = null,
    ?Binding $toggleDebug = null,
    ?Binding $quit = null,
): static

Replaces the framework bindings. A null entry keeps the default.

debug(bool $enabled = true): static

Sets whether the debug bar is available.

backend(Backend $backend): static
clock(Clock $clock): static

Replace the terminal backend and the clock, used by testing.

Exceptions

Classes in the Phui\Exceptions namespace, all extending RuntimeException.

CompleteException(
    public readonly mixed $value = null,
)

Thrown by complete() to end the run. Caught by the runtime, which returns $value from run().

QuitException

Thrown to end the run without a value.

NotATerminalException

Thrown when the process is not attached to a terminal.

static MissingServiceException::for(string $class): self

Thrown by get() when no service is registered under $class.

static MissingColoursException::for(string $class): self

Thrown by resolve() when a colours class has no static for() factory.