Fl_Terminal

Terminal widget with ANSI/xterm escape code support and Unicode

Overview

The Fl_Terminal widget is an output-only text widget supporting ASCII and UTF-8/Unicode with VT100/xterm style escape sequences, text colors and attributes, scrollback history, and mouse selection.

Fl_Terminal does not handle stdio redirection, pseudo ttys, or keyboard input processing. It is output-only. For advanced features, subclass the widget.

Constructor

Fl_Terminal · constructor

Creates a new terminal widget.

X · int · required

X position of the widget

Y · int · required

Y position of the widget

W · int · required

Width of the widget

H · int · required

Height of the widget

L · const char* · default: "0"

Optional label for the widget

Text Output

append · void

Appends text to the terminal.

s · const char* · required

Text to append (supports ANSI escape codes)

len · int · default: "-1"

Length of text (-1 for null-terminated string)

printf · void

Appends formatted text to the terminal.

fmt · const char* · required

Printf-style format string

... · ... · required

Variable arguments

Limited to 1024 characters. For longer strings, use append().

print_char · void

Prints a single character at the cursor position.

c · char · required

Character to print

plot_char · void

Plots a character at a specific row/column position.

c · char · required

Character to plot

drow · int · required

Display row (0-based)

dcol · int · required

Display column (0-based)

Screen Control

clear · void

Clears the entire display and history.

clear_screen · void

Clears the screen (ESC [ 2 J).

scroll_to_hist · bool · default: "true"

Whether to scroll current screen to history

clear_screen_home · void

Clears screen and homes cursor (ESC [ H ESC [ 2 J).

scroll_to_hist · bool · default: "true"

Whether to scroll current screen to history

clear_history · void

Clears the scrollback history (ESC [ 3 J).

reset_terminal · void

Resets the terminal to initial state (ESC c).

cursor_home · void

Homes the cursor to position 0,0 (ESC [ H).

Cursor Control

cursor_row · int

Returns the current cursor row (0-based).

cursor_col · int

Returns the current cursor column (0-based).

cursorfgcolor · void

Sets the cursor foreground color.

val · Fl_Color · required

Color value

cursorbgcolor · void

Sets the cursor background color.

val · Fl_Color · required

Color value

Colors

textfgcolor · void

Sets the default text foreground color.

val · Fl_Color · required

Color value (0xRRGGBB00 format)

textbgcolor · void

Sets the default text background color.

val · Fl_Color · required

Color value (0xffffffff for transparent)

textfgcolor_default · void

Sets the default foreground color used by ESC[0m reset.

val · Fl_Color · required

Color value

textbgcolor_default · void

Sets the default background color used by ESC[0m reset.

val · Fl_Color · required

Color value

Display Settings

display_columns · void

Sets the display width in columns.

val · int · required

Number of columns

display_rows · void

Sets the display height in rows.

val · int · required

Number of rows

history_lines · void

Sets the number of scrollback history lines.

val · int · required

Number of history lines

ansi · void

Enables or disables ANSI escape sequence parsing.

val · bool · required

true to enable, false to disable

Margins

margin_left · void

Sets the left margin in pixels.

val · int · required

Margin size

margin_right · void

Sets the right margin in pixels.

val · int · required

Margin size

margin_top · void

Sets the top margin in pixels.

val · int · required

Margin size

margin_bottom · void

Sets the bottom margin in pixels.

val · int · required

Margin size

Redraw Control

redraw_style · void

Sets when the terminal redraws.

val · RedrawStyle · required

• NO_REDRAW - App must call redraw()
• RATE_LIMITED - Timer controlled (default)
• PER_WRITE - After every append()/printf()

redraw_rate · void

Sets the maximum redraw rate in seconds.

val · float · required

Redraw rate (default 0.10)

Selection

selection_text · const char*

Returns the currently selected text.

Returns pointer to selected text, or NULL if no selection.

selection_text_len · int

Returns the length of the selected text.

Text Attributes

The following text attributes can be set via ANSI escape codes:

• Bold - \033[1m - Brighter/thicker text
• Dim - \033[2m - Lower brightness
• Italic - \033[3m - Italicized text
• Underline - \033[4m - Underlined text
• Inverse - \033[7m - Swap foreground/background
• Strikeout - \033[9m - Line through text
• Normal - \033[0m - Reset to normal

Color Codes

3-bit Colors (8 colors)

// Foreground colors
tty->append("\033[30m Black \033[0m\n");     // 30-37
tty->append("\033[31m Red \033[0m\n");
tty->append("\033[32m Green \033[0m\n");
tty->append("\033[33m Yellow \033[0m\n");
tty->append("\033[34m Blue \033[0m\n");
tty->append("\033[35m Magenta \033[0m\n");
tty->append("\033[36m Cyan \033[0m\n");
tty->append("\033[37m White \033[0m\n");

// Background colors (40-47)
tty->append("\033[41m Red Background \033[0m\n");

24-bit RGB Colors

// Foreground: ESC[38;2;R;G;Bm
tty->append("\033[38;2;255;0;0m Red Text \033[0m\n");

// Background: ESC[48;2;R;G;Bm  
tty->append("\033[48;2;0;0;255m Blue Background \033[0m\n");

Example

#include <FL/Fl_Terminal.H>
#include <FL/Fl_Window.H>

int main() {
  Fl_Window *win = new Fl_Window(640, 480, "Terminal");
  Fl_Terminal *tty = new Fl_Terminal(10, 10, 620, 460);
  
  tty->history_lines(1000);
  tty->ansi(true);
  
  // Simple output
  tty->append("Hello world!\n");
  
  // Colored output
  tty->append("\033[31mRed text\033[0m\n");
  tty->append("\033[1;32mBold green\033[0m\n");
  
  // RGB colors
  tty->append("\033[38;2;255;128;0mOrange text\033[0m\n");
  
  // Printf formatting
  tty->printf("Value: %.2f\n", 3.14159);
  
  // Clear screen
  tty->clear_screen_home();
  
  win->end();
  win->show();
  return Fl::run();
}

Advanced Example with Timer

void update_timer(void *data) {
  Fl_Terminal *tty = (Fl_Terminal*)data;
  time_t t = time(NULL);
  tty->printf("Time: %s", ctime(&t));
  Fl::repeat_timeout(1.0, update_timer, data);
}

int main() {
  // ... create window and terminal ...
  
  Fl::add_timeout(1.0, update_timer, tty);
  
  // ... show and run ...
}

See Also

• Fl_Text_Display - Multi-line text display widget
• Fl_Text_Editor - Text editor with input support