Hints, tips, and tricks

The ncurses manual pages are a complete reference for this library. The following sections provide additional explanations of several useful methods that may not be obvious from the manual pages.

Hints that help prevent problems

If you are considering using noraw() or nocbreak(), you should do so with caution. It is usually better design to use getstr() or a related routine to simulate cooked mode. The noraw() and nocbreak() functions attempt to restore cooked mode, but they might overwrite some control bits that were set before you started your application. In addition, their documentation is incomplete, and using them is likely to make your application less compatible with other curses libraries.

You should note that refresh() is a synonym for wrefresh (stdscr). Do not try to mix the use of stdscr with the use of windows declared by newwin(); a refresh() call will remove them from the screen. You can, however, either use subwin(), or refrain from using stdscr at all, and tile your screen with declared windows for which you then call wnoutrefresh() somewhere in your program event loop, with a single doupdate() call to trigger actual repainting.

You are much less likely to encounter problems if you design your screen layouts to use tiled windows rather than overlapping windows. Historically, curses support for overlapping windows has been weak, fragile, and poorly documented. The ncurses library does not yet solve these problems.

Try to avoid using the global variables LINES and COLS; use getmaxyx() on the stdscr context instead. The reason for this is that your code might be ported to run in an environment with window resizes, in which case several screens could be open with different sizes.

Temporarily leaving ncurses mode

You might want to write a program that spends most of its time in screen mode, but occasionally returns to ordinary canonical (cooked) mode. A common reason for this is to support suspending the program to run a command shell. This behavior is simple to arrange in ncurses.

To leave ncurses mode, call endwin() as though you were terminating the program. This will return the screen to cooked mode so you can run the shell. When you want to return to ncurses mode, simply call refresh() or doupdate(). This will repaint the screen.

There is a Boolean function, isendwin(), that a program can use to test whether ncurses screen mode is active. It returns TRUE in the interval between an endwin() call and the following refresh(), and returns FALSE otherwise.

The following provides some sample code for running a command shell from within an ncurses program:

addstr(“Shelling out...”);
def_prog_mode( ); 	/* save current tty modes */
endwin( ); 			 /* restore original tty modes */
system(“sh”); 		/* run shell */
						 /* prepare return message */
addstr(“returned.\n”);
						 /* restore save modes, repaint screen */
refresh( );

Handling multiple terminal screens

The initscr() function actually calls a function named newterm() to do most of its work. If you are writing a program that opens multiple terminals, use newterm() directly.

For each call, you specify a terminal type and a pair of file pointers; each call returns a screen reference, and stdscr will be set to the last one allocated. You switch between screens with the set_term() call. Note that you must also call def_shell_mode() and def_prog_mode() on each tty.

Testing for terminal capabilities

You might want to write programs that test for the presence of various capabilities before deciding whether to go into ncurses mode. An easy way to do this is to call setupterm(), then use the functions tigetflag(), tigetnum(), and tigetstr() to conduct your testing.

This is particularly useful when you want to test whether a given terminal type should be treated as "smart" (cursor-addressable). The correct way to test this is to see whether the return value of tigetstr("cup") is non-NULL. Alternatively, you can include the <term.h> file and test the value of the macro cursor_address.

Tuning for speed

Use the addchstr() family of functions for fast screen painting of text when you know the text does not contain any control characters. Try to make attribute changes infrequent on your screens. Do not use the immedok() option.

Special features of ncurses

When running on PC clones, ncurses has enhanced support for the IBM high-half and ROM characters. The A_ALTCHARSET highlight enables display of both high-half ACS graphics and the PC ROM graphics 0-31 that are normally interpreted as control characters.

You can use the wresize() function to resize a window in place.