Package org.aesh.terminal.tty

Class TerminalColorDetector

java.lang.Object
org.aesh.terminal.tty.TerminalColorDetector
public final class TerminalColorDetector extends Object
Utility class to detect terminal color capabilities.

This detector can query the terminal to determine:

  • Color depth (8, 16, 256, or true color)
  • Background theme (light or dark)
  • Actual foreground and background RGB colors

Detection methods:

  • Environment variables (COLORTERM, TERM) via TerminalEnvironment
  • terminfo/infocmp database (max_colors capability)
  • OSC 10/11 queries for actual terminal colors
  • Platform-specific config files via PlatformThemeDetector

The detector supports caching to avoid repeated detection overhead. Use detectCached(Connection) for cached detection.

Author:
Ståle W. Pedersen

  • Method Details

    • detectCached

      public static TerminalColorCapability detectCached(Connection connection)
      Detect terminal color capabilities using cached result if available.
      Parameters:
      connection - the terminal connection
      Returns:
      detected color capabilities (may be cached)

    • clearCache

      public static void clearCache()
      Clear the cached color capability.

    • getCached

      public static TerminalColorCapability getCached()
      Get the cached color capability without performing detection.
      Returns:
      the cached capability, or null if not cached

    • detect

      public static TerminalColorCapability detect(Connection connection)
      Detect terminal color capabilities using a fast OSC query (FG + BG only).
      Parameters:
      connection - the terminal connection
      Returns:
      detected color capabilities

    • detect

      public static TerminalColorCapability detect(Connection connection, boolean queryTerminal)
      Detect terminal color capabilities.
      Parameters:
      connection - the terminal connection
      queryTerminal - if true, send OSC queries to the terminal
      Returns:
      detected color capabilities

    • detectFull

      public static TerminalColorCapability detectFull(Connection connection)
      Detect terminal color capabilities including cursor and all 16 palette colors.
      Parameters:
      connection - the terminal connection
      Returns:
      detected color capabilities including palette colors

    • detectFast

      public static TerminalColorCapability detectFast(Connection connection)
      Get a fast, non-blocking color capability based only on environment detection.
      Parameters:
      connection - the terminal connection (may be null)
      Returns:
      detected color capabilities

    • detectColorDepth

      public static ColorDepth detectColorDepth(Connection connection)
      Detect only the color depth without querying the terminal for colors.
      Parameters:
      connection - the terminal connection
      Returns:
      the detected color depth

    • detectThemeFromEnvironment

      public static TerminalTheme detectThemeFromEnvironment()
      Detect terminal theme from environment variables and platform-specific config files.
      Returns:
      the detected theme, or UNKNOWN if not detectable

    • queryColorCapability

      public static TerminalColorCapability queryColorCapability(TerminalConnection connection, long timeoutMs)
      Query terminal color capabilities using synchronous I/O.
      Parameters:
      connection - the terminal connection (must be a TerminalConnection)
      timeoutMs - timeout in milliseconds to wait for all responses
      Returns:
      TerminalColorCapability with detected colors, or null if not supported

    • queryThemeColors

      public static TerminalColorCapability queryThemeColors(Connection connection, long timeoutMs)
      Fast query for theme-relevant colors only (foreground and background).
      Parameters:
      connection - the terminal connection
      timeoutMs - timeout in milliseconds
      Returns:
      TerminalColorCapability with FG/BG colors, or null if not supported

    • queryColors

      public static Map<Integer,int[]> queryColors(Connection connection, long timeoutMs)
      Query foreground, background, and cursor colors in a single batch operation.
      Parameters:
      connection - the terminal connection
      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 static Map<Integer,int[]> queryPaletteColors(Connection connection, long timeoutMs, int... indices)
      Query multiple palette colors in a single batch operation.
      Parameters:
      connection - the terminal connection
      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 static Map<Integer,int[]> queryAnsi16Colors(Connection connection, long timeoutMs)
      Query the ANSI 16-color palette (colors 0-15) in a single batch operation.
      Parameters:
      connection - the terminal connection
      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)

    • queryColorsWithFallback

      public static Map<Integer,int[]> queryColorsWithFallback(Connection connection, long timeoutMs)
      Query colors with automatic fallback to environment-based detection.
      Parameters:
      connection - the terminal connection
      timeoutMs - timeout in milliseconds for OSC queries
      Returns:
      map from OSC code to RGB array; always contains at least estimated foreground and background colors

    • isOscColorQuerySupported

      public static boolean isOscColorQuerySupported(Connection connection)
      Check if the terminal likely supports OSC color queries.
      Parameters:
      connection - the terminal connection to check
      Returns:
      true if OSC color queries are likely supported

    • isDarkColor

      public static boolean isDarkColor(int[] rgb)
      Check if an RGB color represents a dark theme (luminance < 0.5).
      Parameters:
      rgb - the RGB color array [r, g, b] (0-255 each)
      Returns:
      true if the color is dark, false if light