Package org.aesh.terminal.formatting

Class TerminalColor

java.lang.Object
org.aesh.terminal.formatting.TerminalColor
public class TerminalColor extends Object
Represents a combination of foreground and background colors for terminal output.

Supports three color modes:

  • Basic 8/16 colors using Color enum
  • 256 colors using palette indices (0-255)
  • True color (24-bit RGB) using RGB values

Also provides theme-aware factory methods that automatically select appropriate colors based on detected terminal capabilities.

Author:
Ståle W. Pedersen

  • Constructor Details

    • TerminalColor

      public TerminalColor()
      Create a default TerminalColor with no formatting.

    • TerminalColor

      public TerminalColor(Color text, Color background)
      Create a TerminalColor with the specified foreground and background colors.
      Parameters:
      text - the foreground color
      background - the background color

    • TerminalColor

      public TerminalColor(Color textColor, Color background, Color.Intensity intensity)
      Create a TerminalColor with the specified colors and intensity.
      Parameters:
      textColor - the foreground color
      background - the background color
      intensity - the color intensity

    • TerminalColor

      public TerminalColor(int text, int background)
      Create a TerminalColor using 256-color palette indices.

      0x00-0x07: standard colors (as in ESC [ 30..37 m) 0x08-0x0f: high intensity colors (as in ESC [ 90..97 m) 0x10-0xe7: 6*6*6=216 colors: 16 + 36*r + 6*g + b (0 le r,g,b le 5) 0xe8-0xff: grayscale from black to white in 24 steps

      Parameters:
      text - foreground color index (0-255)
      background - background color index (0-255)

    • TerminalColor

      public TerminalColor(int text, Color background)
      Create a TerminalColor with 256-color foreground and basic background.
      Parameters:
      text - foreground color index (0-255)
      background - background color

    • TerminalColor

      public TerminalColor(int text, Color background, Color.Intensity intensity)
      Create a TerminalColor with 256-color foreground, basic background, and intensity.
      Parameters:
      text - foreground color index (0-255)
      background - background color
      intensity - the color intensity

    • TerminalColor

      public TerminalColor(Color text, int background)
      Create a TerminalColor with basic foreground and 256-color background.
      Parameters:
      text - foreground color
      background - background color index (0-255)

    • TerminalColor

      public TerminalColor(Color text, int background, Color.Intensity intensity)
      Create a TerminalColor with basic foreground, 256-color background, and intensity.
      Parameters:
      text - foreground color
      background - background color index (0-255)
      intensity - the color intensity

  • Method Details

    • fromRGB

      public static TerminalColor fromRGB(int r, int g, int b)
      Create a TerminalColor with true color (24-bit RGB) foreground.
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      a new TerminalColor with RGB foreground

    • fromRGB

      public static TerminalColor fromRGB(int textR, int textG, int textB, int bgR, int bgG, int bgB)
      Create a TerminalColor with true color (24-bit RGB) foreground and background.
      Parameters:
      textR - foreground red component (0-255)
      textG - foreground green component (0-255)
      textB - foreground blue component (0-255)
      bgR - background red component (0-255)
      bgG - background green component (0-255)
      bgB - background blue component (0-255)
      Returns:
      a new TerminalColor with RGB foreground and background

    • fromHex

      public static TerminalColor fromHex(String hex)
      Create a TerminalColor with true color foreground from hex string.
      Parameters:
      hex - hex color string (e.g., "#FF5733" or "FF5733")
      Returns:
      a new TerminalColor with RGB foreground, or default if invalid

    • fromHex

      public static TerminalColor fromHex(String textHex, String bgHex)
      Create a TerminalColor with true color foreground and background from hex strings.
      Parameters:
      textHex - foreground hex color string
      bgHex - background hex color string
      Returns:
      a new TerminalColor with RGB colors, or default if invalid

    • fromHSL

      public static TerminalColor fromHSL(float h, float s, float l)
      Create a TerminalColor with true color foreground from HSL values.

      HSL (Hue, Saturation, Lightness) is often more intuitive for generating color palettes and gradients than RGB.

      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      a new TerminalColor with RGB foreground converted from HSL

    • fromHSL

      public static TerminalColor fromHSL(float textH, float textS, float textL, float bgH, float bgS, float bgL)
      Create a TerminalColor with true color foreground and background from HSL values.
      Parameters:
      textH - foreground hue in degrees (0-360)
      textS - foreground saturation as percentage (0-100)
      textL - foreground lightness as percentage (0-100)
      bgH - background hue in degrees (0-360)
      bgS - background saturation as percentage (0-100)
      bgL - background lightness as percentage (0-100)
      Returns:
      a new TerminalColor with RGB colors converted from HSL

    • hslToRgb

      public static int[] hslToRgb(float h, float s, float l)
      Convert HSL (Hue, Saturation, Lightness) to RGB color values.

      This is useful for generating color palettes, as HSL makes it easy to:

      • Create color variations by adjusting lightness
      • Generate harmonious colors by rotating hue
      • Control color intensity via saturation
      Parameters:
      h - hue in degrees (0-360), wraps around
      s - saturation as percentage (0-100), clamped
      l - lightness as percentage (0-100), clamped
      Returns:
      RGB array [r, g, b] with values 0-255

    • rgbToHsl

      public static float[] rgbToHsl(int r, int g, int b)
      Convert RGB color values to HSL (Hue, Saturation, Lightness).

      Useful for analyzing colors or adjusting their properties.

      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      HSL array [h, s, l] where h is 0-360 and s,l are 0-100

    • getTextHSL

      public float[] getTextHSL()
      Get the foreground color as HSL values, if using true color.
      Returns:
      HSL array [h, s, l] or null if not using RGB foreground

    • getBackgroundHSL

      public float[] getBackgroundHSL()
      Get the background color as HSL values, if using true color.
      Returns:
      HSL array [h, s, l] or null if not using RGB background

    • isTrueColor

      public boolean isTrueColor()
      Check if this color uses true color (24-bit RGB) mode.
      Returns:
      true if using RGB colors

    • getTextRGB

      public int[] getTextRGB()
      Get the foreground RGB values if using true color.
      Returns:
      RGB array [r, g, b] or null if not using RGB foreground

    • getBackgroundRGB

      public int[] getBackgroundRGB()
      Get the background RGB values if using true color.
      Returns:
      RGB array [r, g, b] or null if not using RGB background

    • forError

      public static TerminalColor forError(TerminalColorCapability capability)
      Create a TerminalColor appropriate for error messages based on terminal theme.

      For dark themes, uses bright red. For light themes, uses dark red.

      Parameters:
      capability - the detected terminal color capability
      Returns:
      a TerminalColor suitable for error messages

    • forSuccess

      public static TerminalColor forSuccess(TerminalColorCapability capability)
      Create a TerminalColor appropriate for success messages based on terminal theme.

      For dark themes, uses bright green. For light themes, uses dark green.

      Parameters:
      capability - the detected terminal color capability
      Returns:
      a TerminalColor suitable for success messages

    • forWarning

      public static TerminalColor forWarning(TerminalColorCapability capability)
      Create a TerminalColor appropriate for warning messages based on terminal theme.

      For dark themes, uses bright yellow. For light themes, uses dark yellow/orange.

      Parameters:
      capability - the detected terminal color capability
      Returns:
      a TerminalColor suitable for warning messages

    • forInfo

      public static TerminalColor forInfo(TerminalColorCapability capability)
      Create a TerminalColor appropriate for info messages based on terminal theme.

      For dark themes, uses bright blue/cyan. For light themes, uses dark blue.

      Parameters:
      capability - the detected terminal color capability
      Returns:
      a TerminalColor suitable for info messages

    • forHighlight

      public static TerminalColor forHighlight(TerminalColorCapability capability)
      Create a TerminalColor appropriate for highlighted/emphasized text.

      For dark themes, uses bright white. For light themes, uses black.

      Parameters:
      capability - the detected terminal color capability
      Returns:
      a TerminalColor suitable for highlighted text

    • forMuted

      public static TerminalColor forMuted(TerminalColorCapability capability)
      Create a TerminalColor appropriate for muted/secondary text.

      Uses gray tones that are visible but not prominent.

      Parameters:
      capability - the detected terminal color capability
      Returns:
      a TerminalColor suitable for muted text

    • forTimestamp

      public static TerminalColor forTimestamp(TerminalColorCapability capability)
      Create a TerminalColor appropriate for timestamps in log output.

      Uses cyan tones that are subdued compared to the main message content, making timestamps visible but not distracting.

      Parameters:
      capability - the detected terminal color capability
      Returns:
      a TerminalColor suitable for timestamps

    • forMessage

      public static TerminalColor forMessage(TerminalColorCapability capability)
      Create a TerminalColor appropriate for highlighted messages in log output.

      Uses magenta tones that stand out from regular text and other log elements, suitable for emphasizing important message content.

      Parameters:
      capability - the detected terminal color capability
      Returns:
      a TerminalColor suitable for highlighted messages

    • forCapability

      public TerminalColor forCapability(TerminalColorCapability capability)
      Create the best representation of this color for the given terminal capability.

      If the terminal doesn't support true color but this TerminalColor uses RGB, it will be downgraded to the nearest 256-color or 16-color equivalent.

      Parameters:
      capability - the terminal's color capability
      Returns:
      a TerminalColor compatible with the terminal's capabilities

    • toColor256

      public TerminalColor toColor256()
      Convert RGB color to nearest 256-color palette index.
      Returns:
      a new TerminalColor using 256-color mode

    • toColor16

      public TerminalColor toColor16()
      Convert RGB color to nearest 16-color.
      Returns:
      a new TerminalColor using basic 16 colors

    • isFormatted

      public boolean isFormatted()
      Check if this color has any formatting applied.
      Returns:
      true if any color is set (not all defaults)

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • fullString

      public String fullString()
      Get the full ANSI escape sequence for this color.
      Returns:
      the complete ANSI color code

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getLength

      public int getLength()
      Get the length of the ANSI escape sequence.
      Returns:
      the length of the color code string

    • write

      public void write(PrintStream out)
      Write the color code to a print stream.
      Parameters:
      out - the output stream to write to

    • toString

      public String toString(TerminalColor prev)
      Get the ANSI codes for this color relative to a previous color. Only outputs codes for attributes that differ from the previous color.
      Parameters:
      prev - the previous terminal color
      Returns:
      the ANSI codes for changed attributes