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

    • hasForegroundColor

      public boolean hasForegroundColor()
      Check if the foreground color was detected.
      Returns:
      true if foreground RGB is 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 cyan/blue variant that contrasts well with the detected background.

      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 subdued color for debug-level log messages:

      • For dark themes: white (37) - visible but not colorful
      • For light themes: bright black/gray (90) - subdued
      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 cyan variant that is subdued compared to the main message, commonly used for timestamps in log output.

      • For dark themes: bright cyan (96)
      • For light themes: dark cyan (36)
      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

    • 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.
      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