Package org.jline.terminal.impl

Class MouseSupport

java.lang.Object

org.jline.terminal.impl.MouseSupport

public class MouseSupport
extends Object

Utility class for mouse support in terminals.

The MouseSupport class provides functionality for enabling, disabling, and processing mouse events in terminals that support mouse tracking. It handles the details of sending the appropriate escape sequences to the terminal to enable different mouse tracking modes and parsing the responses to create MouseEvent objects.

This class is used internally by terminal implementations to implement the mouse-related methods defined in the Terminal interface, such as Terminal.hasMouseSupport(), Terminal.trackMouse(Terminal.MouseTracking), and Terminal.readMouseEvent().

Mouse tracking in terminals typically works by:

1. Sending special escape sequences to enable a specific mouse tracking mode
2. Receiving escape sequences from the terminal when mouse events occur
3. Parsing these sequences to extract information about the event type, button, modifiers, and coordinates
4. Creating MouseEvent objects that represent these events

Note that mouse support is not available in all terminals, and the methods in this class may not work correctly if the terminal does not support mouse tracking.

See Also:

• Terminal.hasMouseSupport()
• Terminal.trackMouse(Terminal.MouseTracking)
• Terminal.readMouseEvent()
• MouseEvent

Constructor Summary

Constructors

Constructor	Description
MouseSupport()

Method Summary

Modifier and Type	Method	Description
static boolean	hasMouseSupport(Terminal terminal)	Checks if the terminal supports mouse tracking.
static String[]	keys()	Returns a list of key sequences that could be used for mouse events based on the current mouse mode configuration.
static String[]	keys(Terminal terminal)	Returns a list of key sequences that could be used for mouse events, including the terminal's key_mouse capability if available.
static MouseEvent	readMouse(IntSupplier reader, MouseEvent last)	Reads a mouse event using the provided input supplier.
static MouseEvent	readMouse(IntSupplier reader, MouseEvent last, String prefix)	Reads a mouse event using the provided input supplier with a prefix that has already been consumed.
static MouseEvent	readMouse(Terminal terminal, MouseEvent last)	Reads a mouse event from the terminal.
static MouseEvent	readMouse(Terminal terminal, MouseEvent last, String prefix)	Reads a mouse event from the terminal with a prefix that has already been consumed.
static boolean	trackMouse(Terminal terminal, Terminal.MouseTracking tracking)	Enables or disables mouse tracking in the terminal.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MouseSupport

public MouseSupport()

Method Details

hasMouseSupport

public static boolean hasMouseSupport(Terminal terminal)

Checks if the terminal supports mouse tracking.

This method determines whether the terminal supports mouse tracking by checking if it has the key_mouse capability. This capability is required for mouse tracking to work correctly.

Parameters:

terminal - the terminal to check

Returns:

true if the terminal supports mouse tracking, false otherwise

trackMouse

public static boolean trackMouse(Terminal terminal,
 Terminal.MouseTracking tracking)

Enables or disables mouse tracking in the terminal.

This method sends the appropriate escape sequences to the terminal to enable or disable mouse tracking according to the specified tracking mode. The available tracking modes are:

• Terminal.MouseTracking.Off - Disables mouse tracking
• Terminal.MouseTracking.Normal - Reports button press and release events
• Terminal.MouseTracking.Button - Reports button press, release, and motion events while buttons are pressed
• Terminal.MouseTracking.Any - Reports all mouse events, including movement without buttons pressed

This implementation enables multiple mouse modes (1005, 1006, and basic) by default, which provides maximum compatibility across different terminals. The terminal will use the most advanced mode it supports:

• SGR mode (1006) - For terminals that support explicit release events
• UTF-8 mode (1005) - For terminals that need to report coordinates > 223
• Basic mode (1000) - For basic mouse event reporting

When disabling mouse tracking, all modes are disabled to ensure a clean state.

Parameters:

terminal - the terminal to configure

tracking - the mouse tracking mode to enable

Returns:

true if mouse tracking is supported and was configured, false otherwise

readMouse

public static MouseEvent readMouse(Terminal terminal,
 MouseEvent last)

Reads a mouse event from the terminal.

This method reads a mouse event from the terminal's input stream and converts it into a MouseEvent object. It uses the previous mouse event to determine the type of the new event (e.g., to distinguish between press, drag, and release events).

Parameters:

terminal - the terminal to read from

last - the previous mouse event, used to determine the type of the new event

Returns:

the mouse event that was read

readMouse

public static MouseEvent readMouse(Terminal terminal,
 MouseEvent last,
 String prefix)

Reads a mouse event from the terminal with a prefix that has already been consumed.

This method is similar to readMouse(Terminal, MouseEvent), but it allows specifying a prefix that has already been consumed. This is useful when the mouse event prefix (e.g., "\033[invalid input: '<'" or "\033[M") has been consumed by the key binding detection, and we need to continue parsing from the current position.

Parameters:

terminal - the terminal to read from

last - the previous mouse event, used to determine the type of the new event

prefix - the prefix that has already been consumed, or null if none

Returns:

the mouse event that was read

readMouse

public static MouseEvent readMouse(IntSupplier reader,
 MouseEvent last)

Reads a mouse event using the provided input supplier.

This method reads a mouse event using the provided input supplier and converts it into a MouseEvent object. It uses the previous mouse event to determine the type of the new event (e.g., to distinguish between press, drag, and release events).

The input supplier should provide the raw bytes of the mouse event data. This method expects the data to be in the format used by xterm-compatible terminals for mouse reporting.

Parameters:

reader - the input supplier to read from

last - the previous mouse event, used to determine the type of the new event

Returns:

the mouse event that was read

This implementation supports multiple mouse event formats:

• X10 format (default) - Basic mouse reporting
• UTF-8 format (1005) - Extended mouse reporting with UTF-8 encoded coordinates
• SGR format (1006) - Extended mouse reporting with explicit release events
• URXVT format (1015) - Extended mouse reporting with decimal coordinates
• SGR-Pixels format (1016) - Like SGR but reports position in pixels

readMouse

public static MouseEvent readMouse(IntSupplier reader,
 MouseEvent last,
 String prefix)

Reads a mouse event using the provided input supplier with a prefix that has already been consumed.

This method is similar to readMouse(IntSupplier, MouseEvent), but it allows specifying a prefix that has already been consumed. This is useful when the mouse event prefix (e.g., "\033[invalid input: '<'" or "\033[M") has been consumed by the key binding detection, and we need to continue parsing from the current position.

Parameters:

reader - the input supplier to read from

last - the previous mouse event, used to determine the type of the new event

prefix - the prefix that has already been consumed, or null if none

Returns:

the mouse event that was read

keys

public static String[] keys()

Returns a list of key sequences that could be used for mouse events based on the current mouse mode configuration.

This method returns the possible prefixes for mouse events that applications should recognize. This is useful for applications that need to handle mouse events but don't want to rely on the terminal's kmous capability, which might not accurately reflect the actual mouse mode being used.

Returns:

array of possible mouse event prefixes

keys

public static String[] keys(Terminal terminal)

Returns a list of key sequences that could be used for mouse events, including the terminal's key_mouse capability if available.

This method combines the standard mouse event prefixes with the terminal's key_mouse capability. This is useful for applications that need to bind all possible mouse event sequences to ensure compatibility across different terminals.

Parameters:

terminal - the terminal to get the key_mouse capability from

Returns:

array of possible mouse event prefixes including the terminal's key_mouse capability