NAME

cls - clear screen and other terminal dependent functions

SYNOPSIS

initrm()

cls()

short pos()

short csrlin()

locate(rowflag, row, colflag, col)
short rowflag, row, colflag, col;

color(foreflag, fore, backflag, back)
short foreflag, fore, backflag, back;

int inkmatch(s, n, pval)
char *s;
int n, *pval;

DESCRIPTION

These functions deal with terminal dependencies.  The necessary information is obtained from the terminal capabilities database.  For a description of this database refer to termcap(5) or terminfo(4), depending on the ancestry of the system.  The full-blown “screen handling” facility of curses(3) is not used.  Very few of the BASIC I/O functions are screen oriented so the overhead in the size of the executable and in execution time is not justified. 

Initrm obtains and stores the terminal’s length and width, the descriptions of the clear screen and cursor motion functions and the character sequences produced by the special function keys.  Initrm is called when the program starts-up if any terminal dependent functions are required and whenever these functions are invoked.  This function does nothing when invoked redundantly.  In case of difficulty, the terminal’s length is assumed to be 24 lines, the width, 80 columns and the other functions, null. 

Cls writes the terminal’s clear screen function to the current file using btermcap (see bputc(io)) presumably causing the screen to clear.  The row and column numbers of the current file are set to zero.  Within the library, rows and columns are numbered starting with zero.  This function implements the CLS statement. 

Pos returns the current column number of the current file (see initio(io)).  At the level of the user’s code, columns are numbered starting with one.  This function implements the BASIC POS function. 

Csrlin returns the current row number of the current file.  At the level of the user’s code, rows are numbered starting with one.  This function implements the BASIC CSRLIN variable. 

Locate sets the row number of the current file to row if rowflag is set and sets the column number of the current file to col if colflag is set.  This function then writes the terminal’s cursor motion function (based on these values) to the current file using btermcap presumably causing the cursor to move to this location.  At the level of the user’s code, rows and columns are numbered starting with one.  This function implements the LOCATE statement. 

The current row number is assumed to be the bottom of the screen when the program starts-up.  Also, if the current row number is the bottom of the screen and a newline is written, the row number is assumed to remain the same, i.e. the screen is assumed to scroll.  If these assumptions are incorrect, the user may correct a discrepancy regarding the cursor location with locate. 

Color sets the foreground and background colors to fore if foreflag and back if backflag.  Only the low order three bits of fore and back are used in the color determination.  If fore is zero, the foreground is reversed and normal otherwise.  If back is seven, the background is reversed and normal otherwise.  Additionally, if fore is one, the foreground is underlined.  Reverse video and underlining are achieved using the “stand-out” and underlining mode capabilities.  If these are not available, the display is left normal.  The display is not altered if white on white or black on black is specified.  This function implements the COLOR statement. 

Inkmatch attempts to match n characters from s against its list of character sequences produced by the special function keys of the terminal.  Inkmatch returns zero if a partial match is found, i.e., all n characters match part, but not all, of an expected character sequence.  If an exact match is found, inkmatch returns the character code returned by inkeyS (see inkeyS(io) for the list of character codes and special function keys).  This function supports inkeyS(io). 

SEE ALSO

bputc(io), initio(io), inkeyS(io)
cls(stmt), pos(func), csrlin(vrbl), locate(stmt), color(stmt)
curses(3), terminfo(4) or termcap(5) in the UNIX Programmer’s Manual

DIAGNOSTICS

Cls and locate write nothing if initrm fails to obtain the necessary information. 

Initrm, cls and locate generate error 7 (Out of memory) if storage space is exhausted. 

Locate generates error 5 (Illegal function call) if row or column is out of range. 

Color generates error 5 (Illegal function call) if fore or back is negative or greater than 255. 

Inkmatch returns -1 if no match (partial or exact) is found or if initrm fails to obtain the necessary information. 

from The Basmark QuickBASIC Programmer’s Manual by Lawrence Leinweber