mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
bc8b186398
fltk/FL/Fl_Terminal.H
Greg Ercolano bc8b186398 Doc all pub/prot members, remove unused, add todo 
- Made sure all public+protected members are documented.

- Reclassified some private -> protected:
   > vscroll_width()

- Removed signatures for unimplemented (non-existant) methods:
   > u8c_cursor(void)
   > history_use(int,bool)
   > cursor_h()

- Reclassified some protected -> private:
   > x_to_glob_col()
   > xy_to_glob_rowcol()
   > is_hist_ring_row()
   > is_disp_ring_row()
   > handle_ctrl()
   > is_printable()
   > is_ctrl()
   ..etc..
   > handle_selection_autoscroll()
   > handle_selection()
   > is_redraw_style

- Add todo for ESC 7 and ESC 8
- Small code formatting mods
- Small typos
2023-11-19 22:46:04 -08:00

1052 lines
46 KiB
C++
Raw Blame History

//
// Fl_Terminal.cxx - A terminal widget for Fast Light Tool Kit (FLTK).
//
// Copyright 2022 by Greg Ercolano.
// Copyright 2023 by Bill Spitzak and others.
//
// This library is free software. Distribution and use rights are outlined in
// the file "COPYING" which should have been included with this file. If this
// file is missing or damaged, see the license at:
//
// https://www.fltk.org/COPYING.php
//
// Please see the following page on how to report bugs and issues:
//
// https://www.fltk.org/bugs.php
//
/** \file
Fl_Terminal widget.
*/
#ifndef Fl_Terminal_H
#define Fl_Terminal_H
#include <FL/Fl.H>
#include <FL/Fl_Window.H>
#include <FL/Fl_Group.H>
#include <FL/Fl_Scrollbar.H>
#include <FL/Fl_Rect.H>
#include <stdarg.h> // va_list (MinGW)
/** \class Fl_Terminal
\brief Terminal widget supporting Unicode/utf-8, ANSI/xterm escape codes with full RGB color control.
\section Fl_Terminal
\image html Fl_Terminal-demo.png "Fl_Terminal widget showing a linux manual page"
\image latex Fl_Terminal-demo.png "Fl_Terminal widget showing a linux manual page" width=6cm
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 \ref Fl_Terminal_escape_codes), 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. 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.
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.
\subsection Fl_Terminal_Examples Examples
\par
\code
//
// 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
\endcode
\par
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.
\par
\code
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
\endcode
\par
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.
\par
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.
\subsection Fl_Terminal_Writing Writing To Terminal From Applications
\par
An application needing terminal output as part of its user interface
can instance Fl_Terminal, and write text strings with:
\par
- append() to append strings
- printf() to append formatted strings
\par
Single character output can be done with:
\par
- print_char() to print a single ASCII/UTF-8 char at the cursor
- putchar() to put single ASCII/UTF-8 char at an x,y position
\par
\subsection Fl_Terminal_Attributes Text Attributes
\par
The terminal's text supports these attributes:
\par
- Italic - italicized text: <TT>\\033[3m</TT>
- Bold - brighter/thicker text: <TT>\\033[1m</TT>
- Dim - lower brightness text: <TT>\\033[2m</TT>
- Underline - text that is underlined: <TT>\\033[4m</TT>
- Strikeout - text that has a line through the text: <TT>\\033[9m</TT>
- Inverse - text whose background and foreground colors are swapped: <TT>\\033[7m</TT>
- Normal - normal text: <TT>\\033[0m</TT>
\par
\image html Fl_Terminal-utf8-demo.png "Fl_Terminal screen"
\image latex Fl_Terminal-utf8-demo.png "Fl_Terminal screen" width=6cm
\subsection Fl_Terminal_Colors Text and Background Colors
\par
There's at least two ways to specify colors for text and background colors:
\par
- 3 bit / 8 Color Values
- Full 24 bit R/G/B colors
\par
Example of 3 bit colors:
\image html Fl_Terminal-3bit-colors.png "Fl_Terminal 3 bit colors"
\image latex Fl_Terminal-3bit-colors.png "Fl_Terminal 3 bit colors" width=6cm
\par
Example application source code using 3 bit colors:
\code
//
// 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");
\endcode
\par
Example of 24 bit colors:
\image html Fl_Terminal-24bit-colors.png "Fl_Terminal 24 bit colors"
\image latex Fl_Terminal-24bit-colors.png "Fl_Terminal 24 bit colors" width=6cm
\par
Example application source code using 24 bit colors:
\code
//
// 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
\endcode
\par
For more on the ANSI escape codes, see \ref Fl_Terminal_escape_codes.
\subsection Fl_Terminal_Features Features
\par
Most standard terminal behaviors are supported, e.g.
\par
- ASCII + UTF-8/Unicode
- scrollback history management
- mouse selection + copy/paste (^C, ^A)
- autoscroll during selection
\par
Most popular ANSI/DEC VT100/Xterm escape sequences are supported (see \ref Fl_Terminal_escape_codes), 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
\par
Does not (yet) support:
- programmable regions (scroll regions and attribute blocks)
- dynamic line wrap (where resizing display dynamically re-wraps long lines)
\par
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
\par
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.
\subsection Fl_Terminal_Margins Margins
\par
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.
\par
\code
·
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
·
\endcode
\subsection Fl_Terminal_Caveats Caveats
\par
- 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.
\par
- 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.
\par
- For background colors textbgcolor() and textbgcolor_default(), the special
color value 0xffffffff lets the widget's box() color() show through behind
the text.
**/
class FL_EXPORT Fl_Terminal : public Fl_Group {
public:
//////////////////////////////////////
////// Fl_Terminal Public Enums //////
//////////////////////////////////////
/**
\enum 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 redraw_style(), redraw_rate()
*/
enum RedrawStyle {
NO_REDRAW=0, ///< 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
};
/**
\enum 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.
*/
enum Attrib {
NORMAL = 0x00, ///< all attributes off
BOLD = 0x01, ///< bold text: uses bold font, color brighter than normal
DIM = 0x02, ///< dim text; color slightly darker than normal
ITALIC = 0x04, ///< italic font text
UNDERLINE = 0x08, ///< underlined text
_RESERVED_1 = 0x10, ///< <EM>(reserved for internal future use)</EM>
INVERSE = 0x20, ///< inverse text; fg/bg color are swapped
_RESERVED_2 = 0x40, ///< <EM>(reserved for internal future use)</EM>
STRIKEOUT = 0x80 ///< strikeout text
};
/**
\enum CharFlags
Per-character 8 bit flags (uchar) used to manage special states for characters.
*/
enum CharFlags {
FG_XTERM = 0x01, ///< this char's fg color is an XTERM color; can be affected by Dim+Bold
BG_XTERM = 0x02, ///< this char's bg color is an XTERM color; can be affected by Dim+Bold
EOL = 0x04, ///< this char at end of line, used for line wrap during screen resizing
RESV_A = 0x08,
RESV_B = 0x10,
RESV_C = 0x20,
RESV_D = 0x40,
RESV_E = 0x80,
COLORMASK = (FG_XTERM | BG_XTERM)
};
///////////////////////////////////////////////////////////////
//////
////// Fl_Terminal Protected Classes
//////
///////////////////////////////////////////////////////////////
protected:
// Margin Class ////////////////////////////////////////////
//
// Class to manage the terminal's margins
//
class FL_EXPORT Margin {
int left_, right_, top_, bottom_;
public:
Margin(void) { left_ = right_ = top_ = bottom_ = 3; }
int left(void) const { return left_; }
int right(void) const { return right_; }
int top(void) const { return top_; }
int bottom(void) const { return bottom_; }
void left(int val) { left_ = val; }
void right(int val) { right_ = val; }
void top(int val) { top_ = val; }
void bottom(int val) { bottom_ = val; }
};
// CharStyle Class ////////////////////////////////////////////
//
// Class to manage the terminal's character style
// This includes the font, color, and some cached internal
// info for optimized drawing speed.
//
class FL_EXPORT CharStyle {
uchar attrib_; // bold, underline..
uchar flags_; // CharFlags
Fl_Color fgcolor_; // foreground color for text
Fl_Color bgcolor_; // background color for text
Fl_Color defaultfgcolor_; // default fg color used by ESC[0m
Fl_Color defaultbgcolor_; // default bg color used by ESC[0m
Fl_Font fontface_; // font face
Fl_Fontsize fontsize_; // font size
int fontheight_; // font height (in pixels)
int fontdescent_; // font descent (pixels below font baseline)
int charwidth_; // width of a fixed width ASCII character
public:
CharStyle(void);
Fl_Color fgcolor(void) const;
Fl_Color bgcolor(void) const;
Fl_Color defaultfgcolor(void) const { return defaultfgcolor_; }
Fl_Color defaultbgcolor(void) const { return defaultbgcolor_; }
uchar attrib(void) const { return attrib_; }
Fl_Font fontface(void) const { return fontface_; }
Fl_Fontsize fontsize(void) const { return fontsize_; }
int fontheight(void) const { return fontheight_; }
int fontdescent(void) const { return fontdescent_; }
int charwidth(void) const { return charwidth_; }
uchar colorbits_only(uchar inflags) const;
void attrib(uchar val) { attrib_ = val; }
void set_flag(uchar val) { flags_ |= val; }
void clr_flag(uchar val) { flags_ &= ~val; }
void fgcolor_uchar(uchar val);
void bgcolor_uchar(uchar val);
void fgcolor(int r,int g,int b) { fgcolor_ = (r<<24) | (g<<16) | (b<<8); clr_flag(FG_XTERM); }
void bgcolor(int r,int g,int b) { bgcolor_ = (r<<24) | (g<<16) | (b<<8); clr_flag(BG_XTERM); }
void fgcolor(Fl_Color val) { fgcolor_ = val; clr_flag(FG_XTERM); }
void bgcolor(Fl_Color val) { bgcolor_ = val; clr_flag(BG_XTERM); }
void defaultfgcolor(Fl_Color val) { defaultfgcolor_ = val; }
void defaultbgcolor(Fl_Color val) { defaultbgcolor_ = val; }
void fontface(Fl_Font val) { fontface_ = val; update(); }
void fontsize(Fl_Fontsize val) { fontsize_ = val; update(); }
void update(void);
// SGR MODES: Set Graphics Rendition
void sgr_reset(void) { // e.g. ESC[0m
attrib(Fl_Terminal::NORMAL);
fgcolor(defaultfgcolor_);
bgcolor(defaultbgcolor_);
}
int onoff(bool flag, Attrib a) { return (flag ? (attrib_ | a) : (attrib_ & ~a)); }
void sgr_bold(bool val) { attrib_ = onoff(val, Fl_Terminal::BOLD); } // e.g. ESC[1m
void sgr_dim(bool val) { attrib_ = onoff(val, Fl_Terminal::DIM); } // e.g. ESC[2m
void sgr_italic(bool val) { attrib_ = onoff(val, Fl_Terminal::ITALIC); } // e.g. ESC[3m
void sgr_underline(bool val) { attrib_ = onoff(val, Fl_Terminal::UNDERLINE); } // e.g. ESC[3m
void sgr_dbl_under(bool val) { attrib_ = onoff(val, Fl_Terminal::UNDERLINE); } // e.g. ESC[21m (TODO!)
void sgr_blink(bool val) { /* NOT IMPLEMENTED */ } // e.g. ESC[5m
void sgr_inverse(bool val) { attrib_ = onoff(val, Fl_Terminal::INVERSE); } // e.g. ESC[7m
void sgr_strike(bool val) { attrib_ = onoff(val, Fl_Terminal::STRIKEOUT); } // e.g. ESC[9m
};
protected:
// Cursor Class ///////////////////////////////////////////////////////////
//
// Class to manage the terminal's cursor position, color, etc.
//
class FL_EXPORT Cursor {
int col_; // cursor's current col (x) position on display
int row_; // cursor's current row (y) position on display
int h_; // cursor's height (affected by font size)
Fl_Color fgcolor_; // cursor's fg color (color of text, if any)
Fl_Color bgcolor_; // cursor's bg color
public:
Cursor(void) {
col_ = 0;
row_ = 0;
h_ = 10;
fgcolor_ = 0xfffff000; // wht
bgcolor_ = 0x00d00000; // grn
}
int col(void) const { return col_; }
int row(void) const { return row_; }
int h(void) const { return h_; }
Fl_Color fgcolor(void) const { return fgcolor_; }
Fl_Color bgcolor(void) const { return bgcolor_; }
void col(int val) { col_ = val >= 0 ? val : 0; }
void row(int val) { row_ = val >= 0 ? val : 0; }
void h(int val) { h_ = val; }
void fgcolor(Fl_Color val) { fgcolor_ = val; }
void bgcolor(Fl_Color val) { bgcolor_ = val; }
int left(void) { col_ = (col_>0) ? (col_-1) : 0; return col_; }
int right(void) { return ++col_; }
int up(void) { row_ = (row_>0) ? (row_-1) : 0; return row_; }
int down(void) { return ++row_; }
bool is_rowcol(int drow,int dcol) const;
void scroll(int nrows);
void home(void) { row_ = 0; col_ = 0; }
};
// Utf8Char Class ///////////////////////////////////////////////////////////
//
// Class to manage the terminal's individual UTF-8 characters.
// Includes fg/bg color, attributes (BOLD, UNDERLINE..)
//
class FL_EXPORT Utf8Char {
static const int max_utf8_ = 4; // RFC 3629 paraphrased: In UTF-8, chars are encoded with 1 to 4 octets
char text_[max_utf8_]; // memory for actual ASCII or UTF-8 byte contents
uchar len_; // length of bytes in text_[] buffer; 1 for ASCII, >1 for UTF-8
uchar attrib_; // attribute bits for this char (bold, underline..)
uchar flags_; // CharFlags bits
Fl_Color fgcolor_; // fltk fg color (supports 8color or 24bit color set w/ESC[37;<r>;<g>;<b>m)
Fl_Color bgcolor_; // fltk bg color (supports 8color or 24bit color set w/ESC[47;<r>;<g>;<b>m)
// Private methods
void text_utf8_(const char *text, int len);
public:
// Public methods
Utf8Char(void); // ctor
Utf8Char(const Utf8Char& o); // copy ctor
~Utf8Char(void); // dtor
Utf8Char& operator=(const Utf8Char& o); // assignment
inline int max_utf8() const { return max_utf8_; }
void text_utf8(const char *text, int len, const CharStyle& style);
void text_ascii(char c, const CharStyle& style);
void fl_font_set(const CharStyle& style) const;
// Return the UTF-8 text string for this character.
// Use length() to get number of bytes in string, which will be 1 for ASCII chars.
//
const char* text_utf8(void) const { return text_; }
// Return the attribute for this char
uchar attrib(void) const { return attrib_; }
uchar flags(void) const { return flags_; }
Fl_Color fgcolor(void) const;
Fl_Color bgcolor(void) const;
// Return the length of this character in bytes (UTF-8 can be multibyte..)
int length(void) const { return int(len_); }
double pwidth(void) const;
int pwidth_int(void) const;
// Clear the character to a 'space'
void clear(const CharStyle& style) { text_ascii(' ', style); }
bool is_char(char c) const { return *text_ == c; }
void show_char(void) const { ::printf("%.*s", len_, text_); }
void show_char_info(void) const { ::fprintf(stderr, "UTF-8('%.*s', len=%d)\n", len_, text_, len_); }
Fl_Color attr_color(Fl_Color col, const Fl_Widget *grp) const;
Fl_Color attr_fg_color(const Fl_Widget *grp) const;
Fl_Color attr_bg_color(const Fl_Widget *grp) const;
};
// RingBuffer Class ///////////////////////////////////////////////////
//
// Manages ring with indexed row/col and "history" vs. "display" concepts.
//
class FL_EXPORT RingBuffer {
Utf8Char *ring_chars_; // the ring UTF-8 char buffer
int ring_rows_; // #rows in ring total
int ring_cols_; // #columns in ring/hist/disp
int nchars_; // #chars in ring (ring_rows*ring_cols)
int hist_rows_; // #rows in history
int hist_use_; // #rows in use by history
int disp_rows_; // #rows in display
int offset_; // index offset (used for 'scrolling')
private:
void new_copy(int drows, int dcols, int hrows, const CharStyle& style);
//DEBUG void write_row(FILE *fp, Utf8Char *u8c, int cols) const {
//DEBUG cols = (cols != 0) ? cols : ring_cols();
//DEBUG for ( int col=0; col<cols; col++, u8c++ ) {
//DEBUG ::fprintf(fp, "%.*s", u8c->length(), u8c->text_utf8());
//DEBUG }
//DEBUG }
public:
void clear(void);
void clear_hist(void);
RingBuffer(void);
RingBuffer(int drows, int dcols, int hrows);
~RingBuffer(void);
// Methods to access ring
//
// The 'offset' concept allows the 'history' and 'display'
// to be scrolled indefinitely. The 'offset' is applied
// to all the row accesses, and are clamped to within their bounds.
//
// For 'raw' access to the ring (without the offset concept),
// use the ring_chars() method, and walk from 0 - ring_rows().
//
// _____________
// | | <- hist_srow() <- ring_srow()
// | H i s t |
// | |
// |_____________| <- hist_erow()
// | | <- disp_srow()
// | D i s p |
// | |
// |_____________| <- disp_erow() <- ring_erow()
//
// \___________/
// ring_cols()
// hist_cols()
// disp_cols()
//
inline int ring_rows(void) const { return ring_rows_; }
inline int ring_cols(void) const { return ring_cols_; }
inline int ring_srow(void) const { return(0); }
inline int ring_erow(void) const { return(ring_rows_ - 1); }
inline int hist_rows(void) const { return hist_rows_; }
inline int hist_cols(void) const { return ring_cols_; }
inline int hist_srow(void) const { return((offset_ + 0) % ring_rows_); }
inline int hist_erow(void) const { return((offset_ + hist_rows_ - 1) % ring_rows_); }
inline int disp_rows(void) const { return disp_rows_; }
inline int disp_cols(void) const { return ring_cols_; }
inline int disp_srow(void) const { return((offset_ + hist_rows_) % ring_rows_); }
inline int disp_erow(void) const { return((offset_ + hist_rows_ + disp_rows_ - 1) % ring_rows_); }
inline int offset(void) const { return offset_; }
// History use
inline int hist_use(void) const { return hist_use_; }
inline void hist_use(int val) { hist_use_ = val; }
inline int hist_use_srow(void) const { return((offset_ + hist_rows_ - hist_use_) % ring_rows_); }
inline Utf8Char *ring_chars(void) { return ring_chars_; } // access ring buffer directly
inline Utf8Char *ring_chars(void) const { return ring_chars_; } // access ring buffer directly
bool is_hist_ring_row(int grow) const;
bool is_disp_ring_row(int grow) const;
//DEBUG void show_ring_info(void) const;
void move_disp_row(int src_row, int dst_row);
void clear_disp_row(int drow, const CharStyle& style);
void scroll(int rows, const CharStyle& style);
const Utf8Char* u8c_ring_row(int row) const;
const Utf8Char* u8c_hist_row(int hrow) const;
const Utf8Char* u8c_hist_use_row(int hurow) const;
const Utf8Char* u8c_disp_row(int drow) const;
// Non-const versions of the above methods
// Using "Effective C++" ugly-as-hell syntax technique.
//
Utf8Char* u8c_ring_row(int row);
Utf8Char* u8c_hist_row(int hrow);
Utf8Char* u8c_hist_use_row(int hurow);
Utf8Char* u8c_disp_row(int drow);
void create(int drows, int dcols, int hrows);
void resize(int drows, int dcols, int hrows, const CharStyle& style);
void change_disp_rows(int drows, const CharStyle& style);
void change_disp_cols(int dcols, const CharStyle& style);
};
// Selection Class ///////////////////////////////////////////////////
//
// Class to manage mouse selection
//
class FL_EXPORT Selection {
int srow_, scol_, erow_, ecol_; // selection start/end. NOTE: start *might* be > end
int push_row_, push_col_; // global row/col for last FL_PUSH
Fl_Color selectionbgcolor_;
Fl_Color selectionfgcolor_;
int state_ ; // 0=none, 1=started, 2=extended, 3=done
bool is_selection_; // false: no selection
public:
Selection(void);
int srow(void) const { return srow_; }
int scol(void) const { return scol_; }
int erow(void) const { return erow_; }
int ecol(void) const { return ecol_; }
void push_clear() { push_row_ = push_col_ = -1; }
void push_rowcol(int row,int col) { push_row_ = row; push_col_ = col; }
void start_push() { start(push_row_, push_col_); }
bool dragged_off(int row,int col) { return (push_row_ != row) || (push_col_ != col); }
void selectionfgcolor(Fl_Color val) { selectionfgcolor_ = val; }
void selectionbgcolor(Fl_Color val) { selectionbgcolor_ = val; }
Fl_Color selectionfgcolor(void) const { return selectionfgcolor_; }
Fl_Color selectionbgcolor(void) const { return selectionbgcolor_; }
bool is_selection(void) const { return is_selection_; }
bool get_selection(int &srow,int &scol,int &erow,int &ecol) const; // guarantees return (start < end)
bool start(int row, int col);
bool extend(int row, int col);
void end(void);
void select(int srow, int scol, int erow, int ecol);
bool clear(void);
int state(void) const { return state_; }
void scroll(int nrows);
};
// EscapeSeq Class ///////////////////////////////////////////////////
//
// Class to handle parsing ESC sequences
//
// Holds all state information for parsing esc sequences,
// so sequences can span multiple block read(2) operations, etc.
// Handling of parsed sequences is NOT handled in this class,
// just the parsing of the sequences and managing generic integers.
//
class FL_EXPORT EscapeSeq {
public:
// EscapeSeq Constants
// Maximums
static const int maxbuff = 80; // character buffer
static const int maxvals = 20; // integer value buffer
// Return codes
static const int success = 0; // operation succeeded
static const int fail = -1; // operation failed
static const int completed = 1; // multi-step operation completed successfully
private:
char esc_mode_; // escape parsing mode state
char csi_; // This is an ESC[.. sequence (Ctrl Seq Introducer)
char buff_[maxbuff]; // escape sequence being parsed
char *buffp_; // parsing ptr into buff[]
char *buffendp_; // end of buff[] (ptr to last valid buff char)
char *valbuffp_; // pointer to first char in buff of integer being parsed
int vals_[maxvals]; // value array for parsing #'s in ESC[#;#;#..
int vali_; // parsing index into vals_[], 0 if none
int save_row_, save_col_; // used by ESC[s/u for save/restore
int append_buff(char c);
int append_val(void);
public:
EscapeSeq(void);
void reset(void);
char esc_mode(void) const;
void esc_mode(char val);
int total_vals(void) const;
int val(int i) const;
int defvalmax(int dval, int max) const;
bool parse_in_progress(void) const;
bool is_csi(void) const;
int parse(char c);
void save_cursor(int row, int col);
void restore_cursor(int &row, int &col);
};
// Partial UTF-8 Buffer Class ////////////////////////////////////////////
//
// Class to manage buffering partial UTF-8 characters between write calls.
//
class FL_EXPORT PartialUtf8Buf {
char buf_[10]; // buffer partial UTF-8 encoded char
int buflen_; // length of buffered UTF-8 encoded char
int clen_; // final byte length of a UTF-8 char
public:
void clear(void) { buflen_ = clen_ = 0; } // clear the buffer
PartialUtf8Buf(void) { clear(); } // Ctor
// Is byte 'c' in the middle of a UTF-8 encoded byte sequence?
bool is_continuation(char c) {
// Byte 1 Byte 2 Byte 3 ..etc..
// ASCII: 0xxxxxxx
// UTF8(2): 110xxxxx 10xxxxxx
// UTF8(3): 1110xxxx 10xxxxxx 10xxxxxx
// UTF8(4): 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
// UTF8(5): 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
// UTF8(6): 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
// \______/ \______________________________________________/
// Start byte Continuation bytes
// (c & 0xc0) == 0x80
return ((c & 0xc0) == 0x80);
}
// Access buffer
const char* buf(void) const { return buf_; }
// Access buffer length
int buflen(void) const { return buflen_; }
// Append bytes of a partial UTF-8 string to the buffer.
//
// Returns:
// - true if done OK. Use is_complete() to see if a complete char received.
// - false if buffer overrun occurred, class is clear()ed.
//
// An appropriate response to 'false' would be to print the
// "unknown character" and skip all subsequent UTF-8 continuation chars.
//
bool append(const char* p, int len) {
if (len <= 0) return true; // ignore silly requests: say we did but dont
if (buflen_ + len >= (int)sizeof(buf_)) // overrun check
{ clear(); return false; } // clear self, return false
if (!buflen_) clen_ = fl_utf8len(*p); // first byte? save char len for later
while (len>0) { buf_[buflen_++] = *p++; len--; } // append byte to buffer
return true;
}
bool is_complete(void) const { return (buflen_ && (buflen_ == clen_)); }
};
///////////////////////////////////////////////////////////////
//////
////// Fl_Terminal members + methods
//////
///////////////////////////////////////////////////////////////
private:
Fl_Scrollbar *vscroll_; // vertical scrollbar (value: rows above disp_chars[])
int scrollbar_size_; // local preference for scrollbar size
CharStyle current_style_; // current font, attrib, color..
// A ring buffer is used for the terminal's history (hist) and display (disp) buffer.
// See README-Fl_Terminal.txt, section "RING BUFFER DESCRIPTION" for diagrams/info.
//
// Ring buffer
RingBuffer ring_; // terminal history/display ring buffer
Cursor cursor_; // terminal cursor (position, color, etc)
Margin margin_; // terminal margins (top,left,bottom,right)
Selection select_; // mouse selection
EscapeSeq escseq; // Escape sequence parsing (ESC[ xterm/vt100)
bool show_unknown_; // if true, show unknown chars as '¿' (default off)
bool ansi_; // if true, parse ansi codes (default on)
char *tabstops_; // array of tab stops (0|1) \__ TODO: This should probably
int tabstops_size_; // size of tabstops[] array / be a class "TabStops".
Fl_Rect scrn_; // terminal screen xywh inside box(), margins, and vscroll
int autoscroll_dir_; // 0=autoscroll timer off, 3=scrolling up, 4=scrolling down
int autoscroll_amt_; // #pixels above or below edge, used for autoscroll speed
RedrawStyle redraw_style_; // NO_REDRAW, RATE_LIMITED, PER_WRITE
float redraw_rate_; // maximum redraw rate in seconds, default=0.10
bool redraw_modified_; // display modified; used by update_cb() to rate limit redraws
bool redraw_timer_; // if true, redraw timer is running
PartialUtf8Buf pub_; // handles Partial Utf8 Buffer (pub)
protected:
// Ring buffer management
const Utf8Char* u8c_ring_row(int grow) const;
const Utf8Char* u8c_hist_row(int hrow) const;
const Utf8Char* u8c_hist_use_row(int hrow) const;
const Utf8Char* u8c_disp_row(int drow) const;
// non-const versions of the above.
// "Effective C++" says: implement non-const method to cast away const
//
Utf8Char* u8c_ring_row(int grow);
Utf8Char* u8c_hist_row(int hrow);
Utf8Char* u8c_hist_use_row(int hurow);
Utf8Char* u8c_disp_row(int drow);
private:
void create_ring(int drows, int dcols, int hrows);
protected:
int vscroll_width(void) const;
private:
// Tabstops
void init_tabstops(int newsize);
void default_tabstops(void);
void clear_all_tabstops(void);
void set_tabstop(void);
void clear_tabstop(void);
// Updates
void update_screen_xywh(void);
void update_screen(bool font_changed);
void update_scrollbar(void);
// Resize
void resize_display_rows(int drows);
void resize_display_columns(int dcols);
void refit_disp_to_screen(void);
// Callbacks
static void scrollbar_cb(Fl_Widget*, void*); // scrollbar manipulation
static void autoscroll_timer_cb(void*); // mouse drag autoscroll
void autoscroll_timer_cb2(void);
static void redraw_timer_cb(void*); // redraw rate limiting timer
void redraw_timer_cb2(void);
// Screen management
protected:
const CharStyle& current_style(void) const;
void current_style(const CharStyle& sty);
private:
int x_to_glob_col(int X, int grow, int &gcol) const;
int xy_to_glob_rowcol(int X, int Y, int &grow, int &gcol) const;
protected:
int w_to_col(int W) const;
int h_to_row(int H) const;
// API: Display clear operations
void clear_sod(void);
void clear_eod(void);
void clear_eol(void);
void clear_sol(void);
void clear_line(int row);
void clear_line(void);
const Utf8Char* walk_selection(const Utf8Char *u8c, int &row, int &col) const;
bool get_selection(int &srow,int &scol,int &erow,int &ecol) const;
bool is_selection(void) const;
bool is_inside_selection(int row,int col) const;
private:
bool is_hist_ring_row(int grow) const;
bool is_disp_ring_row(int grow) const;
protected:
int selection_text_len(void) const;
const char* selection_text(void) const;
void clear_mouse_selection(void);
bool selection_extend(int X,int Y);
void scroll(int rows);
void insert_rows(int count);
void delete_rows(int count);
void insert_char_eol(char c, int drow, int dcol, int rep);
void insert_char(char c, int rep);
void delete_chars(int drow, int dcol, int rep);
void delete_chars(int rep);
public:
// API: Terminal operations
void clear(void);
void clear(Fl_Color val);
void clear_screen(bool scroll_to_hist=true); // ESC [ 2 J
void clear_screen_home(bool scroll_to_hist=true); // ESC [ H ESC [ 2 J
void clear_history(void); // ESC [ 3 J
void reset_terminal(void); // ESC c
void cursor_home(void); // ESC [ 0 H
public:
// API: Cursor
void cursorfgcolor(Fl_Color val);
void cursorbgcolor(Fl_Color val);
Fl_Color cursorfgcolor(void) const;
Fl_Color cursorbgcolor(void) const;
protected:
void cursor_row(int row);
void cursor_col(int col);
public:
int cursor_row(void) const;
int cursor_col(void) const;
protected:
void cursor_up(int count=1, bool do_scroll=false);
void cursor_down(int count=1, bool do_scroll=false);
void cursor_left(int count=1);
void cursor_right(int count=1, bool do_scroll=false);
void cursor_eol(void);
void cursor_sol(void);
void cursor_cr(void);
void cursor_crlf(int count=1);
void cursor_tab_right(int count=1);
void cursor_tab_left(int count=1);
void save_cursor(void);
void restore_cursor(void);
// Printing
private:
void handle_ctrl(char c);
bool is_printable(char c);
bool is_ctrl(char c);
void handle_SGR(void);
void handle_DECRARA(void);
void handle_escseq(char c);
// --
void display_modified(void);
void display_modified_clear(void);
void clear_char_at_disp(int drow, int dcol);
const Utf8Char* utf8_char_at_disp(int drow, int dcol) const;
const Utf8Char* utf8_char_at_glob(int grow, int gcol) const;
void repeat_char(char c, int rep);
void utf8_cache_clear(void);
void utf8_cache_flush(void);
// API: Character display output
public:
void putchar(const char *text, int len, int drow, int dcol);
void putchar(char c, int drow, int dcol);
void print_char(const char *text, int len=-1);
void print_char(char c);
// API: String display output
void append_utf8(const char *buf, int len=-1);
void append_ascii(const char *s);
void append(const char *s, int len=-1);
protected:
int handle_unknown_char(void);
// Drawing
void draw_row_bg(int grow, int X, int Y) const;
void draw_row(int grow, int Y) const;
void draw_buff(int Y) const;
private:
void handle_selection_autoscroll(void);
int handle_selection(int e);
public:
// FLTK: draw(), resize(), handle()
void draw(void) FL_OVERRIDE;
void resize(int X,int Y,int W,int H) FL_OVERRIDE;
int handle(int e) FL_OVERRIDE;
protected:
// Internal short names
// Don't make these public, but allow internals and
// derived classes to maintain brevity.
//
/// Return the number of rows in the ring buffer.
inline int ring_rows(void) const { return ring_.ring_rows(); }
/// Return the number of columns in the ring buffer.
inline int ring_cols(void) const { return ring_.ring_cols(); }
/// Return the starting row# in the ring buffer. (Always 0)
inline int ring_srow(void) const { return ring_.ring_srow(); }
/// Return the ending row# in the ring buffer (Always ring_rows()-1)
inline int ring_erow(void) const { return ring_.ring_erow(); }
/// Return the number of rows in the scrollback history.
inline int hist_rows(void) const { return ring_.hist_rows(); }
/// Return the number of columns in the scrollback history.
inline int hist_cols(void) const { return ring_.hist_cols(); }
/// Return the starting row# of the scrollback history.
inline int hist_srow(void) const { return ring_.hist_srow(); }
/// Return the ending row# of the scrollback history.
inline int hist_erow(void) const { return ring_.hist_erow(); }
/// Return number of rows in use by the scrollback history.
inline int hist_use(void) const { return ring_.hist_use(); }
/// Return the starting row of the "in use" scrollback history.
inline int hist_use_srow(void) const { return ring_.hist_use_srow(); }
/// Return the number of rows in the display area.
inline int disp_rows(void) const { return ring_.disp_rows(); }
/// Return the number of columns in the display area.
inline int disp_cols(void) const { return ring_.disp_cols(); }
/// Return the starting row# in the display area.
inline int disp_srow(void) const { return ring_.disp_srow(); }
/// Return the ending row# in the display area.
inline int disp_erow(void) const { return ring_.disp_erow(); }
/// Returns the current offset into the ring buffer.
inline int offset(void) const { return ring_.offset(); }
// TODO: CLEAN UP WHAT'S PUBLIC, AND WHAT SHOULD BE 'PROTECTED' AND 'PRIVATE'
// Some of the public stuff should, quite simply, "not be".
// API: Terminal features
public:
// API: Scrollbar
int scrollbar_size(void) const;
void scrollbar_size(int val);
int scrollbar_actual_size(void) const;
// API: History
int history_rows(void) const;
void history_rows(int val);
int history_use(void) const;
// API: Display
int display_rows(void) const;
void display_rows(int val);
int display_columns(void) const;
void display_columns(int val);
// API: Box
/// 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().
///
void box(Fl_Boxtype val) { Fl_Group::box(val); update_screen(false); }
/// Returns the current box type.
Fl_Boxtype box(void) const { return Fl_Group::box(); }
// API: Margins
/// Return the left margin; see \ref Fl_Terminal_Margins.
int margin_left(void) const { return margin_.left(); }
/// Return the right margin; see \ref Fl_Terminal_Margins.
int margin_right(void) const { return margin_.right(); }
/// Return the top margin; see \ref Fl_Terminal_Margins.
int margin_top(void) const { return margin_.top(); }
/// Return the bottom margin; see \ref Fl_Terminal_Margins.
int margin_bottom(void) const { return margin_.bottom(); }
void margin_left(int val);
void margin_right(int val);
void margin_top(int val);
void margin_bottom(int val);
// API: Text font/size/color
void textfont(Fl_Font val);
void textsize(Fl_Fontsize val);
void textcolor(Fl_Color val);
void color(Fl_Color val);
void textfgcolor(Fl_Color val);
void textbgcolor(Fl_Color val);
void textfgcolor_default(Fl_Color val);
void textbgcolor_default(Fl_Color val);
/// Return text font used to draw all text in the terminal.
Fl_Font textfont(void) const { return current_style_.fontface(); }
/// Return text font size used to draw all text in the terminal.
Fl_Fontsize textsize(void) const { return current_style_.fontsize(); }
/// Return base widget Fl_Group's box() color()
Fl_Color color(void) const { return Fl_Group::color(); }
/// Return textcolor(). This is a convenience method that returns textfgcolor_default()
Fl_Color textcolor(void) const { return textfgcolor_default(); }
/// Return text's current foreground color.
Fl_Color textfgcolor(void) const { return current_style_.fgcolor(); }
/// Return text's current background color.
Fl_Color textbgcolor(void) const { return current_style_.bgcolor(); }
/// Return text's default foreground color. \see textfgcolor()
Fl_Color textfgcolor_default(void) const { return current_style_.defaultfgcolor(); }
/// Return text's default background color. \see textbgcolor()
Fl_Color textbgcolor_default(void) const { return current_style_.defaultbgcolor(); }
void textfgcolor_xterm(uchar val);
void textbgcolor_xterm(uchar val);
/// Set mouse selection foreground color.
void selectionfgcolor(Fl_Color val) { select_.selectionfgcolor(val); }
/// Set mouse selection background color.
void selectionbgcolor(Fl_Color val) { select_.selectionbgcolor(val); }
/// Get mouse selection foreground color.
Fl_Color selectionfgcolor(void) const { return select_.selectionfgcolor(); }
/// Get mouse selection background color.
Fl_Color selectionbgcolor(void) const { return select_.selectionbgcolor(); }
// API: Text attrib
void textattrib(uchar val);
// API: Redraw style/rate
RedrawStyle redraw_style(void) const;
void redraw_style(RedrawStyle val);
private:
bool is_redraw_style(RedrawStyle val) { return redraw_style_ == val; }
public:
float redraw_rate(void) const;
void redraw_rate(float val);
// API: Show unknown/unprintable chars
bool show_unknown(void) const;
void show_unknown(bool val);
// API: ANSI sequences
bool ansi(void) const;
void ansi(bool val);
// Fl_Simple_Terminal API compatibility
int history_lines(void) const;
void history_lines(int val);
// API: printf()
void printf(const char *fmt, ...);
void vprintf(const char *fmt, va_list ap);
// Ctor
Fl_Terminal(int X, int Y, int W, int H, const char*L=0);
// Dtor
~Fl_Terminal(void);
// Debugging features
//DEBUG void show_ring_info() const { ring_.show_ring_info(); }
//DEBUG void write_row(FILE *fp, Utf8Char *u8c, int cols) const;
//DEBUG void show_buffers(RingBuffer *a, RingBuffer *b=0) const;
};
#endif
Reference in New Issue View Git Blame Copy Permalink