Color Detection

import org.aesh.terminal.utils.TerminalColorCapability;

TerminalColorCapability cap = TerminalColorCapability.detectFromEnvironment();

if (cap.getTheme().isDark()) {
    // Use light text colors
} else {
    // Use dark text colors
}

import org.aesh.readline.terminal.TerminalColorDetector;
import org.aesh.readline.tty.terminal.TerminalConnection;

TerminalConnection connection = new TerminalConnection();
TerminalColorCapability cap = TerminalColorDetector.detect(connection);

System.out.println("Theme: " + cap.getTheme());
System.out.println("Color depth: " + cap.getColorDepth());

// Detects once and caches for 5 minutes
TerminalColorCapability cap = TerminalColorDetector.detectCached(connection);

TerminalColorCapability cap = TerminalColorDetector.detect(connection);

// Theme detection
TerminalTheme theme = cap.getTheme();        // DARK, LIGHT, or UNKNOWN
boolean isDark = cap.getTheme().isDark();    // true for DARK or UNKNOWN

// Color depth
ColorDepth depth = cap.getColorDepth();
boolean has256 = depth.supports256Colors();
boolean hasTrueColor = depth.supportsTrueColor();

// Actual RGB colors (may be null if not detectable)
int[] fgRGB = cap.getForegroundRGB();     // [r, g, b] or null
int[] bgRGB = cap.getBackgroundRGB();     // [r, g, b] or null
int[] cursorRGB = cap.getCursorRGB();     // [r, g, b] or null

// Palette colors (ANSI 16 colors, indices 0-15)
if (cap.hasPaletteColors()) {
    Map<Integer, int[]> palette = cap.getPaletteColors();
    int[] red = cap.getPaletteColor(1);   // Standard red
    int[] brightRed = cap.getPaletteColor(9);  // Bright red
}

TerminalColorCapability cap = TerminalColorDetector.detect(connection);

// These return appropriate codes for the detected background
int normalText = cap.getSuggestedForegroundCode();  // 30 (black) or 37 (white)
int errorText = cap.getSuggestedErrorCode();        // 31 or 91 (red variants)
int successText = cap.getSuggestedSuccessCode();    // 32 or 92 (green variants)
int warningText = cap.getSuggestedWarningCode();    // 33 or 93 (yellow variants)
int infoText = cap.getSuggestedInfoCode();          // 34 or 94 (blue variants)
int debugText = cap.getSuggestedDebugCode();        // 90 or 37 (gray/white variants)
int traceText = cap.getSuggestedTraceCode();        // 90 (gray - least prominent)
int timestampText = cap.getSuggestedTimestampCode(); // 36 or 96 (cyan variants)
int messageText = cap.getSuggestedMessageCode();     // 35 or 95 (magenta variants)

// Use in ANSI escape sequences
connection.write("\u001B[" + errorText + "mError: Something went wrong\u001B[0m\n");

// Start with detected capability and customize specific colors
TerminalColorCapability detected = TerminalColorDetector.detect(connection);
TerminalColorCapability custom = TerminalColorCapability.builder(detected)
    .errorCode(196)      // Custom 256-color bright red
    .successCode(46)     // Custom 256-color green
    .timestampCode(244)  // Custom 256-color gray for timestamps
    .build();

// Now getSuggestedErrorCode() returns 196 instead of theme-based default
int error = custom.getSuggestedErrorCode();  // Returns 196

TerminalColorCapability custom = TerminalColorCapability.builder()
    .colorDepth(ColorDepth.COLORS_256)
    .theme(TerminalTheme.DARK)
    .errorCode(196)
    .successCode(46)
    .warningCode(208)
    .infoCode(39)
    .debugCode(250)      // 256-color light gray
    .traceCode(240)      // 256-color dark gray
    .timestampCode(244)
    .messageCode(255)
    .foregroundCode(252)
    .build();

ColorDepth depth = cap.getColorDepth();

if (depth.supportsTrueColor()) {
    // Use full RGB colors
    connection.write("\u001B[38;2;255;128;0mOrange text\u001B[0m");
} else if (depth.supports256Colors()) {
    // Use 256-color palette
    connection.write("\u001B[38;5;208mOrange text\u001B[0m");
} else {
    // Fall back to basic colors
    connection.write("\u001B[33mYellow text\u001B[0m");
}

TerminalTheme theme = cap.getTheme();

switch (theme) {
    case DARK:
        // Use bright/light colors for text
        break;
    case LIGHT:
        // Use dark colors for text
        break;
    case UNKNOWN:
        // Default to dark theme assumption
        break;
}

// Helper method - returns true for DARK and UNKNOWN
if (theme.isDark()) {
    // Use light colors
}

