8.3 Ncurses - Introduction

The following terminology will be used in this chapter:

• window - is an internal representation containing an image of a part of the screen. WINDOW is defined in .h.
• screen - is a window with the size of the entire screen (from the upper left to the lower right). and are screens.
• terminal - is a special screen with information about what the screen currently looks like.
• variables - the following variables and constants defined in .h
  • WINDOW *curscr - current screen
  • WINDOW *stdscr - standard screen
  • int LINES - lines on the terminal
  • int COLS - columns on the terminal
  • bool TRUE - true flag, 1
  • bool FALSE - false flag, 0
  • int ERR - error flag, -1
  • int OK - ok flag, 0
• functions - in the function description the arguments are of the following type:
  • win - WINDOW*
  • bf - bool
  • ch - chtype
  • str - char*
  • chstr - chtype*
  • fmt - char*
  • otherwise int

Usually a program using the ncurses library looks like this:

#include 
...
main()
{
  ...
  initscr();
  /* ncurses function calls */
  endwin();
  ...
}

Including .h will define variables and types for ncurses, such as WINDOW and function prototypes. It automatically includes .h, .h, .h and .h.

initscr() is used to initialize the ncurses data structures and to read the proper terminfo file. Memory for and will be allocated. If an error occurs, initscr will return ERR, otherwise a pointer to will be returned. Additionally, the screen will be erased and and will be initialized.

endwin() will clean up all allocated resources from ncurses and restore the tty modes to the status they had before calling initscr(). It must be called before any other function from the ncurses library and endwin() must be called before your program exits. When you want to do output to more than one terminal, you can use newterm(...) instead of initscr().

Compile the program with:

In flags you can include anything you like (gcc(1)). Since the path for ncurses.h has changed you have to include the following line:

Otherwise, ncurses.h, nterm.h, termcap.h and unctrl.h will not be found. Possible other flags for Linux are:

2 tells gcc to do some optimization, -ansi is for ansi conformant c-code, -Wall will print out all warnings, -m486 will use optimized code for an Intel 486 (the binary can be used on an Intel 386, too).

The ncurses library can be found in /usr/lib/. There are three versions of the ncurses library:

• libncurses.a the normal ncurses library.
• libdcurses.a ncurses for debugging.
• libpcurses.a ncurses for profiling (since 1.8.6 libpcurses.a exists no longer ?).
• libcurses.a No fourth version, but the original BSD curses (in my slackware 2.1.0 it is the bsd package).

The data structures for the screen are called windows as defined in .h. A window is something like a character array in memory which the programmer can manipulate without output to the terminal. The default window is with the size of the terminal. You can create other windows with newwin(...).

To update the physical terminal optimally, ncurses has another window declared, . This is an image of how the terminal actually looks and is an image of how the terminal should look. The output will be done when you call refresh(). Ncurses will then update and the physical terminal with the information in . The library functions will use internal optimization for the update process so you can change different windows and then update the screen at once in the most optimal way.

With the ncurses functions you can manipulate the data structure window. Functions beginning with w allow you to specify a window, while others will usually affect . Functions beginning with mv will move the cursor to the position y,x first.

A character has the type chtype which is long unsigned int to store additional information about it (attributes etc.).

Ncurses use the database. Normally the database is located in /lib/terminfo/ and ncurses will look there for local terminal definitions. If you want to test some other definitions for a terminal without changing the original terminfo, set the environment variable . Ncurses will check this variable and use the definitions stored there instead of /usr/lib/terminfo/.

Current ncurses version is 1.8.6 ().

At the end of this chapter you can find a table with an overview for the BSD-Curses, ncurses and the curses from Sun-OS 5.4. Refer to it when you want to look for a specific function and where it is implemented.