If your application generates text and needs to manage the display of that text - it's location, character attributes, etc - then this interface abstracts all that; this interface works with any video terminal type.

Public Methods

UserTerm(device)

const string& device

a string representation of the user's device, e.g. UserDevice.toString()

Default value: ""

Construct a virtual terminal with an optional id.

static UserTerm create(device, screenName, terminalType)

const UserDevice& device

the end-user's device; note that the region here is where the terminal will be displayed

const string& screenName

the application-specific keyword to use for this terminal; if multiple terminals are displayed to the user, this keyword differentiates them

const string& terminalType

if important to your application, specify here, otherwise it's xterm; see TermAPI for supported terminals

Default value: "xterm"

Setup a virtual terminal display on the user's device.

Return value: an instance of UserTerm to connect to the virtual terminal

void create(screenName)

const string& screenName

the application-specific keyword to use for this terminal; if multiple terminals are displayed to the user, this keyword differentiates them

Setup a virtual terminal display on the user's device.

inline const string& getName() const

Get the screen name for this virtual terminal

Return value: virtual terminal screen name

UserDevice& setDevice(device)

UserDevice& device

end user's device

Specify the user device for this virtual terminal.

This needs to be done before calling create(). If called after create(), communication with the virtual terminal may be broken - if it's pointing to the wrong user device region.

inline UserDevice& getDevice()

Query the end user's device

Return value: end user's device

int putchar(c)

int c

the caracter to send

Send a character to the terminal

Return value: the character upon success, 0 upon failure

bool puts(text)

const string& text

the text to display to the terminal

Send some text to the virtual terminal.

Return value: true if directive sent successfully, false if not

bool setTerminalType(termType)

const string& termType

this tells the virtual terminal emulator what capabilities the video terminal has; also, if you send any escape sequences, it knows how to interpret them

Default value: "xterm"

Set the terminal type.

Return value: true if directive sent successfully, false if not

bool redraw()

Tell the virtual terminal to redraw its terminal image.

Return value: true if directive sent successfully, false if not

bool bell()

Sound the terminal bell.

Return value: true if directive sent successfully, false if not

bool tab()

Tab the cursor to the right to the next tab stop.

Return value: true if directive sent successfully, false if not

bool setpos(y, x)

int y	cursor row, from 1+
int x	cursor column, from 1+

Set the cursor position to the coordinates given.

Return value: true if directive sent successfully, false if not

bool bold(mode)

const string& mode

on, off, or toggle

Default value: "toggle"

Turn on, off, or toggle bold mode.

Return value: true if directive sent successfully, false if not

inline bool boldon()

Turn on bold mode.

Return value: true if directive sent successfully, false if not

inline bool boldoff()

Turn off bold mode.

Return value: true if directive sent successfully, false if not

bool underline(mode)

const string& mode

on, off, or toggle

Default value: "toggle"

Turn on, off, or toggle underline mode.

Return value: true if directive sent successfully, false if not

inline bool underlineon()

Turn on underline mode.

Return value: true if directive sent successfully, false if not

inline bool underlineoff()

Turn off underline mode.

Return value: true if directive sent successfully, false if not

bool reverse(mode)

const string& mode

on, off, or toggle

Default value: "toggle"

Turn on, off, or toggle reverse video mode.

Return value: true if directive sent successfully, false if not

inline bool reverseon()

Turn on reverse video mode.

Return value: true if directive sent successfully, false if not

inline bool reverseoff()

Turn off reverse video mode.

Return value: true if directive sent successfully, false if not

bool blinking(mode)

const string& mode

on, off, or toggle

Default value: "toggle"

Turn on, off, or toggle character blinking/flashing mode.

Return value: true if directive sent successfully, false if not

inline bool blinkingon()

Turn on blinking mode.

Return value: true if directive sent successfully, false if not

inline bool blinkingoff()

Turn off blinking mode.

Return value: true if directive sent successfully, false if not

bool color(defaultColor)

const string& defaultColor

color name, e.g. black, red, green, yellow, blue, magenta, cyan, white (default)

Set the character attribute to the specified color. Characters printed after this will be of that color.

Return value: true if directive sent successfully, false if not

inline bool black()

Set character attribute color to black. Characters printed after this will be of that color.

Return value: true if directive sent successfully, false if not

inline bool red()

Set character attribute color to red. Characters printed after this will be of that color.

Return value: true if directive sent successfully, false if not

inline bool green()

Set character attribute color to green. Characters printed after this will be of that color.

Return value: true if directive sent successfully, false if not

inline bool yellow()

Set character attribute color to yellow. Characters printed after this will be of that color.

Return value: true if directive sent successfully, false if not

inline bool blue()

Set character attribute color to blue. Characters printed after this will be of that color.

Return value: true if directive sent successfully, false if not

inline bool magenta()

Set character attribute color to magenta. Characters printed after this will be of that color.

Return value: true if directive sent successfully, false if not

inline bool cyan()

Set character attribute color to cyan. Characters printed after this will be of that color.

Return value: true if directive sent successfully, false if not

inline bool white()

