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:
  • 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:

      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