gterm.doc

This file describes the structure, functionality, and use of the GTerm
core.  GTerm is an abstract class in the sense that a child class must
be derived from it in order to provide required display functionality.

GTerm is implemented as a simple state machine that responds to character
input by performing actions and state changes.  It treats characters
as symbols and their valid arrangements as a deterministic grammar.
The current set of codes includes most of VT52 and passess a VT100
verification test suite with flying colors.

The core is comprised of the following files:

gterm.hpp       - the interface, described in this document
gterm.cpp       - high-level functionality of GTerm
states.cpp      - state tables for the state machine
vt52_states.cpp - state tables for VT52 mode
actions.cpp     - operations controlled by the state machine
utils.cpp       - utility functions used by actions

The public interface comes in three sections: Controls, Manditory hooks,
and Optional hooks.

** Controls - methods which are used to control the terminal

virtual void GTerm::ProcessInput(int len, unsigned char *data)

Call this method, providing the length and pointer to a buffer of data
to be processed for display on the terminal.  This data can include
ASCII text and VT102 escape sequences.

virtual void GTerm::ResizeTerminal(int width, int height)

This instructs the terminal to change dimentions (width and height in
character cells).  Any display, such as a window, should be resized by
the caller.

int GTerm::Width()
int GTerm::Height()

These simply return the width and height (in character cells) of the 
terminal.

virtual void GTerm::Update()

GTerm will perform a great deal of manipulation of the display before
making any updates to the display device, for reasons of efficiency.
In cases where the terminal is configured for deferred updates (the 
DEFERUPDATE flag is set), the caller will have to instruct the terminal 
to update the display device whenever appropriate.

virtual void GTerm::ExposeArea(int x, int y, int w, int h)

In windowing environments, parts of a window may be obscured, and when
they are exposed, they need to be redrawn.  GTerm can be instructed to
update that area of the display by calling this method with the coordinates
and dimentions (in character cells) of the exposed area.

virtual void Reset()

Simply resets the terminal.


** Mandatory hooks - functions to be provided by the derived class

virtual void DrawText(int fg_color, int bg_color, int flags,
    int x, int y, int len, unsigned char *string)

This method must be provided in the derived class in order for characters
to be drawn on the output device.  If the TEXTONLY flag is set (described
later), then only this method and DrawCursor are used to output to the
display device.  The x and y coordinates are in units of character cells.

Colors:
0 - black
1 - red
2 - green
3 - yellow
4 - blue
5 - magenta
6 - cyan
7 - white

Applicable flags:
GTerm::BOLD, GTerm::BLINK, GTerm::UNDERLINE, GTerm::INVERSE

virtual void DrawCursor(int fg_color, int bg_color, int flags,
    int x, int y, unsigned char c)

This method must be provided in the derived class for drawing the cursor.
The colors, applicable flags, and character for the cell where the cursor
is to be placed are provided.


** Optional hooks - functions optionally provided by the derived class

virtual void MoveChars(int sx, int sy, int dx, int dy, int w, int h)

If the TEXTONLY flag is clear, this method is used to optimize scrolling.
The coordinates are in units of character cells and they have the following
meanings:

sx,sy - Coordinates of source rectangle
dx,dy - Coordinates of destination rectangle
w,h   - Dimentions of area to be copied

virtual void ClearChars(int bg_color, int x, int y, int w, int h)

If the TEXTONLY flag is clear, this method is used to optimize the blanking
of regions of the display.  A solid color value is provided which indicates
what color the area should be cleared to.  Coordinates and size are in
units of character cells.

virtual void SendBack(char *data)

If the terminal encounters an escape sequence that requires a response from
the terminal, this method will be called with a null-terminated string
which should be transmitted.

virtual void ModeChange(int state)

Whenever GTerm::set_mode_flag() or GTerm::clear_mode_flag() is called 
(usually from code internal to GTerm), the ModeChange method is called
to inform the derived class of the change.  This is usually not needed
and can be left unimplemented.

virtual void Bell()

When the terminal encounters a control-G (Ascii 7), this method is called.

virtual void RequestSizeChange(int w, int h)

When the terminal encounters an escape sequence that requests that the
terminal size be changes (ie. from 80 to 132 columns), this method is
called.  If the child class allows this, it should implement a
RequestSizeChange method that responds by calling ResizeTerminal.
Otherwise, the size change will be ignored.


** Mode flags

Four methods are provided for dealing with mode flags.  They are:

GTerm::GetMode()             - returns the current mode flags
GTerm::SetMode(int)          - explicitly sets the mode flags
GTerm::set_mode_flag(int)    - Sets (using OR) the specified flags
GTerm::clear_mode_flags(int) - Clears the specified flags

The flags have the following meanings when set:

Character attribute flags:

BOLD            - brighten or double-strike characters
BLINK           - characters drawn should blink
UNDERLINE       - underline characters
INVERSE         - swap foreground and background colors

Other flags:

NOEOLWRAP       - cursor does not wrap to next line when right edge is reached
CURSORAPPMODE   - cursor keys produce alternate <esc>O sequences
CURSORRELATIVE  - cursor positioning is relative to current scrolling region
NEWLINE         - return key should transmit CR/LF
INSERT          - characters drawn cause characters to the right to shift right
KEYAPPMODE      - keypad keys produce escape sequences
DEFERUPDATE     - display updates are not done automatically by GTerm.
                  the caller must call Update() for display updates
DESTRUCTBS      - backspace (ASCII 8) clears the cell is backs into
TEXTONLY        - MoveChars and ClearChars optimizations are not used
LOCALECHO       - typed keys should be echoed to the display
CURSORINVISIBLE - DrawCursor method does not get called