6.4 Getting Started with Curses

There are commands that you must use to initialize and restore the terminal screen when using Curses Screen Management functions and macros. Also, there are predefined variables and constants on which Curses depends. Example 6-1 shows how to set up a program using Curses.

Example 6-1 A Curses Program

 #include <curses.h>

 WINDOW *win1, *win2, *win3;

main()
{
    initscr();
      .
      .
      .
   endwin();
}

Key to Example 6-1:

1. The preprocessor directive includes the <curses.h> header file, which defines the data structures and variables used to implement Curses. The <curses.h> header file includes the <stdio.h> header file, so it is not necessary to duplicate this action by including <stdio.h> again in the program source code. You must include <curses.h> to use any of the Curses functions or macros.

2. In the example, WINDOW is a data structure defined in <curses.h>. You must declare each user-specified window in this manner. In Example 6-1, the three defined windows are win1, win2, and win3.

3. The initscr and endwin functions begin and end the window editing session. The initscr function clears the terminal screen (OpenVMS Curses only; BSD-based Curses does not), and allocates space for the windows stdscr and curscr. The endwin function deletes all windows and clears the terminal screen.

Most Curses users wish to define and modify windows. Example 6-2 shows you how to define and write to a single window.

Example 6-2 Manipulating Windows

#include <curses.h>

WINDOW  *win1, *win2, *win3;

main()
{
   initscr();

    win1 = newwin(24, 80, 0, 0);
    mvwaddstr(win1, 2, 2, "HELLO");
      .
      .
      .
   endwin();
}

Key to Example 6-2:

1. The newwin function defines a window 24 rows high and 80 columns wide with a starting position at coordinates (0,0), the upper left corner of the terminal screen. The program assigns these attributes to win1. The coordinates are specified as follows: (lines,columns) or (y,x).

2. The mvwaddstr macro performs the same task as a call to the separate macros move and addstr. The mvwaddstr macro moves the cursor to the specified coordinates and writes a string onto stdscr.

Note

Most Curses macros update stdscr by default. Curses functions that update other windows have the same name as the macros but with the added prefix "w". For example, the addstr macro adds a given string to stdscr at the current cursor position. The waddstr function adds a given string to a specified window at the current cursor position.

When updating a window, specify the cursor position relative to the origin of the window, not the origin of the terminal screen. For example, if a window has a starting position of (10,10) and you want to add a character to the window at its starting position, specify the coordinates (0,0), not (10,10).

The string HELLO in Example 6-2 does not appear on the terminal screen until you refresh the screen. You accomplish this by using the wrefresh function. Example 6-3 shows how to display the contents of win1 on the terminal screen.

Example 6-3 Refreshing the Terminal Screen

#include <curses.h>

WINDOW  *win1, *win2, *win3;

main()
{
   initscr();

   win1 = newwin(22, 60, 0, 0);
   mvwaddstr(win1, 2, 2, "HELLO");
   wrefresh(win1);
      .
      .
      .
   endwin();
}

The wrefresh function updates just the region of the specified window on the terminal screen. When the program is executed, the string HELLO appears on the terminal screen until the program executes the endwin function. The wrefresh function only refreshes the part of the window on the terminal screen that is not overlapped by another window. If win1 was overlapped by another window and you want all of win1 to be displayed on the terminal screen, call the touchwin function.