Mouse input

TUI4J translates terminal mouse escape sequences into typed MouseMessage values that your update() method receives like any other message. You choose the reporting mode — cell-level motion, all-motion, or disabled — and the runtime handles the rest.

Enabling mouse support

Return a mouse-enable message from init() to activate reporting when the program starts, or return it from update() to toggle at runtime.

@Override
public Command init() {
    // Reports every mouse move, click, and scroll
    return new EnableMouseAllMotionMessage();
}

@Override
public Command init() {
    // Reports clicks and motion only when a button is held
    return new EnableMouseCellMotionMessage();
}

You can also use the convenience methods on Command:

// In update(), switch between modes on a keypress:
case "a" -> UpdateResult.from(this, Command.enableMouseAllMotion());
case "c" -> UpdateResult.from(this, Command.enableMouseCellMotion());
case "d" -> UpdateResult.from(this, Command.disableMouse());

EnableMouseAllMotionMessage reports the cursor position on every mouse move, which lets you implement hover effects. EnableMouseCellMotionMessage only fires while a button is held, which is lighter on bandwidth and enough for drag-selection.

The MouseMessage type

Every mouse event arrives as a MouseMessage with the following fields:

Method	Type	Description
`column()`	`int`	0-based column position
`row()`	`int`	0-based row position
`getAction()`	`MouseAction`	press, release, or motion
`getButton()`	`MouseButton`	which button was involved
`isShift()`	`boolean`	shift held during event
`isAlt()`	`boolean`	alt held during event
`isCtrl()`	`boolean`	ctrl held during event
`isWheel()`	`boolean`	true for scroll-wheel events
`describe()`	`String`	human-readable event description

MouseAction

public enum MouseAction {
    MouseActionPress("press"),
    MouseActionRelease("release"),
    MouseActionMotion("motion");
}

MouseButton

public enum MouseButton {
    MouseButtonNone("none"),
    MouseButtonLeft("left"),
    MouseButtonMiddle("middle"),
    MouseButtonRight("right"),
    MouseButtonWheelUp("wheel up"),
    MouseButtonWheelDown("wheel down"),
    MouseButtonWheelLeft("wheel left"),
    MouseButtonWheelRight("wheel right"),
    MouseButtonBackward("backward"),
    MouseButtonForward("forward"),
    MouseButton10("button 10"),
    MouseButton11("button 11");
}

Handling mouse events in update()

Match on MouseMessage in your update() method alongside other message types. The example below tracks drag-selection: it records start coordinates on press, extends the selection during motion, and clears the active flag on release.

@Override
public UpdateResult<? extends Model> update(Message msg) {
    if (msg instanceof MouseMessage mouse) {
        return switch (mouse.getAction()) {
            case MouseActionPress -> {
                if (mouse.getButton() == MouseButton.MouseButtonLeft) {
                    selecting = true;
                    selectionStartCol = mouse.column();
                    selectionStartRow = mouse.row();
                    selectionEndCol = mouse.column();
                    selectionEndRow = mouse.row();
                }
                yield UpdateResult.from(this);
            }
            case MouseActionMotion -> {
                if (selecting) {
                    selectionEndCol = mouse.column();
                    selectionEndRow = mouse.row();
                }
                yield UpdateResult.from(this);
            }
            case MouseActionRelease -> {
                selecting = false;
                yield UpdateResult.from(this);
            }
        };
    }

    if (msg instanceof KeyPressMessage key) {
        return switch (key.key()) {
            case "q", "Q", "ctrl+c" -> UpdateResult.from(this, QuitMessage::new);
            case "a", "A" -> UpdateResult.from(this, Command.enableMouseAllMotion());
            case "c", "C" -> UpdateResult.from(this, Command.enableMouseCellMotion());
            case "d", "D" -> UpdateResult.from(this, Command.disableMouse());
            default -> UpdateResult.from(this);
        };
    }

    return UpdateResult.from(this);
}

Hit testing

Compare mouse.column() and mouse.row() against the bounds of a rendered region to detect hover or click:

private boolean isInBox(MouseMessage mouse, int boxLeft, int boxTop,
                        int boxWidth, int boxHeight) {
    if (mouse == null) return false;
    int col = mouse.column();
    int row = mouse.row();
    return row >= boxTop
        && row < boxTop + boxHeight
        && col >= boxLeft
        && col < boxLeft + boxWidth;
}

You can then change the rendered output based on whether the cursor is inside:

@Override
public String view() {
    boolean inBox = isInBox(lastMouse, BOX_LEFT, BOX_TOP, BOX_WIDTH, BOX_HEIGHT);
    String border = inBox ? "#" : "+";
    // render differently when hovered
}

Row and column positions are 0-based after TUI4J normalizes the raw escape sequence coordinates.

Scroll wheel

Scroll events set the button to one of the four wheel values while getAction() is MouseActionPress. Use isWheel() for a quick check:

if (msg instanceof MouseMessage mouse && mouse.isWheel()) {
    if (mouse.getButton() == MouseButton.MouseButtonWheelUp) {
        scrollOffset = Math.max(0, scrollOffset - 1);
    } else if (mouse.getButton() == MouseButton.MouseButtonWheelDown) {
        scrollOffset++;
    }
    return UpdateResult.from(this);
}

Disabling mouse on exit

Return DisableMouseMessage before quitting to restore the terminal’s default mouse behavior:

case "q" -> UpdateResult.from(this,
    Command.batch(
        DisableMouseMessage::new,
        QuitMessage::new
    ));

Running the program with mouse support

Pass the mouse mode to Program via the builder methods instead of (or in addition to) returning it from init():

new Program(new MyModel())
        .withMouseAllMotion()
        .run();

Use withMouseCellMotion() for drag-selection scenarios and withMouseAllMotion() when you need hover effects. All-motion generates significantly more events, so prefer cell-motion when you don’t need hover.

Spring Boot integration

Embed TUI4J in a Spring Boot app

External commands

Launch editors and shells from your TUI

Get Started

Core Concepts

Components

Guides

Compatibility

Enabling mouse support

The MouseMessage type

MouseAction

MouseButton

Handling mouse events in update()

Hit testing

Scroll wheel

Disabling mouse on exit

Running the program with mouse support

Spring Boot integration

External commands

​Enabling mouse support

​The MouseMessage type

​MouseAction

​MouseButton

​Handling mouse events in update()

​Hit testing

​Scroll wheel

​Disabling mouse on exit

​Running the program with mouse support

Spring Boot integration

External commands

Enabling mouse support

The MouseMessage type

MouseAction

MouseButton

Handling mouse events in update()

Hit testing

Scroll wheel

Disabling mouse on exit

Running the program with mouse support