Messages and commands

TUI4J uses two complementary types to drive the event loop: messages represent things that have happened (key pressed, timer fired, data loaded), and commands represent things that should happen next (start a timer, quit, fetch data).

Messages

Message is a marker interface with no methods. Any class or record that implements it can be delivered to update.

public interface Message {}

The runtime produces built-in messages automatically. You can also define your own.

KeyPressMessage

Delivered for every key press. Use key() to get the string representation.

@Override
public UpdateResult<? extends Model> update(Message msg) {
    if (msg instanceof KeyPressMessage kp) {
        return switch (kp.key()) {
            case "k", "up"    -> UpdateResult.from(moveUp());
            case "j", "down"  -> UpdateResult.from(moveDown());
            case "enter"      -> UpdateResult.from(makeChoice(), QuitMessage::new);
            case "q", "Q"     -> UpdateResult.from(this, QuitMessage::new);
            case "ctrl+c"     -> UpdateResult.from(this, QuitMessage::new);
            default           -> UpdateResult.from(this);
        };
    }
    return UpdateResult.from(this);
}

Common key strings:

Input	`key()` value
Letter keys	`"a"`, `"b"`, … `"z"`
Arrow keys	`"up"`, `"down"`, `"left"`, `"right"`
Enter	`"enter"`
Escape	`"esc"`
Tab	`"tab"`
Space	`" "`
Ctrl combos	`"ctrl+c"`, `"ctrl+z"`, `"ctrl+d"`
Shift variants	`"K"`, `"J"` (uppercase letter)
Alt combos	check `kp.alt()`

KeyPressMessage also provides type() (KeyType) and runes() for lower-level access.

WindowSizeMessage

Sent at startup and whenever the terminal is resized.

if (msg instanceof WindowSizeMessage ws) {
    int width  = ws.width();
    int height = ws.height();
    // store dimensions in model for layout calculations
    return UpdateResult.from(new MyModel(width, height));
}

Store the window size in your model so that view() can produce layouts that fill the terminal correctly, especially when using Join.joinHorizontal or Style.width().

FocusMessage and BlurMessage

Delivered when the terminal window gains or loses focus. Requires ProgramOption.withReportFocus().

if (msg instanceof FocusMessage) {
    return UpdateResult.from(withFocused(true));
}
if (msg instanceof BlurMessage) {
    return UpdateResult.from(withFocused(false));
}

QuitMessage

A special message that causes the program to exit cleanly after the current frame is rendered. You normally produce it via a Command rather than returning it directly from update.

// Quit immediately when "q" is pressed:
case "q" -> UpdateResult.from(this, QuitMessage::new);

// Or use the Command factory:
case "q" -> UpdateResult.from(this, Command.quit());

Custom messages

Implement Message on any class or Java record. Records are the most concise option:

// A message carrying loaded data
public record DataLoadedMessage(String data) implements Message {}

// A simple flag message
public record TickMessage() implements Message {}

// A message signalling an error
public record ErrorMessage(Exception cause) implements Message {}

Handle them with pattern matching in update:

if (msg instanceof DataLoadedMessage loaded) {
    return UpdateResult.from(withData(loaded.data()));
}
if (msg instanceof ErrorMessage err) {
    return UpdateResult.from(withError(err.cause().getMessage()));
}

Commands

Command is a functional interface that returns a Message when executed.

@FunctionalInterface
public interface Command {
    Message execute();
}

The runtime runs each command on a background thread and delivers the resulting Message back into the event loop. Commands should not update model state directly.

Returning a command from update

// Return a quit command paired with the unchanged model:
return UpdateResult.from(this, QuitMessage::new);

// Return a custom async command:
return UpdateResult.from(this, () -> {
    String result = expensiveOperation();
    return new DataLoadedMessage(result);
});

Built-in command factories

Command provides static factory methods for common operations:

Command.quit();                        // Send QuitMessage
Command.println("text");               // Print a line above the TUI
Command.printf("loaded %d items", n);  // Formatted print
Command.setWindowTitle("My App");      // Set terminal window title
Command.clearScreen();                 // Clear the terminal
Command.checkWindowSize();             // Request a WindowSizeMessage
Command.tick(Duration.ofSeconds(1), t -> new TickMessage()); // One-shot timer
Command.every(Duration.ofMillis(100), t -> new TickMessage()); // Repeating timer
Command.paste();                       // Request clipboard contents
Command.copyToClipboard("text");       // Write to clipboard
Command.openUrl("https://example.com"); // Open URL in host OS browser

Command.none()

Use Command.none() (or null) to signal that no command should run. Prefer Command.none() for clarity:

return UpdateResult.from(this, Command.none());

BatchMessage

BatchMessage runs multiple commands concurrently. Use Command.batch(...) to create one:

@Override
public Command init() {
    return Command.batch(
        Command.checkWindowSize(),
        this::loadInitialData,
        Command.setWindowTitle("My App")
    );
}

The runtime dispatches all batched commands simultaneously. Messages from them arrive in an unspecified order.

// Also accepts a Collection:
List<Command> cmds = buildInitialCommands();
return Command.batch(cmds);

SequenceMessage

SequenceMessage runs commands one at a time, in order. Use Command.sequence(...) to create one:

return UpdateResult.from(this, Command.sequence(
    this::validateInput,
    this::saveToFile,
    Command.quit()
));

Command.sequence executes commands serially and delivers each message as it arrives. Command.batch runs commands concurrently with no ordering guarantee. Use sequence when each step depends on the previous one completing.

Command.sequentially(...) is similar but stops after the first command that returns a non-null message:

// Try primary source, fall back to secondary only if primary returns null:
return UpdateResult.from(this, Command.sequentially(
    this::tryPrimarySource,
    this::trySecondarySource
));

The Elm Architecture

How Model, Update, and View fit together.

Styling with Lipgloss

Colors, borders, padding, and layout.

Get Started

Core Concepts

Components

Guides

Compatibility

Messages and commands

Messages

KeyPressMessage

WindowSizeMessage

FocusMessage and BlurMessage

QuitMessage

Custom messages

Commands

Returning a command from update

Built-in command factories

Command.none()

BatchMessage

SequenceMessage

The Elm Architecture

Styling with Lipgloss

​Messages

​KeyPressMessage

​WindowSizeMessage

​FocusMessage and BlurMessage

​QuitMessage

​Custom messages

​Commands

​Returning a command from update

​Built-in command factories

​Command.none()

​BatchMessage

​SequenceMessage

The Elm Architecture

Styling with Lipgloss

Messages

KeyPressMessage

WindowSizeMessage

FocusMessage and BlurMessage

QuitMessage

Custom messages

Commands

Returning a command from update

Built-in command factories

Command.none()

BatchMessage

SequenceMessage