Reference: Terminality

# Terminality

`

    /* Colors */
    typedef enum {
    	Default = -1, /* Not a real color, needed for listing */
    	Black = 0,
    	Blue = 1,
    	Green = 2,
    	Cyan = 3,
    	Red = 4,
    	Magenta = 5,
    	Brown = 6,
    	LightGray = 7,
    	/* Bright [foreground] */
    	DarkGray = 8,
    	LightBlue = 9,
    	LightGreen = 10,
    	LightCyan = 11,
    	LightRed = 12,
    	LightMagenta = 13,
    	Yellow = 14,
    	White = 15
    } color;

    /* Cursor struct */
    typedef enum {
        none,
        line,
        rect
    } cursor;

    /* Functions */
    void initcons(void);			/* Initialise console */
    void donecons(void);			/* Done with console */
    void clrscr(void);			/* Clear screen */
    void textcolor(color c);		/* Set foreground (text) color */
    void textbackground(color c);		/* Set background color */
    void setcolor(color f, color b);	/* Set color to f, b */
    key readkey(void);			/* Get keypress */
    int keypressed(void);			/* Key pressed? */
    void delay(int ms);			/* Delay for <ms> milliseconds */
    void gotoxy(int x, int y);		/* Move cursor to x,y */
    void writech(chtype c);			/* Write character */
    int update_set(int want);		/* Enable / disable screen updates */
    void update(void);			/* Update screen */
    int has_color(void);			/* Do we have colors? */
    void clreol(void); 			/* Clear to end of line */
    int wherey(void);			/* Return cursor Y position */
    int wherex(void);			/* Return cursor X position */
    int beep(void);				/* Audible beep/bell/alarm thing */
    int printw(const char *format, ...);	/* printf to screen */

    /* No-color terminal functions */
    void highvideo(void);			/* Bright text */
    void lowvideo(void);			/* Dim text */
    void normvideo(void);			/* Normal text */
    void reversevideo(void);		/* Reverse/standout text */

    /* Cursor functions */
    cursor get_cursor(void);		/* Gets cursor */
    void set_cursor(cursor c);		/* Sets cursor */

    /* The following special characters must be supported or emulated:
     *	HLINE	- Horizontal line
     *	VLINE	- Vertical line
     *	CROSS	- Cross/plus
     *	C_UL	- Upper left corner
     *	C_UR	- Upper right
     *	C_LL	- Lower left
     *	C_LR	- Lower right
     *	BLOCK_1	- 25%-full block
     *	BLOCK_2	- 50%-full block
     *	BLOCK_3 - 75%-full block
     *	BLOCK_4	- Solid block
     *	TEE_L	- Tee pointing left
     *	TEE_R	- Tee pointing right
     *	TEE_U	- Tee pointing up
     *	TEE_D	- Tee pointing down
     *	ARROW_L	- Arrow pointing left
     *	ARROW_R	- Arrow pointing right
     *	ARROW_U	- Arrow pointing up
     *	ARROW_D	- Arrow pointing down
     *
     *
     * The macro _c(x) should be provided. It is used to create a
     * chtype value from an integer specifying a regular ASCII
     * character code. i.e. BLOCK_4 = _c(219)
     *
     *
     * The following keys must be provided:
     *	KEY_ENTER
     *	KEY_TAB
     *	KEY_BACKSPACE
     *	KEY_DEL
     *	KEY_UP
     *	KEY_DOWN
     *	KEY_LEFT
     *	KEY_RIGHT
     *	KEY_HOME
     *	KEY_END
     *	KEY_PGUP
     *	KEY_PGDOWN
     */

    /* To obtain the size of the terminal, Terminality backends must
       provide CON_COLS and CON_ROWS as macros or variables. */

`

## void initcons(void);

You must call initcons() to initialise the console before you use it. Make sure you call donecons() to deinitialise the console before your program ends.

## void donecons(void);

You should call donecone() to deinitialise the console before your program exits.

## void clrscr(void);

Clears the screen and homes the cursor.

## void textcolor(color c);

Sets the current text (foreground) colour to the specified colour, c.
See: colour

## void textbackground(color c);

Sets the current background colour to the specified colour, c.
See: colour

## void setcolor(color f, color b);

Sets the foreground and background colours to f and b, respectively.
See: colour

## key readkey(void);

Will do a blocking keyboard read. (meaning it won't return a result until the user hits a key). It returns the pressed key as type key.

## int keypressed(void);

Will return 0 if there is no keypress waiting in the input buffer or 1 if there is. This is a non-blocking call (it returns immediately).

## void delay(int ms);

Pretty straightforward - this function waits ms milliseconds and then returns control back to the program. delay(...) should give up CPU time instead of burning it, it should be accurate, and 1000ms should be equal to one second although all this will depend on the backend (implementation) of Terminality you're compiling with.

## void gotoxy(int x, int y);

Moves the cursor to x,y where 1,1 (NOT 0,0) is the upper-left-most corner of the terminal. To find the width and height of the terminal, use the constants/variables/macros CON_COLS and CON_ROWS, respectively;

## void writech(chtype c);

Use this function to write a single character when you're playing with

extended characters. printw(...) often screws up extended characters so if you're getting garbage on your terminal, try printing your extendeds with writech(...).

## int update_set(int want);

Use 1 if you want Terminality to automatically update the screen or 0 (the default if unset) if you prefer to call update() yourself after you're done writing to the terminal.

## void update(void);

You won't get anything written to the terminal until you call update(). This is done in order to minimise flicker and redraw - minimal changes are made to the screen after you're done writing to the terminal. If you're too lazy to call update() when you need to, you can use update_set(...) to tell Terminality to update the screen automatically after every writing operation.

## int has_color(void);

Some extremely rare terminals don't support color. The ncurses backend of Terminality (along with some other ones, possbily) lets us detect this and will return a zero or a one if the terminal is monochrome or color, respectively.

## void clreol(void);

This function clears the current line form the cursor position to the end of the line.

## int wherey(void);

Returns the vertical position (row) of the cursor.

## int wherex(void);

Returns the horizontal position (column) of the cursor.

## int beep(void);

If possible, produces an audible beep.

## int printw(const char *format, ...);

This function works just like printf(...) except that you must use printw(...) and NOT printf(...) to print to the terminal when using Terminality.

[contents]

$Id: ref-tn.html,v 1.2 2002/07/26 01:49:15 darkmoon Exp $