Package org.aesh.terminal.utils

Class TerminalColorCapability

java.lang.Object
org.aesh.terminal.utils.TerminalColorCapability
public class TerminalColorCapability extends Object
Represents the detected color capabilities of a terminal.

This class encapsulates information about a terminal's color support, including:

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

Use TerminalColorDetector from the readline module to obtain instances of this class, or use the static factory methods like detectFromEnvironment() for quick detection.

Author:
Ståle W. Pedersen

  • Constructor Details

    • TerminalColorCapability

      public TerminalColorCapability(ColorDepth colorDepth, TerminalTheme theme, int[] foregroundRGB, int[] backgroundRGB)
      Create a new TerminalColorCapability with all detected values.
      Parameters:
      colorDepth - the detected color depth
      theme - the detected terminal theme
      foregroundRGB - the foreground RGB color (may be null if not detected)
      backgroundRGB - the background RGB color (may be null if not detected)

    • TerminalColorCapability

      public TerminalColorCapability(ColorDepth colorDepth, TerminalTheme theme, int[] foregroundRGB, int[] backgroundRGB, int[] cursorRGB, Map<Integer,int[]> paletteColors)
      Create a new TerminalColorCapability with all detected values including cursor and palette.
      Parameters:
      colorDepth - the detected color depth
      theme - the detected terminal theme
      foregroundRGB - the foreground RGB color (may be null if not detected)
      backgroundRGB - the background RGB color (may be null if not detected)
      cursorRGB - the cursor RGB color (may be null if not detected)
      paletteColors - the palette colors map (may be null if not detected)

    • TerminalColorCapability

      public TerminalColorCapability(ColorDepth colorDepth, TerminalTheme theme)
      Create a new TerminalColorCapability with color depth and theme.
      Parameters:
      colorDepth - the detected color depth
      theme - the detected terminal theme

    • TerminalColorCapability

      public TerminalColorCapability(ColorDepth colorDepth)
      Create a new TerminalColorCapability with only color depth.
      Parameters:
      colorDepth - the detected color depth

  • Method Details

    • getColorDepth

      public ColorDepth getColorDepth()
      Get the detected color depth capability.
      Returns:
      the detected color depth capability

    • getTheme

      public TerminalTheme getTheme()
      Get the detected terminal theme.
      Returns:
      the detected terminal theme (light/dark/unknown)

    • getForegroundRGB

      public int[] getForegroundRGB()
      Get the detected foreground RGB color.
      Returns:
      the detected foreground RGB color as [r, g, b] (0-255 each), or null if not detected

    • getBackgroundRGB

      public int[] getBackgroundRGB()
      Get the detected background RGB color.
      Returns:
      the detected background RGB color as [r, g, b] (0-255 each), or null if not detected

    • getCursorRGB

      public int[] getCursorRGB()
      Get the detected cursor RGB color.
      Returns:
      the detected cursor RGB color as [r, g, b] (0-255 each), or null if not detected

    • getPaletteColors

      public Map<Integer,int[]> getPaletteColors()
      Get the detected palette colors.

      The map contains palette index to RGB color mappings. Common indices:

      • 0-7: Standard ANSI colors (black, red, green, yellow, blue, magenta, cyan, white)
      • 8-15: Bright ANSI colors
      Returns:
      unmodifiable map of palette index to RGB array, or null if not detected

    • getPaletteColor

      public int[] getPaletteColor(int index)
      Get a specific palette color by index.
      Parameters:
      index - the palette index (0-255)
      Returns:
      the RGB color as [r, g, b] (0-255 each), or null if not available

    • hasForegroundColor

      public boolean hasForegroundColor()
      Check if the foreground color was detected.
      Returns:
      true if foreground RGB is available

    • hasCursorColor

      public boolean hasCursorColor()
      Check if the cursor color was detected.
      Returns:
      true if cursor RGB is available

    • hasPaletteColors

      public boolean hasPaletteColors()
      Check if palette colors were detected.
      Returns:
      true if any palette colors are available

    • hasBackgroundColor

      public boolean hasBackgroundColor()
      Check if the background color was detected.
      Returns:
      true if background RGB is available

    • getForegroundHex

      public String getForegroundHex()
      Get the foreground color as a hex string (e.g., "#FF5733").
      Returns:
      the foreground color in hex format, or null if not detected

    • getBackgroundHex

      public String getBackgroundHex()
      Get the background color as a hex string (e.g., "#1E1E1E").
      Returns:
      the background color in hex format, or null if not detected

    • getForegroundHexValue

      public int getForegroundHexValue()
      Get the foreground color as a hex integer (e.g., 0xFF5733).
      Returns:
      the foreground color as an integer, or -1 if not detected

    • getBackgroundHexValue

      public int getBackgroundHexValue()
      Get the background color as a hex integer (e.g., 0x1E1E1E).
      Returns:
      the background color as an integer, or -1 if not detected

    • hexToRgb

      public static int[] hexToRgb(String hex)
      Parse a hex color string to RGB array.
      Parameters:
      hex - the hex color string (with or without leading #)
      Returns:
      RGB array [r, g, b] with values 0-255, or null if invalid

    • hexToRgb

      public static int[] hexToRgb(int hexValue)
      Parse a hex color integer to RGB array.
      Parameters:
      hexValue - the hex color value (0xRRGGBB)
      Returns:
      RGB array [r, g, b] with values 0-255

    • supportsAnsiColors

      public boolean supportsAnsiColors()
      Check if the terminal supports ANSI colors at all.
      Returns:
      true if at least basic ANSI colors are supported

    • getSuggestedForegroundCode

      public int getSuggestedForegroundCode()
      Get the suggested foreground ANSI color code for text based on the theme.

      If a custom foreground code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a color that contrasts well with the detected background:

      • For dark themes: suggests white/light gray (37)
      • For light themes: suggests black/dark gray (30)
      Returns:
      ANSI color code for suggested foreground

    • getSuggestedErrorCode

      public int getSuggestedErrorCode()
      Get the suggested "error" foreground ANSI color code.

      If a custom error code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a red variant that contrasts well with the detected background:

      • For dark themes: bright red (91)
      • For light themes: dark red (31)
      Returns:
      ANSI color code for suggested error foreground

    • getSuggestedSuccessCode

      public int getSuggestedSuccessCode()
      Get the suggested "success" foreground ANSI color code.

      If a custom success code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a green variant that contrasts well with the detected background.

      Returns:
      ANSI color code for suggested success foreground

    • getSuggestedWarningCode

      public int getSuggestedWarningCode()
      Get the suggested "warning" foreground ANSI color code.

      If a custom warning code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a yellow variant that contrasts well with the detected background.

      Returns:
      ANSI color code for suggested warning foreground

    • getSuggestedInfoCode

      public int getSuggestedInfoCode()
      Get the suggested "info" foreground ANSI color code.

      If a custom info code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a green variant that contrasts well with the detected background. Aligns with JBoss LogManager's color spectrum where INFO maps to yellow-green.

      Returns:
      ANSI color code for suggested info foreground

    • getSuggestedDebugCode

      public int getSuggestedDebugCode()
      Get the suggested "debug" foreground ANSI color code.

      If a custom debug code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a cyan variant for debug-level log messages. Aligns with JBoss LogManager's color spectrum where DEBUG maps to teal/cyan.

      • For dark themes: bright cyan (96)
      • For light themes: dark cyan (36)
      Returns:
      ANSI color code for suggested debug foreground

    • getSuggestedTraceCode

      public int getSuggestedTraceCode()
      Get the suggested "trace" foreground ANSI color code.

      If a custom trace code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a dim color for trace-level log messages (the least prominent log level):

      • For both themes: bright black/gray (90) - very subdued
      Returns:
      ANSI color code for suggested trace foreground

    • getSuggestedTimestampCode

      public int getSuggestedTimestampCode()
      Get the suggested "timestamp" foreground ANSI color code.

      If a custom timestamp code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a neutral gray that is subdued compared to the main message, commonly used for timestamps in log output. Uses 256-color palette grays to closely match JBoss LogManager's DATE color.

      • For dark themes: 252 (light gray, ~rgb 208,208,208)
      • For light themes: 240 (dark gray, ~rgb 88,88,88)
      Returns:
      ANSI color code for suggested timestamp foreground

    • getSuggestedMessageCode

      public int getSuggestedMessageCode()
      Get the suggested "message" foreground ANSI color code.

      If a custom message code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a magenta variant that stands out for highlighted messages in log output.

      • For dark themes: bright magenta (95)
      • For light themes: dark magenta (35)
      Returns:
      ANSI color code for suggested message foreground

    • getSuggestedCategoryCode

      public int getSuggestedCategoryCode()
      Get the suggested "category" (package/class name) foreground ANSI color code.

      If a custom category code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a blue variant suitable for logger/category names in log output. Aligns with JBoss LogManager's ColorPatternFormatter CATEGORY item (HSL 220°, 0.9, 0.8 — a blue hue).

      • For dark themes: bright blue (94)
      • For light themes: dark blue (34)
      Returns:
      ANSI color code for suggested category foreground

    • getSuggestedThreadNameCode

      public int getSuggestedThreadNameCode()
      Get the suggested "thread name" foreground ANSI color code.

      If a custom thread name code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a green variant suitable for thread names in log output. Aligns with JBoss LogManager's ColorPatternFormatter THREAD_NAME item (HSL 120°, 0.429, 0.8 — a muted green).

      • For dark themes: bright green (92)
      • For light themes: dark green (32)
      Returns:
      ANSI color code for suggested thread name foreground

    • getSuggestedFatalCode

      public int getSuggestedFatalCode()
      Get the suggested "fatal" foreground ANSI color code.

      If a custom fatal code was set via the TerminalColorCapability.Builder, it is returned. Otherwise, returns a red variant for fatal-level log messages — the most severe log level. Uses the same red base as error, but typically distinguished by bold styling in usage.

      • For dark themes: bright red (91)
      • For light themes: dark red (31)
      Returns:
      ANSI color code for suggested fatal foreground

    • defaultCapability

      public static TerminalColorCapability defaultCapability()
      Create a default TerminalColorCapability assuming 8 colors and dark theme.
      Returns:
      a default TerminalColorCapability

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • detectColorDepthFromEnvironment

      public static ColorDepth detectColorDepthFromEnvironment()
      Detect color depth from environment variables. This is a fast, non-blocking operation.

      This method delegates to TerminalEnvironment which provides centralized, cached terminal environment detection.

      Returns:
      the detected color depth

    • detectThemeFromEnvironment

      public static TerminalTheme detectThemeFromEnvironment()
      Detect terminal theme from environment variables. This is a fast, non-blocking operation.
      Returns:
      the detected theme, or UNKNOWN if not detectable

    • detectFromEnvironment

      public static TerminalColorCapability detectFromEnvironment()
      Create a TerminalColorCapability by detecting from environment variables only. This is a fast, non-blocking operation that does not query the terminal.
      Returns:
      detected color capabilities based on environment

    • builder

      public static TerminalColorCapability.Builder builder()
      Create a new Builder for constructing a customized TerminalColorCapability.

      Example usage: 

       TerminalColorCapability cap = TerminalColorCapability.builder()
         .colorDepth(ColorDepth.COLORS_256)
         .theme(TerminalTheme.DARK)
         .errorCode(196) // Custom 256-color red
         .successCode(46) // Custom 256-color green
         .timestampCode(244) // Custom gray for timestamps
         .build();
      Returns:
      a new Builder instance

    • builder

      public static TerminalColorCapability.Builder builder(TerminalColorCapability base)
      Create a new Builder initialized with values from an existing capability.

      This allows you to start with detected values and customize specific colors: 

       TerminalColorCapability detected = TerminalColorDetector.detect(connection);
 TerminalColorCapability custom = TerminalColorCapability.builder(detected)
         .errorCode(196) // Override just the error color
         .build();
      Parameters:
      base - the existing capability to copy values from
      Returns:
      a new Builder initialized with the base capability's values