Terminality Documentation

# Tutorial: Using Terminality

Terminality was written to be as simple as possible to use, but before we jump into the fun stuff, like playing with colors, we need to cover the housekeeping side of using Terminality in your programs.

## Housekeeping

Before you call any Terminality functions, you must initialise the console by calling:

> `

>     initcons();

> `

When you are done, you need to deinitialize the console before exiting by calling:

> `

>     donecons();

> `

The screen will not automatically update after every Terminality function you call, you need to "flush" the output to the screen by calling:

> `

>     update();

> `

## Clearing the screen

Back in the Turbo Pascal and Turbo C days we may have only had 33Mhz computers and 16-bit code using segment/offset addressing but we also a lot of very simple screen handling functions that simply WORKED. In today's golden age of portability (snoot!) we find that there's no function in stdio.h to do something as elementary as clear the screen.

The Terminality function for clearing the screen is clrscr(). It clears the screen and homes the cursor to the upper-left-most position. (1,1)

As well as clearing the screen, we'll want to write something to it. For this we use the printw(...) function. It works the same as the standard C printf(...) function except that it prints to the console instead of simply stdout.

Let's put together what we've learned so far into a working program:

> `

>     #include <tn.h>

>     int main()
>     {
>     	initcons();

>     	clrscr();
>     	printw("Hello, world!");
>     	update();

>     	donecons();
>     	return 0;
>     }

> `

hello1.c

Under Linux, compile this with:

> `

>     gcc -DUSE_NCURSES hello1.c ../libtn.a -lncurses

> `

And this is what it does:

That was easy, huh?

## Changing the text color

To change the color we use the old Borland-style textcolor(color) and textbackground(color) functions to change the foreground (text) and background colors, respectively. We can also use setcolor(color, color) to set both at the same time.

For monochrome applications, Terminality provides: highvideo(), lowvideo(), normvideo(), reversevideo()

> `

>     #include <tn.h>

>     int main()
>     {
>     	initcons();

>     	clrscr();
>     	textcolor(LightRed);
>     	printw("Hello, ");
>     	setcolor(LightBlue, Blue);
>     	printw("big blue");
>     	textcolor(LightRed);
>     	textbackground(Black);
>     	printw(" world!\n\n");

>     	setcolor(7,0); /* LightGray, Black */

>     	printw("\n\nHere's some ");
>     	highvideo();     printw("bright, ");
>     	normvideo();     printw("normal, ");
>     	lowvideo();      printw("dim and ");
>     	reversevideo();  printw("reverse");
>     	normvideo();     printw(" text.\n");

>     	update();

>     	donecons();
>     	return 0;
>     }

> `

hello2.c

## Keyboard input and delays

To check if a key has been pressed, we use the keypressed() function. It will return 1 if a key has been pressed or else 0. To read a key (a blocking read, if no key has been pressed the call will not return until one gets pressed) we can use the readkey() function, which will return a value of type key.

To delay the execution of the program at any point, we can use the delay(int) function. The value passed to this function should be the amount of time to wait, given in milliseconds. (1000 ms = 1 second)

> `

>     #include <tn.h>

>     int main()
>     {
>     	initcons();

>     	clrscr();
>     	printw("Waiting for input..");

>     	while (!keypressed())
>     	{
>     		printw(".");
>     		update();
>     		delay(1000);
>     	}

>     	printw("\n\nYou hit the '%c' key!\n",
>     		readkey());
>     	update();

>     	donecons();
>     	return 0;
>     }

> `

keyb1.c

## Cursor-wrangling

Terminality provides the gotoxy(int, int) function to move the cursor to the specified (x,y) coordinate. Note that the upper-left-most corner is at (1,1) and the bottom-right-most corner is at (CON_COLS, CON_ROWS).

The current x and y coordinates of the curosr can be divined using the wherex() and wherey() functions, respectively. The cursor size can be set to none, line and rect using the set_cursor(cursor) function. Likewise, the size of the cursor can be ascertained using the get_cursor() function.

> `

>     #include <tn.h>

>     int main()
>     {
>     	initcons();

>     	clrscr();
>     	set_cursor(none);
>     	gotoxy(20,10);
>     	printw("School is useless");
>     	update();

>     	delay(1000);
>     	gotoxy(wherex()-4, wherey());
>     	printw("ful.\n\n");
>     	set_cursor(line);

>     	update();

>     	donecons();
>     	return 0;
>     }

> `

curs1.c

## In Closing

There are more functions that Terminality implements which haven't been covered here. If you're interested, you can learn more about them by looking through the reference guide or the source code.

[contents]

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