FLTK 1.4.4

Loading...
Searching...
No Matches
Fl_Terminal Class Reference

Terminal widget supporting Unicode/utf-8, ANSI/xterm escape codes with full RGB color control. More...

`#include <Fl_Terminal.H>`

Inheritance diagram for Fl_Terminal:

## Classes
class | CharStyle
class | Cursor
class | EscapeSeq
class | Margin
class | PartialUtf8Buf
class | RingBuffer
class | Selection
class | Utf8Char

## Public Types
enum | Attrib { NORMAL = 0x00 , BOLD = 0x01 , DIM = 0x02 , ITALIC = 0x04 , UNDERLINE = 0x08 , _RESERVED_1 = 0x10 , INVERSE = 0x20 , _RESERVED_2 = 0x40 , STRIKEOUT = 0x80 }
| Bits for the per-character attributes, which control text features such as italic, bold, underlined text, etc. More...
enum | CharFlags { FG_XTERM = 0x01 , BG_XTERM = 0x02 , EOL = 0x04 , RESV_A = 0x08 , RESV_B = 0x10 , RESV_C = 0x20 , RESV_D = 0x40 , RESV_E = 0x80 , COLORMASK = (FG_XTERM | BG_XTERM) }
| Per-character 8 bit flags (uchar) used to manage special states for characters. More...
enum | OutFlags { OFF = 0x00 , CR_TO_LF = 0x01 , LF_TO_CR = 0x02 , LF_TO_CRLF = 0x04 }
| Output translation flags for special control character translations. More...
enum | RedrawStyle { NO_REDRAW =0 , RATE_LIMITED , PER_WRITE }
| Determines when Fl_Terminal calls redraw() if new text is added. More...
enum | ScrollbarStyle { SCROLLBAR_OFF = 0x00 , SCROLLBAR_AUTO = 0x01 , SCROLLBAR_ON = 0x02 }
| Behavior of scrollbars. More...

