-
Writing Programs with NCURSES
by Eric S. Raymond and Zeyd M. Ben-Halim
The ncurses package was originated by Pavel Curtis. The original
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. Jürgen
+ in versions after 1.8.1 and wrote most of this introduction. Juergen
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.
+ binding. Ongoing work is being done by Thomas Dickey (maintainer).
+ 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
Here is a sample program to motivate the discussion:
#include <curses.h>
+#include <curses.h>
#include <signal.h>
static void finish(int sig);
* xterm and similar programs such as rxvt.
* Linux console, when configured with gpm(1), Alessandro Rubini's
mouse server.
+ * FreeBSD sysmouse (console)
* OS/2 EMX
The mouse interface is very simple. To activate it, you use the
refresh() will clear the screen. If an error occurs a message
is written to standard error and the program exits. Otherwise
it returns a pointer to stdscr. A few functions may be called
- before initscr (slk_init(), filter(), ripofflines(), use_env(),
+ before initscr (slk_init(), filter(), ripoffline(), use_env(),
and, if you are using multiple terminals, newterm().)
endwin()
the terminal, as other routines merely manipulate data
structures. wrefresh() copies the named window to the physical
terminal screen, taking into account what is already there in
- order to do optimizations. refresh() does a refresh of
- stdscr(). Unless leaveok() has been enabled, the physical
- cursor of the terminal is left at the location of the window's
- cursor.
+ order to do optimizations. refresh() does a refresh of stdscr.
+ Unless leaveok() has been enabled, the physical cursor of the
+ terminal is left at the location of the window's cursor.
doupdate() and wnoutrefresh(win)
These two functions allow multiple updates with more efficiency
Using NCURSES under XTERM
A resize operation in X sends SIGWINCH to the application running
- 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.
+ under xterm. The easiest way to handle SIGWINCH is to 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
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.
+ The ncurses library provides a SIGWINCH signal handler, which pushes a
+ KEY_RESIZE via the wgetch() calls. When ncurses returns that code, it
+ calls resizeterm to update the size of the standard screen's window,
+ repainting that (filling with blanks or truncating as needed). It also
+ resizes other windows, but its effect may be less satisfactory because
+ it cannot know how you want the screen re-painted. You will usually
+ have to write special-purpose code to handle KEY_RESIZE yourself.
Handling Multiple Terminal Screens
To understand why this is a problem, remember that screen updates are
calculated between two representations of the entire display. The
documentation says that when you refresh a window, it is first copied
- to to the virtual screen, and then changes are calculated to update
- the physical screen (and applied to the terminal). But "copied to" is
- not very specific, and subtle differences in how copying works can
- produce different behaviors in the case where two overlapping windows
- are each being refreshed at unpredictable intervals.
+ to the virtual screen, and then changes are calculated to update the
+ physical screen (and applied to the terminal). But "copied to" is not
+ very specific, and subtle differences in how copying works can produce
+ different behaviors in the case where two overlapping windows are each
+ being refreshed at unpredictable intervals.
What happens to the overlapping region depends on what wnoutrefresh()
does with its argument -- what portions of the argument window it
The really clean way to handle this is to use the panels library. If,
when you want a screen update, you do update_panels(), it will do all
- the necessary wnoutrfresh() calls for whatever panel stacking order
+ the necessary wnoutrefresh() calls for whatever panel stacking order
you have defined. Then you can do one doupdate() and there will be a
single burst of physical I/O that will do all your updates.
1. Initialize curses.
2. Create the menu items, using new_item().
3. Create the menu using new_menu().
- 4. Post the menu using menu_post().
+ 4. Post the menu using post_menu().
5. Refresh the screen.
6. Process user requests via an input loop.
- 7. Unpost the menu using menu_unpost().
+ 7. Unpost the menu using unpost_menu().
8. Free the menu, using free_menu().
9. Free the items using free_item().
10. Terminate curses.
By default, both windows are stdscr. You can set them with the
functions in menu_win(3x).
- When you call menu_post(), you write the menu to its subwindow. When
- you call menu_unpost(), you erase the subwindow, However, neither of
+ When you call post_menu(), you write the menu to its subwindow. When
+ you call unpost_menu(), you erase the subwindow, However, neither of
these actually modifies the screen. To do that, call wrefresh() or
some equivalent.
1. Initialize curses.
2. Create the form fields, using new_field().
3. Create the form using new_form().
- 4. Post the form using form_post().
+ 4. Post the form using post_form().
5. Refresh the screen.
6. Process user requests via an input loop.
- 7. Unpost the form using form_unpost().
+ 7. Unpost the form using unpost_form().
8. Free the form, using free_form().
9. Free the fields using free_field().
10. Terminate curses.
the screen (the third and fourth arguments, which must be zero or
greater). Note that these coordinates are relative to the form
subwindow, which will coincide with stdscr by default but need not be
- stdscr if you've done an explicit set_form_window() call.
+ stdscr if you've done an explicit set_form_win() call.
The fifth argument allows you to specify a number of off-screen rows.
If this is zero, the entire field will always be displayed. If it is