A Hacker's Guide to NCURSES
- Contents
+A Hacker's Guide to NCURSES
+
+Contents
* Abstract
* Objective of the Package
* Style Tips for Developers
* Porting Hints
- Abstract
+Abstract
This document is a hacker's tour of the ncurses library and utilities.
It discusses design philosophy, implementation methods, and the
reading for anyone who is interested in porting, extending or
improving the package.
- Objective of the Package
+Objective of the Package
The objective of the ncurses package is to provide a free software API
for character-cell terminals and terminal emulators with the following
cannot add features if it means breaking the portion of the API
corresponding to historical curses versions.
-Why System V Curses?
+ Why System V Curses?
We used System V curses as a model, reverse-engineering their API, in
order to fulfill the first two objectives.
X/Open is explicitly and closely modeled on System V. So conformance
with System V took us most of the way to base-level XSI conformance.
-How to Design Extensions
+ How to Design Extensions
The third objective (standards conformance) requires that it be easy
to condition source code using ncurses so that the absence of
does not define, but which is defined in the ncurses library header.
You can use this to condition the calls to the mouse API calls.
- Portability and Configuration
+Portability and Configuration
Code written for ncurses may assume an ANSI-standard C compiler and
POSIX-compatible OS interface. It may also assume the presence of a
specification files (configure.in and aclocal.m4) to set up a new
feature macro, which you then use to condition your code.
- Documentation Conventions
+Documentation Conventions
There are three kinds of documentation associated with this package.
Each has a different preferred format:
Our conventions are simple:
1. Maintain package-internal files in plain text. The expected viewer
- for them more(1) or an editor window; there is no point in
+ for them is more(1) or an editor window; there is no point in
elaborate mark-up.
2. Mark up manual pages in the man macros. These have to be viewable
through traditional man(1) programs.
nice-looking printed version from it. Also, of course, it make
exporting things like the announcement document to WWW pretty trivial.
- How to Report Bugs
+How to Report Bugs
The reporting address for bugs is bug-ncurses@gnu.org. This is a
majordomo list; to join, write to bug-ncurses-request@gnu.org with a
If your bug produces a core-dump, please include a symbolic stack
trace generated by gdb(1) or your local equivalent.
Tell us about every terminal on which you have reproduced the bug
- -- and every terminal on which you cannot. Ideally, sent us
+ -- and every terminal on which you cannot. Ideally, send us
terminfo sources for all of these (yours might differ from ours).
Include your ncurses version and your OS/machine type, of course!
You can find your ncurses version in the curses.h file.
comments of hardscroll.c and hashmap.c; then try it out. You can also
test the hardware-scrolling optimization separately with hardscroll.
- A Tour of the Ncurses Library
+A Tour of the Ncurses Library
-Library Overview
+ Library Overview
Most of the library is superstructure -- fairly trivial convenience
interfaces to a small set of basic functions and data structures used
We will discuss these in the compiler tour.
-The Engine Room
+ The Engine Room
- Keyboard Input
+ Keyboard Input
All ncurses input funnels through the function wgetch(), defined in
lib_getch.c. This function is tricky; it has to poll for keyboard and
value. The function timed_wait() effectively simulates a System V
select.
- Mouse Events
+ Mouse Events
If the mouse interface is active, wgetch() polls for mouse events each
call, before it goes to the keyboard for input. It is up to
Here are some more details about mouse event handling:
- The lib_mouse()code is logically split into a lower level that accepts
- event reports in a device-dependent format and an upper level that
- parses mouse gestures and filters events. The mediating data structure
- is a circular queue of event structures.
+ The lib_mouse() code is logically split into a lower level that
+ accepts event reports in a device-dependent format and an upper level
+ that parses mouse gestures and filters events. The mediating data
+ structure is a circular queue of event structures.
Functionally, the lower level's job is to pick up primitive events and
put them on the circular queue. This can happen in one of two ways:
accepted to parse the digested mouse reports (low-level events) into a
gesture (a high-level or composite event).
- Output and Screen Updating
+ Output and Screen Updating
With the single exception of character echoes during a wgetnstr() call
(which simulates cooked-mode line editing in an ncurses window), the
The brains of this operation are the modules hashmap.c, hardscroll.c
and lib_doupdate.c; the latter two use lib_mvcur.c. Essentially, what
happens looks like this:
-
- The hashmap.c module tries to detect vertical motion changes between
- the real and virtual screens. This information is represented by the
- oldindex members in the newscr structure. These are modified by
- vertical-motion and clear operations, and both are re-initialized
- after each update. To this change-journalling information, the hashmap
- code adds deductions made using a modified Heckel algorithm on hash
- values generated from the line contents.
-
- The hardscroll.c module computes an optimum set of scroll, insertion,
- and deletion operations to make the indices match. It calls
- _nc_mvcur_scrolln() in lib_mvcur.c to do those motions.
-
- Then lib_doupdate.c goes to work. Its job is to do line-by-line
- transformations of curscr lines to newscr lines. Its main tool is the
- routine mvcur() in lib_mvcur.c. This routine does cursor-movement
- optimization, attempting to get from given screen location A to given
- location B in the fewest output characters possible.
+ * The hashmap.c module tries to detect vertical motion changes
+ between the real and virtual screens. This information is
+ represented by the oldindex members in the newscr structure. These
+ are modified by vertical-motion and clear operations, and both are
+ re-initialized after each update. To this change-journalling
+ information, the hashmap code adds deductions made using a
+ modified Heckel algorithm on hash values generated from the line
+ contents.
+ * The hardscroll.c module computes an optimum set of scroll,
+ insertion, and deletion operations to make the indices match. It
+ calls _nc_mvcur_scrolln() in lib_mvcur.c to do those motions.
+ * Then lib_doupdate.c goes to work. Its job is to do line-by-line
+ transformations of curscr lines to newscr lines. Its main tool is
+ the routine mvcur() in lib_mvcur.c. This routine does
+ cursor-movement optimization, attempting to get from given screen
+ location A to given location B in the fewest output characters
+ possible.
If you want to work on screen optimizations, you should use the fact
that (in the trace-enabled version of the library) enabling the
variable _nc_optimize_enable. See the file include/curses.h.in for
mask values, near the end.
- The Forms and Menu Libraries
+The Forms and Menu Libraries
The forms and menu libraries should work reliably in any environment
you can port ncurses to. The only portability issue anywhere in them
panels support; u386mon 2.10 and beyond use it. This version has been
slightly cleaned up for ncurses.
- A Tour of the Terminfo Compiler
+A Tour of the Terminfo Compiler
The ncurses implementation of tic is rather complex internally; it has
to do a trying combination of missions. This starts with the fact
the grammar above it is trivial, just "parse entries till you run out
of file".
-Translation of Non-use Capabilities
+ Translation of Non-use Capabilities
Translation of most things besides use capabilities is pretty
straightforward. The lexical analyzer's tokenizer hands each
of adding one line to the include/Caps file. We will have more to say
about this in the section on Source-Form Translation.
-Use Capability Resolution
+ Use Capability Resolution
The background problem that makes tic tricky is not the capability
translation itself, it is the resolution of use capabilities. Older
complain about overwriting entries newly made during the tic run, but
not about overwriting ones that predate it.
-Source-Form Translation
+ Source-Form Translation
Another use of tic is to do source translation between various termcap
and terminfo formats. There are more variants out there than you might
for example, is where the AIX box1 capability get translated to an
acsc string.
- Other Utilities
+Other Utilities
The infocmp utility is just a wrapper around the same entry-dumping
code used by tic for source translation. Perhaps the one interesting
The tput and clear utilities just do an entry load followed by a
tputs() of a selected capability.
- Style Tips for Developers
+Style Tips for Developers
See the TO-DO file in the top-level directory of the source
distribution for additions that would be particularly useful.
Have fun!
- Porting Hints
+Porting Hints
The following notes are intended to be a first step towards DOS and
Macintosh ports of the ncurses libraries.
projects / ncurses.git / blobdiff