Writing Programs with NCURSES
by Eric S. Raymond and Zeyd M. Ben-Halim
+ updates since release 1.9.9e by Thomas Dickey
Contents
Scope of This Document
- This document describes ncurses, a freeware implementation of the
- System V curses API with some clearly marked extensions. It includes
- the following System V curses features:
+ This document describes ncurses, a free implementation of the System V
+ curses API with some clearly marked extensions. It includes the
+ following System V curses features:
* Support for multiple screen highlights (BSD curses could only
handle one `standout' highlight, usually reverse-video).
This document includes tips for using the mouse.
The ncurses package was originated by Pavel Curtis. The original
- maintainer of the package is Zeyd Ben-Halim <zmbenhal@netcom.com>.
+ maintainer of this package is Zeyd Ben-Halim <zmbenhal@netcom.com>.
Eric S. Raymond <esr@snark.thyrsus.com> wrote many of the new features
- in versions after 1.8.1 and wrote most of this introduction. The
- current primary maintainers are Thomas Dickey <dickey@clark.net> and
- Juergen Pfeifer. <Juergen.Pfeifer@T-Online.de>
+ in versions after 1.8.1 and wrote most of this introduction. Jürgen
+ Pfeifer wrote all of the menu and forms code as well as the Ada95
+ binding. Ongoing work is being done by Thomas Dickey and Jürgen
+ Pfeifer. Florian La Roche acts as the maintainer for the Free Software
+ Foundation, which holds the copyright on ncurses. Contact the current
+ maintainers at bug-ncurses@gnu.org.
This document also describes the panels extension library, similarly
modeled on the SVr4 panels facility. This library allows you to
Finally, this document describes in detail the menus and forms
extension libraries, also cloned from System V, which support easy
- construction and sequences of menus and fill-in forms. This code was
- contributed to the project by Jürgen Pfeifer.
+ construction and sequences of menus and fill-in forms.
Terminology
In order to use the library, it is necessary to have certain types and
variables defined. Therefore, the programmer must have a line:
-
#include <curses.h>
at the top of the program source. The screen package uses the Standard
order to avoid clumsiness, most I/O routines can be preceded by the
prefix 'mv' and the desired (y, x) coordinates prepended to the
arguments to the function. For example, the calls
-
move(y, x);
addch(ch);
The curses library sets some variables describing the terminal
capabilities.
-
type name description
------------------------------------------------------------------
int LINES number of lines on the terminal
Mouse Interfacing
- The ncurses library also provides a mouse interface. Note: his
- facility is original to ncurses, it is not part of either the XSI
- Curses standard, nor of System V Release 4, nor BSD curses. Thus, we
- recommend that you wrap mouse-related code in an #ifdef using the
- feature macro NCURSES_MOUSE_VERSION so it will not be compiled and
- linked on non-ncurses systems.
-
- Presently, mouse event reporting works only under xterm. In the
- future, ncurses will detect the presence of gpm(1), Alessandro
- Rubini's freeware mouse server for Linux systems, and accept mouse
- reports through it.
-
+ The ncurses library also provides a mouse interface.
+
+ NOTE: this facility is specific to ncurses, it is not part of
+ either the XSI Curses standard, nor of System V Release 4, nor BSD
+ curses. System V Release 4 curses contains code with similar
+ interface definitions, however it is not documented. Other than by
+ disassembling the library, we have no way to determine exactly how
+ that mouse code works. Thus, we recommend that you wrap
+ mouse-related code in an #ifdef using the feature macro
+ NCURSES_MOUSE_VERSION so it will not be compiled and linked on
+ non-ncurses systems.
+
+ Presently, mouse event reporting works in the following environments:
+ * xterm and similar programs such as rxvt.
+ * Linux console, when configured with gpm(1), Alessandro Rubini's
+ mouse server.
+ * OS/2 EMX
+
The mouse interface is very simple. To activate it, you use the
function mousemask(), passing it as first argument a bit-mask that
specifies what kinds of events you want your program to be able to
Debugging
- NOTE: These functions are not part of the standard curses API!
-
+ NOTE: These functions are not part of the standard curses API!
+
trace()
This function can be used to explicitly set a trace level. If
the trace level is nonzero, execution of your program will
likely to hurt your application's usability with other curses
libraries.
- Bear in mind that refresh() is a synonym for wrefresh(stdscr), and
- don't try to mix use of stdscr with use of windows declared by
- newwin(); a refresh() call will blow them off the screen. The right
- way to handle this is to use subwin(), or not touch stdscr at all and
- tile your screen with declared windows which you then wnoutrefresh()
- somewhere in your program event loop, with a single doupdate() call to
- trigger actual repainting.
+ Bear in mind that refresh() is a synonym for wrefresh(stdscr). Don't
+ try to mix use of stdscr with use of windows declared by newwin(); a
+ refresh() call will blow them off the screen. The right way to handle
+ this is to use subwin(), or not touch stdscr at all and tile your
+ screen with declared windows which you then wnoutrefresh() somewhere
+ in your program event loop, with a single doupdate() call to trigger
+ actual repainting.
You are much less likely to run into problems if you design your
screen layouts to use tiled rather than overlapping windows.
fragile, and poorly documented. The ncurses library is not yet an
exception to this rule.
- There is a freeware panels library included in the ncurses
- distribution that does a pretty good job of strengthening the
- overlapping-windows facilities.
+ There is a panels library included in the ncurses distribution that
+ does a pretty good job of strengthening the overlapping-windows
+ facilities.
Try to avoid using the global variables LINES and COLS. Use getmaxyx()
on the stdscr context instead. Reason: your code may 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
+ Temporarily Leaving NCURSES Mode
Sometimes you will want to write a program that spends most of its
time in screen mode, but occasionally returns to ordinary `cooked'
addstr("returned.\n"); /* prepare return message */
refresh(); /* restore save modes, repaint screen */
- Using ncurses Under xterm
+ Using NCURSES under XTERM
A resize operation in X sends SIGWINCH to the application running
- under xterm. The ncurses library does not catch this signal, because
- it cannot in general know how you want the screen re-painted. You will
- have to write the SIGWINCH handler yourself.
+ under xterm. The ncurses library provides an experimental signal
+ handler, but in general does not catch this signal, because it cannot
+ know how you want the screen re-painted. You will usually have to
+ write the SIGWINCH handler yourself. Ncurses can give you some help.
The easiest way to code your SIGWINCH handler is to have it do an
endwin, followed by an refresh and a screen repaint you code yourself.
The refresh will pick up the new screen size from the xterm's
environment.
+ That is the standard way, of course (it even works with some vendor's
+ curses implementations). Its drawback is that it clears the screen to
+ reinitialize the display, and does not resize subwindows which must be
+ shrunk. Ncurses provides an extension which works better, the
+ resizeterm function. That function ensures that all windows are
+ limited to the new screen dimensions, and pads stdscr with blanks if
+ the screen is larger.
+
+ Finally, ncurses can be configured to provide its own SIGWINCH
+ handler, based on resizeterm.
+
Handling Multiple Terminal Screens
The initscr() function actually calls a function named newterm() to do
Try to make attribute changes infrequent on your screens. Don't use
the immedok() option!
- Special Features of ncurses
+ 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.
+ The wresize() function allows you to resize a window in place. The
+ associated resizeterm() function simplifies the construction of
+ SIGWINCH handlers, for resizing all windows.
- The wresize() function allows you to resize a window in place.
+ The define_key() function allows you to define at runtime function-key
+ control sequences which are not in the terminal description. The
+ keyok() function allows you to temporarily enable or disable
+ interpretation of any function-key control sequence.
+
+ The use_default_colors() function allows you to construct applications
+ which can use the terminal's default foreground and background colors
+ as an additional "default" color. Several terminal emulators support
+ this feature, which is based on ISO 6429.
+
+ Ncurses supports up 16 colors, unlike SVr4 curses which defines only
+ 8. While most terminals which provide color allow only 8 colors, about
+ a quarter (including XFree86 xterm) support 16 colors.
Compatibility with Older Versions
panels library.
The panel library first appeared in AT&T System V. The version
- documented here is the freeware panel code distributed with ncurses.
+ documented here is the panel code distributed with ncurses.
Compiling With the Panels Library
Your panels-using modules must import the panels library declarations
with
-
#include <panel.h>
and must be linked explicitly with the panels library using an -lpanel
flexible interface.
The menu library first appeared in AT&T System V. The version
- documented here is the freeware menu code distributed with ncurses.
+ documented here is the menu code distributed with ncurses.
Compiling With the menu Library
Your menu-using modules must import the menu library declarations with
-
#include <menu.h>
and must be linked explicitly with the menus library using an -lmenu
of on-screen forms for data entry and program control.
The form library first appeared in AT&T System V. The version
- documented here is the freeware form code distributed with ncurses.
+ documented here is the form code distributed with ncurses.
Compiling With the form Library
Your form-using modules must import the form library declarations with
-
#include <form.h>
and must be linked explicitly with the forms library using an -lform
Changing the Field Location
- If is possible to move a field's location on the screen:
+ It is possible to move a field's location on the screen:
int move_field(FIELD *field, /* field to alter */
int top, int left); /* new upper-left corner */
There is also a large collection of field option bits you can set to
control various aspects of forms processing. You can manipulate them
with these functions:
-
int set_field_opts(FIELD *field, /* field to alter */
int attr); /* attribute to set */
Each field structure contains one character pointer slot that is not
used by the forms library. It is intended to be used by applications
to store private per-field data. You can manipulate it with:
-
int set_field_userptr(FIELD *field, /* field to alter */
char *userptr); /* mode to set */
by the user's editing actions on that field. It's sometimes useful to
be able to set the value of the zero-numbered (or some other) buffer
from your application:
-
int set_field_buffer(FIELD *field, /* field to alter */
int bufindex, /* number of buffer to alter */
char *value); /* string value to set */
The form dimensions are passed back in the locations pointed to by the
arguments. Once you have this information, you can use it to declare
of windows, then use one of these functions:
-
int set_form_win(FORM *form, /* form to alter */
WINDOW *win); /* frame window to connect */
projects / ncurses.git / blobdiff