Package org.aesh.terminal

Class TerminalFeatures

java.lang.Object
org.aesh.terminal.TerminalFeatures
public class TerminalFeatures extends Object
Advanced terminal features: queries, capability detection, semantic output, and mode management.

This class wraps a Connection and provides access to all terminal-specific functionality that goes beyond basic I/O. Access it via Connection.terminal().

Features are organized into four areas:

  • Queries — send escape sequences and parse responses (OSC, DA1/DA2, DECRQM, theme DSR)
  • Capability Detection — heuristic checks based on terminal type and environment
  • Semantic Output — shell integration markers, hyperlinks, clipboard
  • Mode Toggles — synchronized output, grapheme cluster mode, theme notifications
See Also:

  • Field Details

    • DEFAULT_QUERY_TIMEOUT_MS

      public static final long DEFAULT_QUERY_TIMEOUT_MS
      Default timeout in milliseconds for terminal queries (OSC, DA1, DA2, etc.). Suitable for most query operations where the terminal is expected to respond.
      See Also:

    • FAST_QUERY_TIMEOUT_MS

      public static final long FAST_QUERY_TIMEOUT_MS
      Fast timeout in milliseconds for lightweight terminal queries. Use for simple queries like theme DSR or when low latency is important.
      See Also:

  • Constructor Details

    • TerminalFeatures

      public TerminalFeatures(Connection connection)

  • Method Details

    • connection

      public Connection connection()
      Access the underlying connection.
      Returns:
      the connection this features object wraps

    • queryTerminal

      public <T> T queryTerminal(String query, long timeoutMs, Function<int[],T> responseParser)
      Send a query to the terminal and wait for a response with timeout.

      This method enters raw mode, sends the query, collects the response, and restores the original terminal attributes. It's useful for both OSC queries and CSI queries (DA1/DA2, DECRQM, theme DSR, etc.).

      This method uses Connection.setStdinHandler(Consumer) to receive responses, which requires the connection to be actively reading input (i.e., Connection.reading() returns true). If not reading, this method returns null.

      Type Parameters:
      T - the type of the parsed response
      Parameters:
      query - the query sequence to send
      timeoutMs - timeout in milliseconds to wait for response
      responseParser - function to parse the response; should return non-null when a complete response is received, null to continue waiting
      Returns:
      the parsed response, or null if not reading, timeout, or parsing failed

    • getCursorPosition

      public Point getCursorPosition()
      Get the current cursor position in the terminal.
      Returns:
      the current cursor position as a Point (row, column)

    • queryOsc

      public <T> T queryOsc(int oscCode, String param, long timeoutMs, Function<int[],T> responseParser)
      Send an OSC (Operating System Command) query to the terminal.
      Type Parameters:
      T - the type of the parsed response
      Parameters:
      oscCode - the OSC code (e.g., 10 for foreground, 11 for background)
      param - the query parameter (typically "?" for queries)
      timeoutMs - timeout in milliseconds to wait for response
      responseParser - function to parse the response
      Returns:
      the parsed response, or null if timeout or not supported

    • queryForegroundColor

      public int[] queryForegroundColor(long timeoutMs)
      Query the terminal for its foreground color using OSC 10.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for response
      Returns:
      RGB array [r, g, b] (0-255 each), or null if not supported or timeout

    • queryBackgroundColor

      public int[] queryBackgroundColor(long timeoutMs)
      Query the terminal for its background color using OSC 11.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for response
      Returns:
      RGB array [r, g, b] (0-255 each), or null if not supported or timeout

    • queryCursorColor

      public int[] queryCursorColor(long timeoutMs)
      Query the terminal for its cursor color using OSC 12.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for response
      Returns:
      RGB array [r, g, b] (0-255 each), or null if not supported or timeout

    • queryThemeMode

      public TerminalTheme queryThemeMode(long timeoutMs)
      Query the terminal for its current theme mode using the CSI ? 996 n protocol.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for response
      Returns:
      TerminalTheme.DARK or TerminalTheme.LIGHT, or null if not supported or timeout

    • queryOsc

      public <T> T queryOsc(int oscCode, int index, String param, long timeoutMs, Function<int[],T> responseParser)
      Send an OSC query with an index parameter to the terminal.
      Type Parameters:
      T - the type of the parsed response
      Parameters:
      oscCode - the OSC code (e.g., 4 for palette color)
      index - the index parameter (e.g., palette color index 0-255)
      param - the query parameter (typically "?" for queries)
      timeoutMs - timeout in milliseconds to wait for response
      responseParser - function to parse the response
      Returns:
      the parsed response, or null if timeout or not supported

    • queryPaletteColor

      public int[] queryPaletteColor(int index, long timeoutMs)
      Query the terminal for a palette color using OSC 4.
      Parameters:
      index - the palette color index (0-255)
      timeoutMs - timeout in milliseconds to wait for response
      Returns:
      RGB array [r, g, b] (0-255 each), or null if not supported or timeout

    • queryWithResponseBuffering

      public Map<Integer,int[]> queryWithResponseBuffering(long timeoutMs, int expectedCount, String batchQuery, Function<int[],Map<Integer,int[]>> parser)
      Shared orchestration for batch OSC queries with response buffering.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for all responses
      expectedCount - the number of expected responses
      batchQuery - the concatenated query string to send
      parser - function to parse the buffered response into a result map
      Returns:
      map from key to RGB array [r, g, b] (0-255 each)

    • queryBatchOsc

      public Map<Integer,int[]> queryBatchOsc(long timeoutMs, int... oscCodes)
      Query multiple OSC color codes in a single batch operation.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for all responses
      oscCodes - the OSC codes to query (e.g., 10 for foreground, 11 for background)
      Returns:
      map from OSC code to RGB array [r, g, b] (0-255 each)

    • queryColors

      public Map<Integer,int[]> queryColors(long timeoutMs)
      Query foreground, background, and cursor colors in a single batch operation.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for all responses
      Returns:
      map from OSC code to RGB array [r, g, b] (0-255 each)

    • queryPaletteColors

      public Map<Integer,int[]> queryPaletteColors(long timeoutMs, int... indices)
      Query multiple palette colors in a single batch operation.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for all responses
      indices - the palette color indices to query (0-255)
      Returns:
      map from palette index to RGB array [r, g, b] (0-255 each)

    • queryAnsi16Colors

      public Map<Integer,int[]> queryAnsi16Colors(long timeoutMs)
      Query the ANSI 16-color palette (colors 0-15) in a single batch operation.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for all responses
      Returns:
      map from palette index (0-15) to RGB array [r, g, b] (0-255 each)

    • queryPrimaryDeviceAttributes

      public DeviceAttributes queryPrimaryDeviceAttributes(long timeoutMs)
      Query the terminal for its primary device attributes (DA1).
      Parameters:
      timeoutMs - timeout in milliseconds to wait for response
      Returns:
      DeviceAttributes with DA1 data, or null if not supported or timeout

    • querySecondaryDeviceAttributes

      public DeviceAttributes querySecondaryDeviceAttributes(long timeoutMs)
      Query the terminal for its secondary device attributes (DA2).
      Parameters:
      timeoutMs - timeout in milliseconds to wait for response
      Returns:
      DeviceAttributes with DA2 data, or null if not supported or timeout

    • queryDeviceAttributes

      public DeviceAttributes queryDeviceAttributes(long timeoutMs)
      Query the terminal for both primary and secondary device attributes.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for each response
      Returns:
      DeviceAttributes with merged DA1 and DA2 data, or null if neither succeeded

    • queryImageProtocol

      public ImageProtocol queryImageProtocol(long timeoutMs)
      Query the terminal for its image protocol support.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for DA1 response
      Returns:
      the detected image protocol

    • querySynchronizedOutput

      public Boolean querySynchronizedOutput(long timeoutMs)
      Query the terminal to check if Mode 2026 is supported via DECRQM.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for response
      Returns:
      true if supported, false if not supported, null if no response/timeout

    • queryGraphemeClusterMode

      public Boolean queryGraphemeClusterMode(long timeoutMs)
      Query the terminal to check if Mode 2027 is supported via DECRQM.
      Parameters:
      timeoutMs - timeout in milliseconds to wait for response
      Returns:
      true if supported, false if not supported, null if no response/timeout

    • querySupportsOscQueries

      public boolean querySupportsOscQueries(long timeoutMs)
      Query the terminal to check if OSC queries are supported.
      Parameters:
      timeoutMs - timeout in milliseconds for the DA1 query
      Returns:
      true if OSC queries are likely supported

    • queryPaletteColorIfSupported

      public int[] queryPaletteColorIfSupported(int index, long timeoutMs)
      Query palette color only if the terminal supports it.
      Parameters:
      index - the palette color index (0-255)
      timeoutMs - timeout in milliseconds to wait for response
      Returns:
      RGB array [r, g, b] (0-255 each), or null if not supported or timeout

    • supportsOscQueries

      public boolean supportsOscQueries()
      Check if OSC (Operating System Command) queries are supported.
      Returns:
      true if OSC queries are likely supported

    • supportsOscQueries

      public boolean supportsOscQueries(DeviceAttributes attrs)
      Check if OSC queries are supported, using DA1 device attributes for improved detection.
      Parameters:
      attrs - the device attributes from DA1 query (may be null)
      Returns:
      true if OSC queries are likely supported

    • colorDepth

      public ColorDepth colorDepth()
      Get the color depth of this terminal connection.
      Returns:
      the detected color depth

    • colorCapability

      public TerminalColorCapability colorCapability()
      Get the color capabilities of this terminal connection.
      Returns:
      the detected color capabilities

    • supportsThemeQuery

      public boolean supportsThemeQuery()
      Check if the terminal supports the CSI ? 996 n theme mode query.
      Returns:
      true if the terminal supports theme mode queries

    • supportsSynchronizedOutput

      public boolean supportsSynchronizedOutput()
      Check if Mode 2026 (synchronized output) is likely supported.
      Returns:
      true if Mode 2026 is likely supported

    • supportsShellIntegration

      public boolean supportsShellIntegration()
      Check if OSC 133 (shell integration) is likely supported.
      Returns:
      true if OSC 133 shell integration is likely supported

    • supportsGraphemeClusterMode

      public boolean supportsGraphemeClusterMode()
      Check if Mode 2027 (grapheme cluster segmentation) is likely supported.
      Returns:
      true if Mode 2027 is likely supported

    • supportsHyperlinks

      public boolean supportsHyperlinks()
      Check if OSC 8 hyperlinks are likely supported.
      Returns:
      true if OSC 8 hyperlinks are likely supported

    • getTerminalType

      public Device.TerminalType getTerminalType()
      Get the detected terminal type based on environment variables.
      Returns:
      the detected terminal type

    • supportsOscCode

      public boolean supportsOscCode(Device.OscCode oscCode)
      Check if the terminal likely supports a specific OSC code.
      Parameters:
      oscCode - the OSC code to check
      Returns:
      true if the terminal likely supports this OSC code

    • supportsPaletteQuery

      public boolean supportsPaletteQuery()
      Check if the terminal likely supports OSC 4 palette color queries.
      Returns:
      true if OSC 4 is likely supported

    • supportsColorQuery

      public boolean supportsColorQuery()
      Check if the terminal likely supports OSC 10/11 color queries.
      Returns:
      true if OSC 10/11 are likely supported

    • supportsClipboard

      public boolean supportsClipboard()
      Check if the terminal likely supports OSC 52 clipboard access.
      Returns:
      true if OSC 52 clipboard access is likely supported

    • enableSynchronizedOutput

      public Connection enableSynchronizedOutput()
      Enable Mode 2026 (synchronized output) — Begin Synchronized Update (BSU).
      Returns:
      the underlying connection

    • disableSynchronizedOutput

      public Connection disableSynchronizedOutput()
      Disable Mode 2026 (synchronized output) — End Synchronized Update (ESU).
      Returns:
      the underlying connection

    • writePromptStart

      public Connection writePromptStart()
      Write OSC 133;A (Prompt Start) to the terminal.
      Returns:
      the underlying connection

    • writePromptEnd

      public Connection writePromptEnd()
      Write OSC 133;B (Prompt End) to the terminal.
      Returns:
      the underlying connection

    • writeCommandStart

      public Connection writeCommandStart()
      Write OSC 133;C (Command Start) to the terminal.
      Returns:
      the underlying connection

    • writeCommandFinished

      public Connection writeCommandFinished()
      Write OSC 133;D (Command Finished) to the terminal without an exit code.
      Returns:
      the underlying connection

    • writeCommandFinished

      public Connection writeCommandFinished(int exitCode)
      Write OSC 133;D (Command Finished) to the terminal with an exit code.
      Parameters:
      exitCode - the command exit code
      Returns:
      the underlying connection

    • enableGraphemeClusterMode

      public Connection enableGraphemeClusterMode()
      Enable Mode 2027 (grapheme cluster segmentation).
      Returns:
      the underlying connection

    • disableGraphemeClusterMode

      public Connection disableGraphemeClusterMode()
      Disable Mode 2027 (grapheme cluster segmentation).
      Returns:
      the underlying connection

    • writeHyperlink

      public Connection writeHyperlink(String url, String text)
      Write a clickable hyperlink to the terminal.
      Parameters:
      url - the hyperlink URL
      text - the visible text
      Returns:
      the underlying connection

    • writeHyperlink

      public Connection writeHyperlink(String url, String text, String id)
      Write a clickable hyperlink with a grouping id.
      Parameters:
      url - the hyperlink URL
      text - the visible text
      id - the grouping id
      Returns:
      the underlying connection

    • writeClipboard

      public Connection writeClipboard(String text)
      Write text to the system clipboard via OSC 52.
      Parameters:
      text - the text to copy to the clipboard
      Returns:
      the underlying connection

    • enableThemeChangeNotification

      public void enableThemeChangeNotification()
      Enable unsolicited theme change notifications.

    • enableThemeChangeNotification

      public void enableThemeChangeNotification(Consumer<TerminalTheme> handler)
      Enable unsolicited theme change notifications with a handler.
      Parameters:
      handler - the handler to invoke with the new theme

    • disableThemeChangeNotification

      public void disableThemeChangeNotification()
      Disable unsolicited theme change notifications.