Set character attribute color to white. Characters printed after this will be of that color.

Return value: true if directive sent successfully, false if not

bool reset()

Reset all the character attributes back to default.

Return value: true if directive sent successfully, false if not

bool clear(area)

const string& area

identify area by name, e.g. all, above, below, left, right, line, toptohere, heretoend, last

Default value: "all"

Clear a region of the screen with respect to the cursor

Return value: true if directive sent successfully, false if not

bool delline(y)

int y

the row to delete, from 1+

Delete the screen row. Rows below it will scroll up to fill in the deleted line

Return value: true if directive sent successfully, false if not

bool insline(y)

int y

the row to delete, from 1+

Insert a blank row at screen row. Rows below it will scroll down to make room

Return value: true if directive sent successfully, false if not

bool delchar()

Delete the character at the cursor. Characters to the right will scroll left one character.

Return value: true if directive sent successfully, false if note

bool delchar(x)

int x

the column of character to delete, from 1+

Delete the character at the column specified. Characters to the right will scroll left one character.

Return value: true if directive sent successfully, false if note

bool delchar(y, x)

int y	the row of the character to delete, from 1+
int x	the column of character to delete, from 1+

Delete the character at the row and column specified. Characters to the right will scroll left one character.

Return value: true if directive sent successfully, false if note

bool inschar(c)

int c

the character to insert

Default value: ' '

Insert a character at the cursor. Characters to the right will scroll right one character

Return value: true if directive sent successfully, false if note

bool inschar(x, c)

int x

the column of character to insert, from 1+

int c

the character to insert

Default value: ' '

Insert a character at the column specified. Characters to the right will scroll right one character.

Return value: true if directive sent successfully, false if note

bool inschar(y, x, c)

int y

the row of the character to insert, from 1+

int x

the column of character to insert, from 1+

int c

the character to insert

Default value: ' '

Insert a character at the row and column specified. Characters to the right will scroll right one character.

Return value: true if directive sent successfully, false if note

bool clear(y1, x1, y2, x2)

int y1	row of corner 1, from 1+
int x1	column of corner 1, from 1+
int y2	row of corner 2, from 1+
int x2	column of corner 2, from 1+

Clear an area of the screen specified by the two corners provided.

Return value: true if directive sent successfully, false if note

bool fill(y1, x1, y2, x2, c)

int y1	row of corner 1, from 1+
int x1	column of corner 1, from 1+
int y2	row of corner 2, from 1+
int x2	column of corner 2, from 1+
int c	the character to fill Default value: ' '

Fill an area of the screen specified by the two corners provided with the character provided.

Return value: true if directive sent successfully, false if note

bool move(y1, x1, y2, x2, yt, xt, c)

int y1	row of corner 1, from 1+
int x1	column of corner 1, from 1+
int y2	row of corner 2, from 1+
int x2	column of corner 2, from 1+
int yt	row of target upper corner, from 1+
int xt	column of target left corner, from 1+
int c	the character to fill in the old area Default value: 0

Move text from an area of the screen specified by the two corners provided to a new target spot (upper left corner prividd).

Return value: true if directive sent successfully, false if note

bool cursor(direction, amount)

const string& direction

direction to move cursor, e.g. up, down, left, right, home

int amount

number of columns or rows to move

Default value: 1

Move the cursor in the specified direction the specified amount

Return value: true if directive sent successfully, false if not (or if invalid direction)

bool home()

Move the cursor to the home position, (1,1).

Return value: true if directive sent successfully, false if not

bool up(amount)

int amount

number of rows to move

Default value: 1

Move the cursor upward the specified amount.

Return value: true if directive sent successfully, false if not

bool down(amount)

int amount

number of rows to move

Default value: 1

Move the cursor downward the specified amount.

Return value: true if directive sent successfully, false if not

bool left(amount)

int amount

number of columns to move

Default value: 1

Move the cursor to the right the specified amount.

Return value: true if directive sent successfully, false if not

bool right(amount)

int amount

number of columns to move

Default value: 1

Move the cursor to the right the specified amount.

Return value: true if directive sent successfully, false if not

int getposy()

Future feature. Query the terminal's row.

This may not be the actual row; this is UserTerm's estimation of where the cursor row is.

Return value: terminal row of cursor

int getposx()

Future feature. Query the terminal's column

This may not be the actual column; this is UserTerm's estimation of where the cursor column is.

Return value: terminal column of cursor

Private Properties

string name	virtual terminal screen name
string termType	terminal type of virtual terminal, e.g. xterm
bool stable	Flag: (unused) have any attributes been sent to video terminal
int x	Cursor location (column, row)
int y	Cursor location (column, row)
int rows	Size of video terminal
int columns	Size of video terminal
string _bold	Character attribute flags
string _underline	Character attribute flags
string _reverse	Character attribute flags
string _blinking	Character attribute flags
string _color	Character attribute flags

Private Methods

void clearState(yxonly)

bool yxonly

true to only reset cursor position; false to reset character attribute state, too

Default value: true

Clear video terminal state. Cursor location and character attributes are typically tracked.