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(TerminalFeatures) for cached detection.

Author:
Ståle W. Pedersen

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    clearCache()
    Clear the cached color capability.
    static org.aesh.terminal.utils.TerminalColorCapability
    detect(org.aesh.terminal.TerminalFeatures terminal)
    Detect terminal color capabilities using a fast OSC query (FG + BG only).
    static org.aesh.terminal.utils.TerminalColorCapability
    detect(org.aesh.terminal.TerminalFeatures terminal, boolean queryTerminal)
    Detect terminal color capabilities.
    static org.aesh.terminal.utils.TerminalColorCapability
    detectCached(org.aesh.terminal.TerminalFeatures terminal)
    Detect terminal color capabilities using cached result if available.
    static org.aesh.terminal.utils.ColorDepth
    detectColorDepth(org.aesh.terminal.TerminalFeatures terminal)
    Detect only the color depth without querying the terminal for colors.
    static org.aesh.terminal.utils.TerminalColorCapability
    detectFast(org.aesh.terminal.TerminalFeatures terminal)
    Get a fast, non-blocking color capability based only on environment detection.
    static org.aesh.terminal.utils.TerminalColorCapability
    detectFull(org.aesh.terminal.TerminalFeatures terminal)
    Detect terminal color capabilities including cursor and all 16 palette colors.
    static org.aesh.terminal.detect.TerminalTheme
    detectThemeFromEnvironment()
    Detect terminal theme from environment variables and platform-specific config files.
    static org.aesh.terminal.utils.TerminalColorCapability
    getCached()
    Get the cached color capability without performing detection.
    static boolean
    isDarkColor(int[] rgb)
    Check if an RGB color represents a dark theme (luminance < 0.5).
    static boolean
    isOscColorQuerySupported(org.aesh.terminal.TerminalFeatures terminal)
    Check if the terminal likely supports OSC color queries.
    static Map<Integer,int[]>
    queryAnsi16Colors(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs)
    Query the ANSI 16-color palette (colors 0-15) in a single batch operation.
    static org.aesh.terminal.utils.TerminalColorCapability
    queryColorCapability(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs)
    Query terminal color capabilities using synchronous I/O.
    static Map<Integer,int[]>
    queryColors(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs)
    Query foreground, background, and cursor colors in a single batch operation.
    static Map<Integer,int[]>
    queryColorsWithFallback(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs)
    Query colors with automatic fallback to environment-based detection.
    static Map<Integer,int[]>
    queryPaletteColors(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs, int... indices)
    Query multiple palette colors in a single batch operation.
    static org.aesh.terminal.utils.TerminalColorCapability
    queryThemeColors(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs)
    Fast query for theme-relevant colors only (foreground and background).

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • detectCached

      public static org.aesh.terminal.utils.TerminalColorCapability detectCached(org.aesh.terminal.TerminalFeatures terminal)
      Detect terminal color capabilities using cached result if available.
      Parameters:
      terminal - the terminal features
      Returns:
      detected color capabilities (may be cached)

    • clearCache

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

    • getCached

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

    • detect

      public static org.aesh.terminal.utils.TerminalColorCapability detect(org.aesh.terminal.TerminalFeatures terminal)
      Detect terminal color capabilities using a fast OSC query (FG + BG only).
      Parameters:
      terminal - the terminal features
      Returns:
      detected color capabilities

    • detect

      public static org.aesh.terminal.utils.TerminalColorCapability detect(org.aesh.terminal.TerminalFeatures terminal, boolean queryTerminal)
      Detect terminal color capabilities.
      Parameters:
      terminal - the terminal features
      queryTerminal - if true, send OSC queries to the terminal
      Returns:
      detected color capabilities

    • detectFull

      public static org.aesh.terminal.utils.TerminalColorCapability detectFull(org.aesh.terminal.TerminalFeatures terminal)
      Detect terminal color capabilities including cursor and all 16 palette colors.
      Parameters:
      terminal - the terminal features
      Returns:
      detected color capabilities including palette colors

    • detectFast

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

    • detectColorDepth

      public static org.aesh.terminal.utils.ColorDepth detectColorDepth(org.aesh.terminal.TerminalFeatures terminal)
      Detect only the color depth without querying the terminal for colors.
      Parameters:
      terminal - the terminal features
      Returns:
      the detected color depth

    • detectThemeFromEnvironment

      public static org.aesh.terminal.detect.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 org.aesh.terminal.utils.TerminalColorCapability queryColorCapability(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs)
      Query terminal color capabilities using synchronous I/O.
      Parameters:
      terminal - the terminal features (must wrap a TerminalConnection)
      timeoutMs - timeout in milliseconds to wait for all responses
      Returns:
      TerminalColorCapability with detected colors, or null if not supported

    • queryThemeColors

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

    • queryColors

      public static Map<Integer,int[]> queryColors(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs)
      Query foreground, background, and cursor colors in a single batch operation.
      Parameters:
      terminal - the terminal features
      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(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs, int... indices)
      Query multiple palette colors in a single batch operation.
      Parameters:
      terminal - the terminal features
      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(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs)
      Query the ANSI 16-color palette (colors 0-15) in a single batch operation.
      Parameters:
      terminal - the terminal features
      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(org.aesh.terminal.TerminalFeatures terminal, long timeoutMs)
      Query colors with automatic fallback to environment-based detection.
      Parameters:
      terminal - the terminal features
      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(org.aesh.terminal.TerminalFeatures terminal)
      Check if the terminal likely supports OSC color queries.
      Parameters:
      terminal - the terminal features 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