Program

Program is the entry point for every TUI4J application. It owns the terminal, starts the event loop, and drives the Model/Update/View cycle until a QuitMessage is received.

Basic usage

Implement Model

Write a class that implements the Model interface with init(), update(), and view(). See The Elm Architecture for details.

Instantiate Program

Pass your model to the Program constructor.

Program program = new Program(new MyModel());

Run the event loop

Call run(). This blocks the calling thread, puts the terminal into raw mode, and begins processing events.

program.run();

Putting it together:

import com.williamcallahan.tui4j.compat.bubbletea.Program;

public class Main {
    public static void main(String[] args) {
        new Program(new MyModel()).run();
    }
}

Getting the final model state

run() returns void. If you need to inspect the model after the program exits — for example, to read a value the user entered — use runWithFinalModel() instead.

import com.williamcallahan.tui4j.compat.bubbletea.Model;
import com.williamcallahan.tui4j.compat.bubbletea.Program;

MyModel initial = new MyModel();
Program program = new Program(initial);

Model finalModel = program.runWithFinalModel();
MyModel result = (MyModel) finalModel;

System.out.println("You chose: " + result.getChoice());

runWithFinalModel() is a tui4j extension with no equivalent in Bubble Tea. In Go the idiomatic approach is to read state from a shared pointer; in Java, accessing the typed final model is usually cleaner.

ProgramOptions

Pass one or more ProgramOption values to the constructor to configure the program at startup.

import static com.williamcallahan.tui4j.compat.bubbletea.ProgramOption.*;

Program program = new Program(
    new MyModel(),
    withAltScreen(),
    withMouseCellMotion()
);
program.run();

The following options are available:

Option	Description
`withAltScreen()`	Use the alternate screen buffer — clears the terminal on start and restores it on exit.
`withMouseCellMotion()`	Enable mouse tracking for cell-level motion events.
`withMouseAllMotion()`	Enable mouse tracking for all motion events, including hover.
`withReportFocus()`	Enable `FocusMessage` / `BlurMessage` when the terminal window gains or loses focus.
`withoutBracketedPaste()`	Disable bracketed paste mode.
`withoutRenderer()`	Disable the built-in renderer (useful when writing output manually).
`withoutSignalHandler()`	Disable the default SIGTERM/SIGINT handler.
`withFilter(fn)`	Intercept every message before it reaches `update`.
`withFps(n)`	Set the target render frame rate.
`withInput(stream)`	Override the input stream (useful for testing).
`withOutput(stream)`	Override the output stream (useful for testing).
`withContext(future)`	Cancel the program when the given `CompletableFuture` completes.

The common options also exist as fluent methods directly on Program:

Program program = new Program(new MyModel())
    .withAltScreen()
    .withReportFocus()
    .withMouseAllMotion()
    .withKittyKeyboard(); // Kitty keyboard protocol
program.run();

Use withAltScreen() for full-screen applications so the terminal is restored cleanly on exit. Omit it for programs that print output that should remain visible after the TUI exits.

Sending messages from background threads

Use Program.send(Message) to inject a message into the running event loop from any thread. This is useful for pushing events from background goroutines — HTTP responses, file watchers, timers managed outside the command system, etc.

Program program = new Program(new MyModel());

// Kick off a background task that sends a message when done.
Thread.ofVirtual().start(() -> {
    String data = fetchFromApi();
    program.send(new DataLoadedMessage(data));
});

program.run();

send() enqueues the message asynchronously. Do not call it before run() has been called or after the program has exited.

Waiting for initialization

If you need to wait until init() has completed before proceeding (for example in tests), use waitForInit():

Program program = new Program(new MyModel());
Thread.ofVirtual().start(program::run);
program.waitForInit();
// model is now fully initialized

Checking program state

program.isRunning(); // true while the event loop is active

The Elm Architecture

How Model, Update, and View fit together.

Messages and commands

All built-in messages and how to create custom ones.

Get Started

Core Concepts

Components

Guides

Compatibility

Basic usage

Getting the final model state

ProgramOptions

Sending messages from background threads

Waiting for initialization

Checking program state

The Elm Architecture

Messages and commands

​Basic usage

​Getting the final model state

​ProgramOptions

​Sending messages from background threads

​Waiting for initialization

​Checking program state

The Elm Architecture

Messages and commands

Basic usage

Getting the final model state

ProgramOptions

Sending messages from background threads

Waiting for initialization

Checking program state