LIBCURSOR(3)

NAME
libcursor - cursor control library

SYNOPSIS
#include <stdio.h>

int InitTermCap(fp);
FILE *fp;

int MvCursor(x, y);
int x, y;

int HmCursor();

int ClrEOL();

int ClrText();

int ClrStandout();

int SetStandout();

int SetScrlReg(top, bottom);
int top, bottom;

int ResetScrlReg();

int ScrollUp();

int ScrollDn();

int DeleteLn();

int PutChr(c);
int c;

extern char termName[];
extern int LI;    /* number of lines on screen (or layer) */
extern int CO;    /* number of columns on screen (or layer) */
extern char *BC;    /* backspace */
extern char *PC;    /* padding character */
extern char *UP;    /* move cursor up one line */
extern char *CS;    /* change scrolling region */
extern char *SO;    /* begin standout mode */
extern char *SE;    /* end standout mode */
extern char *CE;    /* clear to end of line */
extern char *CL;    /* clear display (also homes cursor) */
extern char *HO;    /* home cursor */
extern char *CM;    /* screen-relative cursor motion */
extern char *TI;    /* initialize terminal */
extern char *DL;    /* delete current line */
extern char *SR;    /* scroll text down (backward) */
extern char *SF;    /* scroll text up (forward) */

DESCRIPTION
These routines are designed to provide a terminal-independent means of controlling cursor movement, character attributes, text scrolling, and erasure of text which is a level above the termlib(3) library. It is similar to the curses(3) library, but does not address the problem of maintaining windows, so it has much less overhead and avoids the associated bugs.

InitTermCap must be passed the output stream pointer and invoked before any other functions in this library. This function reads the termcap(4) capability data base to extract terminal-specific parameters and control strings, then initializes the terminal, returning 1 for success and 0 for failure. After InitTermCap is used, the global buffer termName will contain the name of the terminal device, or ``UNKNOWN'' in the event of failure (e.g., the environment variable $TERM was not set or exported (see sh(1))); the global variables LI and CO will contain the number of lines and columns, respectively, of the terminal screen or window layer attached to the specified output stream; and the terminal control string pointers will be set, or NULL if their respective capabilities are not found. The terminal control strings are not generally suitable for direct use as they require the tputs or tgoto macros from the termlib(3) library, but they may be checked for being NULL to test in advance for a capability, rather than testing the respective function for success or failure. The function PutChr will place the specified character on the terminal's output stream. It is not intended for use by the application (although such use is permissible), but is defined for the termlib(3) library.

All the following functions will return 1 for success and 0 if the capability is not described in the termcap(4) entry. MvCursor will move the cursor to the specified column and row (x and y) screen location specified. HmCursor will move the cursor to the origin (top left) of the screen and is equivalent to MvCursor(1,1). To erase from the cursor position to the end of the line, use ClrEOL, and to erase the entire screen call ClrText (typically has the side effect of homing the cursor). To initiate the output of reverse video or emboldened text (depending upon the terminal's capabilities), use SetStandout; ClrStandout will restore the normal mode. For terminals such as the DEC VT100 which have scrolling region capability, the functions SetScrlReg and ResetScrlReg can be used. SetScrlReg must be invoked with the top and bottom line numbers of the region of the screen to be scrolled. The functions ScrollUp and ScrollDn will scroll the text on the screen up and down (forward and backward) respectively, by one line per invocation. The function DeleteLn will delete the line containing the cursor, causing the text below to scroll up to fill the void.

EXAMPLE
Libcursor can be loaded with any C program:

    $ cc program.c -lcursor -ltermlib

FILES
/usr/brl/lib/libcursor.a
/usr/lib/libtermlib.a
/etc/termcap

SEE ALSO
curses(3X), termlib(3), termcap(4).

AUTHOR
Gary S. Moss, BRL/VLD-VMB