- Generated by
1.9.8
|
FLTK 1.4.0
|
This chapter covers the vt100/xterm style "escape codes" used by Fl_Terminal for cursor positioning, text colors, and other display screen control features such as full or partial screen clearing, up/down scrolling, character insert/delete, etc.
These are the escape codes Fl_Terminal actually supports, and is not the 'complete' list that e.g. xterm supports. Most of the important stuff has been implemented, but esoteric features (such as scroll regions) has not.
Features will be added as the widget matures.
Useful links for reference:
When I started this project, I identified the key concepts needed to implement Fl_Terminal:
A class was created for each character, since characters can be either ASCII or Utf8 encoded byte sequences. This class is called Utf8Char, and handles the character, its fg and bg color, and any attributes like dim, bold, italic, etc.
For managing the screen, after various experiments, I decided a ring buffer was the best way to manage things, the ring split in two:
Scrolling the display, either by scrollbar or by new text causing the display to scroll up one line, would simply change an 'offset' index# of where in the ring buffer the top of the screen is, automatically moving the top line into the history, all without moving memory around.
In fact the only time screen memory is moved around is during these infrequent operations:
So a class "RingBuffer" is defined to manage the ring, and accessing its various parts, either as the entire entity ring, just the history, or just the display.
These three concepts, "ring", "history" and "display" are given abbreviated names in the RingBuffer class's API:
┌─────────────────────────────────────────┬──────────────────────────────┐ │ NOTE: Abbreviations "hist" and "disp" │ │ ├─────────────────────────────────────────┘ │ │ │ │ "history" may be abbreviated as "hist", and "display" as "disp" in │ │ both this text and the source code. 4 character names are used so │ │ they line up cleanly in the source, e.g. │ │ │ │ ring_rows() ring_cols() │ │ hist_rows() hist_cols() │ │ disp_rows() disp_cols() │ │ └─┬┘ └─┬┘ └─┬┘ └─┬┘ │ │ └────┴──────────┴────┴───────── 4 characters │ │ │ └────────────────────────────────────────────────────────────────────────┘
These concepts were able to fit into C++ classes:
Each character on the screen is a "Utf8Char" which can manage the UTF-8 encoding of any character as one or more bytes. Also in that class is a byte for an attribute (underline, bold, etc), and two integers for fg/bg color.
The RingBuffer class keeps track of the buffer itself, a single array of Utf8Chars called "ring_chars" whose width is ring_cols() and whose height is ring_rows().
The "top" part of the ring is the history, whose width is hist_cols() and whose height is hist_rows(). hist_use_rows() is used to define what part of the history is currently in use.
The "bottom" part of the ring is the display, whose width is disp_cols() and whose height is disp_rows().
An index number called "offset" points to where in the ring buffer the top of the ring currently is. This index changes each time the screen is scrolled, and affects both where the top of the display is, and where the top of the history is.
The memory layout of the Utf8Char character array is:
ring_chars[]:
___________________ _ _
| | ʌ
| | |
| | |
| H i s t o r y | | hist_rows
| | |
| | |
|___________________| _v_
| | ʌ
| | |
| D i s p l a y | | disp_rows
| | |
|___________________| _v_
|<----------------->|
ring_cols
hist_cols
disp_cols
So it's basically a single continuous array of Utf8Char instances where any character can generally be accessed by index# using the formula:
ring_chars[ (row*ring_cols)+col ]
..where 'row' is the desired row, 'col' is the desired column, and 'ring_cols' is how many columns "wide" the buffer is.
The "offset" index affects that formula as an extra row offset, and the resulting index is then clamped within the range of the ring buffer using modulus.
Methods are used to allow direct access to the characters in the buffer that automatically handle the offset and modulus formulas, namely:
u8c_ring_row(row,col) // access the entire ring by row/col
u8c_hist_row(row,col) // access just the history buffer
u8c_disp_row(row,col) // access just the display buffer
A key concept is the use of the simple 'offset' index integer to allow the starting point of the history and display to be moved around to implement 'text scrolling', such as when crlf at the screen bottom causes a 'scroll up'.
This is simply an "index offset" integer applied to the hist and disp indexes when drawing the display. So after scrolling two lines up, the offset is just increased by 2, redefining where the top of the history and display are, e.g.
Offset is 0: 2 Offset now 2:
┌───────────────────┐ ──┐ ┌───────────────────┐
│ │ │ │ D i s p l a y │
│ │ └─> ├───────────────────┤
│ │ │ │
│ H i s t o r y │ │ │
│ │ │ H i s t o r y │
│ │ 2 │ │
├───────────────────┤ ──┐ │ │
│ │ │ │ │
│ │ └─> ├───────────────────┤
│ D i s p l a y │ │ │
│ │ │ D i s p l a y │
│ │ │ │
└───────────────────┘ └───────────────────┘
This 'offset' trivially implements "text scrolling", avoiding having to physically move memory around. Just the 'offset' changes, the text remains where it is in memory.
This also makes it appear the top line in the display is 'scrolled up' into the bottom of the scrollback 'history'.
If the offset exceeds the size of the ring buffer, it simply wraps around back to the beginning of the buffer with a modulo.
Indexes into the display and history are also modulo their respective rows, e.g.
act_ring_index = (hist_rows + disp_row + offset - scrollbar_pos) % ring_rows;
This way indexes for ranges can run beyond the bottom of the ring, and automatically wrap around the ring, e.g.
┌───────────────────┐
┌─> 2 │ │
│ 3 │ D i s p l a y │
│ 4 │ │
│ ├───────────────────┤ <-- offset points here
│ │ │
disp │ │ │
index ┤ │ H i s t o r y │
wraps │ │ │
│ │ │
│ │ │
│ ├───────────────────┤
│ 0 │ D i s p l a y │
│ 1 └───────────────────┘ <- ring_rows points to end of ring
└── 2 : :
3 : :
disp_row(5) -> 4 :...................:
The dotted lines show where the display would be if not for the fact it extends beyond the bottom of the ring buffer (due to the current offset), and therefore wraps up to the top of the ring.
So to find a particular row in the display, in this case a 5 line display whose lines lie between 0 and 4, some simple math calculates the row position into the ring:
act_ring_index = (histrows // the display exists AFTER the history, so offset the hist_rows
+ offset // include the scroll 'offset'
+ disp_row // add the desired row relative to the top of the display (0..disp_rows)
) % ring_rows; // make sure the resulting index is within the ring buffer (0..ring_rows)
An additional bit of math makes sure if a negative result occurs, that negative value works relative to the end of the ring, e.g.
if (act_ring_index < 0) act_ring_index = ring_rows + act_ring_index;
This guarantees the act_ring_index is within the ring buffer's address space, with all offsets applied.
The math that implements this can be found in the u8c_xxxx_row() methods, where "xxxx" is one of the concept regions "ring", "hist" or "disp":
Utf8Char *u8c; u8c = u8c_ring_row(rrow); // address within ring, rrow can be 0..(ring_rows-1) u8c = u8c_hist_row(hrow); // address within hist, hrow can be 0..(hist_rows-1) u8c = u8c_disp_row(drow); // address within disp, drow can be 0..(disp_rows-1)
The small bit of math is only involved whenever a new row address is needed, so in a display that's 80x25, to walk all the characters in the screen, the math above would only be called 25 times, once for each row, and each column in the row is just a simple integer offset:
for ( int row=0; row<disp_rows(); row++ ) { // walk rows: disp_rows = 25
Utf8Char *u8c = u8c_disp_row(row); // get first char in display 'row'
for ( int col=0; col<disp_cols(); col++ ) { // walk cols: disp_cols = 80
u8c[col].do_something(); // work with the char at row/col
}
}
So to recap, the concepts here are:
ring_rows -- how many rows in the entire ring buffer
ring_cols -- how many columns in the ring buffer
nchars -- total chars in ring, e.g. (ring_rows * ring_cols)
0 .. hist_rows()-1
hist_rows() .. hist_rows()+disp_rows()-1..or similarly:
(hist_rows)..(ring_rows-1)The following convenience methods provide access to the start and end indexes within the ring buffer for each entity:
Entire ring ring_srow() – start row index of the ring buffer (always 0) ring_erow() – end row index of the ring buffer
"history" part of ring hist_srow() – start row index of the screen history hist_erow() – end row index of the screen history
"display" part of ring disp_srow() – start row index of the display disp_erow() – end row index of the display
The values returned by these are as described above. For the hist_xxx() and disp_xxx() methods the 'offset' included into the forumula. (For this reason hist_srow() won't always be zero the way ring_srow() is, due to the 'offset')
The values returned by these methods can all be passed to the u8c_ring_row() function to access the actual character buffer's contents.
The ring buffer allows new content to simply be appended to the ring buffer, and the index# for the start of the display and start of scrollback history are simply incremented. So the next time the display is "drawn", it starts at a different position in the ring.
This makes scrolling content at high speed trivial, without memory moves. It also makes the concept of "scrolling" with the scrollbar simple as well, simply being an extra index offset applied during drawing.
Dragging the mouse across the screen should highlight the text, allowing the user to extend the selection either beyond or before the point started. Extending the drag to the top of the screen should automatically 'scroll up' to select more lines in the scrollback history, or below the bottom to do the opposite.
The mouse selection is implemented as a class to keep track of the start/end row/col positions of the selection, and other details such as a flag indicating if a selection has been made, what color the fg/bg text should appear when text is selected, and methods that allow setting and extending the selection, clearing the selection, and "scrolling" the selection, to ensure the row/col indexes adjust correctly to track when the screen or scrollbar is scrolled.
Knowing when to redraw is tricky with a terminal, because sometimes high volumes of input will come in asynchronously, so in that case we need to determine when to redraw the screen to show the new content; too quickly will cause the screen to spend more time redrawing itself, preventing new input from being added. Too slowly, the user won't see new information appear in a timely manner.
To solve this, a rate timer is used to prevent too many redraws:
In this way, redraws don't happen more than 10x per second, and redraw() is called only when there's new content to see.
The redraw rate can be set by the user application using the Fl_Terminal::redraw_rate(), 0.10 being the default.
Some terminal operations necessarily call redraw() directly, such as interactive mouse selection, or during user scrolling the terminal's scrollbar, where it's important there's no delay in what the user sees while interacting directly with the widget.
1.9.8