Class MouseSupport
- java.lang.Object
-
- org.jline.terminal.impl.MouseSupport
-
public class MouseSupport extends java.lang.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)
, andTerminal.readMouseEvent()
.Mouse tracking in terminals typically works by:
- Sending special escape sequences to enable a specific mouse tracking mode
- Receiving escape sequences from the terminal when mouse events occur
- Parsing these sequences to extract information about the event type, button, modifiers, and coordinates
- 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.
-
-
Constructor Summary
Constructors Constructor Description MouseSupport()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static boolean
hasMouseSupport(Terminal terminal)
Checks if the terminal supports mouse tracking.static java.lang.String[]
keys()
Returns a list of key sequences that could be used for mouse events based on the current mouse mode configuration.static java.lang.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(java.util.function.IntSupplier reader, MouseEvent last)
Reads a mouse event using the provided input supplier.static MouseEvent
readMouse(java.util.function.IntSupplier reader, MouseEvent last, java.lang.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, java.lang.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.
-
-
-
Method Detail
-
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 trackingTerminal.MouseTracking.Normal
- Reports button press and release eventsTerminal.MouseTracking.Button
- Reports button press, release, and motion events while buttons are pressedTerminal.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 configuretracking
- 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 fromlast
- 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, java.lang.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[<" 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 fromlast
- the previous mouse event, used to determine the type of the new eventprefix
- the prefix that has already been consumed, or null if none- Returns:
- the mouse event that was read
-
readMouse
public static MouseEvent readMouse(java.util.function.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 fromlast
- 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(java.util.function.IntSupplier reader, MouseEvent last, java.lang.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[<" 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 fromlast
- the previous mouse event, used to determine the type of the new eventprefix
- the prefix that has already been consumed, or null if none- Returns:
- the mouse event that was read
-
keys
public static java.lang.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 java.lang.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
-
-