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

Public Attributes
Fl_Scrollbar *	hscrollbar
	Horizontal scrollbar. More...
Fl_Scrollbar *	scrollbar
	Vertical scrollbar. More...

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. More...
void	cursor_cr (void)
	Move cursor as if a CR (\r) was received. More...
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. More...
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. More...
void	cursor_row (int row)
	Move cursor to the specified row row. More...
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. More...
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. More...
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. More...
void	draw_row (int grow, int Y) const
	Draw the specified global row, which is the row in ring_chars[]. More...
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. More...
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. More...
int	h_to_row (int H) const
	Given a height in pixels, return number of rows that "fits" into that area. More...
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(). More...
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(). More...
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. More...
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. More...
bool	is_inside_selection (int row, int col) const
	Is global row/column inside the current mouse selection? More...
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. More...
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. More...
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. More...
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. More...
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. More...
Utf8Char *	u8c_ring_row (int grow)
	Return UTF-8 char for row grow in the ring buffer. More...
const Utf8Char *	u8c_ring_row (int grow) const
	See docs for non-const version of u8c_ring_row(int)
int	w_to_col (int W) const
	Given a width in pixels, return number of columns that "fits" into that area. More...
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. More...
Protected Member Functions inherited from Fl_Group
Fl_Rect *	bounds ()
	Returns the internal array of widget sizes and positions. More...
void	draw () FL_OVERRIDE
	Draws the widget. More...
void	draw_child (Fl_Widget &widget) const
	Forces a child to redraw. More...
void	draw_children ()
	Draws all children of the group. More...
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. More...
virtual int	on_move (int, int)
	Allow derived groups to act when a widget is moved within the group. More...
virtual void	on_remove (int)
	Allow derived groups to act when a child widget is removed from the group. More...
int *	sizes ()
	Returns the internal array of widget sizes and positions. More...
void	update_child (Fl_Widget &widget) const
	Draws a child only if it needs it. More...
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. More...
void	draw_focus (Fl_Boxtype t, int X, int Y, int W, int H) const
	Draws a focus rectangle around the widget. More...
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. More...
void	draw_label () const
	Draws the widget's label at the defined label position. More...
void	draw_label (int, int, int, int) const
	Draws the label in an arbitrary bounding box. More...
	Fl_Widget (int x, int y, int w, int h, const char *label=0L)
	Creates a widget at the given position and size. More...
unsigned int	flags () const
	Gets the widget flags mask.
void	h (int v)
	Internal use only. More...
void	set_flag (unsigned int c)
	Sets a flag in the flags mask.
void	w (int v)
	Internal use only. More...
void	x (int v)
	Internal use only. More...
void	y (int v)
	Internal use only. More...

Additional Inherited Members
Static Public Member Functions inherited from Fl_Group
static Fl_Group *	current ()
	Returns the currently active group. More...
static void	current (Fl_Group *g)
	Sets the current group. More...
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. More...
static unsigned int	label_shortcut (const char *t)
	Returns the Unicode value of the '&x' shortcut in a given text. More...
static int	test_shortcut (const char *, const bool require_alt=false)
	Returns true if the given text t contains the entered '&x' shortcut. More...
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

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

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

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

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

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());
    :

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.

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!

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

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
  }

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.

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 ring buffer..
for (int row=0; row<ring.rows(); row++) {
    Utf8Char *u8c = ring.u8c_ring_row(row);
    for (int col=0; col<ring.cols(); col++,u8c++) {
        ..make use of u8c->xxx() methods..
    }
}

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

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