// Query background color (OSC 11)
int[] bg = connection.queryBackgroundColor(500);
if (bg != null) {
    int r = bg[0], g = bg[1], b = bg[2];
    boolean isDark = (r + g + b) / 3 < 128;
    System.out.println("Background: RGB(" + r + "," + g + "," + b + ")");
}

// Query foreground color (OSC 10)
int[] fg = connection.queryForegroundColor(500);

// Query cursor color (OSC 12)
int[] cursor = connection.queryCursorColor(500);

// Generic OSC query for any code
String result = connection.queryOsc(oscCode, "?", 500, responseParser);

import org.aesh.terminal.tty.TerminalColorDetector;
import org.aesh.terminal.utils.ANSI;

// Query foreground, background, and cursor in one operation (~50-100ms vs ~600ms)
Map<Integer, int[]> colors = TerminalColorDetector.queryColors(connection, 500);

int[] fg = colors.get(ANSI.OSC_FOREGROUND);   // OSC 10
int[] bg = colors.get(ANSI.OSC_BACKGROUND);   // OSC 11
int[] cursor = colors.get(ANSI.OSC_CURSOR_COLOR);  // OSC 12

// Query multiple palette colors at once
Map<Integer, int[]> palette = TerminalColorDetector.queryPaletteColors(
    connection, 500, 0, 1, 2, 3, 4, 5, 6, 7);

// Query all 16 ANSI colors
Map<Integer, int[]> ansi16 = TerminalColorDetector.queryAnsi16Colors(connection, 500);

// Always returns colors - actual or estimated based on environment
Map<Integer, int[]> colors = TerminalColorDetector.queryColorsWithFallback(connection, 500);

int[] bg = colors.get(ANSI.OSC_BACKGROUND);
// bg is never null - will be estimated if OSC queries failed

// Check if it's a dark theme
boolean isDark = TerminalColorDetector.isDarkColor(bg);

// Check if OSC queries are supported
if (TerminalColorDetector.isOscColorQuerySupported(connection)) {
    // OSC queries will work
    Map<Integer, int[]> colors = TerminalColorDetector.queryColors(connection, 500);
} else {
    // Use environment-based detection
    TerminalTheme theme = TerminalColorDetector.detectThemeFromEnvironment();
}

// Check palette query support specifically
if (connection.supportsPaletteQuery()) {
    Map<Integer, int[]> palette = TerminalColorDetector.queryAnsi16Colors(connection, 500);
}

// Query device attributes first
DeviceAttributes da = connection.queryPrimaryDeviceAttributes(500);

// Check if OSC queries are likely supported
if (connection.supportsOscQueries(da)) {
    int[] bgColor = connection.queryBackgroundColor(500);
    // ...
}

// Or use combined query-based check
if (connection.querySupportsOscQueries(500)) {
    // Terminal likely supports OSC queries
}

int[] bgColor = connection.queryBackgroundColor(500);

if (bgColor != null) {
    // Convert to 256-color palette index
    int paletteIndex = ANSI.rgbTo256Color(bgColor[0], bgColor[1], bgColor[2]);

    // Convert to basic ANSI foreground code (30-37 or 90-97)
    int ansiCode = ANSI.rgbToAnsiColor(bgColor[0], bgColor[1], bgColor[2]);

    // Check brightness for theme detection
    boolean isDark = !ANSI.rgbIsBright(bgColor[0], bgColor[1], bgColor[2]);

    // Reverse conversion: get RGB from palette index
    int[] rgb = ANSI.color256ToRgb(paletteIndex);
}

import org.aesh.terminal.utils.TerminalEnvironment;

TerminalEnvironment env = TerminalEnvironment.getInstance();

// Check if running in a multiplexer
if (env.isInTmux()) {
    System.out.println("Running inside tmux");
}

if (env.isInMultiplexer()) {
    System.out.println("Running inside tmux or screen");
}

// Check if passthrough is enabled
if (env.isTmuxPassthroughEnabled()) {
    System.out.println("OSC passthrough is enabled");
}

// Legacy static methods still work
if (TerminalColorDetector.isRunningInTmux()) {
    System.out.println("Running inside tmux");
}

# In tmux.conf
set -g allow-passthrough on

# Or at runtime
tmux set -g allow-passthrough on

import org.aesh.readline.terminal.TerminalColorDetector;
import org.aesh.readline.tty.terminal.TerminalConnection;
import org.aesh.terminal.utils.TerminalColorCapability;

public class AdaptiveColorApp {
    private static final String RESET = "\u001B[0m";
    
