Class 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), 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

      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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • MouseSupport

        public MouseSupport()
    • 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:

        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,
                                           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 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​(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 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​(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 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 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