## Public Member Functions
void | ansi (bool val)
| Enable/disable the ANSI mode flag.
bool | ansi (void) const
| Return the state of the ANSI flag.
void | append (const char *s, int len=-1)
| Appends string `s` to the terminal at the current cursor position using the current text color/attributes.
void | append_ascii (const char *s)
| Append NULL terminated ASCII string to terminal, slightly more efficient than append_utf8().
void | append_utf8 (const char *buf, int len=-1)
| Append NULL terminated UTF-8 string to terminal.
void | box (Fl_Boxtype val)
| Sets the box type, updates terminal margins et al.
Fl_Boxtype | box (void) const
| Returns the current box type.
void | clear (Fl_Color val)
| Clears the screen to a specific color `val` and homes the cursor.
void | clear (void)
| Clears the screen to the current textbgcolor(), and homes the cursor.
void | clear_history (void)
| Clears the scroll history buffer and adjusts scrollbar, forcing it to redraw().
void | clear_screen (bool scroll_to_hist=true)
| Clear the terminal screen only; does not affect the cursor position.
void | clear_screen_home (bool scroll_to_hist=true)
| Clear the terminal screen and home the cursor.
void | color (Fl_Color val)
| Sets the background color for the terminal's Fl_Group::box().
Fl_Color | color (void) const
| Return base widget Fl_Group's box() color()
int | cursor_col (void) const
| Return the cursor's current column position on the screen.
void | cursor_home (void)
| Move cursor to the home position (top/left).
int | cursor_row (void) const
| Return the cursor's current row position on the screen.
void | cursorbgcolor (Fl_Color val)
| Set the cursor's background color used for the cursor itself.
Fl_Color | cursorbgcolor (void) const
| Get the cursor's background color used for the cursor itself.
void | cursorfgcolor (Fl_Color val)
| Set the cursor's foreground color used for text under the cursor.
Fl_Color | cursorfgcolor (void) const
| Get the cursor's foreground color used for text under the cursor.
void | display_columns (int val)
| Set terminal's display width in columns of text characters.
int | display_columns (void) const
| Return terminal's display width in columns of text characters.
void | display_rows (int val)
| Set terminal's display height in lines of text (rows).
int | display_rows (void) const
| Return terminal's display height in lines of text (rows).
void | draw (void) FL_OVERRIDE
| Draws the entire Fl_Terminal.
void | error_char (const char *val)
| Sets the "error character" utf8 string shown for invalid utf8 or bad ANSI sequences if show_unknown() is true.
const char * | error_char (void) const
| Returns the "error character" utf8 string, which is shown for invalid utf8 or bad ANSI sequences if show_unknown() is true.
| Fl_Terminal (int X, int Y, int W, int H, const char *L, int rows, int cols, int hist)
| Same as the default FLTK constructor, but lets the user force the rows, columns and history to specific sizes on creation.
| Fl_Terminal (int X, int Y, int W, int H, const char *L=0)
| The constructor for Fl_Terminal.
int | handle (int e) FL_OVERRIDE
| Handle FLTK events.
void | history_lines (int val)
| Set the number of lines of screen history.
int | history_lines (void) const
| Return the number of lines of screen history.
void | history_rows (int val)
| Set terminal's scrollback history buffer size in lines of text (rows).
int | history_rows (void) const
| Return terminal's scrollback history buffer size in lines of text (rows).
int | history_use (void) const
| Returns how many lines are "in use" by the screen history buffer.
void | hscrollbar_style (ScrollbarStyle val)
| Set the horizontal scrollbar behavior style.
ScrollbarStyle | hscrollbar_style (void) const
| Get the horizontal scrollbar behavior style.
void | margin_bottom (int val)
| Set the bottom margin; see Margins.
int | margin_bottom (void) const
| Return the bottom margin; see Margins.
void | margin_left (int val)
| Set the left margin; see Margins.
int | margin_left (void) const
| Return the left margin; see Margins.
void | margin_right (int val)
| Set the right margin; see Margins.
int | margin_right (void) const
| Return the right margin; see Margins.
void | margin_top (int val)
| Set the top margin; see Margins.
int | margin_top (void) const
| Return the top margin; see Margins.
void | output_translate (Fl_Terminal::OutFlags val)
| Sets the combined output translation flags to `val`.
Fl_Terminal::OutFlags | output_translate (void) const
| Return the current combined output translation flags.
void | plot_char (char c, int drow, int dcol)
| Plot the ASCII character `c` at the terminal's display position ``(drow,dcol).
void | plot_char (const char *text, int len, int drow, int dcol)
| Plot the UTF-8 character `text` of length `len` at display position ``(drow,dcol).
void | print_char (char c)
| Prints single ASCII char `c` at current cursor position, and advances the cursor.
void | print_char (const char *text, int len=-1)
| Prints single UTF-8 char `text` of optional byte length `len` at current cursor position, and advances the cursor if the character is printable.
void | printf (const char *fmt,...)
| Appends printf formatted messages to the terminal.
void | redraw_rate (float val)
| Set the maximum rate redraw speed in floating point seconds if redraw_style() is set to RATE_LIMITED.
float | redraw_rate (void) const
| Get max rate redraw speed in floating point seconds.
void | redraw_style (RedrawStyle val)
| Set how Fl_Terminal manages screen redrawing.
RedrawStyle | redraw_style (void) const
| Get the redraw style.
void | reset_terminal (void)
| Resets terminal to default colors, clears screen, history and mouse selection, homes cursor, resets tabstops.
void | resize (int X, int Y, int W, int H) FL_OVERRIDE
| Handle widget resizing, such as if user resizes parent window.
int | scrollbar_actual_size (void) const
| Returns the scrollbar's actual "trough size", which is the width of FL_VERTICAL scrollbars, or height of FL_HORIZONTAL scrollbars.
void | scrollbar_size (int val)
| Set the pixel size of both horizontal and vertical scrollbar's "trough" to `val`.
int | scrollbar_size (void) const
| Get current pixel size of all the scrollbar's troughs for this widget, or zero if the global Fl::scrollbar_size() is being used (default).
const char * | selection_text (void) const
| Return text selection (for copy()/paste() operations)
int | selection_text_len (void) const
| Return byte length of all UTF-8 chars in selection, or 0 if no selection.
void | selectionbgcolor (Fl_Color val)
| Set mouse selection background color.
Fl_Color | selectionbgcolor (void) const
| Get mouse selection background color.
void | selectionfgcolor (Fl_Color val)
| Set mouse selection foreground color.
Fl_Color | selectionfgcolor (void) const
| Get mouse selection foreground color.
void | show_unknown (bool val)
| Set the "show unknown" flag.
bool | show_unknown (void) const
| Return the "show unknown" flag.
const char * | text (bool lines_below_cursor=false) const
| Return a string copy of all lines in the terminal (including history).
uchar | textattrib () const
| Get text attribute bits (underline, inverse, etc).
void | textattrib (uchar val)
| Set text attribute bits (underline, inverse, etc).
void | textbgcolor (Fl_Color val)
| Set text background color to fltk color `val` used by any new text added.
Fl_Color | textbgcolor (void) const
| Return text's current background color.
void | textbgcolor_default (Fl_Color val)
| Set the default text background color used by any new text added after a reset (`<ESC>c`, `<ESC>`[0m, or reset_terminal()).
Fl_Color | textbgcolor_default (void) const
| Return text's default background color.
void | textbgcolor_xterm (uchar val)
| Sets the background text color as one of the 8 'xterm color' values.
void | textcolor (Fl_Color val)
| Set the text color for the terminal.
Fl_Color | textcolor (void) const
| Return textcolor(). This is a convenience method that returns textfgcolor_default()
void | textfgcolor (Fl_Color val)
| Set text foreground drawing color to fltk color `val` used by any new text added.
Fl_Color | textfgcolor (void) const
| Return text's current foreground color.
void | textfgcolor_default (Fl_Color val)
| Set the default text foreground color used by `<ESC>c`, `<ESC>`[0m, and reset_terminal().
Fl_Color | textfgcolor_default (void) const
| Return text's default foreground color.
void | textfgcolor_xterm (uchar val)
| Sets the foreground text color as one of the 8 'xterm color' values.
void | textfont (Fl_Font val)
| Sets the font used for all text displayed in the terminal.
Fl_Font | textfont (void) const
| Return text font used to draw all text in the terminal.
void | textsize (Fl_Fontsize val)
| Sets the font size used for all text displayed in the terminal.
Fl_Fontsize | textsize (void) const
| Return text font size used to draw all text in the terminal.
void | vprintf (const char *fmt, va_list ap)
| Appends printf formatted messages to the terminal.
| ~Fl_Terminal (void)
| The destructor for Fl_Terminal.
Public Member Functions inherited from Fl_Group
Fl_Widget *& | _ddfdesign_kludge ()
| This is for forms compatibility only.
void | add (Fl_Widget &)
| The widget is removed from its current group (if any) and then added to the end of this group.
void | add (Fl_Widget *o)
| See void Fl_Group::add(Fl_Widget &w)
void | add_resizable (Fl_Widget &o)
| Adds a widget to the group and makes it the resizable widget.
Fl_Widget *const * | array () const
| Returns a pointer to the array of children.
Fl_Group const * | as_group () const FL_OVERRIDE
Fl_Group * | as_group () FL_OVERRIDE
| Returns an Fl_Group pointer if this widget is an Fl_Group.
void | begin ()
| Sets the current group so you can build the widget tree by just constructing the widgets.
Fl_Widget * | child (int n) const
| Returns the n'th child.
int | children () const
| Returns how many child widgets the group has.
void | clear ()
| Deletes all child widgets from memory recursively.
unsigned int | clip_children ()
| Returns the current clipping mode.
void | clip_children (int c)
| Controls whether the group widget clips the drawing of child widgets to its bounding box.
virtual int | delete_child (int n)
| Removes the widget at `index` from the group and deletes it.
void | end ()
| Exactly the same as current(this->parent()).
int | find (const Fl_Widget &o) const
| See int Fl_Group::find(const Fl_Widget *w) const.
int | find (const Fl_Widget *) const
| Searches the child array for the widget and returns the index.
| Fl_Group (int, int, int, int, const char *=0)
| Creates a new Fl_Group widget using the given position, size, and label string.
void | focus (Fl_Widget *W)
void | forms_end ()
| This is for forms compatibility only.
void | init_sizes ()
| Resets the internal array of widget sizes and positions.
void | insert (Fl_Widget &, int i)
| The widget is removed from its current group (if any) and then inserted into this group.
void | insert (Fl_Widget &o, Fl_Widget *before)
| This does insert(w, find(before)).
void | remove (Fl_Widget &)
| Removes a widget from the group but does not delete it.
void | remove (Fl_Widget *o)
| Removes the widget `o` from the group.
void | remove (int index)
| Removes the widget at `index` from the group but does not delete it.
Fl_Widget * | resizable () const
| Returns the group's resizable widget.
void | resizable (Fl_Widget &o)
| Sets the group's resizable widget.
void | resizable (Fl_Widget *o)
| The resizable widget defines both the resizing box and the resizing behavior of the group and its children.
virtual | ~Fl_Group ()
| The destructor also deletes all the children.
Public Member Functions inherited from Fl_Widget
void | _clear_fullscreen ()
void | _set_fullscreen ()
void | activate ()
| Activates the widget.
unsigned int | active () const
| Returns whether the widget is active.
int | active_r () const
| Returns whether the widget and all of its parents are active.
Fl_Align | align () const
| Gets the label alignment.
void | align (Fl_Align alignment)
| Sets the label alignment.
long | argument () const
| Gets the current user data (long) argument that is passed to the callback function.
void | argument (long v)
| Sets the current user data (long) argument that is passed to the callback function.
virtual class Fl_Gl_Window * | as_gl_window ()
| Returns an Fl_Gl_Window pointer if this widget is an Fl_Gl_Window.
virtual class Fl_Gl_Window const * | as_gl_window () const
virtual Fl_Window * | as_window ()
| Returns an Fl_Window pointer if this widget is an Fl_Window.
virtual Fl_Window const * | as_window () const
void | bind_deimage (Fl_Image *img)
| Sets the image to use as part of the widget label when in the inactive state.
void | bind_deimage (int f)
| Bind the inactive image to the widget, so the widget will delete the image when it is no longer needed.
void | bind_image (Fl_Image *img)
| Sets the image to use as part of the widget label when in the active state.
void | bind_image (int f)
| Bind the image to the widget, so the widget will delete the image when it is no longer needed.
Fl_Boxtype | box () const
| Gets the box type of the widget.
void | box (Fl_Boxtype new_box)
| Sets the box type for the widget.
Fl_Callback_p | callback () const
| Gets the current callback function for the widget.
void | callback (Fl_Callback *cb)
| Sets the current callback function for the widget.
void | callback (Fl_Callback *cb, Fl_Callback_User_Data *p, bool auto_free)
| Sets the current callback function and managed user data for the widget.
void | callback (Fl_Callback *cb, void *p)
| Sets the current callback function and data for the widget.
void | callback (Fl_Callback0 *cb)
| Sets the current callback function for the widget.
void | callback (Fl_Callback1 *cb, long p=0)
| Sets the current callback function for the widget.
unsigned int | changed () const
| Checks if the widget value changed since the last callback.
void | clear_active ()
| Marks the widget as inactive without sending events or changing focus.
void | clear_changed ()
| Marks the value of the widget as unchanged.
void | clear_damage (uchar c=0)
| Clears or sets the damage flags.
void | clear_output ()
| Sets a widget to accept input.
void | clear_visible ()
| Hides the widget.
void | clear_visible_focus ()
| Disables keyboard focus navigation with this widget.
Fl_Color | color () const
| Gets the background color of the widget.
void | color (Fl_Color bg)
| Sets the background color of the widget.
void | color (Fl_Color bg, Fl_Color sel)
| Sets the background and selection color of the widget.
Fl_Color | color2 () const
| For back compatibility only.
void | color2 (unsigned a)
| For back compatibility only.
int | contains (const Fl_Widget *w) const
| Checks if w is a child of this widget.
void | copy_label (const char *new_label)
| Sets the current label.
void | copy_tooltip (const char *text)
| Sets the current tooltip text.
uchar | damage () const
| Returns non-zero if draw() needs to be called.
void | damage (uchar c)
| Sets the damage bits for the widget.
void | damage (uchar c, int x, int y, int w, int h)
| Sets the damage bits for an area inside the widget.
int | damage_resize (int, int, int, int)
| Internal use only.
void | deactivate ()
| Deactivates the widget.
Fl_Image * | deimage ()
| Gets the image that is used as part of the widget label when in the inactive state.
const Fl_Image * | deimage () const
| Gets the image that is used as part of the widget label when in the inactive state.
void | deimage (Fl_Image &img)
| Sets the image to use as part of the widget label when in the inactive state.
void | deimage (Fl_Image *img)
| Sets the image to use as part of the widget label when in the inactive state.
int | deimage_bound () const
| Returns whether the inactive image is managed by the widget.
void | do_callback (Fl_Callback_Reason reason=FL_REASON_UNKNOWN)
| Calls the widget callback function with default arguments.
void | do_callback (Fl_Widget *widget, long arg, Fl_Callback_Reason reason=FL_REASON_UNKNOWN)
| Calls the widget callback function with arbitrary arguments.
void | do_callback (Fl_Widget *widget, void *arg=0, Fl_Callback_Reason reason=FL_REASON_UNKNOWN)
| Calls the widget callback function with arbitrary arguments.
void | draw_label (int, int, int, int, Fl_Align) const
| Draws the label in an arbitrary bounding box with an arbitrary alignment.
int | h () const
| Gets the widget height.
virtual void | hide ()
| Makes a widget invisible.
int | horizontal_label_margin ()
| Get the spacing between the label and the horizontal edge of the widget.
void | horizontal_label_margin (int px)
| Set the spacing between the label and the horizontal edge of the widget.
Fl_Image * | image ()
| Gets the image that is used as part of the widget label when in the active state.
const Fl_Image * | image () const
| Gets the image that is used as part of the widget label when in the active state.
void | image (Fl_Image &img)
| Sets the image to use as part of the widget label when in the active state.
void | image (Fl_Image *img)
| Sets the image to use as part of the widget label when in the active state.
int | image_bound () const
| Returns whether the image is managed by the widget.
int | inside (const Fl_Widget *wgt) const
| Checks if this widget is a child of `wgt`.
int | is_label_copied () const
| Returns whether the current label was assigned with copy_label().
const char * | label () const
| Gets the current label text.
void | label (const char *text)
| Sets the current label pointer.
void | label (Fl_Labeltype a, const char *b)
| Shortcut to set the label text and type in one call.
int | label_image_spacing ()
| Return the gap size between the label and the image.
void | label_image_spacing (int gap)
| Set the gap between the label and the image in pixels.
Fl_Color | labelcolor () const
| Gets the label color.
void | labelcolor (Fl_Color c)
| Sets the label color.
Fl_Font | labelfont () const
| Gets the font to use.
void | labelfont (Fl_Font f)
| Sets the font to use.
Fl_Fontsize | labelsize () const
| Gets the font size in pixels.
void | labelsize (Fl_Fontsize pix)
| Sets the font size in pixels.
Fl_Labeltype | labeltype () const
| Gets the label type.
void | labeltype (Fl_Labeltype a)
| Sets the label type.
void | measure_label (int &ww, int &hh) const
| Sets width ww and height hh accordingly with the label size.
bool | needs_keyboard () const
| Returns whether this widget needs a keyboard.
void | needs_keyboard (bool needs)
| Sets whether this widget needs a keyboard.
unsigned int | output () const
| Returns if a widget is used for output only.
Fl_Group * | parent () const
| Returns a pointer to the parent widget.
void | parent (Fl_Group *p)
| Internal use only - "for hacks only".
void | position (int X, int Y)
| Repositions the window or widget.
void | redraw ()
| Schedules the drawing of the widget.
void | redraw_label ()
| Schedules the drawing of the label.
Fl_Color | selection_color () const
| Gets the selection color.
void | selection_color (Fl_Color a)
| Sets the selection color.
void | set_active ()
| Marks the widget as active without sending events or changing focus.
void | set_changed ()
| Marks the value of the widget as changed.
void | set_output ()
| Sets a widget to output only.
void | set_visible ()
| Makes the widget visible.
void | set_visible_focus ()
| Enables keyboard focus navigation with this widget.
int | shortcut_label () const
| Returns whether the widget's label uses '&' to indicate shortcuts.
void | shortcut_label (int value)
| Sets whether the widget's label uses '&' to indicate shortcuts.
virtual void | show ()
| Makes a widget visible.
void | size (int W, int H)
| Changes the size of the widget.
int | take_focus ()
| Gives the widget the keyboard focus.
unsigned int | takesevents () const
| Returns if the widget is able to take events.
int | test_shortcut ()
| Returns true if the widget's label contains the entered '&x' shortcut.
const char * | tooltip () const
| Gets the current tooltip text.
void | tooltip (const char *text)
| Sets the current tooltip text.
Fl_Window * | top_window () const
| Returns a pointer to the top-level window for the widget.
Fl_Window * | top_window_offset (int &xoff, int &yoff) const
| Finds the x/y offset of the current widget relative to the top-level window.
uchar | type () const
| Gets the widget type.
void | type (uchar t)
| Sets the widget type.
int | use_accents_menu ()
| Returns non zero if MAC_USE_ACCENTS_MENU flag is set, 0 otherwise.
void * | user_data () const
| Gets the user data for this widget.
void | user_data (Fl_Callback_User_Data *v, bool auto_free)
| Sets the user data for this widget.
void | user_data (void *v)
| Sets the user data for this widget.
int | vertical_label_margin ()
| Get the spacing between the label and the vertical edge of the widget.
void | vertical_label_margin (int px)
| Set the spacing between the label and the vertical edge of the widget.
unsigned int | visible () const
| Returns whether a widget is visible.
unsigned int | visible_focus () const
| Checks whether this widget has a visible focus.
void | visible_focus (int v)
| Modifies keyboard focus navigation.
int | visible_r () const
| Returns whether a widget and all its parents are visible.
int | w () const
| Gets the widget width.
Fl_When | when () const
| Returns the conditions under which the callback is called.
void | when (uchar i)
| Sets the flags used to decide when a callback is called.
Fl_Window * | window () const
| Returns a pointer to the nearest parent window up the widget hierarchy.
int | x () const
| Gets the widget position in its window.
int | y () const
| Gets the widget position in its window.
virtual | ~Fl_Widget ()
| Destroys the widget.

## Public Attributes
Fl_Scrollbar * | hscrollbar
| Horizontal scrollbar.
Fl_Scrollbar * | scrollbar
| Vertical scrollbar.

## Protected Member Functions
void | clear_eod (void)
| Clear from cursor to End Of Display (EOD), like `"<ESC>[J<ESC>[0J"`.
void | clear_eol (void)
| Clear from cursor to End Of Line (EOL), like `"<ESC>[K"`.
void | clear_line (int row)
| Clear entire line for specified row.
void | clear_line (void)
| Clear entire line cursor is currently on.
void | clear_mouse_selection (void)
| Clear any current mouse selection.
void | clear_sod (void)
| Clear from cursor to Start Of Display (EOD), like `"<ESC>[1J"`.
void | clear_sol (void)
| Clear from cursor to Start Of Line (SOL), like `"<ESC>[1K"`.
void | current_style (const CharStyle &sty)
| Set current style for rendering text.
CharStyle & | current_style (void) const
| Return reference to internal current style for rendering text.
void | cursor_col (int col)
| Move cursor to the specified column `col`.
void | cursor_cr (void)
| Move cursor as if a CR (\r) was received.
void | cursor_crlf (int count=1)
| Move cursor as if a CR/LF pair (\r\n) was received.
void | cursor_down (int count=1, bool do_scroll=false)
| Moves cursor down `count` lines.
void | cursor_eol (void)
| Move cursor to the last column (at the far right) on the current line.
void | cursor_left (int count=1)
| Moves cursor left `count` columns, and cursor stops (does not wrap) if it hits screen edge.
void | cursor_right (int count=1, bool do_scroll=false)
| Moves cursor right `count` columns.
void | cursor_row (int row)
| Move cursor to the specified row `row`.
void | cursor_sol (void)
| Move cursor to the first column (at the far left) on the current line.
void | cursor_tab_left (int count=1)
| Tab left, do not wrap beyond left edge.
void | cursor_tab_right (int count=1)
| Tab right, do not wrap beyond right edge.
void | cursor_up (int count=1, bool do_scroll=false)
| Moves cursor up `count` lines.
void | delete_chars (int drow, int dcol, int rep)
| Delete char(s) at (drow,dcol) for 'rep' times.
void | delete_chars (int rep)
| Delete char(s) at cursor position for 'rep' times.
void | delete_rows (int count)
| Delete (count) rows at cursor position.
int | disp_cols (void) const
| Return the number of columns in the display area.
int | disp_erow (void) const
| Return the ending row# in the display area.
int | disp_rows (void) const
| Return the number of rows in the display area.
int | disp_srow (void) const
| Return the starting row# in the display area.
void | draw_buff (int Y) const
| Draws the buffer position we are scrolled to onto the FLTK screen starting at pixel position Y.
void | draw_row (int grow, int Y) const
| Draw the specified global row, which is the row in ring_chars[].
void | draw_row_bg (int grow, int X, int Y) const
| Draw the background for the specified ring_chars[] global row `grow` starting at FLTK coords `X` and `Y`.
bool | get_selection (int &srow, int &scol, int &erow, int &ecol) const
| Return mouse selection's start/end position in the ring buffer, if any.
int | h_to_row (int H) const
| Given a height in pixels, return number of rows that "fits" into that area.
int | handle_unknown_char (int drow, int dcol)
| Handle an unknown char by either emitting an error symbol to the tty, or do nothing, depending on the user configurable value of show_unknown().
int | handle_unknown_char (void)
| Handle an unknown char by either emitting an error symbol to the tty, or do nothing, depending on the user configurable value of show_unknown().
int | hist_cols (void) const
| Return the number of columns in the scrollback history.
int | hist_erow (void) const
| Return the ending row# of the scrollback history.
int | hist_rows (void) const
| Return the number of rows in the scrollback history.
int | hist_srow (void) const
| Return the starting row# of the scrollback history.
int | hist_use (void) const
| Return number of rows in use by the scrollback history.
int | hist_use_srow (void) const
| Return the starting row of the "in use" scrollback history.
void | insert_char (char c, int rep)
| Insert char 'c' at the current cursor position for 'rep' times.
void | insert_char_eol (char c, int drow, int dcol, int rep)
| Insert char 'c' for 'rep' times at display row `'drow'` and column `'dcol'`.
void | insert_rows (int count)
| Insert (count) rows at current cursor position.
bool | is_inside_selection (int row, int col) const
| Is global row/column inside the current mouse selection?
bool | is_selection (void) const
| Returns true if there's a mouse selection.
int | offset (void) const
| Returns the current offset into the ring buffer.
void | restore_cursor (void)
| Restore previously saved cursor position, if any. Used by ESC [ u.
int | ring_cols (void) const
| Return the number of columns in the ring buffer.
int | ring_erow (void) const
| Return the ending row# in the ring buffer (Always ring_rows()-1)
int | ring_rows (void) const
| Return the number of rows in the ring buffer.
int | ring_srow (void) const
| Return the starting row# in the ring buffer. (Always 0)
void | save_cursor (void)
| Save current cursor position. Used by ESC [ s.
void | scroll (int rows)
| Scroll the display up(+) or down(-) the specified `rows`.
void | select_line (int grow)
| Select the entire row.
void | select_word (int grow, int gcol)
| Select the word around the given row and column.
bool | selection_extend (int X, int Y)
| Extend selection to FLTK coords X,Y.
Utf8Char * | u8c_cursor (void)
| Return the Utf8Char* for character under cursor.
Utf8Char * | u8c_disp_row (int drow)
| Return pointer to the first u8c character in row `drow` of the display.
const Utf8Char * | u8c_disp_row (int drow) const
| See docs for non-const version of u8c_disp_row(int)
Utf8Char * | u8c_hist_row (int hrow)
| Return u8c for beginning of a row inside the scrollback history.
const Utf8Char * | u8c_hist_row (int hrow) const
| See docs for non-const version of u8c_hist_row(int)
const Utf8Char * | u8c_hist_use_row (int hrow) const
| See docs for non-const version of u8c_hist_use_row(int)
Utf8Char * | u8c_hist_use_row (int hurow)
| Return u8c for beginning of row `hurow` inside the 'in use' part of the scrollback history.
Utf8Char * | u8c_ring_row (int grow)
| Return UTF-8 char for row `grow` in the ring buffer.
const Utf8Char * | u8c_ring_row (int grow) const
| See docs for non-const version of u8c_ring_row(int)
const Utf8Char * | utf8_char_at_disp (int drow, int dcol) const
| Return Utf8Char* for char at specified display row and column.
const Utf8Char * | utf8_char_at_glob (int grow, int gcol) const
| Return Utf8Char* for char at specified global (grow,gcol).
int | w_to_col (int W) const
| Given a width in pixels, return number of columns that "fits" into that area.
const Utf8Char * | walk_selection (const Utf8Char *u8c, int &row, int &col) const
| Walk the mouse selection one character at a time from beginning to end, returning a Utf8Char* to the next character in the selection, or NULL if the end was reached, or if there's no selection.
Protected Member Functions inherited from Fl_Group
Fl_Rect * | bounds ()
| Returns the internal array of widget sizes and positions.
void | draw_child (Fl_Widget &widget) const
| Forces a child to redraw.
void | draw_children ()
| Draws all children of the group.
void | draw_outside_label (const Fl_Widget &widget) const
| Parents normally call this to draw outside labels of child widgets.
virtual int | on_insert (Fl_Widget *, int)
| Allow derived groups to act when a widget is added as a child.
virtual int | on_move (int, int)
| Allow derived groups to act when a widget is moved within the group.
virtual void | on_remove (int)
| Allow derived groups to act when a child widget is removed from the group.
int * | sizes ()
| Returns the internal array of widget sizes and positions.
void | update_child (Fl_Widget &widget) const
| Draws a child only if it needs it.
Protected Member Functions inherited from Fl_Widget
void | clear_flag (unsigned int c)
| Clears a flag in the flags mask.
void | draw_backdrop () const
| If FL_ALIGN_IMAGE_BACKDROP is set, the image or deimage will be drawn.
void | draw_box () const
| Draws the widget box according its box style.
void | draw_box (Fl_Boxtype t, Fl_Color c) const
| Draws a box of type t, of color c at the widget's position and size.
void | draw_box (Fl_Boxtype t, int x, int y, int w, int h, Fl_Color c) const
| Draws a box of type t, of color c at the position X,Y and size W,H.
void | draw_focus () const
| Draws a focus rectangle around the widget.
void | draw_focus (Fl_Boxtype t, int X, int Y, int W, int H) const
| Draws a focus rectangle around the widget.
void | draw_focus (Fl_Boxtype t, int x, int y, int w, int h, Fl_Color bg) const
| Draws a focus box for the widget at the given position and size.
void | draw_label () const
| Draws the widget's label at the defined label position.
void | draw_label (int, int, int, int) const
| Draws the label in an arbitrary bounding box.
| Fl_Widget (int x, int y, int w, int h, const char *label=0L)
| Creates a widget at the given position and size.
unsigned int | flags () const
| Gets the widget flags mask.
void | h (int v)
| Internal use only.
void | set_flag (unsigned int c)
| Sets a flag in the flags mask.
void | w (int v)
| Internal use only.
void | x (int v)
| Internal use only.
void | y (int v)
| Internal use only.

## Additional Inherited Members
Static Public Member Functions inherited from Fl_Group
static Fl_Group * | current ()
| Returns the currently active group.
static void | current (Fl_Group *g)
| Sets the current group.
Static Public Member Functions inherited from Fl_Widget
static void | default_callback (Fl_Widget *widget, void *data)
| The default callback for all widgets that don't set a callback.
static unsigned int | label_shortcut (const char *t)
| Returns the Unicode value of the '&x' shortcut in a given text.
static int | test_shortcut (const char *, const bool require_alt=false)
| Returns true if the given text `t` contains the entered '&x' shortcut.
Protected Types inherited from Fl_Widget
enum | { INACTIVE = 1<<0 , INVISIBLE = 1<<1 , OUTPUT = 1<<2 , NOBORDER = 1<<3 , FORCE_POSITION = 1<<4 , NON_MODAL = 1<<5 , SHORTCUT_LABEL = 1<<6 , CHANGED = 1<<7 , OVERRIDE = 1<<8 , VISIBLE_FOCUS = 1<<9 , COPIED_LABEL = 1<<10 , CLIP_CHILDREN = 1<<11 , MENU_WINDOW = 1<<12 , TOOLTIP_WINDOW = 1<<13 , MODAL = 1<<14 , NO_OVERLAY = 1<<15 , GROUP_RELATIVE = 1<<16 , COPIED_TOOLTIP = 1<<17 , FULLSCREEN = 1<<18 , MAC_USE_ACCENTS_MENU = 1<<19 , NEEDS_KEYBOARD = 1<<20 , IMAGE_BOUND = 1<<21 , DEIMAGE_BOUND = 1<<22 , AUTO_DELETE_USER_DATA = 1<<23 , MAXIMIZED = 1<<24 , POPUP = 1<<25 , USERFLAG3 = 1<<29 , USERFLAG2 = 1<<30 , USERFLAG1 = 1<<31 }
| flags possible values enumeration. More...

## Detailed Description

Terminal widget supporting Unicode/utf-8, ANSI/xterm escape codes with full RGB color control.

# Fl_Terminal

Fl_Terminal widget showing a linux manual page

Fl_Terminal is an output-only text widget supporting ASCII and UTF-8/Unicode. It supports most terminal text features, such as most VT100/xterm style escape sequences (see The Escape Codes Fl_Terminal Supports), text colors/attributes, scrollback history, mouse selection, etc.

It is recommended that accessing features such as setting text colors and cursor positioning is best done with ANSI/XTERM escape sequences. But if one sets ansi(false) then this is not possible, so the public API can be used for common operations, e.g.

  Public API | ESC code equivalent | Description
  --- | --- | ---
  clear_screen_home() | ESC [ H ESC [ 2 J | Clear screen, home cursor
  cursor_home() | ESC [ H | Home the cursor
  clear_history() | ESC [ 3 J | Clear scrollback history
  reset_terminal() | ESC [ c | Reset terminal

To access more advanced API calls, one can derive a class from Fl_Terminal to access protected methods manipulate the terminal more directly, e.g.

  Protected API | ESC code equiv. | Description
  --- | --- | ---
  current_style() | ESC [ # m | Set text attributes
  clear_eod() | ESC [ 0 J | Clear from cursor to end of display
  clear_sod() | ESC [ 1 J | Clear from cursor to start of display
  clear_eol() | ESC [ 0 K | Clear from cursor to end of line
  clear_sol() | ESC [ 1 K | Clear from cursor to start of line
  clear_line() | ESC [ 2 K | Clear line cursor is on
  scroll(int) // >0 for up | ESC [ 1 S | Scroll up one line
  scroll(int) // <0 for down | ESC [ 1 T | Scroll down one line
  cursor_left() | ESC [ 1 D | Move cursor left (no wrap)
  cursor_right() | ESC [ 1 C | Move cursor right (no wrap)
  cursor_up() | ESC [ 1 B | Move cursor up (no scroll or wrap)
  cursor_down() | ESC [ 1 A | Move cursor down (no scroll or wrap)
  cursor_row() cursor_col() | ESC [ # ; # H | Move cursor to row# / column#
  insert_char() | ESC [ # @ | Insert a char at cursor position
  delete_chars() | ESC [ # P | Delete chars at cursor position
  insert_rows() | ESC [ # L | Insert rows at cursor position
  delete_rows() | ESC [ # M | Delete rows at cursor position
  etc... | etc... | etc...

Many commonly used API functions are public, such as textfgcolor() for setting text colors. Others, such as cursor_up() are protected to prevent common misuse, and are available only to subclasses.

Some common operations:

- Set the terminal's background color, see color(Fl_Color)
- Set the terminal's default text color, see textfgcolor_default(Fl_Color)
- Printing text to the terminal, see Fl_Terminal::printf() and Fl_Terminal::append()
- Clearing the screen, see clear()
- Getting the terminal's buffer contents, see text()
- Getting single utf8 characters by row/col from the terminal display, see utf8_char_at_disp()
- Getting the text from a text selection, see get_selection()

For applications that need input support, the widget can be subclassed to provide keyboard input, and advanced features like pseudo ttys, termio, serial port I/O, etc., as such features are beyond the scope of FLTK.

## Examples

  //
  // Fl_Terminal: Simple Use
  //
  Fl_Terminal *tty = new Fl_Terminal(...);
  :
  tty->append("Hello world.\n"); // simple strings
  tty->append("\033[31mThis text is red.\033[0m\n"); // colored text
  tty->append("\033[32mThis text is green.\033[0m\n");
  tty->printf("The value of x is %.02f\n", x); // printf() formatting
  Fl_Terminal::printf
  void printf(const char *fmt,...)
  Appends printf formatted messages to the terminal.
  Definition Fl_Terminal.cxx:4157
  Fl_Terminal::Fl_Terminal
  Fl_Terminal(int X, int Y, int W, int H, const char *L=0)
  The constructor for Fl_Terminal.
  Definition Fl_Terminal.cxx:3398
  Fl_Terminal::append
  void append(const char *s, int len=-1)
  Appends string s to the terminal at the current cursor position using the current text color/attribut...
  Definition Fl_Terminal.cxx:3280
  Fl_Widget::x
  void x(int v)
  Internal use only.
  Definition Fl_Widget.H:150

  There are also public methods for doing what most "\033[" escape codes do, so that if ansi(bool) is set to "false", one can still change text colors or clear the screen via application control, e.g.

  tty->home(); // home the cursor
  tty->clear_screen(); // clear the screen
  tty->textfgcolor(0xff000000); // change the text color to RED
  tty->textbgcolor(0x0000ff00); // change the background color to BLUE
  // ├┘├┘├┘
  // R G B
  Fl_Terminal::textfgcolor
  void textfgcolor(Fl_Color val)
  Set text foreground drawing color to fltk color val used by any new text added.
  Definition Fl_Terminal.cxx:1754
  Fl_Terminal::textbgcolor
  void textbgcolor(Fl_Color val)
  Set text background color to fltk color val used by any new text added.
  Definition Fl_Terminal.cxx:1781
  Fl_Terminal::clear_screen
  void clear_screen(bool scroll_to_hist=true)
  Clear the terminal screen only; does not affect the cursor position.
  Definition Fl_Terminal.cxx:1907

  When creating the widget, the width/height determine the default column and row count for the terminal's display based on the current font size. The column width determines where text will wrap.

  You can specify wider column sizes than the screen using display_columns(colwidth). When this value is larger than the widget's width, text will wrap off-screen, and can be revealed by resizing the widget wider.

## Writing To Terminal From Applications

  An application needing terminal output as part of its user interface can instance Fl_Terminal, and write text strings with:

  - append() to append strings
  - printf() to append formatted strings

  Single character output can be done with:

  - print_char() to print a single ASCII/UTF-8 char at the cursor
  - plot_char() to put single ASCII/UTF-8 char at an x,y position

## Text Attributes

  The terminal's text supports these attributes:

  - Italic - italicized text: \033[3m
  - Bold - brighter/thicker text: \033[1m
  - Dim - lower brightness text: \033[2m
  - Underline - text that is underlined: \033[4m
  - Strikeout - text that has a line through the text: \033[9m
  - Inverse - text whose background and foreground colors are swapped: \033[7m
  - Normal - normal text: \033[0m

  Fl_Terminal screen

## Text and Background Colors

  There's at least two ways to specify colors for text and background colors:

  - 3 bit / 8 Color Values
  - Full 24 bit R/G/B colors

  Example of 3 bit colors:
  Fl_Terminal 3 bit colors

  Example application source code using 3 bit colors:
  //
  // Text colors
  //
  tty->append("\033[31m Red text.\033[0m\n"); // Print red text..
  tty->append("\033[32m Green text.\033[0m\n");
  :
  tty->append("\033[36m Cyan text.\033[0m\n");
  tty->append("\033[37m White text.\033[0m\n");
  //
  // Background colors
  //
  tty->append("\033[41m Red Background.\033[0m\n"); // background will be red
  tty->append("\033[42m Green Background.\033[0m\n");
  :
  tty->append("\033[46m Cyan Background.\033[0m\n");
  tty->append("\033[47m White Background.\033[0m\n");

  Example of 24 bit colors:
  Fl_Terminal 24 bit colors

  Example application source code using 24 bit colors:
  //
  // 24 bit Text Color
  //
  tty->append("\033[38;2;0;0;255m Text is BLUE.\033[0m\n"); // RGB: R=0, G=0, B=255
  tty->append("\033[38;2;255;0;0m Text is RED.\033[0m\n"); // RGB: R=255, G=0, B=0
  tty->append("\033[38;2;127;64;0m Text is DARK ORANGE.\033[0m\n"); // RGB: R=127, G=64, B=0
  //
  // 24 bit Background Color
  //
  tty->append("\033[48;2;0;0;255m Background is BLUE.\033[0m\n"); // RGB: R=0, G=0, B=255
  tty->append("\033[48;2;255;0;0m Background is RED.\033[0m\n"); // RGB: R=255, G=0, B=0
  tty->append("\033[48;2;127;64;0m Background is DARK ORANGE.\033[0m\n"); // RGB: R=127, G=64, B=0

  For more on the ANSI escape codes, see The Escape Codes Fl_Terminal Supports.

## Features

  Most standard terminal behaviors are supported, e.g.

  - ASCII + UTF-8/Unicode
  - scrollback history management
  - mouse selection + copy/paste (^C, ^A)
  - autoscroll during selection

  Most popular ANSI/DEC VT100/Xterm escape sequences are supported (see The Escape Codes Fl_Terminal Supports), including:
  - per-character colors for text and background
  - per-character text attributes: bold/dim, underline, strikeout
  - scrolling up/down
  - character insert/delete for characters/rows/screen
  - clearing characters/rows/screen

  Does not (yet) support:
  - programmable regions (scroll regions and attribute blocks)
  - dynamic line wrap (where resizing display dynamically re-wraps long lines)

  Will likely never implement as part of this widget:
  - pty/termio management (such features should be subclassed)
  - Different per-character font family + sizes (font family/size is global only)
  - variable width fonts

  Regarding the font family+size; the way the terminal is currently designed, the font family and size must not vary within text; rows have to be consistent height. Varying widths are tricky too, esp. when it comes to moving the cursor up/down within a column; varying widths are supported (due to Unicode characters sometimes being "wide", but not heights.

## Margins

  The margins define the amount of space (in pixels) around the outside of the text display area, the space between the widget's inner edge (inside the box()) and the text display area's outer edge. The margins can be inspected and changed with the margin_left(), margin_right(), margin_top() and margin_bottom() methods.

  ·
  TERMINAL WIDGET (Fl_Terminal)
  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━┓
  ┃ ↑ margin_top ┃ ┃
  ┃ TEXT DISPLAY AREA ↓ ┃ ┃
  ┃ ┌┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬─▴─┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┬┐ ┃ ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ S ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ c ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ display_rows ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ r ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ o ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ l ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ l ┃
  ┃ │◄── display_columns ─────────┼───────────────────────────►│ ┃ ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ B ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ a ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ r ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ ┃
  ┃ ├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤ ┃ ┃
  ┃◄─┬─►├┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼ │ ┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┤◄─┬─►┃ ┃
  ┃ │ └┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴─▾─┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┘ │ ┃ ┃
  ┃ margin_left ↑ margin_right ┃ ┃
  ┃ ↓ margin_bottom ┃ ┃
  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━┛
  Fl_Terminal Margins
  ░░░░░░░░░░░░░░░░░░░░░░░░░
  ░░░░░░░░░░░░░░░░░░░░░░░░░
  ░░░░░░:::::::::::::░░░░░◉
  ░░░░░░::##:::::##:◉░░░░░░╲
  ░░░░░░::###:::###::╲░░░░░ ╲
  ░░░░░░::####:####::░╲░░░░ Fl_Terminal::color()
  ░░░░░░::##:###:##::░░╲░░░
  ░░░░░░::##::#::##::░░░╲░░
  ░░░░░░::##:.:::##::░░░░╲░
  ░░░░░░::##:::::#◉::░░░░░╲
  ░░░░░░:::::::::::╲:░░░░░░╲
  ░░░░░░░░░░░░░░░░░░╲░░░░░░ Fl_Terminal::textbgcolor()
  ░░░░░░░░░░░░░░░░░░░╲░░░░░
  ╲
  Fl_Terminal::textfgcolor()
  ·
  Fl_Terminal::color
  Fl_Color color(void) const
  Return base widget Fl_Group's box() color()
  Definition Fl_Terminal.H:1143
  Fl_Terminal::margin_left
  int margin_left(void) const
  Return the left margin; see Margins.
  Definition Fl_Terminal.H:1118
  Fl_Terminal::display_columns
  int display_columns(void) const
  Return terminal's display width in columns of text characters.
  Definition Fl_Terminal.cxx:1529
  Fl_Terminal::margin_bottom
  int margin_bottom(void) const
  Return the bottom margin; see Margins.
  Definition Fl_Terminal.H:1124
  Fl_Terminal::margin_top
  int margin_top(void) const
  Return the top margin; see Margins.
  Definition Fl_Terminal.H:1122
  Fl_Terminal::margin_right
  int margin_right(void) const
  Return the right margin; see Margins.
  Definition Fl_Terminal.H:1120
  Fl_Terminal::display_rows
  int display_rows(void) const
  Return terminal's display height in lines of text (rows).
  Definition Fl_Terminal.cxx:1504

## Caveats

  - This widget is not a full terminal emulator; it does not do stdio redirection, pseudo ttys/termios/character cooking, keyboard input processing, full curses(3) support. However, such features CAN be implemented with subclassing.

  - The printf() and vprintf() functions are limited to strings no longer than 1024 characters (including NULL). For printing longer strings, use append() which has no string limits.

  - For background colors textbgcolor() and textbgcolor_default(), the special color value 0xffffffff lets the widget's box() color() show through behind the text.

## Member Enumeration Documentation

## ◆ Attrib

enum Fl_Terminal::Attrib

Bits for the per-character attributes, which control text features such as italic, bold, underlined text, etc.

NOTE: enum names with a leading underbar must not be used, and are reserved for future use.

Enumerator
NORMAL | all attributes off
BOLD | bold text: uses bold font, color brighter than normal
DIM | dim text; color slightly darker than normal
ITALIC | italic font text
UNDERLINE | underlined text
_RESERVED_1 | (reserved for internal future use)
INVERSE | inverse text; fg/bg color are swapped
_RESERVED_2 | (reserved for internal future use)
STRIKEOUT | strikeout text

## ◆ CharFlags

enum Fl_Terminal::CharFlags

Per-character 8 bit flags (uchar) used to manage special states for characters.

Enumerator
FG_XTERM | this char's fg color is an XTERM color; can be affected by Dim+Bold
BG_XTERM | this char's bg color is an XTERM color; can be affected by Dim+Bold
EOL | TODO: char at EOL, used for line re-wrap during screen resizing.

## ◆ OutFlags

enum Fl_Terminal::OutFlags

Output translation flags for special control character translations.

Enumerator
OFF | no output translation
CR_TO_LF | carriage return generates a vertical line-feed (\r -> \n)
LF_TO_CR | line-feed generates a carriage return (\n -> \r)
LF_TO_CRLF | line-feed generates a carriage return line-feed (\n -> \r\n)

## ◆ RedrawStyle

enum Fl_Terminal::RedrawStyle

Determines when Fl_Terminal calls redraw() if new text is added.

RATE_LIMITED is the recommended setting, using redraw_rate(float) to determine the maximum rate of redraws.

See also
  redraw_style(), redraw_rate()

Enumerator
NO_REDRAW | app must call redraw() as needed to update text to screen
RATE_LIMITED | timer controlled redraws. (DEFAULT)
PER_WRITE | redraw triggered after every append() / printf() / etc. operation

## ◆ ScrollbarStyle

enum Fl_Terminal::ScrollbarStyle

Behavior of scrollbars.

Enumerator
SCROLLBAR_OFF | scrollbar always invisible
SCROLLBAR_AUTO | scrollbar visible if widget resized in a way that hides columns (default)
SCROLLBAR_ON | scrollbar always visible

## Constructor & Destructor Documentation

## ◆ Fl_Terminal() [1/2]

Fl_Terminal::Fl_Terminal | ( | int | X,
|  | int | Y,
|  | int | W,
|  | int | H,
|  | const char * | L = 0 )

The constructor for Fl_Terminal.

This creates an empty terminal with defaults:

- white on black text; see textfgcolor(Fl_Color), textbgcolor(Fl_Color)
- rows/cols based on the `W` and `H` values, see display_rows(), display_columns()
- scrollback history of 100 lines, see history_rows()
- redraw_style() set to RATE_LIMITED, redraw_rate() set to 0.10 seconds

Note: While Fl_Terminal derives from Fl_Group, it's not intended for user code to use it as a parent for other widgets, so end() is called.

Parameters

  [in] | X,Y,W,H | position and size.
  [in] | L | label string (optional), may be NULL.

## ◆ Fl_Terminal() [2/2]

Fl_Terminal::Fl_Terminal | ( | int | X,
|  | int | Y,
|  | int | W,
|  | int | H,
|  | const char * | L,
|  | int | rows,
|  | int | cols,
|  | int | hist )

Same as the default FLTK constructor, but lets the user force the rows, columns and history to specific sizes on creation.

Since the row/cols/hist are specified directly, this prevents the widget from auto-calculating the initial text buffer size based on the widget's pixel width/height, bypassing calls to the font system before the widget is displayed.

Note
  fluid uses this constructor internally to avoid font calculations that opens the display, useful for when running in a headless context. (issue 837)

## ◆ ~Fl_Terminal()

Fl_Terminal::~Fl_Terminal | ( | void |  | ) |

The destructor for Fl_Terminal.

Destroys the terminal display, scroll history, and associated widgets.

## Member Function Documentation

## ◆ ansi() [1/2]

void Fl_Terminal::ansi | ( | bool | val | ) |

Enable/disable the ANSI mode flag.

If true, ANSI and VT100/xterm codes will be processed. If false, these codes won't be processed and will either be ignored or print the error character "¿", depending on the value of show_unknown().

See also
  show_unknown(), The Escape Codes Fl_Terminal Supports

## ◆ ansi() [2/2]

bool Fl_Terminal::ansi | ( | void |  | ) | const

Return the state of the ANSI flag.

See also
  ansi(bool)

## ◆ append()

void Fl_Terminal::append | ( | const char * | s,
|  | int | len = -1 )

Appends string `s` to the terminal at the current cursor position using the current text color/attributes.

If `s` is NULL, the UTF-8 character cache is cleared, which is recommended before starting a block reading loop, and again after the block loop has completed.

If `len` is not specified, it's assumed `s` is a NULL terminated string. If `len` IS specified, it can be used for writing strings that aren't NULL terminated, such as block reads on a pipe, network, or other block oriented data source.

Redraws of the terminal widget are by default handled automatically, but can be changed with redraw_rate() and redraw_style().

Block I/O

When reading block oriented sources (such as pipes), append() will handle partial UTF-8 chars straddling the block boundaries. It does this using an internal byte cache, which should be cleared before and after block I/O loops by calling append(NULL) as shown in the example below, to prevent the possibilities of partial UTF-8 characters left behind by an interrupted or incomplete block loop.

  // Example block reading a command pipe in Unix
  // Run command and read as a pipe
  FILE *fp = popen("ls -la", "r");
  if (!fp) { ..error_handling.. }
  // Enable non-blocking I/O
  int fd = fileno(fp);
  fcntl(fd, F_SETFL, O_NONBLOCK);
  // Clear UTF-8 character cache before starting block loop
  G_tty->append(NULL); // prevents leftover partial UTF-8 bytes
  // Block read loop
  while (1) {
  Fl::wait(0.05); // give fltk .05 secs of cpu to manage UI
  ssize_t bytes = read(fd, s, sizeof(s)); // read block from pipe
  if (bytes == -1 && errno == EAGAIN) continue; // no data yet? continue
  if (bytes > 0) G_tty->append(s); // append output to terminal
  else break; // end of pipe?
  }
  // Flush cache again after block loop completes
  G_tty->append(NULL);
  // Close pipe, done
  pclose(fp);
  Fl::wait
  static int wait()
  Waits until "something happens" and then returns.
  Definition Fl.cxx:672

Note
  - String can contain ASCII or UTF-8 chars
  - `len` is optional; if unspecified, expects `s` to be a NULL terminated string
  - Handles partial UTF-8 chars split between calls (e.g. block oriented writes)
  - If `s` is NULL, this clears the "partial UTF-8" character cache
  - Redraws are managed automatically by default; see redraw_style()

## ◆ append_ascii()

void Fl_Terminal::append_ascii | ( | const char * | s | ) |

Append NULL terminated ASCII string to terminal, slightly more efficient than append_utf8().

- If `s` is NULL, behavior is to do nothing
- Redraws are triggered automatically, depending on redraw_style()

## ◆ append_utf8()

void Fl_Terminal::append_utf8 | ( | const char * | buf,
|  | int | len = -1 )

Append NULL terminated UTF-8 string to terminal.

- If buf is NULL, UTF-8 cache buffer is cleared
- If optional `len` isn't specified or is -1, strlen(text) is used.
- If `len` is 0 or <-1, no changes are made
- Handles UTF-8 chars split across calls (e.g. block writes from pipes, etc)
- Redraws are triggered automatically, depending on redraw_style()

## ◆ box()

void Fl_Terminal::box | ( | Fl_Boxtype | val | ) |
| inline

Sets the box type, updates terminal margins et al.

Default is FL_DOWN_FRAME.

FL_XXX_FRAME types are handled in a special way by this widget, and guarantee the background is a flat field.

FL_XXX_BOX may draw gradients as inherited by Fl::scheme().

## ◆ clear() [1/2]

void Fl_Terminal::clear | ( | Fl_Color | val | ) |

Clears the screen to a specific color `val` and homes the cursor.

See also
  clear_screen(), clear_screen_home(), cursor_home()

## ◆ clear() [2/2]

void Fl_Terminal::clear | ( | void |  | ) |

Clears the screen to the current textbgcolor(), and homes the cursor.

See also
  clear_screen(), clear_screen_home(), cursor_home()

## ◆ clear_screen()

void Fl_Terminal::clear_screen | ( | bool | scroll_to_hist = true | ) |

Clear the terminal screen only; does not affect the cursor position.

Also clears the current mouse selection.

If `'scroll_to_hist'` is true, the screen is cleared by scrolling the contents into the scrollback history, where it can be retrieved with the scrollbar. This is the default behavior. If false, the screen is cleared and the scrollback history is unchanged.

Similar to the escape sequence `"<ESC>[2J"`.

See also
  clear_screen_home()

## ◆ clear_screen_home()

void Fl_Terminal::clear_screen_home | ( | bool | scroll_to_hist = true | ) |

Clear the terminal screen and home the cursor.

Also clears the current mouse selection.

If `'scroll_to_hist'` is true, the screen is cleared by scrolling the contents into the scrollback history, where it can be retrieved with the scrollbar. This is the default behavior. If false, the screen is cleared and the scrollback history is unchanged.

Similar to the escape sequence `"<ESC>[2J<ESC>[H"`.

See also
  clear_screen()

## ◆ color()

void Fl_Terminal::color | ( | Fl_Color | val | ) |

Sets the background color for the terminal's Fl_Group::box().

If the textbgcolor() and textbgcolor_default() are set to the special "see through" color 0xffffffff when any text was added, changing color() affects the color that shows through behind that existing text.

Otherwise, whatever specific background color was set for existing text will persist after changing color().

To see the effects of a change to color(), follow up with a call to redraw().

The default value is 0x0.

## ◆ cursor_col()

void Fl_Terminal::cursor_col | ( | int | col | ) |
| protected

Move cursor to the specified column `col`.

This value is clamped to the range (0..display_columns()-1).

## ◆ cursor_cr()

void Fl_Terminal::cursor_cr | ( | void |  | ) |
| protected

Move cursor as if a CR (\r) was received.

Same as cursor_sol()

## ◆ cursor_down()

void Fl_Terminal::cursor_down | ( | int | count = 1,
|  | bool | do_scroll = false )
| protected

Moves cursor down `count` lines.

If cursor hits screen bottom, it either stops (does not wrap) if `do_scroll` is false, or wraps and scrolls up if `do_scroll` is true.

Parameters

  count | Number of lines to move cursor down
  do_scroll | Enable scrolling if set to true

## ◆ cursor_right()

void Fl_Terminal::cursor_right | ( | int | count = 1,
|  | bool | do_scroll = false )
| protected

Moves cursor right `count` columns.

If cursor hits right edge of screen, it either stops (does not wrap) if `do_scroll` is false, or wraps and scrolls up one line if `do_scroll` is true.

## ◆ cursor_row()

void Fl_Terminal::cursor_row | ( | int | row | ) |
| protected

Move cursor to the specified row `row`.

This value is clamped to the range (0..display_rows()-1).

## ◆ cursor_up()

void Fl_Terminal::cursor_up | ( | int | count = 1,
|  | bool | do_scroll = false )
| protected

Moves cursor up `count` lines.

If cursor hits screen top, it either stops (does not wrap) if `do_scroll` is false, or scrolls down if `do_scroll` is true.

## ◆ delete_rows()

void Fl_Terminal::delete_rows | ( | int | count | ) |
| protected

Delete (count) rows at cursor position.

Causes rows to scroll up, and empty lines created at bottom of screen. Lines deleted by scroll up are NOT moved into the scroll history.

## ◆ display_columns() [1/2]

void Fl_Terminal::display_columns | ( | int | dcols | ) |

Set terminal's display width in columns of text characters.

This value is normally managed automatically by resize() based on the current font size, and should not be changed.

You CAN make the display_columns() larger than the width of the widget; text in the terminal will simply run off the screen edge and be clipped; the only way to reveal that text is if the user enlarges the widget, or the font size made smaller.

To change the display width, it is best to use resize() instead.

## ◆ display_columns() [2/2]

int Fl_Terminal::display_columns | ( | void |  | ) | const

Return terminal's display width in columns of text characters.

This value is normally managed automatically by resize() based on the current font size.

## ◆ display_rows() [1/2]

void Fl_Terminal::display_rows | ( | int | drows | ) |

Set terminal's display height in lines of text (rows).

This value is normally managed automatically by resize() based on the current font size, and should not be changed.

To change the display height, use resize() instead.

## ◆ display_rows() [2/2]

int Fl_Terminal::display_rows | ( | void |  | ) | const

Return terminal's display height in lines of text (rows).

This value is normally managed automatically by resize() based on the current font size.

## ◆ draw()

void Fl_Terminal::draw | ( | void |  | ) |
| virtual

Draws the entire Fl_Terminal.

Lets the group draw itself first (scrollbars should be only members), followed by the terminal's screen contents.

Reimplemented from Fl_Group.

## ◆ draw_buff()

void Fl_Terminal::draw_buff | ( | int | Y | ) | const
| protected

Draws the buffer position we are scrolled to onto the FLTK screen starting at pixel position Y.

This can be anywhere in the ring buffer, not just the 'active diplay'; depends on what position the scrollbar is set to.

Handles attributes, colors, text selections, cursor.

Parameters

  [in] | Y | top position of top left character in the window in FLTK coordinates

## ◆ draw_row()

void Fl_Terminal::draw_row | ( | int | grow,
|  | int | Y ) const
| protected

Draw the specified global row, which is the row in ring_chars[].

The global row includes history + display buffers.

Parameters

  [in] | grow | row number
  [in] | Y | top position of characters in the row in FLTK coordinates

## ◆ draw_row_bg()

void Fl_Terminal::draw_row_bg | ( | int | grow,
|  | int | X,
|  | int | Y ) const
| protected

Draw the background for the specified ring_chars[] global row `grow` starting at FLTK coords `X` and `Y`.

Note we may be called to draw display, or even history if we're scrolled back. If there's any change in bg color, we draw the filled rects here.

If the bg color for a character is the special "see through" color 0xffffffff, no pixels are drawn.

Parameters

  [in] | grow | row number
  [in] | X,Y | top left corner of the row in FLTK coordinates

## ◆ error_char() [1/2]

void Fl_Terminal::error_char | ( | const char * | val | ) |
| inline

Sets the "error character" utf8 string shown for invalid utf8 or bad ANSI sequences if show_unknown() is true.

Default: "¿".

See also
  show_unknown(bool)

## ◆ error_char() [2/2]

const char * Fl_Terminal::error_char | ( | void |  | ) | const
| inline

Returns the "error character" utf8 string, which is shown for invalid utf8 or bad ANSI sequences if show_unknown() is true.

See also
  show_unknown(bool)

## ◆ get_selection()

bool Fl_Terminal::get_selection | ( | int & | srow,
|  | int & | scol,
|  | int & | erow,
|  | int & | ecol ) const
| protected

Return mouse selection's start/end position in the ring buffer, if any.

Ensures (start < end) to allow walking 'forward' thru selection, left-to-right, top-to-bottom. The row/col values are indexes into the entire ring buffer.

Example: walk the characters of the mouse selection:

  // Get selection
  int srow,scol,erow,ecol;
  if (get_selection(srow,scol,erow,ecol)) { // mouse selection exists?
  // Walk entire selection from start to end
  for (int row=srow; row<=erow; row++) { // walk rows of selection
  const Utf8Char *u8c = u8c_ring_row(row); // ptr to first character in row
  int col_start = (row==srow) ? scol : 0; // start row? start at scol
  int col_end = (row==erow) ? ecol : ring_cols(); // end row? end at ecol
  u8c += col_start; // include col offset (if any)
  for (int col=col_start; col<=col_end; col++,u8c++) { // walk columns
  ..do something with each char at *u8c..
  }
  }
  }
  Fl_Terminal::Utf8Char
  Definition Fl_Terminal.H:539
  Fl_Terminal::u8c_ring_row
  const Utf8Char * u8c_ring_row(int grow) const
  See docs for non-const version of u8c_ring_row(int)
  Definition Fl_Terminal.cxx:1054
  Fl_Terminal::ring_cols
  int ring_cols(void) const
  Return the number of columns in the ring buffer.
  Definition Fl_Terminal.H:1057
  Fl_Terminal::get_selection
  bool get_selection(int &srow, int &scol, int &erow, int &ecol) const
  Return mouse selection's start/end position in the ring buffer, if any.
  Definition Fl_Terminal.cxx:2067

Returns:

- true – valid selection values returned
- false – no selection was made, returned values undefined

See also
  walk_selection(), is_selection()

Parameters

  srow | starting row for selection
  scol | starting column for selection
  erow | ending row for selection
  ecol | ending column for selection

## ◆ h_to_row()

int Fl_Terminal::h_to_row | ( | int | H | ) | const
| protected

Given a height in pixels, return number of rows that "fits" into that area.

This is used by the constructor to size the row/cols to fit the widget size.

## ◆ handle()

int Fl_Terminal::handle | ( | int | e | ) |
| virtual

Handle FLTK events.

Reimplemented from Fl_Group.

## ◆ handle_unknown_char() [1/2]

int Fl_Terminal::handle_unknown_char | ( | int | drow,
|  | int | dcol )
| protected

Handle an unknown char by either emitting an error symbol to the tty, or do nothing, depending on the user configurable value of show_unknown().

This writes the "unknown" character to the display position ``(drow,dcol) if show_unknown() is true.

Returns 1 if tty modified, 0 if not.

See also
  show_unknown()

## ◆ handle_unknown_char() [2/2]

int Fl_Terminal::handle_unknown_char | ( | void |  | ) |
| protected

Handle an unknown char by either emitting an error symbol to the tty, or do nothing, depending on the user configurable value of show_unknown().

This writes the "unknown" character to the output stream if show_unknown() is true.

Returns 1 if tty modified, 0 if not.

See also
  show_unknown()

## ◆ history_lines()

void Fl_Terminal::history_lines | ( | int | val | ) |

Set the number of lines of screen history.

Large values can be briefly heavy on cpu and memory usage.

## ◆ history_use()

int Fl_Terminal::history_use | ( | void |  | ) | const

Returns how many lines are "in use" by the screen history buffer.

This value will be 0 if history was recently cleared with e.g. clear_history() or `"<ESC>c"`.

Return value will be in the range 0 .. (history_lines()-1).

## ◆ hscrollbar_style() [1/2]

void Fl_Terminal::hscrollbar_style | ( | ScrollbarStyle | val | ) |

Set the horizontal scrollbar behavior style.

This determines when the scrollbar is visible.

  ScrollbarStyle enum | Description
  --- | ---
  SCROLLBAR_ON | Horizontal scrollbar always displayed.
  SCROLLBAR_OFF | Horizontal scrollbar never displayed.
  SCROLLBAR_AUTO | Horizontal scrollbar displayed whenever widget width hides columns.

The default style is SCROLLBAR_AUTO.

See also
  ScrollbarStyle

## ◆ hscrollbar_style() [2/2]

Fl_Terminal::ScrollbarStyle Fl_Terminal::hscrollbar_style | ( | void |  | ) | const

Get the horizontal scrollbar behavior style.

This determines when the scrollbar is visible.

Value will be one of the Fl_Terminal::ScrollbarStyle enum values.

See also
  hscrollbar_style(Fl_Terminal::ScrollbarStyle)

## ◆ insert_char()

void Fl_Terminal::insert_char | ( | char | c,
|  | int | rep )
| protected

Insert char 'c' at the current cursor position for 'rep' times.

Does not wrap; characters at end of line are lost.

## ◆ insert_rows()

void Fl_Terminal::insert_rows | ( | int | count | ) |
| protected

Insert (count) rows at current cursor position.

Causes rows below to scroll down, and empty lines created. Lines deleted by scroll down are NOT moved into the scroll history.

## ◆ is_inside_selection()

bool Fl_Terminal::is_inside_selection | ( | int | grow,
|  | int | gcol ) const
| protected

Is global row/column inside the current mouse selection?

Returns
  - true – (`grow`, `gcol`) is inside a valid selection.
  - false – (`grow`, `gcol`) is outside, or no valid selection.

## ◆ output_translate()

void Fl_Terminal::output_translate | ( | Fl_Terminal::OutFlags | val | ) |

Sets the combined output translation flags to `val`.

`val` can be sensible combinations of the OutFlags bit flags.

The default is LF_TO_CRLF, so that \n will generate both carriage-return (CR) and line-feed (LF).

For \r and \n to be handled literally, use output_translate(Fl_Terminal::OutFlags::OFF);

To disable all output translations, use 0 or Fl_Terminal::OutFlags::OFF.

## ◆ plot_char() [1/2]

void Fl_Terminal::plot_char | ( | char | c,
|  | int | drow,
|  | int | dcol )

Plot the ASCII character `c` at the terminal's display position ``(drow,dcol).

The character MUST be printable (in range 0x20 - 0x7e), and is displayed using the current text color/attributes. Characters outside that range are either ignored or print the error character (¿), depending on show_unknown(bool).

This is a very low level method.

No range checking is done on drow,dcol:

- `drow` must be in range 0..(display_rows()-1)
- `dcol` must be in range 0..(display_columns()-1)
- Does not trigger redraws
- Does NOT handle control codes, ANSI or XTERM escape sequences.

See also
  show_unknown(bool), handle_unknown_char(), is_printable()

## ◆ plot_char() [2/2]

void Fl_Terminal::plot_char | ( | const char * | text,
|  | int | len,
|  | int | drow,
|  | int | dcol )

Plot the UTF-8 character `text` of length `len` at display position ``(drow,dcol).

The character is displayed using the current text color/attributes.

This is a very low level method.

No range checking is done on drow,dcol:

- `drow` must be in range 0..(display_rows()-1)
- `dcol` must be in range 0..(display_columns()-1)
- Does not trigger redraws
- Does not handle control codes, ANSI or XTERM escape sequences.
- Invalid UTF-8 chars show the error character (¿) depending on show_unknown(bool).

See also
  handle_unknown_char()

## ◆ print_char() [1/2]

void Fl_Terminal::print_char | ( | char | c | ) |

Prints single ASCII char `c` at current cursor position, and advances the cursor.

The character is displayed at the current cursor position using the current text color/attributes.

- `c` must be ASCII, not utf-8
- Does not trigger redraws

## ◆ print_char() [2/2]

void Fl_Terminal::print_char | ( | const char * | text,
|  | int | len = -1 )

Prints single UTF-8 char `text` of optional byte length `len` at current cursor position, and advances the cursor if the character is printable.

Handles ASCII and control codes (CR, LF, etc).

The character is displayed at the current cursor position using the current text color/attributes.

Handles control codes and can be used to construct ANSI/XTERM escape sequences.

- If optional `len` isn't specified or <0, strlen(text) is used.
- `text` must not be NULL.
- `len` must not be 0.
- `text` must be a single char only (whether UTF-8 or ASCII)
- `text` can be an ASCII character, though not as efficent as print_char()
- Invalid UTF-8 chars show the error character (¿) depending on show_unknown(bool).
- Does not trigger redraws

See also
  show_unknown(bool), handle_unknown_char()

## ◆ printf()

void Fl_Terminal::printf | ( | const char * | fmt,
|  |  | ... )

Appends printf formatted messages to the terminal.

The string can contain UTF-8, crlf's, and ANSI sequences are also supported. Example:

  #include <FL/Fl_Terminal.H>
  int main(..) {
  :
  // Create a terminal, and append some messages to it
  Fl_Terminal *tty = new Fl_Terminal(..);
  :
  // Append three lines of formatted text to the buffer
  tty->printf("The current date is: %s.\nThe time is: %s\n", date_str, time_str);
  tty->printf("The current PID is %ld.\n", (long)getpid());
  :
  Fl_Terminal.H
  Fl_Terminal widget.

Note
  The expanded string is currently limited to 1024 characters (including NULL). For longer strings use append() which has no string limits.

## ◆ redraw_rate()

void Fl_Terminal::redraw_rate | ( | float | val | ) |

Set the maximum rate redraw speed in floating point seconds if redraw_style() is set to RATE_LIMITED.

When output is sent to the terminal, rather than calling redraw() right away, a timer is started with this value indicating how long to wait before calling redraw(), causing the output to be shown. 0.10 is recommended (1/10th of a second), to limit redraws to no more than 10 redraws per second.

The value that works best depends on how fast data arrives, and how fast the font system can draw text at runtime.

Values too small cause too many redraws to occur, causing the terminal to get backlogged if large bursts of data arrive quickly. Values too large cause realtime output to be too "choppy".

## ◆ redraw_style() [1/2]

void Fl_Terminal::redraw_style | ( | RedrawStyle | val | ) |

Set how Fl_Terminal manages screen redrawing.

This setting is relevant when Fl_Terminal is used for high bandwidth data; too many redraws will slow things down, too few cause redraws to be 'choppy' when realtime data comes in.

Redrawing can be cpu intensive, depending on how many rows/cols are being displayed; worst case: large display + small font. Speed largely depends on the end user's graphics hardware and font drawing system.

  RedrawStyle enum | Description
  --- | ---
  NO_REDRAW | App must call redraw() as needed to update text to screen
  RATE_LIMITED | Rate limited, timer controlled redraws. (DEFAULT) See redraw_rate()
  PER_WRITE | Redraw triggered every call to append() / printf() / etc.

The default style is RATE_LIMITED, which is the easiest to use, and automates redrawing to be capped at 10 redraws per second max. See redraw_rate(float) to control this automated redraw speed.

See also
  redraw_rate(), RedrawStyle

## ◆ redraw_style() [2/2]

Fl_Terminal::RedrawStyle Fl_Terminal::redraw_style | ( | void |  | ) | const

Get the redraw style.

This determines when the terminal redraws itself while text is being added to it.

Value will be one of the Fl_Terminal::RedrawStyle enum values.

See also
  redraw_style(Fl_Terminal::RedrawStyle)

## ◆ reset_terminal()

void Fl_Terminal::reset_terminal | ( | void |  | ) |

Resets terminal to default colors, clears screen, history and mouse selection, homes cursor, resets tabstops.

Same as `"<ESC>c"`

## ◆ resize()

void Fl_Terminal::resize | ( | int | X,
|  | int | Y,
|  | int | W,
|  | int | H )
| virtual

Handle widget resizing, such as if user resizes parent window.

This may increase the column width of the widget if the width of the widget is made larger than it was.

Note
  Resizing currently does not rewrap existing text. Currently enlarging makes room for longer lines, and shrinking the size lets long lines run off the right edge of the display, hidden from view. This behavior may change in the future to rewrap.

Reimplemented from Fl_Group.

## ◆ scroll()

void Fl_Terminal::scroll | ( | int | rows | ) |
| protected

Scroll the display up(+) or down(-) the specified `rows`.

- Negative value scrolls "down", clearing top line, and history unaffected.
- Postive value scrolls "up", clearing bottom line, rotating top line into history.

## ◆ scrollbar_actual_size()

int Fl_Terminal::scrollbar_actual_size | ( | void |  | ) | const

Returns the scrollbar's actual "trough size", which is the width of FL_VERTICAL scrollbars, or height of FL_HORIZONTAL scrollbars.

If scrollbar_size() is zero (default), then the value of the global Fl::scrollbar_size() is returned, which is the default global scrollbar size for the entire application.

## ◆ scrollbar_size() [1/2]

void Fl_Terminal::scrollbar_size | ( | int | val | ) |

Set the pixel size of both horizontal and vertical scrollbar's "trough" to `val`.

Setting `val` to the special value 0 causes the widget to track the global Fl::scrollbar_size().

Use non-zero values only if you need to override the global Fl::scrollbar_size() size.

See also
  Fl::scrollbar_size(), scrollbar_actual_size()

## ◆ scrollbar_size() [2/2]

int Fl_Terminal::scrollbar_size | ( | void |  | ) | const

Get current pixel size of all the scrollbar's troughs for this widget, or zero if the global Fl::scrollbar_size() is being used (default).

If this value returns zero, this widget's scrollbars are using the global Fl::scrollbar_size(), in which case use scrollbar_actual_size() to get the actual (effective) pixel scrollbar size being used.

Returns
  Scrollbar trough size in pixels, or 0 if the global Fl::scrollbar_size() is being used.

See also
  Fl::scrollbar_size(int), scrollbar_actual_size()

## ◆ selection_extend()

bool Fl_Terminal::selection_extend | ( | int | X,
|  | int | Y )
| protected

Extend selection to FLTK coords X,Y.

Returns true if extended, false if nothing done (X,Y offscreen)

## ◆ selection_text()

const char * Fl_Terminal::selection_text | ( | void |  | ) | const

Return text selection (for copy()/paste() operations)

- Returns allocated NULL terminated string for entire selection.
- Caller must free() this memory when done.
- Unicode safe.

## ◆ selection_text_len()

int Fl_Terminal::selection_text_len | ( | void |  | ) | const

Return byte length of all UTF-8 chars in selection, or 0 if no selection.

NOTE: Length includes trailing white on each line.

## ◆ show_unknown() [1/2]

void Fl_Terminal::show_unknown | ( | bool | val | ) |

Set the "show unknown" flag.

If true, invalid utf8 and invalid ANSI sequences will be shown with the error character "¿".

If false, errors characters won't be shown.

See also
  handle_unknown_char(), error_char(const char*).

## ◆ show_unknown() [2/2]

bool Fl_Terminal::show_unknown | ( | void |  | ) | const

Return the "show unknown" flag.

See also
  show_unknown(bool), error_char(const char*).

## ◆ text()

const char * Fl_Terminal::text | ( | bool | lines_below_cursor = false | ) | const

Return a string copy of all lines in the terminal (including history).

The returned string is allocated with strdup(3), which the caller must free(3).

If `'lines_below_cursor'` is false (default), lines below the cursor on down to the bottom of the display are ignored, and not included in the returned string.

If `'lines_below_cursor'` is true, then all lines in the display are returned including any below the cursor, even if all are blank.

Example use:

  Fl_Terminal *tty = new Fl_Terminal(..);
  :
  const char *s = tty->text(); // get a copy of the terminal's contents
  printf("Terminal's contents is:\n%s\n", s);
  free((void*)s); // free() the copy when done!
  Fl_Terminal::text
  const char * text(bool lines_below_cursor=false) const
  Return a string copy of all lines in the terminal (including history).
  Definition Fl_Terminal.cxx:3983

Parameters

  [in] | lines_below_cursor | include lines below cursor, default: false

Returns
  A string allocated with strdup(3) which must be free'd, text is UTF-8.

## ◆ textattrib() [1/2]

uchar Fl_Terminal::textattrib | ( |  | ) | const

Get text attribute bits (underline, inverse, etc).

This is the default attribute used for all newly printed text.

See also
  textattrib(uchar), Fl_Terminal::Attrib

## ◆ textattrib() [2/2]

void Fl_Terminal::textattrib | ( | uchar | val | ) |

Set text attribute bits (underline, inverse, etc).

This will be the default attribute used for all newly printed text.

See also
  Fl_Terminal::Attrib

## ◆ textbgcolor()

void Fl_Terminal::textbgcolor | ( | Fl_Color | val | ) |

Set text background color to fltk color `val` used by any new text added.

Use this for temporary color changes, similar to <ESC>[48;2;<R>;<G>;<B>m

Colors set this way will NOT be influenced by the xterm Dim/Bold color intensity attributes. For that, use textbgcolor_xterm(uchar) instead.

This setting does not affect the 'default' text colors used by <ESC>[0m, <ESC>c, reset_terminal(), etc. To set that too, also set textbgcolor_default(Fl_Color), e.g.

  // Set both 'current' and 'default' colors
  Fl_Color darkamber = 0x20100000;
  tty->textbgcolor(darkamber); // set 'current' bg color
  tty->textbgcolor_default(darkamber); // set 'default' bg color used by ESC[0m reset
  Fl_Color
  unsigned int Fl_Color
  An FLTK color value; see also Colors.
  Definition Enumerations.H:1120

The special color value 0xffffffff (all ff's) is the "see through" color, which lets the widget's own Fl_Group::color() show through behind the text. This special text background color is the default, and is what most situations need.

See also
  textbgcolor_default(Fl_Color), textbgcolor_xterm(uchar)

## ◆ textbgcolor_default() [1/2]

void Fl_Terminal::textbgcolor_default | ( | Fl_Color | val | ) |

Set the default text background color used by any new text added after a reset (`<ESC>c`, `<ESC>`[0m, or reset_terminal()).

Does not affect the 'current' text background color; use textbgcolor(Fl_Color) to set that.

The special color value 0xffffffff (all ff's) is the "see through" color, which lets the widget's own Fl_Group::color() show through behind the text. This special text background color is the default, and is what most situations need.

See also
  textbgcolor(Fl_Color)

## ◆ textbgcolor_default() [2/2]

Fl_Color Fl_Terminal::textbgcolor_default | ( | void |  | ) | const
| inline

Return text's default background color.

See also
  textbgcolor()

## ◆ textbgcolor_xterm()

void Fl_Terminal::textbgcolor_xterm | ( | uchar | val | ) |

Sets the background text color as one of the 8 'xterm color' values.

This will be the foreground color used for all newly printed text, similar to the `<ESC>`[#m escape sequence, where # is between 40 and 47.

This color will be reset to the default bg color if reset_terminal() is called, or by `<ESC>c`, `<ESC>`[0m, etc.

The xterm color intensity values can be influenced by the Dim/Bold/Normal modes (which can be set with e.g. `<ESC>`[1m, textattrib(), etc), so the actual RGB values of these colors allow room for Dim/Bold to influence their brightness. For instance, "Normal Red" is not full brightness to allow "Bold Red" to be brighter. This goes for all colors except 'Black', which is not influenced by Dim or Bold; Black is always Black.

The 8 color xterm values are:

- 0 = Black
- 1 = Red
- 2 = Green
- 3 = Yellow
- 4 = Blue
- 5 = Magenta
- 6 = Cyan
- 7 = White

See also
  textbgcolor_default(Fl_Color)

## ◆ textcolor()

void Fl_Terminal::textcolor | ( | Fl_Color | val | ) |

Set the text color for the terminal.

This is a convenience method that sets both textfgcolor() and textfgcolor_default(), ensuring both are set to the same value.

Colors set this way will NOT be influenced by the xterm Dim/Bold color intensity attributes. For that, use textcolor_xterm() instead.

See also
  textfgcolor(Fl_Color), textfgcolor_default(Fl_Color), textbgcolor_xterm(uchar)

## ◆ textfgcolor()

void Fl_Terminal::textfgcolor | ( | Fl_Color | val | ) |

Set text foreground drawing color to fltk color `val` used by any new text added.

Use this for temporary color changes, similar to <ESC>[38;2;<R>;<G>;<B>m

Colors set this way will NOT be influenced by the xterm Dim/Bold color intensity attributes. For that, use textfgcolor_xterm(uchar) instead.

This setting does not affect the 'default' text colors used by <ESC>[0m, <ESC>c, reset_terminal(), etc. To change both the current and default fg color, also use textfgcolor_default(Fl_Color). Example:

  // Set both 'current' and 'default' colors
  Fl_Color amber = 0xd0704000;
  tty->textfgcolor(amber); // set 'current' fg color
  tty->textfgcolor_default(amber); // set 'default' fg color used by ESC[0m reset

See also
  textfgcolor_default(Fl_Color), textfgcolor_xterm(uchar)

## ◆ textfgcolor_default() [1/2]

void Fl_Terminal::textfgcolor_default | ( | Fl_Color | val | ) |

Set the default text foreground color used by `<ESC>c`, `<ESC>`[0m, and reset_terminal().

Does not affect the 'current' text foreground color; use textfgcolor(Fl_Color) to set that.

See also
  textfgcolor(Fl_Color)

## ◆ textfgcolor_default() [2/2]

Fl_Color Fl_Terminal::textfgcolor_default | ( | void |  | ) | const
| inline

Return text's default foreground color.

See also
  textfgcolor()

## ◆ textfgcolor_xterm()

void Fl_Terminal::textfgcolor_xterm | ( | uchar | val | ) |

Sets the foreground text color as one of the 8 'xterm color' values.

This will be the foreground color used for all newly printed text, similar to the `<ESC>`[#m escape sequence, where # is between 30 and 37.

This color will be reset to the default fg color if reset_terminal() is called, or by `<ESC>c`, `<ESC>`[0m, etc.

The xterm color intensity values can be influenced by the Dim/Bold/Normal modes (which can be set with e.g. `<ESC>`[1m, textattrib(), etc), so the actual RGB values of these colors allow room for Dim/Bold to influence their brightness. For instance, "Normal Red" is not full brightness to allow "Bold Red" to be brighter. This goes for all colors except 'Black', which is not influenced by Dim or Bold; Black is always Black.

The 8 color xterm values are:

- 0 = Black
- 1 = Red
- 2 = Green
- 3 = Yellow
- 4 = Blue
- 5 = Magenta
- 6 = Cyan
- 7 = White

See also
  textfgcolor_default(Fl_Color)

## ◆ textfont()

void Fl_Terminal::textfont | ( | Fl_Font | val | ) |

Sets the font used for all text displayed in the terminal.

This affects all existing text (in display and history) as well as any newly printed text.

Only monospace fonts are recommended, such as FL_COURIER or FL_SCREEN. Custom fonts configured with Fl::set_font() will also work, as long as they are monospace.

## ◆ textsize()

void Fl_Terminal::textsize | ( | Fl_Fontsize | val | ) |

Sets the font size used for all text displayed in the terminal.

This affects all existing text (in display and history) as well as any newly printed text.

Changing this will affect the display_rows() and display_columns().

## ◆ u8c_disp_row()

Fl_Terminal::Utf8Char * Fl_Terminal::u8c_disp_row | ( | int | drow | ) |
| protected

Return pointer to the first u8c character in row `drow` of the display.

- 'drow' is indexed relative to the beginning of the display buffer.
- This can be used to walk all columns in the specfied row, e.g.
  // Print all chars in first row of display (ASCII and UTF-8)
  Utf8Char *u8c = u8c_disp_row(0); // first char of first display row
  int scol = 0, ecol = disp_cols(); // start/end for column loop
  for (int col=scol; col<ecol; col++,u8c++) { // loop from first char to last
  char *text = u8c->text_utf8(); // text string for char
  int len = u8c->length(); // text string length for char
  ::printf("<%.*s>", len, text); // print potentially multibyte char
  }
  Fl_Terminal::u8c_disp_row
  const Utf8Char * u8c_disp_row(int drow) const
  See docs for non-const version of u8c_disp_row(int)
  Definition Fl_Terminal.cxx:1066
  Fl_Terminal::disp_cols
  int disp_cols(void) const
  Return the number of columns in the display area.
  Definition Fl_Terminal.H:1077
- This can also be used to walk all rows on the display screen up to the cursor row, e.g.
  // Write all chars in display up to cursor row to stdout
  for (int row=0; row<disp_rows() && row<=cursor_row(); row++) {
  const Utf8Char *u8c = u8c_disp_row(row); // first char in row
  for (int col=0; col<=display_cols(); col++,u8c++) { // walk columns left-to-right
  // ..Do things here with each u8c char..
  ::printf("%.*s", u8c->text_utf8(), u8c->length()); // write each utf8 char to stdout
  }
  ::printf("\n");
  }
  Fl_Terminal::cursor_row
  int cursor_row(void) const
  Return the cursor's current row position on the screen.
  Definition Fl_Terminal.cxx:2447
  Fl_Terminal::disp_rows
  int disp_rows(void) const
  Return the number of rows in the display area.
  Definition Fl_Terminal.H:1075

See also
  u8c_hist_use_row() for examples of walking the screen history

## ◆ u8c_hist_row()

Fl_Terminal::Utf8Char * Fl_Terminal::u8c_hist_row | ( | int | hrow | ) |
| protected

Return u8c for beginning of a row inside the scrollback history.

'hrow' is indexed relative to the beginning of the scrollback history buffer.

See also
  u8c_disp_row(int) for example use.

## ◆ u8c_hist_use_row()

Fl_Terminal::Utf8Char * Fl_Terminal::u8c_hist_use_row | ( | int | hurow | ) |
| protected

Return u8c for beginning of row `hurow` inside the 'in use' part of the scrollback history.

'hurow' is indexed relative to the beginning of the 'in use' part of the scrollback history buffer. This may be a different from u8c_hist_row(int) if the history was recently cleared, and there aren't many (or any) rows in the history buffer that have been populated with scrollback text yet.

Example to walk all "in use" lines of the history buffer:

// Walk the entire screen history ("in use") and display to stdout
for (int row=0; row<hist_use(); row++) {
const Utf8Char *u8c = u8c_hist_use_row(row); // first char in row
for (int col=0; col<=hist_cols(); col++,u8c++) { // walk columns left-to-right
// ..Do things here with each u8c char..
::printf("%.*s", u8c->length(), u8c->text_utf8()); // show each utf8 char to stdout
}
::printf("\n"); // end of each line
}
Fl_Terminal::hist_cols
int hist_cols(void) const
Return the number of columns in the scrollback history.
Definition Fl_Terminal.H:1065
Fl_Terminal::u8c_hist_use_row
const Utf8Char * u8c_hist_use_row(int hrow) const
See docs for non-const version of u8c_hist_use_row(int)
Definition Fl_Terminal.cxx:1062
Fl_Terminal::hist_use
int hist_use(void) const
Return number of rows in use by the scrollback history.
Definition Fl_Terminal.H:1071

See also
  u8c_disp_row(int) for example use.

## ◆ u8c_ring_row()

Fl_Terminal::Utf8Char * Fl_Terminal::u8c_ring_row | ( | int | grow | ) |
| protected

Return UTF-8 char for row `grow` in the ring buffer.

`grow` is globally indexed relative to the beginning of the ring buffer, so this method can access ANY character in the entire ring buffer (hist or disp) by the global index.

Scrolling offset is NOT applied; this is raw access to the ring's rows.

Should really ONLY be used for making a complete copy of the ring.

Example:

// Walk ALL rows and cols in the raw ring buffer..
// These will not necessarily be in order as they appear
// on-screen.
// For walking the terminal lines in order, see examples
// for u8c_hist_use_row() and u8c_disp_row().
//
for (int row=0; row<ring_rows(); row++) {
Utf8Char *u8c = u8c_ring_row(row);
for (int col=0; col<ring_cols(); col++,u8c++) {
..make use of u8c->xxx() methods..
}
}
Fl_Terminal::ring_rows
int ring_rows(void) const
Return the number of rows in the ring buffer.
Definition Fl_Terminal.H:1055

## ◆ utf8_char_at_disp()

const Fl_Terminal::Utf8Char * Fl_Terminal::utf8_char_at_disp | ( | int | drow,
|  | int | dcol ) const
| protected

Return Utf8Char* for char at specified display row and column.

This accesses any character in the display part of the ring buffer.

No range checking done on drow,dcol:

- `drow` must be in range 0..(disp_rows()-1)
- `dcol` must be in range 0..(disp_cols()-1)

See also
  u8c_disp_row()

## ◆ utf8_char_at_glob()

const Fl_Terminal::Utf8Char * Fl_Terminal::utf8_char_at_glob | ( | int | grow,
|  | int | gcol ) const
| protected

Return Utf8Char* for char at specified global (grow,gcol).

This accesses any character in the ring buffer (history + display).

No range checking done on grow,gcol:

- `grow` must be in range 0..(ring_rows()-1)
- `gcol` must be in range 0..(ring_cols()-1)

See also
  u8c_ring_row()

## ◆ vprintf()

void Fl_Terminal::vprintf | ( | const char * | fmt,
|  | va_list | ap )

Appends printf formatted messages to the terminal.

Subclasses can use this to implement their own printf() functionality.

The string can contain UTF-8, crlf's, and ANSI sequences are also supported when ansi(bool) is set to 'true'.

Note
  The expanded string is currently limited to 1024 characters (including NULL). For longer strings use append() which has no string limits.

Parameters

  fmt | is a printf format string for the message text.
  ap | is a va_list created by va_start() and closed with va_end(), which the caller is responsible for handling.

## ◆ w_to_col()

int Fl_Terminal::w_to_col | ( | int | W | ) | const
| protected

Given a width in pixels, return number of columns that "fits" into that area.

This is used by the constructor to size the row/cols to fit the widget size.

## ◆ walk_selection()

const Fl_Terminal::Utf8Char * Fl_Terminal::walk_selection | ( | const Utf8Char * | u8c,
|  | int & | row,
|  | int & | col ) const
| protected

Walk the mouse selection one character at a time from beginning to end, returning a Utf8Char* to the next character in the selection, or NULL if the end was reached, or if there's no selection.

This is easier to use for walking the selection than get_selection().

`u8c` should start out as NULL, rewinding to the beginning of the selection. If the returned Utf8Char* is not NULL, `row` and `col` return the character's row/column position in the ring buffer.

  // EXAMPLE: Walk the entire mouse selection, if any
  int row,col; // the returned row/col for each char
  Utf8Char *u8c = NULL; // start with NULL to begin walk
  while ((u8c = walk_selection(u8c, row, col))) { // loop until end char reached
  ..do something with *u8c..
  }
  Fl_Terminal::walk_selection
  const Utf8Char * walk_selection(const Utf8Char *u8c, int &row, int &col) const
  Walk the mouse selection one character at a time from beginning to end, returning a Utf8Char* to the ...
  Definition Fl_Terminal.cxx:2014

See also
  get_selection(), is_selection()

Parameters

  u8c | NULL on first iter
  row | returned row#
  col | returned col#

## Member Data Documentation

## ◆ hscrollbar

Fl_Scrollbar* Fl_Terminal::hscrollbar

Horizontal scrollbar.

This is public so it can be accessed directly, e.g.

- hscrollbar->value() returns the column offset position from the left edge of the display; 0 being the left edge (default).
- hscrollbar->value(int) similarly sets the column offset, which should be in the range [0 .. Fl_Scrollbar::maximum()].
- hscrollbar->step(double) sets the smoothness of scrolling, default is 0.25 for 4 steps of motion per column.

## ◆ scrollbar

Fl_Scrollbar* Fl_Terminal::scrollbar

Vertical scrollbar.

This is public so it can be accessed directly, e.g.

- scrollbar->value() returns the row offset from the bottom of the display, 0 being the bottom (default).
- scrollbar->value(int) similarly sets the row offset, which should be in the range [0 .. Fl_Scrollbar::maximum()].

- scrollbar->step(double) sets the smoothness of scrolling, default is 0.25 for 4 steps of motion per column.

  Todo

    Support scrollbar_left/right() - See Fl_Browser_::scrollbar docs

    Support new ScrollbarStyle

The documentation for this class was generated from the following files:

- Fl_Terminal.H
- Fl_Terminal.cxx