    public static void main(String[] args) throws Exception {
        TerminalConnection connection = new TerminalConnection();
        TerminalColorCapability cap = TerminalColorDetector.detect(connection);
        
        // Get theme-appropriate colors
        int error = cap.getSuggestedErrorCode();
        int success = cap.getSuggestedSuccessCode();
        int info = cap.getSuggestedInfoCode();
        
        // Display messages with appropriate colors
        connection.write("\u001B[" + info + "m[INFO]\u001B[0m Application started\n");
        connection.write("\u001B[" + success + "m[OK]\u001B[0m Configuration loaded\n");
        connection.write("\u001B[" + error + "m[ERROR]\u001B[0m Unable to connect\n");
        
        // Show detection results
        connection.write("\nDetected: " + cap.getTheme() + " theme, " + 
                        cap.getColorDepth() + "\n");
        
        if (cap.hasBackgroundColor()) {
            int[] bg = cap.getBackgroundRGB();
            connection.write("Background: RGB(" + bg[0] + "," + bg[1] + "," + bg[2] + ")\n");
        }
        
        connection.close();
    }
}

// Good: Detect once at startup
public class MyApp {
    private static TerminalColorCapability colors;
    
    public static void main(String[] args) {
        TerminalConnection conn = new TerminalConnection();
        colors = TerminalColorDetector.detectCached(conn);
        // Use 'colors' throughout the application
    }
}

// With custom timeout (milliseconds)
TerminalColorCapability cap = TerminalColorDetector.detect(connection, 100);

import org.aesh.readline.terminal.formatting.TerminalColor;
import org.aesh.terminal.utils.TerminalColorCapability;

TerminalColorCapability cap = TerminalColorDetector.detect(connection);

// These methods automatically choose appropriate colors for the theme
TerminalColor error = TerminalColor.forError(cap);          // Red, bright on dark
TerminalColor success = TerminalColor.forSuccess(cap);      // Green, bright on dark
TerminalColor warning = TerminalColor.forWarning(cap);      // Yellow, bright on dark
TerminalColor info = TerminalColor.forInfo(cap);            // Cyan/Blue, bright on dark
TerminalColor highlight = TerminalColor.forHighlight(cap);  // Emphasized text
TerminalColor muted = TerminalColor.forMuted(cap);          // Secondary/dim text
TerminalColor timestamp = TerminalColor.forTimestamp(cap);  // Cyan, for log timestamps
TerminalColor message = TerminalColor.forMessage(cap);      // Magenta, for highlighted messages

TerminalColorCapability cap = TerminalColorDetector.detectCached(connection);

// Create semantic colors once
TerminalColor errorColor = TerminalColor.forError(cap);
TerminalColor successColor = TerminalColor.forSuccess(cap);
TerminalColor infoColor = TerminalColor.forInfo(cap);

// Use with TerminalString
TerminalString errorMsg = new TerminalString("[ERROR] Connection failed", errorColor);
TerminalString okMsg = new TerminalString("[OK] Connected", successColor);
TerminalString infoMsg = new TerminalString("[INFO] Processing...", infoColor);

connection.write(errorMsg.toString() + "\n");
connection.write(okMsg.toString() + "\n");
connection.write(infoMsg.toString() + "\n");

TerminalColorCapability cap = TerminalColorDetector.detect(connection);
ANSIBuilder builder = ANSIBuilder.builder(cap);

// Log line with timestamp, level, and message
connection.write(builder
    .timestamp("2024-01-15 10:30:45").append(" ")
    .error("[ERROR]").append(" ")
    .append("Connection to database failed")
    .toLine());

builder.reset();
connection.write(builder
    .timestamp("2024-01-15 10:30:46").append(" ")
    .warning("[WARN]").append(" ")
    .append("Low memory condition detected")
    .toLine());

builder.reset();
connection.write(builder
    .timestamp("2024-01-15 10:30:47").append(" ")
    .info("[INFO]").append(" ")
    .message("Application started successfully")
    .toLine());

builder.reset();
connection.write(builder
    .timestamp("2024-01-15 10:30:48").append(" ")
    .debug("[DEBUG]").append(" ")
    .append("Configuration loaded from /etc/app.conf")
    .toLine());

builder.reset();
connection.write(builder
    .timestamp("2024-01-15 10:30:49").append(" ")
    .trace("[TRACE]").append(" ")
    .append("Entering method processRequest()")
    .toLine());

// Create an RGB color
TerminalColor brandColor = TerminalColor.fromHex("#FF5733");

// Adapt to terminal capabilities
TerminalColor adapted = brandColor.forCapability(cap);

// 'adapted' will be:
// - The original RGB if terminal supports true color
// - Nearest 256-color palette index if terminal supports 256 colors
// - Nearest basic 16 color if terminal only supports basic colors