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:

  • 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

    • readMouseX10

      private static MouseEvent readMouseX10(int cb, IntSupplier reader, MouseEvent last)
      Reads a mouse event in X10 format.
      Parameters:
      cb - the button code (already read)
      reader - the input supplier to read from
      last - the previous mouse event
      Returns:
      the mouse event that was read

    • readMouseX10

      private static MouseEvent readMouseX10(int cb, int cx, int cy, MouseEvent last)
      Reads a mouse event in X10 format with pre-read coordinates.
      Parameters:
      cb - the button code (already read)
      cx - the x coordinate (already read and processed)
      cy - the y coordinate (already read and processed)
      last - the previous mouse event
      Returns:
      the mouse event that was read

    • readMouseUTF8

      private static MouseEvent readMouseUTF8(int cb, int cx, int cy, IntSupplier reader, MouseEvent last)
      Reads a mouse event in UTF-8 format (1005). In this format, coordinates are UTF-8 encoded to support values > 223.
      Parameters:
      cb - the button code (already read)
      cx - the first byte of the x coordinate (already read)
      cy - the first byte of the y coordinate (already read)
      reader - the input supplier to read from
      last - the previous mouse event
      Returns:
      the mouse event that was read

    • decodeUtf8Coordinate

      private static int decodeUtf8Coordinate(int firstByte, IntSupplier reader)
      Decodes a UTF-8 encoded coordinate value.
      Parameters:
      firstByte - the first byte of the UTF-8 encoded value
      reader - the input supplier to read additional bytes if needed
      Returns:
      the decoded coordinate value

    • readMouseSGR

      private static MouseEvent readMouseSGR(IntSupplier reader, MouseEvent last)
      Reads a mouse event in SGR format (1006 or 1016). Format: CSI invalid input: '<' Cb ; Cx ; Cy M/m

      This method handles both standard SGR format (1006) and SGR-Pixels format (1016). In SGR format, coordinates are reported in character cells. In SGR-Pixels format, coordinates are reported in pixels.

      Currently, the MouseEvent class doesn't distinguish between cell and pixel coordinates, so both formats are treated the same. In the future, this could be enhanced to provide different handling for pixel coordinates.

      Parameters:
      reader - the input supplier to read from
      last - the previous mouse event
      Returns:
      the mouse event that was read

    • readMouseURXVT

      private static MouseEvent readMouseURXVT(int firstDigit, IntSupplier reader, MouseEvent last)
      Reads a mouse event in URXVT format (1015). Format: CSI Cb ; Cx ; Cy M
      Parameters:
      firstDigit - the first digit of the button code (already read)
      reader - the input supplier to read from
      last - the previous mouse event
      Returns:
      the mouse event that was read

    • parseMouseEvent

      private static MouseEvent parseMouseEvent(int cb, int cx, int cy, boolean isRelease, MouseEvent last)
      Parses a mouse event from the given parameters.
      Parameters:
      cb - the button code
      cx - the x coordinate
      cy - the y coordinate
      isRelease - whether this is an explicit release event (SGR format)
      last - the previous mouse event
      Returns:
      the parsed mouse event

    • getButtonForCode

      private static MouseEvent.Button getButtonForCode(int code)
      Gets the button for the given button code.
      Parameters:
      code - the button code
      Returns:
      the corresponding button

    • 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

    • readExt

      private static int readExt(Terminal terminal)
      Reads a single character from the terminal's input stream.

      This method reads a single character from the terminal's input stream, handling the case where the terminal's encoding is not UTF-8. Mouse events are encoded in UTF-8, so if the terminal is using a different encoding, this method creates a temporary UTF-8 reader to read the character.

      Parameters:
      terminal - the terminal to read from
      Returns:
      the character that was read
      Throws:
      IOError - if an I/O error occurs while reading

    • createReaderFromString

      private static IntSupplier createReaderFromString(String s)
      Creates a reader from a string.
      Parameters:
      s - the string to read from
      Returns:
      an IntSupplier that reads from the string

    • chainReaders

      private static IntSupplier chainReaders(IntSupplier first, IntSupplier second)
      Chains two readers together, reading from the first reader until it's exhausted, then reading from the second reader.
      Parameters:
      first - the first reader to read from
      second - the second reader to read from after the first is exhausted
      Returns:
      an IntSupplier that reads from both readers in sequence