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
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
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
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.