aboutsummaryrefslogtreecommitdiff
path: root/contrib/ncurses/doc
diff options
context:
space:
mode:
authorRong-En Fan <rafan@FreeBSD.org>2008-11-09 09:06:04 +0000
committerRong-En Fan <rafan@FreeBSD.org>2008-11-09 09:06:04 +0000
commita388f199193767bacbb38b172ab89cb84369736c (patch)
treea1816f5667d2280b970ca44e407bac8cc4496c0a /contrib/ncurses/doc
parentaa59d4d4c5dda7e1c6f9dc0cc6edc58992a525c7 (diff)
downloadsrc-a388f199193767bacbb38b172ab89cb84369736c.tar.gz
src-a388f199193767bacbb38b172ab89cb84369736c.zip
- Flatten the vendor area
Notes
Notes: svn path=/vendor/ncurses/dist/; revision=184786
Diffstat (limited to 'contrib/ncurses/doc')
-rw-r--r--contrib/ncurses/doc/hackguide.doc682
-rw-r--r--contrib/ncurses/doc/html/NCURSES-Programming-HOWTO.html6413
-rw-r--r--contrib/ncurses/doc/html/announce.html600
-rw-r--r--contrib/ncurses/doc/html/hackguide.html914
-rw-r--r--contrib/ncurses/doc/html/ncurses-intro.html2722
-rw-r--r--contrib/ncurses/doc/ncurses-intro.doc2501
6 files changed, 0 insertions, 13832 deletions
diff --git a/contrib/ncurses/doc/hackguide.doc b/contrib/ncurses/doc/hackguide.doc
deleted file mode 100644
index 8e0ba5c0f85b..000000000000
--- a/contrib/ncurses/doc/hackguide.doc
+++ /dev/null
@@ -1,682 +0,0 @@
- A Hacker's Guide to NCURSES
-
- Contents
-
- * Abstract
- * Objective of the Package
- + Why System V Curses?
- + How to Design Extensions
- * Portability and Configuration
- * Documentation Conventions
- * How to Report Bugs
- * A Tour of the Ncurses Library
- + Library Overview
- + The Engine Room
- + Keyboard Input
- + Mouse Events
- + Output and Screen Updating
- * The Forms and Menu Libraries
- * A Tour of the Terminfo Compiler
- + Translation of Non-use Capabilities
- + Use Capability Resolution
- + Source-Form Translation
- * Other Utilities
- * Style Tips for Developers
- * Porting Hints
-
- Abstract
-
- This document is a hacker's tour of the ncurses library and utilities.
- It discusses design philosophy, implementation methods, and the
- conventions used for coding and documentation. It is recommended
- reading for anyone who is interested in porting, extending or
- improving 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
- characteristics:
- * Source-compatible with historical curses implementations
- (including the original BSD curses and System V curses.
- * Conformant with the XSI Curses standard issued as part of XPG4 by
- X/Open.
- * High-quality -- stable and reliable code, wide portability, good
- packaging, superior documentation.
- * Featureful -- should eliminate as much of the drudgery of C
- interface programming as possible, freeing programmers to think at
- a higher level of design.
-
- These objectives are in priority order. So, for example, source
- compatibility with older version must trump featurefulness -- we
- cannot add features if it means breaking the portion of the API
- corresponding to historical curses versions.
-
-Why System V Curses?
-
- We used System V curses as a model, reverse-engineering their API, in
- order to fulfill the first two objectives.
-
- System V curses implementations can support BSD curses programs with
- just a recompilation, so by capturing the System V API we also capture
- BSD's.
-
- More importantly for the future, the XSI Curses standard issued by
- 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
-
- The third objective (standards conformance) requires that it be easy
- to condition source code using ncurses so that the absence of
- nonstandard extensions does not break the code.
-
- Accordingly, we have a policy of associating with each nonstandard
- extension a feature macro, so that ncurses client code can use this
- macro to condition in or out the code that requires the ncurses
- extension.
-
- For example, there is a macro NCURSES_MOUSE_VERSION which XSI Curses
- 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
-
- Code written for ncurses may assume an ANSI-standard C compiler and
- POSIX-compatible OS interface. It may also assume the presence of a
- System-V-compatible select(2) call.
-
- We encourage (but do not require) developers to make the code friendly
- to less-capable UNIX environments wherever possible.
-
- We encourage developers to support OS-specific optimizations and
- methods not available under POSIX/ANSI, provided only that:
- * All such code is properly conditioned so the build process does
- not attempt to compile it under a plain ANSI/POSIX environment.
- * Adding such implementation methods does not introduce
- incompatibilities in the ncurses API between platforms.
-
- We use GNU autoconf(1) as a tool to deal with portability issues. The
- right way to leverage an OS-specific feature is to modify the autoconf
- specification files (configure.in and aclocal.m4) to set up a new
- feature macro, which you then use to condition your code.
-
- Documentation Conventions
-
- There are three kinds of documentation associated with this package.
- Each has a different preferred format:
- * Package-internal files (README, INSTALL, TO-DO etc.)
- * Manual pages.
- * Everything else (i.e., narrative documentation).
-
- Our conventions are simple:
- 1. Maintain package-internal files in plain text. The expected viewer
- for them more(1) or an editor window; there's 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.
- 3. Write everything else in HTML.
-
- When in doubt, HTMLize a master and use lynx(1) to generate plain
- ASCII (as we do for the announcement document).
-
- The reason for choosing HTML is that it's (a) well-adapted for on-line
- browsing through viewers that are everywhere; (b) more easily readable
- as plain text than most other mark-ups, if you don't have a viewer;
- and (c) carries enough information that you can generate a
- 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
-
- 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
- message containing the line:
- subscribe <name>@<host.domain>
-
- The ncurses code is maintained by a small group of volunteers. While
- we try our best to fix bugs promptly, we simply don't have a lot of
- hours to spend on elementary hand-holding. We rely on intelligent
- cooperation from our users. If you think you have found a bug in
- ncurses, there are some steps you can take before contacting us that
- will help get the bug fixed quickly.
-
- In order to use our bug-fixing time efficiently, we put people who
- show us they've taken these steps at the head of our queue. This means
- that if you don't, you'll probably end up at the tail end and have to
- wait a while.
- 1. Develop a recipe to reproduce the bug.
- Bugs we can reproduce are likely to be fixed very quickly, often
- within days. The most effective single thing you can do to get a
- quick fix is develop a way we can duplicate the bad behavior --
- ideally, by giving us source for a small, portable test program
- that breaks the library. (Even better is a keystroke recipe using
- one of the test programs provided with the distribution.)
- 2. Try to reproduce the bug on a different terminal type.
- In our experience, most of the behaviors people report as library
- bugs are actually due to subtle problems in terminal descriptions.
- This is especially likely to be true if you're using a traditional
- asynchronous terminal or PC-based terminal emulator, rather than
- xterm or a UNIX console entry.
- It's therefore extremely helpful if you can tell us whether or not
- your problem reproduces on other terminal types. Usually you'll
- have both a console type and xterm available; please tell us
- whether or not your bug reproduces on both.
- If you have xterm available, it is also good to collect xterm
- reports for different window sizes. This is especially true if you
- normally use an unusual xterm window size -- a surprising number
- of the bugs we've seen are either triggered or masked by these.
- 3. Generate and examine a trace file for the broken behavior.
- Recompile your program with the debugging versions of the
- libraries. Insert a trace() call with the argument set to
- TRACE_UPDATE. (See "Writing Programs with NCURSES" for details on
- trace levels.) Reproduce your bug, then look at the trace file to
- see what the library was actually doing.
- Another frequent cause of apparent bugs is application coding
- errors that cause the wrong things to be put on the virtual
- screen. Looking at the virtual-screen dumps in the trace file will
- tell you immediately if this is happening, and save you from the
- possible embarrassment of being told that the bug is in your code
- and is your problem rather than ours.
- If the virtual-screen dumps look correct but the bug persists,
- it's possible to crank up the trace level to give more and more
- information about the library's update actions and the control
- sequences it issues to perform them. The test directory of the
- distribution contains a tool for digesting these logs to make them
- less tedious to wade through.
- Often you'll find terminfo problems at this stage by noticing that
- the escape sequences put out for various capabilities are wrong.
- If not, you're likely to learn enough to be able to characterize
- any bug in the screen-update logic quite exactly.
- 4. Report details and symptoms, not just interpretations.
- If you do the preceding two steps, it is very likely that you'll
- discover the nature of the problem yourself and be able to send us
- a fix. This will create happy feelings all around and earn you
- good karma for the first time you run into a bug you really can't
- characterize and fix yourself.
- If you're still stuck, at least you'll know what to tell us.
- Remember, we need details. If you guess about what is safe to
- leave out, you are too likely to be wrong.
- If your bug produces a bad update, include a trace file. Try to
- make the trace at the least voluminous level that pins down the
- bug. Logs that have been through tracemunch are OK, it doesn't
- throw away any information (actually they're better than
- un-munched ones because they're easier to read).
- 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've reproduced the bug --
- and every terminal on which you can't. Ideally, sent 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.
-
- If your problem smells like a logic error or in cursor movement or
- scrolling or a bad capability, there are a couple of tiny test frames
- for the library algorithms in the progs directory that may help you
- isolate it. These are not part of the normal build, but do have their
- own make productions.
-
- The most important of these is mvcur, a test frame for the
- cursor-movement optimization code. With this program, you can see
- directly what control sequences will be emitted for any given cursor
- movement or scroll/insert/delete operations. If you think you've got a
- bad capability identified, you can disable it and test again. The
- program is command-driven and has on-line help.
-
- If you think the vertical-scroll optimization is broken, or just want
- to understand how it works better, build hashmap and read the header
- 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
-
-Library Overview
-
- Most of the library is superstructure -- fairly trivial convenience
- interfaces to a small set of basic functions and data structures used
- to manipulate the virtual screen (in particular, none of this code
- does any I/O except through calls to more fundamental modules
- described below). The files
-
- lib_addch.c lib_bkgd.c lib_box.c lib_chgat.c lib_clear.c
- lib_clearok.c lib_clrbot.c lib_clreol.c lib_colorset.c lib_data.c
- lib_delch.c lib_delwin.c lib_echo.c lib_erase.c lib_gen.c
- lib_getstr.c lib_hline.c lib_immedok.c lib_inchstr.c lib_insch.c
- lib_insdel.c lib_insstr.c lib_instr.c lib_isendwin.c lib_keyname.c
- lib_leaveok.c lib_move.c lib_mvwin.c lib_overlay.c lib_pad.c
- lib_printw.c lib_redrawln.c lib_scanw.c lib_screen.c lib_scroll.c
- lib_scrollok.c lib_scrreg.c lib_set_term.c lib_slk.c
- lib_slkatr_set.c lib_slkatrof.c lib_slkatron.c lib_slkatrset.c
- lib_slkattr.c lib_slkclear.c lib_slkcolor.c lib_slkinit.c
- lib_slklab.c lib_slkrefr.c lib_slkset.c lib_slktouch.c lib_touch.c
- lib_unctrl.c lib_vline.c lib_wattroff.c lib_wattron.c lib_window.c
-
- are all in this category. They are very unlikely to need change,
- barring bugs or some fundamental reorganization in the underlying data
- structures.
-
- These files are used only for debugging support:
-
- lib_trace.c lib_traceatr.c lib_tracebits.c lib_tracechr.c
- lib_tracedmp.c lib_tracemse.c trace_buf.c
-
- It is rather unlikely you will ever need to change these, unless you
- want to introduce a new debug trace level for some reason.
-
- There is another group of files that do direct I/O via tputs(),
- computations on the terminal capabilities, or queries to the OS
- environment, but nevertheless have only fairly low complexity. These
- include:
-
- lib_acs.c lib_beep.c lib_color.c lib_endwin.c lib_initscr.c
- lib_longname.c lib_newterm.c lib_options.c lib_termcap.c lib_ti.c
- lib_tparm.c lib_tputs.c lib_vidattr.c read_entry.c.
-
- They are likely to need revision only if ncurses is being ported to an
- environment without an underlying terminfo capability representation.
-
- These files have serious hooks into the tty driver and signal
- facilities:
-
- lib_kernel.c lib_baudrate.c lib_raw.c lib_tstp.c lib_twait.c
-
- If you run into porting snafus moving the package to another UNIX, the
- problem is likely to be in one of these files. The file lib_print.c
- uses sleep(2) and also falls in this category.
-
- Almost all of the real work is done in the files
-
- hardscroll.c hashmap.c lib_addch.c lib_doupdate.c lib_getch.c
- lib_mouse.c lib_mvcur.c lib_refresh.c lib_setup.c lib_vidattr.c
-
- Most of the algorithmic complexity in the library lives in these
- files. If there is a real bug in ncurses itself, it's probably here.
- We'll tour some of these files in detail below (see The Engine Room).
-
- Finally, there is a group of files that is actually most of the
- terminfo compiler. The reason this code lives in the ncurses library
- is to support fallback to /etc/termcap. These files include
-
- alloc_entry.c captoinfo.c comp_captab.c comp_error.c comp_hash.c
- comp_parse.c comp_scan.c parse_entry.c read_termcap.c write_entry.c
-
- We'll discuss these in the compiler tour.
-
-The Engine Room
-
- 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
- mouse events and do a running match of incoming input against the set
- of defined special keys.
-
- The central data structure in this module is a FIFO queue, used to
- match multiple-character input sequences against special-key
- capabilities; also to implement pushback via ungetch().
-
- The wgetch() code distinguishes between function key sequences and the
- same sequences typed manually by doing a timed wait after each input
- character that could lead a function key sequence. If the entire
- sequence takes less than 1 second, it is assumed to have been
- generated by a function key press.
-
- Hackers bruised by previous encounters with variant select(2) calls
- may find the code in lib_twait.c interesting. It deals with the
- problem that some BSD selects don't return a reliable time-left value.
- The function timed_wait() effectively simulates a System V select.
-
- 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
- lib_mouse.c how the polling is accomplished; it may vary for different
- devices.
-
- Under xterm, however, mouse event notifications come in via the
- keyboard input stream. They are recognized by having the kmous
- capability as a prefix. This is kind of klugey, but trying to wire in
- recognition of a mouse key prefix without going through the
- function-key machinery would be just too painful, and this turns out
- to imply having the prefix somewhere in the function-key capabilities
- at terminal-type initialization.
-
- This kluge only works because kmous isn't actually used by any
- historic terminal type or curses implementation we know of. Best guess
- is it's a relic of some forgotten experiment in-house at Bell Labs
- that didn't leave any traces in the publicly-distributed System V
- terminfo files. If System V or XPG4 ever gets serious about using it
- again, this kluge may have to change.
-
- 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.
-
- 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:
- either (a) _nc_mouse_event() detects a series of incoming mouse
- reports and queues them, or (b) code in lib_getch.c detects the kmous
- prefix in the keyboard input stream and calls _nc_mouse_inline to
- queue up a series of adjacent mouse reports.
-
- In either case, _nc_mouse_parse() should be called after the series is
- accepted to parse the digested mouse reports (low-level events) into a
- gesture (a high-level or composite event).
-
- 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
- library normally does all its output at refresh time.
-
- The main job is to go from the current state of the screen (as
- represented in the curscr window structure) to the desired new state
- (as represented in the newscr window structure), while doing as little
- I/O as possible.
-
- 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.
-
- If you want to work on screen optimizations, you should use the fact
- that (in the trace-enabled version of the library) enabling the
- TRACE_TIMES trace level causes a report to be emitted after each
- screen update giving the elapsed time and a count of characters
- emitted during the update. You can use this to tell when an update
- optimization improves efficiency.
-
- In the trace-enabled version of the library, it is also possible to
- disable and re-enable various optimizations at runtime by tweaking 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 should work reliably in any environment
- you can port ncurses to. The only portability issue anywhere in them
- is what flavor of regular expressions the built-in form field type
- TYPE_REGEXP will recognize.
-
- The configuration code prefers the POSIX regex facility, modeled on
- System V's, but will settle for BSD regexps if the former isn't
- available.
-
- Historical note: the panels code was written primarily to assist in
- porting u386mon 2.0 (comp.sources.misc v14i001-4) to systems lacking
- panels support; u386mon 2.10 and beyond use it. This version has been
- slightly cleaned up for ncurses.
-
- 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
- that, in addition to its normal duty of compiling terminfo sources
- into loadable terminfo binaries, it has to be able to handle termcap
- syntax and compile that too into terminfo entries.
-
- The implementation therefore starts with a table-driven, dual-mode
- lexical analyzer (in comp_scan.c). The lexer chooses its mode (termcap
- or terminfo) based on the first `,' or `:' it finds in each entry. The
- lexer does all the work of recognizing capability names and values;
- the grammar above it is trivial, just "parse entries till you run out
- of file".
-
-Translation of Non-use Capabilities
-
- Translation of most things besides use capabilities is pretty
- straightforward. The lexical analyzer's tokenizer hands each
- capability name to a hash function, which drives a table lookup. The
- table entry yields an index which is used to look up the token type in
- another table, and controls interpretation of the value.
-
- One possibly interesting aspect of the implementation is the way the
- compiler tables are initialized. All the tables are generated by
- various awk/sed/sh scripts from a master table include/Caps; these
- scripts actually write C initializers which are linked to the
- compiler. Furthermore, the hash table is generated in the same way, so
- it doesn't have to be generated at compiler startup time (another
- benefit of this organization is that the hash table can be in
- shareable text space).
-
- Thus, adding a new capability is usually pretty trivial, just a matter
- of adding one line to the include/Caps file. We'll have more to say
- about this in the section on Source-Form Translation.
-
-Use Capability Resolution
-
- The background problem that makes tic tricky isn't the capability
- translation itself, it's the resolution of use capabilities. Older
- versions would not handle forward use references for this reason (that
- is, a using terminal always had to follow its use target in the source
- file). By doing this, they got away with a simple implementation
- tactic; compile everything as it blows by, then resolve uses from
- compiled entries.
-
- This won't do for ncurses. The problem is that that the whole
- compilation process has to be embeddable in the ncurses library so
- that it can be called by the startup code to translate termcap entries
- on the fly. The embedded version can't go promiscuously writing
- everything it translates out to disk -- for one thing, it will
- typically be running with non-root permissions.
-
- So our tic is designed to parse an entire terminfo file into a
- doubly-linked circular list of entry structures in-core, and then do
- use resolution in-memory before writing everything out. This design
- has other advantages: it makes forward and back use-references equally
- easy (so we get the latter for free), and it makes checking for name
- collisions before they're written out easy to do.
-
- And this is exactly how the embedded version works. But the
- stand-alone user-accessible version of tic partly reverts to the
- historical strategy; it writes to disk (not keeping in core) any entry
- with no use references.
-
- This is strictly a core-economy kluge, implemented because the
- terminfo master file is large enough that some core-poor systems swap
- like crazy when you compile it all in memory...there have been reports
- of this process taking three hours, rather than the twenty seconds or
- less typical on the author's development box.
-
- So. The executable tic passes the entry-parser a hook that immediately
- writes out the referenced entry if it has no use capabilities. The
- compiler main loop refrains from adding the entry to the in-core list
- when this hook fires. If some other entry later needs to reference an
- entry that got written immediately, that's OK; the resolution code
- will fetch it off disk when it can't find it in core.
-
- Name collisions will still be detected, just not as cleanly. The
- write_entry() code complains before overwriting an entry that
- postdates the time of tic's first call to write_entry(), Thus it will
- complain about overwriting entries newly made during the tic run, but
- not about overwriting ones that predate it.
-
-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
- think; the ones we know about are described in the captoinfo(1) manual
- page.
-
- The translation output code (dump_entry() in ncurses/dump_entry.c) is
- shared with the infocmp(1) utility. It takes the same internal
- representation used to generate the binary form and dumps it to
- standard output in a specified format.
-
- The include/Caps file has a header comment describing ways you can
- specify source translations for nonstandard capabilities just by
- altering the master table. It's possible to set up capability aliasing
- or tell the compiler to plain ignore a given capability without
- writing any C code at all.
-
- For circumstances where you need to do algorithmic translation, there
- are functions in parse_entry.c called after the parse of each entry
- that are specifically intended to encapsulate such translations. This,
- for example, is where the AIX box1 capability get translated to an
- acsc string.
-
- 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
- aspect of the code is the use of a predicate function passed in to
- dump_entry() to control which capabilities are dumped. This is
- necessary in order to handle both the ordinary De-compilation case and
- entry difference reporting.
-
- The tput and clear utilities just do an entry load followed by a
- tputs() of a selected capability.
-
- 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.
-
- The prefix _nc_ should be used on library public functions that are
- not part of the curses API in order to prevent pollution of the
- application namespace. If you have to add to or modify the function
- prototypes in curses.h.in, read ncurses/MKlib_gen.sh first so you can
- avoid breaking XSI conformance. Please join the ncurses mailing list.
- See the INSTALL file in the top level of the distribution for details
- on the list.
-
- Look for the string FIXME in source files to tag minor bugs and
- potential problems that could use fixing.
-
- Don't try to auto-detect OS features in the main body of the C code.
- That's the job of the configuration system.
-
- To hold down complexity, do make your code data-driven. Especially, if
- you can drive logic from a table filtered out of include/Caps, do it.
- If you find you need to augment the data in that file in order to
- generate the proper table, that's still preferable to ad-hoc code --
- that's why the fifth field (flags) is there.
-
- Have fun!
-
- Porting Hints
-
- The following notes are intended to be a first step towards DOS and
- Macintosh ports of the ncurses libraries.
-
- The following library modules are `pure curses'; they operate only on
- the curses internal structures, do all output through other curses
- calls (not including tputs() and putp()) and do not call any other
- UNIX routines such as signal(2) or the stdio library. Thus, they
- should not need to be modified for single-terminal ports.
-
- lib_addch.c lib_addstr.c lib_bkgd.c lib_box.c lib_clear.c
- lib_clrbot.c lib_clreol.c lib_delch.c lib_delwin.c lib_erase.c
- lib_inchstr.c lib_insch.c lib_insdel.c lib_insstr.c lib_keyname.c
- lib_move.c lib_mvwin.c lib_newwin.c lib_overlay.c lib_pad.c
- lib_printw.c lib_refresh.c lib_scanw.c lib_scroll.c lib_scrreg.c
- lib_set_term.c lib_touch.c lib_tparm.c lib_tputs.c lib_unctrl.c
- lib_window.c panel.c
-
- This module is pure curses, but calls outstr():
-
- lib_getstr.c
-
- These modules are pure curses, except that they use tputs() and
- putp():
-
- lib_beep.c lib_color.c lib_endwin.c lib_options.c lib_slk.c
- lib_vidattr.c
-
- This modules assist in POSIX emulation on non-POSIX systems:
-
- sigaction.c
- signal calls
-
- The following source files will not be needed for a
- single-terminal-type port.
-
- alloc_entry.c captoinfo.c clear.c comp_captab.c comp_error.c
- comp_hash.c comp_main.c comp_parse.c comp_scan.c dump_entry.c
- infocmp.c parse_entry.c read_entry.c tput.c write_entry.c
-
- The following modules will use open()/read()/write()/close()/lseek()
- on files, but no other OS calls.
-
- lib_screen.c
- used to read/write screen dumps
-
- lib_trace.c
- used to write trace data to the logfile
-
- Modules that would have to be modified for a port start here:
-
- The following modules are `pure curses' but contain assumptions
- inappropriate for a memory-mapped port.
-
- lib_longname.c
- assumes there may be multiple terminals
-
- lib_acs.c
- assumes acs_map as a double indirection
-
- lib_mvcur.c
- assumes cursor moves have variable cost
-
- lib_termcap.c
- assumes there may be multiple terminals
-
- lib_ti.c
- assumes there may be multiple terminals
-
- The following modules use UNIX-specific calls:
-
- lib_doupdate.c
- input checking
-
- lib_getch.c
- read()
-
- lib_initscr.c
- getenv()
-
- lib_newterm.c
- lib_baudrate.c
- lib_kernel.c
- various tty-manipulation and system calls
-
- lib_raw.c
- various tty-manipulation calls
-
- lib_setup.c
- various tty-manipulation calls
-
- lib_restart.c
- various tty-manipulation calls
-
- lib_tstp.c
- signal-manipulation calls
-
- lib_twait.c
- gettimeofday(), select().
- _________________________________________________________________
-
-
- Eric S. Raymond <esr@snark.thyrsus.com>
-
- (Note: This is not the bug address!)
diff --git a/contrib/ncurses/doc/html/NCURSES-Programming-HOWTO.html b/contrib/ncurses/doc/html/NCURSES-Programming-HOWTO.html
deleted file mode 100644
index 3a1010635ff0..000000000000
--- a/contrib/ncurses/doc/html/NCURSES-Programming-HOWTO.html
+++ /dev/null
@@ -1,6413 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-<head>
-<meta name="generator" content=
-"HTML Tidy for Linux/x86 (vers 1st December 2004), see www.w3.org">
-<title>NCURSES Programming HOWTO</title>
-<meta name="GENERATOR" content=
-"Modular DocBook HTML Stylesheet Version 1.7">
-</head>
-<body class="ARTICLE" bgcolor="#FFFFFF" text="#000000" link=
-"#0000FF" vlink="#840084" alink="#0000FF">
-<div class="ARTICLE">
-<div class="TITLEPAGE">
-<h1 class="TITLE"><a name="AEN2" id="AEN2">NCURSES Programming
-HOWTO</a></h1>
-<h3 class="AUTHOR"><a name="AEN4" id="AEN4">Pradeep Padala</a></h3>
-<div class="AFFILIATION">
-<div class="ADDRESS">
-<p class="ADDRESS"><code class="EMAIL">&lt;<a href=
-"mailto:ppadala@gmail.com">ppadala@gmail.com</a>&gt;</code></p>
-</div>
-</div>
-<p class="PUBDATE">v1.9, 2005-06-20<br></p>
-<div class="REVHISTORY">
-<table width="100%" border="0">
-<tr>
-<th align="left" valign="top" colspan="3"><b>Revision
-History</b></th>
-</tr>
-<tr>
-<td align="left">Revision 1.9</td>
-<td align="left">2005-06-20</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">The license has been changed to the
-MIT-style license used by NCURSES. Note that the programs are also
-re-licensed under this.</td>
-</tr>
-<tr>
-<td align="left">Revision 1.8</td>
-<td align="left">2005-06-17</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">Lots of updates. Added references and
-perl examples. Changes to examples. Many grammatical and stylistic
-changes to the content. Changes to NCURSES history.</td>
-</tr>
-<tr>
-<td align="left">Revision 1.7.1</td>
-<td align="left">2002-06-25</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">Added a README file for building and
-instructions for building from source.</td>
-</tr>
-<tr>
-<td align="left">Revision 1.7</td>
-<td align="left">2002-06-25</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">Added "Other formats" section and made
-a lot of fancy changes to the programs. Inlining of programs is
-gone.</td>
-</tr>
-<tr>
-<td align="left">Revision 1.6.1</td>
-<td align="left">2002-02-24</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">Removed the old Changelog section,
-cleaned the makefiles</td>
-</tr>
-<tr>
-<td align="left">Revision 1.6</td>
-<td align="left">2002-02-16</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">Corrected a lot of spelling mistakes,
-added ACS variables section</td>
-</tr>
-<tr>
-<td align="left">Revision 1.5</td>
-<td align="left">2002-01-05</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">Changed structure to present proper
-TOC</td>
-</tr>
-<tr>
-<td align="left">Revision 1.3.1</td>
-<td align="left">2001-07-26</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">Corrected maintainers paragraph,
-Corrected stable release number</td>
-</tr>
-<tr>
-<td align="left">Revision 1.3</td>
-<td align="left">2001-07-24</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">Added copyright notices to main
-document (LDP license) and programs (GPL), Corrected
-printw_example.</td>
-</tr>
-<tr>
-<td align="left">Revision 1.2</td>
-<td align="left">2001-06-05</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">Incorporated ravi's changes. Mainly to
-introduction, menu, form, justforfun sections</td>
-</tr>
-<tr>
-<td align="left">Revision 1.1</td>
-<td align="left">2001-05-22</td>
-<td align="left">Revised by: ppadala</td>
-</tr>
-<tr>
-<td align="left" colspan="3">Added "a word about window" section,
-Added scanw_example.</td>
-</tr>
-</table>
-</div>
-<div>
-<div class="ABSTRACT"><a name="AEN67" id="AEN67"></a>
-<p><em>This document is intended to be an "All in One" guide for
-programming with ncurses and its sister libraries. We graduate from
-a simple "Hello World" program to more complex form manipulation.
-No prior experience in ncurses is assumed. Send comments to
-<a href="mailto:ppadala@gmail.com" target="_top">this
-address</a></em></p>
-</div>
-</div>
-<hr></div>
-<div class="TOC">
-<dl>
-<dt><b>Table of Contents</b></dt>
-<dt>1. <a href="#INTRO">Introduction</a></dt>
-<dd>
-<dl>
-<dt>1.1. <a href="#WHATIS">What is NCURSES?</a></dt>
-<dt>1.2. <a href="#WHATCANWEDO">What we can do with
-NCURSES</a></dt>
-<dt>1.3. <a href="#WHERETOGETIT">Where to get it</a></dt>
-<dt>1.4. <a href="#PURPOSE">Purpose/Scope of the document</a></dt>
-<dt>1.5. <a href="#ABOUTPROGRAMS">About the Programs</a></dt>
-<dt>1.6. <a href="#OTHERFORMATS">Other Formats of the
-document</a></dt>
-<dt>1.7. <a href="#CREDITS">Credits</a></dt>
-<dt>1.8. <a href="#WISHLIST">Wish List</a></dt>
-<dt>1.9. <a href="#COPYRIGHT">Copyright</a></dt>
-</dl>
-</dd>
-<dt>2. <a href="#HELLOWORLD">Hello World !!!</a></dt>
-<dd>
-<dl>
-<dt>2.1. <a href="#COMPILECURSES">Compiling With the NCURSES
-Library</a></dt>
-<dt>2.2. <a href="#DISSECTION">Dissection</a></dt>
-</dl>
-</dd>
-<dt>3. <a href="#GORY">The Gory Details</a></dt>
-<dt>4. <a href="#INIT">Initialization</a></dt>
-<dd>
-<dl>
-<dt>4.1. <a href="#ABOUTINIT">Initialization functions</a></dt>
-<dt>4.2. <a href="#RAWCBREAK">raw() and cbreak()</a></dt>
-<dt>4.3. <a href="#ECHONOECHO">echo() and noecho()</a></dt>
-<dt>4.4. <a href="#KEYPAD">keypad()</a></dt>
-<dt>4.5. <a href="#HALFDELAY">halfdelay()</a></dt>
-<dt>4.6. <a href="#MISCINIT">Miscellaneous Initialization
-functions</a></dt>
-<dt>4.7. <a href="#INITEX">An Example</a></dt>
-</dl>
-</dd>
-<dt>5. <a href="#AWORDWINDOWS">A Word about Windows</a></dt>
-<dt>6. <a href="#PRINTW">Output functions</a></dt>
-<dd>
-<dl>
-<dt>6.1. <a href="#ADDCHCLASS">addch() class of functions</a></dt>
-<dt>6.2. <a href="#AEN298">mvaddch(), waddch() and
-mvwaddch()</a></dt>
-<dt>6.3. <a href="#PRINTWCLASS">printw() class of
-functions</a></dt>
-<dt>6.4. <a href="#ADDSTRCLASS">addstr() class of
-functions</a></dt>
-<dt>6.5. <a href="#ACAUTION">A word of caution</a></dt>
-</dl>
-</dd>
-<dt>7. <a href="#SCANW">Input functions</a></dt>
-<dd>
-<dl>
-<dt>7.1. <a href="#GETCHCLASS">getch() class of functions</a></dt>
-<dt>7.2. <a href="#SCANWCLASS">scanw() class of functions</a></dt>
-<dt>7.3. <a href="#GETSTRCLASS">getstr() class of
-functions</a></dt>
-<dt>7.4. <a href="#GETSTREX">Some examples</a></dt>
-</dl>
-</dd>
-<dt>8. <a href="#ATTRIB">Attributes</a></dt>
-<dd>
-<dl>
-<dt>8.1. <a href="#ATTRIBDETAILS">The details</a></dt>
-<dt>8.2. <a href="#ATTRONVSATTRSET">attron() vs attrset()</a></dt>
-<dt>8.3. <a href="#ATTR_GET">attr_get()</a></dt>
-<dt>8.4. <a href="#ATTR_FUNCS">attr_ functions</a></dt>
-<dt>8.5. <a href="#WATTRFUNCS">wattr functions</a></dt>
-<dt>8.6. <a href="#CHGAT">chgat() functions</a></dt>
-</dl>
-</dd>
-<dt>9. <a href="#WINDOWS">Windows</a></dt>
-<dd>
-<dl>
-<dt>9.1. <a href="#WINDOWBASICS">The basics</a></dt>
-<dt>9.2. <a href="#LETBEWINDOW">Let there be a Window !!!</a></dt>
-<dt>9.3. <a href="#BORDEREXEXPL">Explanation</a></dt>
-<dt>9.4. <a href="#OTHERSTUFF">The other stuff in the
-example</a></dt>
-<dt>9.5. <a href="#OTHERBORDERFUNCS">Other Border
-functions</a></dt>
-</dl>
-</dd>
-<dt>10. <a href="#COLOR">Colors</a></dt>
-<dd>
-<dl>
-<dt>10.1. <a href="#COLORBASICS">The basics</a></dt>
-<dt>10.2. <a href="#CHANGECOLORDEFS">Changing Color
-Definitions</a></dt>
-<dt>10.3. <a href="#COLORCONTENT">Color Content</a></dt>
-</dl>
-</dd>
-<dt>11. <a href="#KEYS">Interfacing with the key board</a></dt>
-<dd>
-<dl>
-<dt>11.1. <a href="#KEYSBASICS">The Basics</a></dt>
-<dt>11.2. <a href="#SIMPLEKEYEX">A Simple Key Usage
-example</a></dt>
-</dl>
-</dd>
-<dt>12. <a href="#MOUSE">Interfacing with the mouse</a></dt>
-<dd>
-<dl>
-<dt>12.1. <a href="#MOUSEBASICS">The Basics</a></dt>
-<dt>12.2. <a href="#GETTINGEVENTS">Getting the events</a></dt>
-<dt>12.3. <a href="#MOUSETOGETHER">Putting it all Together</a></dt>
-<dt>12.4. <a href="#MISCMOUSEFUNCS">Miscellaneous
-Functions</a></dt>
-</dl>
-</dd>
-<dt>13. <a href="#SCREEN">Screen Manipulation</a></dt>
-<dd>
-<dl>
-<dt>13.1. <a href="#GETYX">getyx() functions</a></dt>
-<dt>13.2. <a href="#SCREENDUMP">Screen Dumping</a></dt>
-<dt>13.3. <a href="#WINDOWDUMP">Window Dumping</a></dt>
-</dl>
-</dd>
-<dt>14. <a href="#MISC">Miscellaneous features</a></dt>
-<dd>
-<dl>
-<dt>14.1. <a href="#CURSSET">curs_set()</a></dt>
-<dt>14.2. <a href="#TEMPLEAVE">Temporarily Leaving Curses
-mode</a></dt>
-<dt>14.3. <a href="#ACSVARS">ACS_ variables</a></dt>
-</dl>
-</dd>
-<dt>15. <a href="#OTHERLIB">Other libraries</a></dt>
-<dt>16. <a href="#PANELS">Panel Library</a></dt>
-<dd>
-<dl>
-<dt>16.1. <a href="#PANELBASICS">The Basics</a></dt>
-<dt>16.2. <a href="#COMPILEPANELS">Compiling With the Panels
-Library</a></dt>
-<dt>16.3. <a href="#PANELBROWSING">Panel Window Browsing</a></dt>
-<dt>16.4. <a href="#USERPTRUSING">Using User Pointers</a></dt>
-<dt>16.5. <a href="#PANELMOVERESIZE">Moving and Resizing
-Panels</a></dt>
-<dt>16.6. <a href="#PANELSHOWHIDE">Hiding and Showing
-Panels</a></dt>
-<dt>16.7. <a href="#PANELABOVE">panel_above() and panel_below()
-Functions</a></dt>
-</dl>
-</dd>
-<dt>17. <a href="#MENUS">Menus Library</a></dt>
-<dd>
-<dl>
-<dt>17.1. <a href="#MENUBASICS">The Basics</a></dt>
-<dt>17.2. <a href="#COMPILEMENUS">Compiling With the Menu
-Library</a></dt>
-<dt>17.3. <a href="#MENUDRIVER">Menu Driver: The work horse of the
-menu system</a></dt>
-<dt>17.4. <a href="#MENUWINDOWS">Menu Windows</a></dt>
-<dt>17.5. <a href="#SCROLLMENUS">Scrolling Menus</a></dt>
-<dt>17.6. <a href="#MULTICOLUMN">Multi Columnar Menus</a></dt>
-<dt>17.7. <a href="#MULTIVALUEMENUS">Multi Valued Menus</a></dt>
-<dt>17.8. <a href="#MENUOPT">Menu Options</a></dt>
-<dt>17.9. <a href="#MENUUSERPTR">The useful User Pointer</a></dt>
-</dl>
-</dd>
-<dt>18. <a href="#FORMS">Forms Library</a></dt>
-<dd>
-<dl>
-<dt>18.1. <a href="#FORMBASICS">The Basics</a></dt>
-<dt>18.2. <a href="#COMPILEFORMS">Compiling With the Forms
-Library</a></dt>
-<dt>18.3. <a href="#PLAYFIELDS">Playing with Fields</a></dt>
-<dt>18.4. <a href="#FORMWINDOWS">Form Windows</a></dt>
-<dt>18.5. <a href="#FILEDVALIDATE">Field Validation</a></dt>
-<dt>18.6. <a href="#FORMDRIVER">Form Driver: The work horse of the
-forms system</a></dt>
-</dl>
-</dd>
-<dt>19. <a href="#TOOLS">Tools and Widget Libraries</a></dt>
-<dd>
-<dl>
-<dt>19.1. <a href="#CDK">CDK (Curses Development Kit)</a></dt>
-<dt>19.2. <a href="#DIALOG">The dialog</a></dt>
-<dt>19.3. <a href="#PERLCURSES">Perl Curses Modules CURSES::FORM
-and CURSES::WIDGETS</a></dt>
-</dl>
-</dd>
-<dt>20. <a href="#JUSTFORFUN">Just For Fun !!!</a></dt>
-<dd>
-<dl>
-<dt>20.1. <a href="#GAMEOFLIFE">The Game of Life</a></dt>
-<dt>20.2. <a href="#MAGIC">Magic Square</a></dt>
-<dt>20.3. <a href="#HANOI">Towers of Hanoi</a></dt>
-<dt>20.4. <a href="#QUEENS">Queens Puzzle</a></dt>
-<dt>20.5. <a href="#SHUFFLE">Shuffle</a></dt>
-<dt>20.6. <a href="#TT">Typing Tutor</a></dt>
-</dl>
-</dd>
-<dt>21. <a href="#REF">References</a></dt>
-</dl>
-</div>
-<div class="SECT1">
-<h2 class="SECT1"><a name="INTRO" id="INTRO">1.
-Introduction</a></h2>
-<p>In the olden days of teletype terminals, terminals were away
-from computers and were connected to them through serial cables.
-The terminals could be configured by sending a series of bytes. All
-the capabilities (such as moving the cursor to a new location,
-erasing part of the screen, scrolling the screen, changing modes
-etc.) of terminals could be accessed through these series of bytes.
-These control seeuqnces are usually called escape sequences,
-because they start with an escape(0x1B) character. Even today, with
-proper emulation, we can send escape sequences to the emulator and
-achieve the same effect on a terminal window.</p>
-<p>Suppose you wanted to print a line in color. Try typing this on
-your console.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000">echo "^[[0;31;40mIn Color"</font>
-</pre></td>
-</tr>
-</table>
-<p>The first character is an escape character, which looks like two
-characters ^ and [. To be able to print it, you have to press
-CTRL+V and then the ESC key. All the others are normal printable
-characters. You should be able to see the string "In Color" in red.
-It stays that way and to revert back to the original mode type
-this.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000">echo "^[[0;37;40m"</font>
-</pre></td>
-</tr>
-</table>
-<p>Now, what do these magic characters mean? Difficult to
-comprehend? They might even be different for different terminals.
-So the designers of UNIX invented a mechanism named <var class=
-"LITERAL">termcap</var>. It is a file that lists all the
-capabilities of a particular terminal, along with the escape
-sequences needed to achieve a particular effect. In the later
-years, this was replaced by <var class="LITERAL">terminfo</var>.
-Without delving too much into details, this mechanism allows
-application programs to query the terminfo database and obtain the
-control characters to be sent to a terminal or terminal
-emulator.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="WHATIS" id="WHATIS">1.1. What is
-NCURSES?</a></h3>
-<p>You might be wondering, what the import of all this technical
-gibberish is. In the above scenario, every application program is
-supposed to query the terminfo and perform the necessary stuff
-(sending control characters etc.). It soon became difficult to
-manage this complexity and this gave birth to 'CURSES'. Curses is a
-pun on the name "cursor optimization". The Curses library forms a
-wrapper over working with raw terminal codes, and provides highly
-flexible and efficient API (Application Programming Interface). It
-provides functions to move the cursor, create windows, produce
-colors, play with mouse etc. The application programs need not
-worry about the underlying terminal capabilities.</p>
-<p>So what is NCURSES? NCURSES is a clone of the original System V
-Release 4.0 (SVr4) curses. It is a freely distributable library,
-fully compatible with older version of curses. In short, it is a
-library of functions that manages an application's display on
-character-cell terminals. In the remainder of the document, the
-terms curses and ncurses are used interchangeably.</p>
-<p>A detailed history of NCURSES can be found in the NEWS file from
-the source distribution. The current package is maintained by
-<a href="mailto:dickey@his.com" target="_top">Thomas Dickey</a>.
-You can contact the maintainers at <a href=
-"mailto:bug-ncurses@gnu.org" target=
-"_top">bug-ncurses@gnu.org</a>.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="WHATCANWEDO" id="WHATCANWEDO">1.2. What
-we can do with NCURSES</a></h3>
-<p>NCURSES not only creates a wrapper over terminal capabilities,
-but also gives a robust framework to create nice looking UI (User
-Interface)s in text mode. It provides functions to create windows
-etc. Its sister libraries panel, menu and form provide an extension
-to the basic curses library. These libraries usually come along
-with curses. One can create applications that contain multiple
-windows, menus, panels and forms. Windows can be managed
-independently, can provide 'scrollability' and even can be
-hidden.</p>
-<p>Menus provide the user with an easy command selection option.
-Forms allow the creation of easy-to-use data entry and display
-windows. Panels extend the capabilities of ncurses to deal with
-overlapping and stacked windows.</p>
-<p>These are just some of the basic things we can do with ncurses.
-As we move along, We will see all the capabilities of these
-libraries.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="WHERETOGETIT" id="WHERETOGETIT">1.3.
-Where to get it</a></h3>
-<p>All right, now that you know what you can do with ncurses, you
-must be rearing to get started. NCURSES is usually shipped with
-your installation. In case you don't have the library or want to
-compile it on your own, read on.</p>
-<p><em>Compiling the package</em></p>
-<p>NCURSES can be obtained from <a href=
-"ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz" target=
-"_top">ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz</a> or any
-of the ftp sites mentioned in <a href=
-"http://www.gnu.org/order/ftp.html" target=
-"_top">http://www.gnu.org/order/ftp.html</a>.</p>
-<p>Read the README and INSTALL files for details on to how to
-install it. It usually involves the following operations.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"> tar zxvf ncurses&lt;version&gt;.tar.gz # unzip and untar the archive
- cd ncurses&lt;version&gt; # cd to the directory
- ./configure # configure the build according to your
- # environment
- make # make it
- su root # become root
- make install # install it</font>
-</pre></td>
-</tr>
-</table>
-<p><em>Using the RPM</em></p>
-<p>NCURSES RPM can be found and downloaded from <a href=
-"http://rpmfind.net" target="_top">http://rpmfind.net</a> . The RPM
-can be installed with the following command after becoming
-root.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> rpm -i &lt;downloaded rpm&gt;</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PURPOSE" id="PURPOSE">1.4. Purpose/Scope
-of the document</a></h3>
-<p>This document is intended to be a "All in One" guide for
-programming with ncurses and its sister libraries. We graduate from
-a simple "Hello World" program to more complex form manipulation.
-No prior experience in ncurses is assumed. The writing is informal,
-but a lot of detail is provided for each of the examples.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ABOUTPROGRAMS" id="ABOUTPROGRAMS">1.5.
-About the Programs</a></h3>
-<p>All the programs in the document are available in zipped form
-<a href=
-"http://www.tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs.tar.gz"
-target="_top">here</a>. Unzip and untar it. The directory structure
-looks like this.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000">ncurses
- |
- |----&gt; JustForFun -- just for fun programs
- |----&gt; basics -- basic programs
- |----&gt; demo -- output files go into this directory after make
- | |
- | |----&gt; exe -- exe files of all example programs
- |----&gt; forms -- programs related to form library
- |----&gt; menus -- programs related to menus library
- |----&gt; panels -- programs related to panels library
- |----&gt; perl -- perl equivalents of the examples (contributed
- | by Anuradha Ratnaweera)
- |----&gt; Makefile -- the top level Makefile
- |----&gt; README -- the top level README file. contains instructions
- |----&gt; COPYING -- copyright notice</font>
-</pre></td>
-</tr>
-</table>
-<p>The individual directories contain the following files.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000">Description of files in each directory
---------------------------------------
-JustForFun
- |
- |----&gt; hanoi.c -- The Towers of Hanoi Solver
- |----&gt; life.c -- The Game of Life demo
- |----&gt; magic.c -- An Odd Order Magic Square builder
- |----&gt; queens.c -- The famous N-Queens Solver
- |----&gt; shuffle.c -- A fun game, if you have time to kill
- |----&gt; tt.c -- A very trivial typing tutor
-
- basics
- |
- |----&gt; acs_vars.c -- ACS_ variables example
- |----&gt; hello_world.c -- Simple "Hello World" Program
- |----&gt; init_func_example.c -- Initialization functions example
- |----&gt; key_code.c -- Shows the scan code of the key pressed
- |----&gt; mouse_menu.c -- A menu accessible by mouse
- |----&gt; other_border.c -- Shows usage of other border functions apa
- | -- rt from box()
- |----&gt; printw_example.c -- A very simple printw() example
- |----&gt; scanw_example.c -- A very simple getstr() example
- |----&gt; simple_attr.c -- A program that can print a c file with
- | -- comments in attribute
- |----&gt; simple_color.c -- A simple example demonstrating colors
- |----&gt; simple_key.c -- A menu accessible with keyboard UP, DOWN
- | -- arrows
- |----&gt; temp_leave.c -- Demonstrates temporarily leaving curses mode
- |----&gt; win_border.c -- Shows Creation of windows and borders
- |----&gt; with_chgat.c -- chgat() usage example
-
- forms
- |
- |----&gt; form_attrib.c -- Usage of field attributes
- |----&gt; form_options.c -- Usage of field options
- |----&gt; form_simple.c -- A simple form example
- |----&gt; form_win.c -- Demo of windows associated with forms
-
- menus
- |
- |----&gt; menu_attrib.c -- Usage of menu attributes
- |----&gt; menu_item_data.c -- Usage of item_name() etc.. functions
- |----&gt; menu_multi_column.c -- Creates multi columnar menus
- |----&gt; menu_scroll.c -- Demonstrates scrolling capability of menus
- |----&gt; menu_simple.c -- A simple menu accessed by arrow keys
- |----&gt; menu_toggle.c -- Creates multi valued menus and explains
- | -- REQ_TOGGLE_ITEM
- |----&gt; menu_userptr.c -- Usage of user pointer
- |----&gt; menu_win.c -- Demo of windows associated with menus
-
- panels
- |
- |----&gt; panel_browse.c -- Panel browsing through tab. Usage of user
- | -- pointer
- |----&gt; panel_hide.c -- Hiding and Un hiding of panels
- |----&gt; panel_resize.c -- Moving and resizing of panels
- |----&gt; panel_simple.c -- A simple panel example
-
- perl
- |----&gt; 01-10.pl -- Perl equivalents of first ten example programs</font>
-</pre></td>
-</tr>
-</table>
-<p>There is a top level Makefile included in the main directory. It
-builds all the files and puts the ready-to-use exes in demo/exe
-directory. You can also do selective make by going into the
-corresponding directory. Each directory contains a README file
-explaining the purpose of each c file in the directory.</p>
-<p>For every example, I have included path name for the file
-relative to the examples directory.</p>
-<p>If you prefer browsing individual programs, point your browser
-to <a href=
-"http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/"
-target=
-"_top">http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/</a></p>
-<p>All the programs are released under the same license that is
-used by ncurses (MIT-style). This gives you the ability to do
-pretty much anything other than claiming them as yours. Feel free
-to use them in your programs as appropriate.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="OTHERFORMATS" id="OTHERFORMATS">1.6.
-Other Formats of the document</a></h3>
-<p>This howto is also availabe in various other formats on the
-tldp.org site. Here are the links to other formats of this
-document.</p>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="LISTFORMATS" id="LISTFORMATS">1.6.1.
-Readily available formats from tldp.org</a></h4>
-<ul>
-<li>
-<p><a href=
-"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/pdf/NCURSES-Programming-HOWTO.pdf"
-target="_top">Acrobat PDF Format</a></p>
-</li>
-<li>
-<p><a href=
-"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/ps/NCURSES-Programming-HOWTO.ps.gz"
-target="_top">PostScript Format</a></p>
-</li>
-<li>
-<p><a href=
-"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html/NCURSES-Programming-HOWTO-html.tar.gz"
-target="_top">In Multiple HTML pages</a></p>
-</li>
-<li>
-<p><a href=
-"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/NCURSES-Programming-HOWTO.html"
-target="_top">In One big HTML format</a></p>
-</li>
-</ul>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="BUILDSOURCE" id="BUILDSOURCE">1.6.2.
-Building from source</a></h4>
-<p>If above links are broken or if you want to experiment with sgml
-read on.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">&#13; Get both the source and the tar,gzipped programs, available at
- http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/
- NCURSES-HOWTO/NCURSES-Programming-HOWTO.sgml
- http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/
- NCURSES-HOWTO/ncurses_programs.tar.gz
-
- Unzip ncurses_programs.tar.gz with
- tar zxvf ncurses_programs.tar.gz
-
- Use jade to create various formats. For example if you just want to create
- the multiple html files, you would use
- jade -t sgml -i html -d &lt;path to docbook html stylesheet&gt;
- NCURSES-Programming-HOWTO.sgml
- to get pdf, first create a single html file of the HOWTO with
- jade -t sgml -i html -d &lt;path to docbook html stylesheet&gt; -V nochunks
- NCURSES-Programming-HOWTO.sgml &gt; NCURSES-ONE-BIG-FILE.html
- then use htmldoc to get pdf file with
- htmldoc --size universal -t pdf --firstpage p1 -f &lt;output file name.pdf&gt;
- NCURSES-ONE-BIG-FILE.html
- for ps, you would use
- htmldoc --size universal -t ps --firstpage p1 -f &lt;output file name.ps&gt;
- NCURSES-ONE-BIG-FILE.html</font>
-</pre></td>
-</tr>
-</table>
-<p>See <a href="http://www.tldp.org/LDP/LDP-Author-Guide/" target=
-"_top">LDP Author guide</a> for more details. If all else failes,
-mail me at <a href="ppadala@gmail.com" target=
-"_top">ppadala@gmail.com</a></p>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="CREDITS" id="CREDITS">1.7.
-Credits</a></h3>
-<p>I thank <a href="mailto:sharath_1@usa.net" target=
-"_top">Sharath</a> and Emre Akbas for helping me with few sections.
-The introduction was initially written by sharath. I rewrote it
-with few excerpts taken from his initial work. Emre helped in
-writing printw and scanw sections.</p>
-<p>Perl equivalents of the example programs are contributed by
-<a href="mailto:Aratnaweera@virtusa.com" target="_top">Anuradha
-Ratnaweera</a>.</p>
-<p>Then comes <a href="mailto:parimi@ece.arizona.edu" target=
-"_top">Ravi Parimi</a>, my dearest friend, who has been on this
-project before even one line was written. He constantly bombarded
-me with suggestions and patiently reviewed the whole text. He also
-checked each program on Linux and Solaris.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="WISHLIST" id="WISHLIST">1.8. Wish
-List</a></h3>
-<p>This is the wish list, in the order of priority. If you have a
-wish or you want to work on completing the wish, mail <a href=
-"mailto:ppadala@gmail.com" target="_top">me</a>.</p>
-<ul>
-<li>
-<p>Add examples to last parts of forms section.</p>
-</li>
-<li>
-<p>Prepare a Demo showing all the programs and allow the user to
-browse through description of each program. Let the user compile
-and see the program in action. A dialog based interface is
-preferred.</p>
-</li>
-<li>
-<p>Add debug info. _tracef, _tracemouse stuff.</p>
-</li>
-<li>
-<p>Accessing termcap, terminfo using functions provided by ncurses
-package.</p>
-</li>
-<li>
-<p>Working on two terminals simultaneously.</p>
-</li>
-<li>
-<p>Add more stuff to miscellaneous section.</p>
-</li>
-</ul>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="COPYRIGHT" id="COPYRIGHT">1.9.
-Copyright</a></h3>
-<p>Copyright &copy; 2001 by Pradeep Padala.</p>
-<p>Permission is hereby granted, free of charge, to any person
-obtaining a copy of this software and associated documentation
-files (the "Software"), to deal in the Software without
-restriction, including without limitation the rights to use, copy,
-modify, merge, publish, distribute, distribute with modifications,
-sublicense, and/or sell copies of the Software, and to permit
-persons to whom the Software is furnished to do so, subject to the
-following conditions:</p>
-<p>The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.</p>
-<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
-ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.</p>
-<p>Except as contained in this notice, the name(s) of the above
-copyright holders shall not be used in advertising or otherwise to
-promote the sale, use or other dealings in this Software without
-prior written authorization.</p>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="HELLOWORLD" id="HELLOWORLD">2. Hello
-World !!!</a></h2>
-<p>Welcome to the world of curses. Before we plunge into the
-library and look into its various features, let's write a simple
-program and say hello to the world.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="COMPILECURSES" id="COMPILECURSES">2.1.
-Compiling With the NCURSES Library</a></h3>
-<p>To use ncurses library functions, you have to include ncurses.h
-in your programs. To link the program with ncurses the flag
--lncurses should be added.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> #include &lt;ncurses.h&gt;
- .
- .
- .
-
- compile and link: gcc &lt;program file&gt; -lncurses</font>
-</pre></td>
-</tr>
-</table>
-<div class="EXAMPLE"><a name="BHW" id="BHW"></a>
-<p><b>Example 1. The Hello World !!! Program</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
-
-int main()
-{
- initscr(); /* Start curses mode */
- printw("Hello World !!!"); /* Print Hello World */
- refresh(); /* Print it on to the real screen */
- getch(); /* Wait for user input */
- endwin(); /* End curses mode */
-
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="DISSECTION" id="DISSECTION">2.2.
-Dissection</a></h3>
-<p>The above program prints "Hello World !!!" to the screen and
-exits. This program shows how to initialize curses and do screen
-manipulation and end curses mode. Let's dissect it line by
-line.</p>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="ABOUT-INITSCR" id="ABOUT-INITSCR">2.2.1.
-About initscr()</a></h4>
-<p>The function initscr() initializes the terminal in curses mode.
-In some implementations, it clears the screen and presents a blank
-screen. To do any screen manipulation using curses package this has
-to be called first. This function initializes the curses system and
-allocates memory for our present window (called <var class=
-"LITERAL">stdscr</var>) and some other data-structures. Under
-extreme cases this function might fail due to insufficient memory
-to allocate memory for curses library's data structures.</p>
-<p>After this is done, we can do a variety of initializations to
-customize our curses settings. These details will be explained
-<a href="#INIT">later</a> .</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="MYST-REFRESH" id="MYST-REFRESH">2.2.2.
-The mysterious refresh()</a></h4>
-<p>The next line printw prints the string "Hello World !!!" on to
-the screen. This function is analogous to normal printf in all
-respects except that it prints the data on a window called stdscr
-at the current (y,x) co-ordinates. Since our present co-ordinates
-are at 0,0 the string is printed at the left hand corner of the
-window.</p>
-<p>This brings us to that mysterious refresh(). Well, when we
-called printw the data is actually written to an imaginary window,
-which is not updated on the screen yet. The job of printw is to
-update a few flags and data structures and write the data to a
-buffer corresponding to stdscr. In order to show it on the screen,
-we need to call refresh() and tell the curses system to dump the
-contents on the screen.</p>
-<p>The philosophy behind all this is to allow the programmer to do
-multiple updates on the imaginary screen or windows and do a
-refresh once all his screen update is done. refresh() checks the
-window and updates only the portion which has been changed. This
-improves performance and offers greater flexibility too. But, it is
-sometimes frustrating to beginners. A common mistake committed by
-beginners is to forget to call refresh() after they did some update
-through printw() class of functions. I still forget to add it
-sometimes :-)</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="ABOUT-ENDWIN" id="ABOUT-ENDWIN">2.2.3.
-About endwin()</a></h4>
-<p>And finally don't forget to end the curses mode. Otherwise your
-terminal might behave strangely after the program quits. endwin()
-frees the memory taken by curses sub-system and its data structures
-and puts the terminal in normal mode. This function must be called
-after you are done with the curses mode.</p>
-</div>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="GORY" id="GORY">3. The Gory
-Details</a></h2>
-<p>Now that we have seen how to write a simple curses program let's
-get into the details. There are many functions that help customize
-what you see on screen and many features which can be put to full
-use.</p>
-<p>Here we go...</p>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="INIT" id="INIT">4.
-Initialization</a></h2>
-<p>We now know that to initialize curses system the function
-initscr() has to be called. There are functions which can be called
-after this initialization to customize our curses session. We may
-ask the curses system to set the terminal in raw mode or initialize
-color or initialize the mouse etc.. Let's discuss some of the
-functions that are normally called immediately after initscr();</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ABOUTINIT" id="ABOUTINIT">4.1.
-Initialization functions</a></h3>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="RAWCBREAK" id="RAWCBREAK">4.2. raw() and
-cbreak()</a></h3>
-<p>Normally the terminal driver buffers the characters a user types
-until a new line or carriage return is encountered. But most
-programs require that the characters be available as soon as the
-user types them. The above two functions are used to disable line
-buffering. The difference between these two functions is in the way
-control characters like suspend (CTRL-Z), interrupt and quit
-(CTRL-C) are passed to the program. In the raw() mode these
-characters are directly passed to the program without generating a
-signal. In the <var class="LITERAL">cbreak()</var> mode these
-control characters are interpreted as any other character by the
-terminal driver. I personally prefer to use raw() as I can exercise
-greater control over what the user does.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ECHONOECHO" id="ECHONOECHO">4.3. echo()
-and noecho()</a></h3>
-<p>These functions control the echoing of characters typed by the
-user to the terminal. <var class="LITERAL">noecho()</var> switches
-off echoing. The reason you might want to do this is to gain more
-control over echoing or to suppress unnecessary echoing while
-taking input from the user through the getch() etc. functions. Most
-of the interactive programs call <var class=
-"LITERAL">noecho()</var> at initialization and do the echoing of
-characters in a controlled manner. It gives the programmer the
-flexibility of echoing characters at any place in the window
-without updating current (y,x) co-ordinates.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="KEYPAD" id="KEYPAD">4.4.
-keypad()</a></h3>
-<p>This is my favorite initialization function. It enables the
-reading of function keys like F1, F2, arrow keys etc. Almost every
-interactive program enables this, as arrow keys are a major part of
-any User Interface. Do <var class="LITERAL">keypad(stdscr,
-TRUE)</var> to enable this feature for the regular screen (stdscr).
-You will learn more about key management in later sections of this
-document.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="HALFDELAY" id="HALFDELAY">4.5.
-halfdelay()</a></h3>
-<p>This function, though not used very often, is a useful one at
-times. halfdelay()is called to enable the half-delay mode, which is
-similar to the cbreak() mode in that characters typed are
-immediately available to program. However, it waits for 'X' tenths
-of a second for input and then returns ERR, if no input is
-available. 'X' is the timeout value passed to the function
-halfdelay(). This function is useful when you want to ask the user
-for input, and if he doesn't respond with in certain time, we can
-do some thing else. One possible example is a timeout at the
-password prompt.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MISCINIT" id="MISCINIT">4.6.
-Miscellaneous Initialization functions</a></h3>
-<p>There are few more functions which are called at initialization
-to customize curses behavior. They are not used as extensively as
-those mentioned above. Some of them are explained where
-appropriate.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="INITEX" id="INITEX">4.7. An
-Example</a></h3>
-<p>Let's write a program which will clarify the usage of these
-functions.</p>
-<div class="EXAMPLE"><a name="BINFU" id="BINFU"></a>
-<p><b>Example 2. Initialization Function Usage example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
-
-int main()
-{ int ch;
-
- initscr(); /* Start curses mode */
- raw(); /* Line buffering disabled */
- keypad(stdscr, TRUE); /* We get F1, F2 etc.. */
- noecho(); /* Don't echo() while we do getch */
-
- printw("Type any character to see it in bold\n");
- ch = getch(); /* If raw() hadn't been called
- * we have to press enter before it
- * gets to the program */
- if(ch == KEY_F(1)) /* Without keypad enabled this will */
- printw("F1 Key pressed");/* not get to us either */
- /* Without noecho() some ugly escape
- * charachters might have been printed
- * on screen */
- else
- { printw("The pressed key is ");
- attron(A_BOLD);
- printw("%c", ch);
- attroff(A_BOLD);
- }
- refresh(); /* Print it on to the real screen */
- getch(); /* Wait for user input */
- endwin(); /* End curses mode */
-
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>This program is self-explanatory. But I used functions which
-aren't explained yet. The function <var class=
-"LITERAL">getch()</var> is used to get a character from user. It is
-equivalent to normal <var class="LITERAL">getchar()</var> except
-that we can disable the line buffering to avoid &lt;enter&gt; after
-input. Look for more about <var class="LITERAL">getch()</var>and
-reading keys in the <a href="#KEYS">key management section</a> .
-The functions attron and attroff are used to switch some attributes
-on and off respectively. In the example I used them to print the
-character in bold. These functions are explained in detail
-later.</p>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="AWORDWINDOWS" id="AWORDWINDOWS">5. A
-Word about Windows</a></h2>
-<p>Before we plunge into the myriad ncurses functions, let me clear
-few things about windows. Windows are explained in detail in
-following <a href="#WINDOWS">sections</a></p>
-<p>A Window is an imaginary screen defined by curses system. A
-window does not mean a bordered window which you usually see on
-Win9X platforms. When curses is initialized, it creates a default
-window named <var class="LITERAL">stdscr</var> which represents
-your 80x25 (or the size of window in which you are running) screen.
-If you are doing simple tasks like printing few strings, reading
-input etc., you can safely use this single window for all of your
-purposes. You can also create windows and call functions which
-explicitly work on the specified window.</p>
-<p>For example, if you call</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> printw("Hi There !!!");
- refresh();</font>
-</pre></td>
-</tr>
-</table>
-<p>It prints the string on stdscr at the present cursor position.
-Similarly the call to refresh(), works on stdscr only.</p>
-<p>Say you have created <a href="#WINDOWS">windows</a> then you
-have to call a function with a 'w' added to the usual function.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> wprintw(win, "Hi There !!!");
- wrefresh(win);</font>
-</pre></td>
-</tr>
-</table>
-<p>As you will see in the rest of the document, naming of functions
-follow the same convention. For each function there usually are
-three more functions.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"> printw(string); /* Print on stdscr at present cursor position */
- mvprintw(y, x, string);/* Move to (y, x) then print string */
- wprintw(win, string); /* Print on window win at present cursor position */
- /* in the window */
- mvwprintw(win, y, x, string); /* Move to (y, x) relative to window */
- /* co-ordinates and then print */</font>
-</pre></td>
-</tr>
-</table>
-<p>Usually the w-less functions are macros which expand to
-corresponding w-function with stdscr as the window parameter.</p>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="PRINTW" id="PRINTW">6. Output
-functions</a></h2>
-<p>I guess you can't wait any more to see some action. Back to our
-odyssey of curses functions. Now that curses is initialized, let's
-interact with world.</p>
-<p>There are three classes of functions which you can use to do
-output on screen.</p>
-<ol type="1">
-<li>
-<p>addch() class: Print single character with attributes</p>
-</li>
-<li>
-<p>printw() class: Print formatted output similar to printf()</p>
-</li>
-<li>
-<p>addstr() class: Print strings</p>
-</li>
-</ol>
-<p>These functions can be used interchangeably and it's a matter of
-style as to which class is used. Let's see each one in detail.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ADDCHCLASS" id="ADDCHCLASS">6.1. addch()
-class of functions</a></h3>
-<p>These functions put a single character into the current cursor
-location and advance the position of the cursor. You can give the
-character to be printed but they usually are used to print a
-character with some attributes. Attributes are explained in detail
-in later <a href="#ATTRIB">sections</a> of the document. If a
-character is associated with an attribute(bold, reverse video
-etc.), when curses prints the character, it is printed in that
-attribute.</p>
-<p>In order to combine a character with some attributes, you have
-two options:</p>
-<ul>
-<li>
-<p>By OR'ing a single character with the desired attribute macros.
-These attribute macros could be found in the header file
-<var class="LITERAL">ncurses.h</var>. For example, you want to
-print a character ch(of type char) bold and underlined, you would
-call addch() as below.</p>
-<table border="0" bgcolor="#E0E0E0" width="90%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> addch(ch | A_BOLD | A_UNDERLINE);</font>
-</pre></td>
-</tr>
-</table>
-</li>
-<li>
-<p>By using functions like <var class=
-"LITERAL">attrset(),attron(),attroff()</var>. These functions are
-explained in the <a href="#ATTRIB">Attributes</a> section. Briefly,
-they manipulate the current attributes of the given window. Once
-set, the character printed in the window are associated with the
-attributes until it is turned off.</p>
-</li>
-</ul>
-<p>Additionally, <var class="LITERAL">curses</var> provides some
-special characters for character-based graphics. You can draw
-tables, horizontal or vertical lines, etc. You can find all
-avaliable characters in the header file <var class=
-"LITERAL">ncurses.h</var>. Try looking for macros beginning with
-<var class="LITERAL">ACS_</var> in this file.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="AEN298" id="AEN298">6.2. mvaddch(),
-waddch() and mvwaddch()</a></h3>
-<p><var class="LITERAL">mvaddch()</var> is used to move the cursor
-to a given point, and then print. Thus, the calls:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"> move(row,col); /* moves the cursor to row<em>th</em> row and col<em>th</em> column */
- addch(ch);</font>
-</pre></td>
-</tr>
-</table>
-can be replaced by
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> mvaddch(row,col,ch);</font>
-</pre></td>
-</tr>
-</table>
-<p><var class="LITERAL">waddch()</var> is similar to <var class=
-"LITERAL">addch()</var>, except that it adds a character into the
-given window. (Note that <var class="LITERAL">addch()</var> adds a
-character into the window <var class="LITERAL">stdscr</var>.)</p>
-<p>In a similar fashion <var class="LITERAL">mvwaddch()</var>
-function is used to add a character into the given window at the
-given coordinates.</p>
-<p>Now, we are familiar with the basic output function <var class=
-"LITERAL">addch()</var>. But, if we want to print a string, it
-would be very annoying to print it character by character.
-Fortunately, <var class="LITERAL">ncurses</var> provides
-<var class="LITERAL">printf</var><em>-like</em> or <var class=
-"LITERAL">puts</var><em>-like</em> functions.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PRINTWCLASS" id="PRINTWCLASS">6.3.
-printw() class of functions</a></h3>
-<p>These functions are similar to <var class=
-"LITERAL">printf()</var> with the added capability of printing at
-any position on the screen.</p>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="PRINTWMVPRINTW" id=
-"PRINTWMVPRINTW">6.3.1. printw() and mvprintw</a></h4>
-<p>These two functions work much like <var class=
-"LITERAL">printf()</var>. <var class="LITERAL">mvprintw()</var> can
-be used to move the cursor to a position and then print. If you
-want to move the cursor first and then print using <var class=
-"LITERAL">printw()</var> function, use <var class=
-"LITERAL">move()</var> first and then use <var class=
-"LITERAL">printw()</var> though I see no point why one should avoid
-using <var class="LITERAL">mvprintw()</var>, you have the
-flexibility to manipulate.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="WPRINTWMVWPRINTW" id=
-"WPRINTWMVWPRINTW">6.3.2. wprintw() and mvwprintw</a></h4>
-<p>These two functions are similar to above two except that they
-print in the corresponding window given as argument.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="VWPRINTW" id="VWPRINTW">6.3.3.
-vwprintw()</a></h4>
-<p>This function is similar to <var class=
-"LITERAL">vprintf()</var>. This can be used when variable number of
-arguments are to be printed.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="SIMPLEPRINTWEX" id=
-"SIMPLEPRINTWEX">6.3.4. A Simple printw example</a></h4>
-<div class="EXAMPLE"><a name="BPREX" id="BPREX"></a>
-<p><b>Example 3. A Simple printw example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt; /* ncurses.h includes stdio.h */
-#include &lt;string.h&gt;
-
-int main()
-{
- char mesg[]="Just a string"; /* message to be appeared on the screen */
- int row,col; /* to store the number of rows and *
- * the number of colums of the screen */
- initscr(); /* start the curses mode */
- getmaxyx(stdscr,row,col); /* get the number of rows and columns */
- mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg);
- /* print the message at the center of the screen */
- mvprintw(row-2,0,"This screen has %d rows and %d columns\n",row,col);
- printw("Try resizing your window(if possible) and then run this program again");
- refresh();
- getch();
- endwin();
-
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Above program demonstrates how easy it is to use <var class=
-"LITERAL">printw</var>. You just feed the coordinates and the
-message to be appeared on the screen, then it does what you
-want.</p>
-<p>The above program introduces us to a new function <var class=
-"LITERAL">getmaxyx()</var>, a macro defined in <var class=
-"LITERAL">ncurses.h</var>. It gives the number of columns and the
-number of rows in a given window. <var class=
-"LITERAL">getmaxyx()</var> does this by updating the variables
-given to it. Since <var class="LITERAL">getmaxyx()</var> is not a
-function we don't pass pointers to it, we just give two integer
-variables.</p>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ADDSTRCLASS" id="ADDSTRCLASS">6.4.
-addstr() class of functions</a></h3>
-<p><var class="LITERAL">addstr()</var> is used to put a character
-string into a given window. This function is similar to calling
-<var class="LITERAL">addch()</var> once for each character in a
-given string. This is true for all output functions. There are
-other functions from this family such as <var class=
-"LITERAL">mvaddstr(),mvwaddstr()</var> and <var class=
-"LITERAL">waddstr()</var>, which obey the naming convention of
-curses.(e.g. mvaddstr() is similar to the respective calls move()
-and then addstr().) Another function of this family is addnstr(),
-which takes an integer parameter(say n) additionally. This function
-puts at most n characters into the screen. If n is negative, then
-the entire string will be added.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ACAUTION" id="ACAUTION">6.5. A word of
-caution</a></h3>
-<p>All these functions take y co-ordinate first and then x in their
-arguments. A common mistake by beginners is to pass x,y in that
-order. If you are doing too many manipulations of (y,x)
-co-ordinates, think of dividing the screen into windows and
-manipulate each one separately. Windows are explained in the
-<a href="#WINDOWS">windows</a> section.</p>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="SCANW" id="SCANW">7. Input
-functions</a></h2>
-<p>Well, printing without taking input, is boring. Let's see
-functions which allow us to get input from user. These functions
-also can be divided into three categories.</p>
-<ol type="1">
-<li>
-<p>getch() class: Get a character</p>
-</li>
-<li>
-<p>scanw() class: Get formatted input</p>
-</li>
-<li>
-<p>getstr() class: Get strings</p>
-</li>
-</ol>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="GETCHCLASS" id="GETCHCLASS">7.1. getch()
-class of functions</a></h3>
-<p>These functions read a single character from the terminal. But
-there are several subtle facts to consider. For example if you
-don't use the function cbreak(), curses will not read your input
-characters contiguously but will begin read them only after a new
-line or an EOF is encountered. In order to avoid this, the cbreak()
-function must used so that characters are immediately available to
-your program. Another widely used function is noecho(). As the name
-suggests, when this function is set (used), the characters that are
-keyed in by the user will not show up on the screen. The two
-functions cbreak() and noecho() are typical examples of key
-management. Functions of this genre are explained in the <a href=
-"#KEYS">key management section</a> .</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="SCANWCLASS" id="SCANWCLASS">7.2. scanw()
-class of functions</a></h3>
-<p>These functions are similar to <var class=
-"LITERAL">scanf()</var> with the added capability of getting the
-input from any location on the screen.</p>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="SCANWMVSCANW" id="SCANWMVSCANW">7.2.1.
-scanw() and mvscanw</a></h4>
-<p>The usage of these functions is similar to that of <var class=
-"LITERAL">sscanf()</var>, where the line to be scanned is provided
-by <var class="LITERAL">wgetstr()</var> function. That is, these
-functions call to <var class="LITERAL">wgetstr()</var>
-function(explained below) and uses the resulting line for a
-scan.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="WSCANWMVWSCANW" id=
-"WSCANWMVWSCANW">7.2.2. wscanw() and mvwscanw()</a></h4>
-<p>These are similar to above two functions except that they read
-from a window, which is supplied as one of the arguments to these
-functions.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="VWSCANW" id="VWSCANW">7.2.3.
-vwscanw()</a></h4>
-<p>This function is similar to <var class="LITERAL">vscanf()</var>.
-This can be used when a variable number of arguments are to be
-scanned.</p>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="GETSTRCLASS" id="GETSTRCLASS">7.3.
-getstr() class of functions</a></h3>
-<p>These functions are used to get strings from the terminal. In
-essence, this function performs the same task as would be achieved
-by a series of calls to <var class="LITERAL">getch()</var> until a
-newline, carriage return, or end-of-file is received. The resulting
-string of characters are pointed to by <var class=
-"LITERAL">str</var>, which is a character pointer provided by the
-user.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="GETSTREX" id="GETSTREX">7.4. Some
-examples</a></h3>
-<div class="EXAMPLE"><a name="BSCEX" id="BSCEX"></a>
-<p><b>Example 4. A Simple scanw example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt; /* ncurses.h includes stdio.h */
-#include &lt;string.h&gt;
-
-int main()
-{
- char mesg[]="Enter a string: "; /* message to be appeared on the screen */
- char str[80];
- int row,col; /* to store the number of rows and *
- * the number of colums of the screen */
- initscr(); /* start the curses mode */
- getmaxyx(stdscr,row,col); /* get the number of rows and columns */
- mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg);
- /* print the message at the center of the screen */
- getstr(str);
- mvprintw(LINES - 2, 0, "You Entered: %s", str);
- getch();
- endwin();
-
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="ATTRIB" id="ATTRIB">8.
-Attributes</a></h2>
-<p>We have seen an example of how attributes can be used to print
-characters with some special effects. Attributes, when set
-prudently, can present information in an easy, understandable
-manner. The following program takes a C file as input and prints
-the file with comments in bold. Scan through the code.</p>
-<div class="EXAMPLE"><a name="BSIAT" id="BSIAT"></a>
-<p><b>Example 5. A Simple Attributes example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">/* pager functionality by Joseph Spainhour" &lt;spainhou@bellsouth.net&gt; */
-#include &lt;ncurses.h&gt;
-#include &lt;stdlib.h&gt;
-
-int main(int argc, char *argv[])
-{
- int ch, prev, row, col;
- prev = EOF;
- FILE *fp;
- int y, x;
-
- if(argc != 2)
- {
- printf("Usage: %s &lt;a c file name&gt;\n", argv[0]);
- exit(1);
- }
- fp = fopen(argv[1], "r");
- if(fp == NULL)
- {
- perror("Cannot open input file");
- exit(1);
- }
- initscr(); /* Start curses mode */
- getmaxyx(stdscr, row, col); /* find the boundaries of the screeen */
- while((ch = fgetc(fp)) != EOF) /* read the file till we reach the end */
- {
- getyx(stdscr, y, x); /* get the current curser position */
- if(y == (row - 1)) /* are we are at the end of the screen */
- {
- printw("&lt;-Press Any Key-&gt;"); /* tell the user to press a key */
- getch();
- clear(); /* clear the screen */
- move(0, 0); /* start at the beginning of the screen */
- }
- if(prev == '/' &amp;&amp; ch == '*') /* If it is / and * then only
- * switch bold on */
- {
- attron(A_BOLD); /* cut bold on */
- getyx(stdscr, y, x); /* get the current curser position */
- move(y, x - 1); /* back up one space */
- printw("%c%c", '/', ch); /* The actual printing is done here */
- }
- else
- printw("%c", ch);
- refresh();
- if(prev == '*' &amp;&amp; ch == '/')
- attroff(A_BOLD); /* Switch it off once we got *
- * and then / */
- prev = ch;
- }
- endwin(); /* End curses mode */
- fclose(fp);
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Don't worry about all those initialization and other crap.
-Concentrate on the while loop. It reads each character in the file
-and searches for the pattern /*. Once it spots the pattern, it
-switches the BOLD attribute on with <var class=
-"LITERAL">attron()</var> . When we get the pattern */ it is
-switched off by <var class="LITERAL">attroff()</var> .</p>
-<p>The above program also introduces us to two useful functions
-<var class="LITERAL">getyx()</var> and <var class=
-"LITERAL">move()</var>. The first function gets the co-ordinates of
-the present cursor into the variables y, x. Since getyx() is a
-macro we don't have to pass pointers to variables. The function
-<var class="LITERAL">move()</var> moves the cursor to the
-co-ordinates given to it.</p>
-<p>The above program is really a simple one which doesn't do much.
-On these lines one could write a more useful program which reads a
-C file, parses it and prints it in different colors. One could even
-extend it to other languages as well.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ATTRIBDETAILS" id="ATTRIBDETAILS">8.1.
-The details</a></h3>
-<p>Let's get into more details of attributes. The functions
-<var class="LITERAL">attron(), attroff(), attrset()</var> , and
-their sister functions <var class="LITERAL">attr_get()</var> etc..
-can be used to switch attributes on/off , get attributes and
-produce a colorful display.</p>
-<p>The functions attron and attroff take a bit-mask of attributes
-and switch them on or off, respectively. The following video
-attributes, which are defined in &lt;curses.h&gt; can be passed to
-these functions.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000">
- A_NORMAL Normal display (no highlight)
- A_STANDOUT Best highlighting mode of the terminal.
- A_UNDERLINE Underlining
- A_REVERSE Reverse video
- A_BLINK Blinking
- A_DIM Half bright
- A_BOLD Extra bright or bold
- A_PROTECT Protected mode
- A_INVIS Invisible or blank mode
- A_ALTCHARSET Alternate character set
- A_CHARTEXT Bit-mask to extract a character
- COLOR_PAIR(n) Color-pair number n
- </font>
-</pre></td>
-</tr>
-</table>
-<p>The last one is the most colorful one :-) Colors are explained
-in the <a href="#color" target="_top">next sections</a>.</p>
-<p>We can OR(|) any number of above attributes to get a combined
-effect. If you wanted reverse video with blinking characters you
-can use</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> attron(A_REVERSE | A_BLINK);</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ATTRONVSATTRSET" id=
-"ATTRONVSATTRSET">8.2. attron() vs attrset()</a></h3>
-<p>Then what is the difference between attron() and attrset()?
-attrset sets the attributes of window whereas attron just switches
-on the attribute given to it. So attrset() fully overrides whatever
-attributes the window previously had and sets it to the new
-attribute(s). Similarly attroff() just switches off the
-attribute(s) given to it as an argument. This gives us the
-flexibility of managing attributes easily.But if you use them
-carelessly you may loose track of what attributes the window has
-and garble the display. This is especially true while managing
-menus with colors and highlighting. So decide on a consistent
-policy and stick to it. You can always use <var class=
-"LITERAL">standend()</var> which is equivalent to <var class=
-"LITERAL">attrset(A_NORMAL)</var> which turns off all attributes
-and brings you to normal mode.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ATTR_GET" id="ATTR_GET">8.3.
-attr_get()</a></h3>
-<p>The function attr_get() gets the current attributes and color
-pair of the window. Though we might not use this as often as the
-above functions, this is useful in scanning areas of screen. Say we
-wanted to do some complex update on screen and we are not sure what
-attribute each character is associated with. Then this function can
-be used with either attrset or attron to produce the desired
-effect.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ATTR_FUNCS" id="ATTR_FUNCS">8.4. attr_
-functions</a></h3>
-<p>There are series of functions like attr_set(), attr_on etc..
-These are similar to above functions except that they take
-parameters of type <var class="LITERAL">attr_t</var>.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="WATTRFUNCS" id="WATTRFUNCS">8.5. wattr
-functions</a></h3>
-<p>For each of the above functions we have a corresponding function
-with 'w' which operates on a particular window. The above functions
-operate on stdscr.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="CHGAT" id="CHGAT">8.6. chgat()
-functions</a></h3>
-<p>The function chgat() is listed in the end of the man page
-curs_attr. It actually is a useful one. This function can be used
-to set attributes for a group of characters without moving. I mean
-it !!! without moving the cursor :-) It changes the attributes of a
-given number of characters starting at the current cursor
-location.</p>
-<p>We can give -1 as the character count to update till end of
-line. If you want to change attributes of characters from current
-position to end of line, just use this.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> chgat(-1, A_REVERSE, 0, NULL);</font>
-</pre></td>
-</tr>
-</table>
-<p>This function is useful when changing attributes for characters
-that are already on the screen. Move to the character from which
-you want to change and change the attribute.</p>
-<p>Other functions wchgat(), mvchgat(), wchgat() behave similarly
-except that the w functions operate on the particular window. The
-mv functions first move the cursor then perform the work given to
-them. Actually chgat is a macro which is replaced by a wchgat()
-with stdscr as the window. Most of the "w-less" functions are
-macros.</p>
-<div class="EXAMPLE"><a name="BWICH" id="BWICH"></a>
-<p><b>Example 6. Chgat() Usage example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
-
-int main(int argc, char *argv[])
-{ initscr(); /* Start curses mode */
- start_color(); /* Start color functionality */
-
- init_pair(1, COLOR_CYAN, COLOR_BLACK);
- printw("A Big string which i didn't care to type fully ");
- mvchgat(0, 0, -1, A_BLINK, 1, NULL);
- /*
- * First two parameters specify the position at which to start
- * Third parameter number of characters to update. -1 means till
- * end of line
- * Forth parameter is the normal attribute you wanted to give
- * to the charcter
- * Fifth is the color index. It is the index given during init_pair()
- * use 0 if you didn't want color
- * Sixth one is always NULL
- */
- refresh();
- getch();
- endwin(); /* End curses mode */
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>This example also introduces us to the color world of curses.
-Colors will be explained in detail later. Use 0 for no color.</p>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="WINDOWS" id="WINDOWS">9.
-Windows</a></h2>
-<p>Windows form the most important concept in curses. You have seen
-the standard window stdscr above where all the functions implicitly
-operated on this window. Now to make design even a simplest GUI,
-you need to resort to windows. The main reason you may want to use
-windows is to manipulate parts of the screen separately, for better
-efficiency, by updating only the windows that need to be changed
-and for a better design. I would say the last reason is the most
-important in going for windows. You should always strive for a
-better and easy-to-manage design in your programs. If you are
-writing big, complex GUIs this is of pivotal importance before you
-start doing anything.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="WINDOWBASICS" id="WINDOWBASICS">9.1. The
-basics</a></h3>
-<p>A Window can be created by calling the function <var class=
-"LITERAL">newwin()</var>. It doesn't create any thing on the screen
-actually. It allocates memory for a structure to manipulate the
-window and updates the structure with data regarding the window
-like it's size, beginy, beginx etc.. Hence in curses, a window is
-just an abstraction of an imaginary window, which can be
-manipulated independent of other parts of screen. The function
-newwin() returns a pointer to structure WINDOW, which can be passed
-to window related functions like wprintw() etc.. Finally the window
-can be destroyed with delwin(). It will deallocate the memory
-associated with the window structure.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="LETBEWINDOW" id="LETBEWINDOW">9.2. Let
-there be a Window !!!</a></h3>
-<p>What fun is it, if a window is created and we can't see it. So
-the fun part begins by displaying the window. The function
-<var class="LITERAL">box()</var> can be used to draw a border
-around the window. Let's explore these functions in more detail in
-this example.</p>
-<div class="EXAMPLE"><a name="BWIBO" id="BWIBO"></a>
-<p><b>Example 7. Window Border example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
-
-
-WINDOW *create_newwin(int height, int width, int starty, int startx);
-void destroy_win(WINDOW *local_win);
-
-int main(int argc, char *argv[])
-{ WINDOW *my_win;
- int startx, starty, width, height;
- int ch;
-
- initscr(); /* Start curses mode */
- cbreak(); /* Line buffering disabled, Pass on
- * everty thing to me */
- keypad(stdscr, TRUE); /* I need that nifty F1 */
-
- height = 3;
- width = 10;
- starty = (LINES - height) / 2; /* Calculating for a center placement */
- startx = (COLS - width) / 2; /* of the window */
- printw("Press F1 to exit");
- refresh();
- my_win = create_newwin(height, width, starty, startx);
-
- while((ch = getch()) != KEY_F(1))
- { switch(ch)
- { case KEY_LEFT:
- destroy_win(my_win);
- my_win = create_newwin(height, width, starty,--startx);
- break;
- case KEY_RIGHT:
- destroy_win(my_win);
- my_win = create_newwin(height, width, starty,++startx);
- break;
- case KEY_UP:
- destroy_win(my_win);
- my_win = create_newwin(height, width, --starty,startx);
- break;
- case KEY_DOWN:
- destroy_win(my_win);
- my_win = create_newwin(height, width, ++starty,startx);
- break;
- }
- }
-
- endwin(); /* End curses mode */
- return 0;
-}
-
-WINDOW *create_newwin(int height, int width, int starty, int startx)
-{ WINDOW *local_win;
-
- local_win = newwin(height, width, starty, startx);
- box(local_win, 0 , 0); /* 0, 0 gives default characters
- * for the vertical and horizontal
- * lines */
- wrefresh(local_win); /* Show that box */
-
- return local_win;
-}
-
-void destroy_win(WINDOW *local_win)
-{
- /* box(local_win, ' ', ' '); : This won't produce the desired
- * result of erasing the window. It will leave it's four corners
- * and so an ugly remnant of window.
- */
- wborder(local_win, ' ', ' ', ' ',' ',' ',' ',' ',' ');
- /* The parameters taken are
- * 1. win: the window on which to operate
- * 2. ls: character to be used for the left side of the window
- * 3. rs: character to be used for the right side of the window
- * 4. ts: character to be used for the top side of the window
- * 5. bs: character to be used for the bottom side of the window
- * 6. tl: character to be used for the top left corner of the window
- * 7. tr: character to be used for the top right corner of the window
- * 8. bl: character to be used for the bottom left corner of the window
- * 9. br: character to be used for the bottom right corner of the window
- */
- wrefresh(local_win);
- delwin(local_win);
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="BORDEREXEXPL" id="BORDEREXEXPL">9.3.
-Explanation</a></h3>
-<p>Don't scream. I know it's a big example. But I have to explain
-some important things here :-). This program creates a rectangular
-window that can be moved with left, right, up, down arrow keys. It
-repeatedly creates and destroys windows as user press a key. Don't
-go beyond the screen limits. Checking for those limits is left as
-an exercise for the reader. Let's dissect it by line by line.</p>
-<p>The <var class="LITERAL">create_newwin()</var> function creates
-a window with <var class="LITERAL">newwin()</var> and displays a
-border around it with box. The function <var class=
-"LITERAL">destroy_win()</var> first erases the window from screen
-by painting a border with ' ' character and then calling
-<var class="LITERAL">delwin()</var> to deallocate memory related to
-it. Depending on the key the user presses, starty or startx is
-changed and a new window is created.</p>
-<p>In the destroy_win, as you can see, I used wborder instead of
-box. The reason is written in the comments (You missed it. I know.
-Read the code :-)). wborder draws a border around the window with
-the characters given to it as the 4 corner points and the 4 lines.
-To put it clearly, if you have called wborder as below:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"> wborder(win, '|', '|', '-', '-', '+', '+', '+', '+');</font>
-</pre></td>
-</tr>
-</table>
-<p>it produces some thing like</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> +------------+
- | |
- | |
- | |
- | |
- | |
- | |
- +------------+</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="OTHERSTUFF" id="OTHERSTUFF">9.4. The
-other stuff in the example</a></h3>
-<p>You can also see in the above examples, that I have used the
-variables COLS, LINES which are initialized to the screen sizes
-after initscr(). They can be useful in finding screen dimensions
-and finding the center co-ordinate of the screen as above. The
-function <var class="LITERAL">getch()</var> as usual gets the key
-from keyboard and according to the key it does the corresponding
-work. This type of switch- case is very common in any GUI based
-programs.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="OTHERBORDERFUNCS" id=
-"OTHERBORDERFUNCS">9.5. Other Border functions</a></h3>
-<p>Above program is grossly inefficient in that with each press of
-a key, a window is destroyed and another is created. So let's write
-a more efficient program which uses other border related
-functions.</p>
-<p>The following program uses <var class="LITERAL">mvhline()</var>
-and <var class="LITERAL">mvvline()</var> to achieve similar effect.
-These two functions are simple. They create a horizontal or
-vertical line of the specified length at the specified
-position.</p>
-<div class="EXAMPLE"><a name="BOTBO" id="BOTBO"></a>
-<p><b>Example 8. More border functions</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
-
-typedef struct _win_border_struct {
- chtype ls, rs, ts, bs,
- tl, tr, bl, br;
-}WIN_BORDER;
-
-typedef struct _WIN_struct {
-
- int startx, starty;
- int height, width;
- WIN_BORDER border;
-}WIN;
-
-void init_win_params(WIN *p_win);
-void print_win_params(WIN *p_win);
-void create_box(WIN *win, bool flag);
-
-int main(int argc, char *argv[])
-{ WIN win;
- int ch;
-
- initscr(); /* Start curses mode */
- start_color(); /* Start the color functionality */
- cbreak(); /* Line buffering disabled, Pass on
- * everty thing to me */
- keypad(stdscr, TRUE); /* I need that nifty F1 */
- noecho();
- init_pair(1, COLOR_CYAN, COLOR_BLACK);
-
- /* Initialize the window parameters */
- init_win_params(&amp;win);
- print_win_params(&amp;win);
-
- attron(COLOR_PAIR(1));
- printw("Press F1 to exit");
- refresh();
- attroff(COLOR_PAIR(1));
-
- create_box(&amp;win, TRUE);
- while((ch = getch()) != KEY_F(1))
- { switch(ch)
- { case KEY_LEFT:
- create_box(&amp;win, FALSE);
- --win.startx;
- create_box(&amp;win, TRUE);
- break;
- case KEY_RIGHT:
- create_box(&amp;win, FALSE);
- ++win.startx;
- create_box(&amp;win, TRUE);
- break;
- case KEY_UP:
- create_box(&amp;win, FALSE);
- --win.starty;
- create_box(&amp;win, TRUE);
- break;
- case KEY_DOWN:
- create_box(&amp;win, FALSE);
- ++win.starty;
- create_box(&amp;win, TRUE);
- break;
- }
- }
- endwin(); /* End curses mode */
- return 0;
-}
-void init_win_params(WIN *p_win)
-{
- p_win-&gt;height = 3;
- p_win-&gt;width = 10;
- p_win-&gt;starty = (LINES - p_win-&gt;height)/2;
- p_win-&gt;startx = (COLS - p_win-&gt;width)/2;
-
- p_win-&gt;border.ls = '|';
- p_win-&gt;border.rs = '|';
- p_win-&gt;border.ts = '-';
- p_win-&gt;border.bs = '-';
- p_win-&gt;border.tl = '+';
- p_win-&gt;border.tr = '+';
- p_win-&gt;border.bl = '+';
- p_win-&gt;border.br = '+';
-
-}
-void print_win_params(WIN *p_win)
-{
-#ifdef _DEBUG
- mvprintw(25, 0, "%d %d %d %d", p_win-&gt;startx, p_win-&gt;starty,
- p_win-&gt;width, p_win-&gt;height);
- refresh();
-#endif
-}
-void create_box(WIN *p_win, bool flag)
-{ int i, j;
- int x, y, w, h;
-
- x = p_win-&gt;startx;
- y = p_win-&gt;starty;
- w = p_win-&gt;width;
- h = p_win-&gt;height;
-
- if(flag == TRUE)
- { mvaddch(y, x, p_win-&gt;border.tl);
- mvaddch(y, x + w, p_win-&gt;border.tr);
- mvaddch(y + h, x, p_win-&gt;border.bl);
- mvaddch(y + h, x + w, p_win-&gt;border.br);
- mvhline(y, x + 1, p_win-&gt;border.ts, w - 1);
- mvhline(y + h, x + 1, p_win-&gt;border.bs, w - 1);
- mvvline(y + 1, x, p_win-&gt;border.ls, h - 1);
- mvvline(y + 1, x + w, p_win-&gt;border.rs, h - 1);
-
- }
- else
- for(j = y; j &lt;= y + h; ++j)
- for(i = x; i &lt;= x + w; ++i)
- mvaddch(j, i, ' ');
-
- refresh();
-
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="COLOR" id="COLOR">10. Colors</a></h2>
-<div class="SECT2">
-<h3 class="SECT2"><a name="COLORBASICS" id="COLORBASICS">10.1. The
-basics</a></h3>
-<p>Life seems dull with no colors. Curses has a nice mechanism to
-handle colors. Let's get into the thick of the things with a small
-program.</p>
-<div class="EXAMPLE"><a name="BSICO" id="BSICO"></a>
-<p><b>Example 9. A Simple Color example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
-
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string);
-int main(int argc, char *argv[])
-{ initscr(); /* Start curses mode */
- if(has_colors() == FALSE)
- { endwin();
- printf("Your terminal does not support color\n");
- exit(1);
- }
- start_color(); /* Start color */
- init_pair(1, COLOR_RED, COLOR_BLACK);
-
- attron(COLOR_PAIR(1));
- print_in_middle(stdscr, LINES / 2, 0, 0, "Viola !!! In color ...");
- attroff(COLOR_PAIR(1));
- getch();
- endwin();
-}
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string)
-{ int length, x, y;
- float temp;
-
- if(win == NULL)
- win = stdscr;
- getyx(win, y, x);
- if(startx != 0)
- x = startx;
- if(starty != 0)
- y = starty;
- if(width == 0)
- width = 80;
-
- length = strlen(string);
- temp = (width - length)/ 2;
- x = startx + (int)temp;
- mvwprintw(win, y, x, "%s", string);
- refresh();
-}
-</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>As you can see, to start using color, you should first call the
-function <var class="LITERAL">start_color()</var>. After that, you
-can use color capabilities of your terminals using various
-functions. To find out whether a terminal has color capabilities or
-not, you can use <var class="LITERAL">has_colors()</var> function,
-which returns FALSE if the terminal does not support color.</p>
-<p>Curses initializes all the colors supported by terminal when
-start_color() is called. These can be accessed by the define
-constants like <var class="LITERAL">COLOR_BLACK</var> etc. Now to
-actually start using colors, you have to define pairs. Colors are
-always used in pairs. That means you have to use the function
-<var class="LITERAL">init_pair()</var> to define the foreground and
-background for the pair number you give. After that that pair
-number can be used as a normal attribute with <var class=
-"LITERAL">COLOR_PAIR()</var>function. This may seem to be
-cumbersome at first. But this elegant solution allows us to manage
-color pairs very easily. To appreciate it, you have to look into
-the the source code of "dialog", a utility for displaying dialog
-boxes from shell scripts. The developers have defined foreground
-and background combinations for all the colors they might need and
-initialized at the beginning. This makes it very easy to set
-attributes just by accessing a pair which we already have defined
-as a constant.</p>
-<p>The following colors are defined in <var class=
-"LITERAL">curses.h</var>. You can use these as parameters for
-various color functions.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> COLOR_BLACK 0
- COLOR_RED 1
- COLOR_GREEN 2
- COLOR_YELLOW 3
- COLOR_BLUE 4
- COLOR_MAGENTA 5
- COLOR_CYAN 6
- COLOR_WHITE 7</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="CHANGECOLORDEFS" id=
-"CHANGECOLORDEFS">10.2. Changing Color Definitions</a></h3>
-<p>The function <var class="LITERAL">init_color()</var>can be used
-to change the rgb values for the colors defined by curses
-initially. Say you wanted to lighten the intensity of red color by
-a minuscule. Then you can use this function as</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> init_color(COLOR_RED, 700, 0, 0);
- /* param 1 : color name
- * param 2, 3, 4 : rgb content min = 0, max = 1000 */</font>
-</pre></td>
-</tr>
-</table>
-<p>If your terminal cannot change the color definitions, the
-function returns ERR. The function <var class=
-"LITERAL">can_change_color()</var> can be used to find out whether
-the terminal has the capability of changing color content or not.
-The rgb content is scaled from 0 to 1000. Initially RED color is
-defined with content 1000(r), 0(g), 0(b).</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="COLORCONTENT" id="COLORCONTENT">10.3.
-Color Content</a></h3>
-<p>The functions <var class="LITERAL">color_content()</var> and
-<var class="LITERAL">pair_content()</var> can be used to find the
-color content and foreground, background combination for the
-pair.</p>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="KEYS" id="KEYS">11. Interfacing with the
-key board</a></h2>
-<div class="SECT2">
-<h3 class="SECT2"><a name="KEYSBASICS" id="KEYSBASICS">11.1. The
-Basics</a></h3>
-<p>No GUI is complete without a strong user interface and to
-interact with the user, a curses program should be sensitive to key
-presses or the mouse actions done by the user. Let's deal with the
-keys first.</p>
-<p>As you have seen in almost all of the above examples, it's very
-easy to get key input from the user. A simple way of getting key
-presses is to use <var class="LITERAL">getch()</var> function. The
-cbreak mode should be enabled to read keys when you are interested
-in reading individual key hits rather than complete lines of text
-(which usually end with a carriage return). keypad should be
-enabled to get the Functions keys, arrow keys etc. See the
-initialization section for details.</p>
-<p><var class="LITERAL">getch()</var> returns an integer
-corresponding to the key pressed. If it is a normal character, the
-integer value will be equivalent to the character. Otherwise it
-returns a number which can be matched with the constants defined in
-<var class="LITERAL">curses.h</var>. For example if the user
-presses F1, the integer returned is 265. This can be checked using
-the macro KEY_F() defined in curses.h. This makes reading keys
-portable and easy to manage.</p>
-<p>For example, if you call getch() like this</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> int ch;
-
- ch = getch();</font>
-</pre></td>
-</tr>
-</table>
-<p>getch() will wait for the user to press a key, (unless you
-specified a timeout) and when user presses a key, the corresponding
-integer is returned. Then you can check the value returned with the
-constants defined in curses.h to match against the keys you
-want.</p>
-<p>The following code piece will do that job.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> if(ch == KEY_LEFT)
- printw("Left arrow is pressed\n");</font>
-</pre></td>
-</tr>
-</table>
-<p>Let's write a small program which creates a menu which can be
-navigated by up and down arrows.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="SIMPLEKEYEX" id="SIMPLEKEYEX">11.2. A
-Simple Key Usage example</a></h3>
-<div class="EXAMPLE"><a name="BSIKE" id="BSIKE"></a>
-<p><b>Example 10. A Simple Key Usage example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;stdio.h&gt;
-#include &lt;ncurses.h&gt;
-
-#define WIDTH 30
-#define HEIGHT 10
-
-int startx = 0;
-int starty = 0;
-
-char *choices[] = {
- "Choice 1",
- "Choice 2",
- "Choice 3",
- "Choice 4",
- "Exit",
- };
-int n_choices = sizeof(choices) / sizeof(char *);
-void print_menu(WINDOW *menu_win, int highlight);
-
-int main()
-{ WINDOW *menu_win;
- int highlight = 1;
- int choice = 0;
- int c;
-
- initscr();
- clear();
- noecho();
- cbreak(); /* Line buffering disabled. pass on everything */
- startx = (80 - WIDTH) / 2;
- starty = (24 - HEIGHT) / 2;
-
- menu_win = newwin(HEIGHT, WIDTH, starty, startx);
- keypad(menu_win, TRUE);
- mvprintw(0, 0, "Use arrow keys to go up and down, Press enter to select a choice");
- refresh();
- print_menu(menu_win, highlight);
- while(1)
- { c = wgetch(menu_win);
- switch(c)
- { case KEY_UP:
- if(highlight == 1)
- highlight = n_choices;
- else
- --highlight;
- break;
- case KEY_DOWN:
- if(highlight == n_choices)
- highlight = 1;
- else
- ++highlight;
- break;
- case 10:
- choice = highlight;
- break;
- default:
- mvprintw(24, 0, "Charcter pressed is = %3d Hopefully it can be printed as '%c'", c, c);
- refresh();
- break;
- }
- print_menu(menu_win, highlight);
- if(choice != 0) /* User did a choice come out of the infinite loop */
- break;
- }
- mvprintw(23, 0, "You chose choice %d with choice string %s\n", choice, choices[choice - 1]);
- clrtoeol();
- refresh();
- endwin();
- return 0;
-}
-
-
-void print_menu(WINDOW *menu_win, int highlight)
-{
- int x, y, i;
-
- x = 2;
- y = 2;
- box(menu_win, 0, 0);
- for(i = 0; i &lt; n_choices; ++i)
- { if(highlight == i + 1) /* High light the present choice */
- { wattron(menu_win, A_REVERSE);
- mvwprintw(menu_win, y, x, "%s", choices[i]);
- wattroff(menu_win, A_REVERSE);
- }
- else
- mvwprintw(menu_win, y, x, "%s", choices[i]);
- ++y;
- }
- wrefresh(menu_win);
-}
-</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="MOUSE" id="MOUSE">12. Interfacing with
-the mouse</a></h2>
-<p>Now that you have seen how to get keys, lets do the same thing
-from mouse. Usually each UI allows the user to interact with both
-keyboard and mouse.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MOUSEBASICS" id="MOUSEBASICS">12.1. The
-Basics</a></h3>
-<p>Before you do any thing else, the events you want to receive
-have to be enabled with <var class="LITERAL">mousemask()</var>.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"> mousemask( mmask_t newmask, /* The events you want to listen to */
- mmask_t *oldmask) /* The old events mask */</font>
-</pre></td>
-</tr>
-</table>
-<p>The first parameter to above function is a bit mask of events
-you would like to listen. By default, all the events are turned
-off. The bit mask <var class="LITERAL">ALL_MOUSE_EVENTS</var> can
-be used to get all the events.</p>
-<p>The following are all the event masks:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> Name Description
- ---------------------------------------------------------------------
- BUTTON1_PRESSED mouse button 1 down
- BUTTON1_RELEASED mouse button 1 up
- BUTTON1_CLICKED mouse button 1 clicked
- BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked
- BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked
- BUTTON2_PRESSED mouse button 2 down
- BUTTON2_RELEASED mouse button 2 up
- BUTTON2_CLICKED mouse button 2 clicked
- BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked
- BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked
- BUTTON3_PRESSED mouse button 3 down
- BUTTON3_RELEASED mouse button 3 up
- BUTTON3_CLICKED mouse button 3 clicked
- BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked
- BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked
- BUTTON4_PRESSED mouse button 4 down
- BUTTON4_RELEASED mouse button 4 up
- BUTTON4_CLICKED mouse button 4 clicked
- BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked
- BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked
- BUTTON_SHIFT shift was down during button state change
- BUTTON_CTRL control was down during button state change
- BUTTON_ALT alt was down during button state change
- ALL_MOUSE_EVENTS report all button state changes
- REPORT_MOUSE_POSITION report mouse movement</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="GETTINGEVENTS" id="GETTINGEVENTS">12.2.
-Getting the events</a></h3>
-<p>Once a class of mouse events have been enabled, getch() class of
-functions return KEY_MOUSE every time some mouse event happens.
-Then the mouse event can be retrieved with <var class=
-"LITERAL">getmouse()</var>.</p>
-<p>The code approximately looks like this:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> MEVENT event;
-
- ch = getch();
- if(ch == KEY_MOUSE)
- if(getmouse(&amp;event) == OK)
- . /* Do some thing with the event */
- .
- .</font>
-</pre></td>
-</tr>
-</table>
-<p>getmouse() returns the event into the pointer given to it. It's
-a structure which contains</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> typedef struct
- {
- short id; /* ID to distinguish multiple devices */
- int x, y, z; /* event coordinates */
- mmask_t bstate; /* button state bits */
- } </font>
-</pre></td>
-</tr>
-</table>
-<p>The <var class="LITERAL">bstate</var> is the main variable we
-are interested in. It tells the button state of the mouse.</p>
-<p>Then with a code snippet like the following, we can find out
-what happened.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> if(event.bstate &amp; BUTTON1_PRESSED)
- printw("Left Button Pressed");</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MOUSETOGETHER" id="MOUSETOGETHER">12.3.
-Putting it all Together</a></h3>
-<p>That's pretty much interfacing with mouse. Let's create the same
-menu and enable mouse interaction. To make things simpler, key
-handling is removed.</p>
-<div class="EXAMPLE"><a name="BMOME" id="BMOME"></a>
-<p><b>Example 11. Access the menu with mouse !!!</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
-
-#define WIDTH 30
-#define HEIGHT 10
-
-int startx = 0;
-int starty = 0;
-
-char *choices[] = { "Choice 1",
- "Choice 2",
- "Choice 3",
- "Choice 4",
- "Exit",
- };
-
-int n_choices = sizeof(choices) / sizeof(char *);
-
-void print_menu(WINDOW *menu_win, int highlight);
-void report_choice(int mouse_x, int mouse_y, int *p_choice);
-
-int main()
-{ int c, choice = 0;
- WINDOW *menu_win;
- MEVENT event;
-
- /* Initialize curses */
- initscr();
- clear();
- noecho();
- cbreak(); //Line buffering disabled. pass on everything
-
- /* Try to put the window in the middle of screen */
- startx = (80 - WIDTH) / 2;
- starty = (24 - HEIGHT) / 2;
-
- attron(A_REVERSE);
- mvprintw(23, 1, "Click on Exit to quit (Works best in a virtual console)");
- refresh();
- attroff(A_REVERSE);
-
- /* Print the menu for the first time */
- menu_win = newwin(HEIGHT, WIDTH, starty, startx);
- print_menu(menu_win, 1);
- /* Get all the mouse events */
- mousemask(ALL_MOUSE_EVENTS, NULL);
-
- while(1)
- { c = wgetch(menu_win);
- switch(c)
- { case KEY_MOUSE:
- if(getmouse(&amp;event) == OK)
- { /* When the user clicks left mouse button */
- if(event.bstate &amp; BUTTON1_PRESSED)
- { report_choice(event.x + 1, event.y + 1, &amp;choice);
- if(choice == -1) //Exit chosen
- goto end;
- mvprintw(22, 1, "Choice made is : %d String Chosen is \"%10s\"", choice, choices[choice - 1]);
- refresh();
- }
- }
- print_menu(menu_win, choice);
- break;
- }
- }
-end:
- endwin();
- return 0;
-}
-
-
-void print_menu(WINDOW *menu_win, int highlight)
-{
- int x, y, i;
-
- x = 2;
- y = 2;
- box(menu_win, 0, 0);
- for(i = 0; i &lt; n_choices; ++i)
- { if(highlight == i + 1)
- { wattron(menu_win, A_REVERSE);
- mvwprintw(menu_win, y, x, "%s", choices[i]);
- wattroff(menu_win, A_REVERSE);
- }
- else
- mvwprintw(menu_win, y, x, "%s", choices[i]);
- ++y;
- }
- wrefresh(menu_win);
-}
-
-/* Report the choice according to mouse position */
-void report_choice(int mouse_x, int mouse_y, int *p_choice)
-{ int i,j, choice;
-
- i = startx + 2;
- j = starty + 3;
-
- for(choice = 0; choice &lt; n_choices; ++choice)
- if(mouse_y == j + choice &amp;&amp; mouse_x &gt;= i &amp;&amp; mouse_x &lt;= i + strlen(choices[choice]))
- { if(choice == n_choices - 1)
- *p_choice = -1;
- else
- *p_choice = choice + 1;
- break;
- }
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MISCMOUSEFUNCS" id=
-"MISCMOUSEFUNCS">12.4. Miscellaneous Functions</a></h3>
-<p>The functions mouse_trafo() and wmouse_trafo() can be used to
-convert to mouse co-ordinates to screen relative co-ordinates. See
-curs_mouse(3X) man page for details.</p>
-<p>The mouseinterval function sets the maximum time (in thousands
-of a second) that can elapse between press and release events in
-order for them to be recognized as a click. This function returns
-the previous interval value. The default is one fifth of a
-second.</p>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="SCREEN" id="SCREEN">13. Screen
-Manipulation</a></h2>
-<p>In this section, we will look into some functions, which allow
-us to manage the screen efficiently and to write some fancy
-programs. This is especially important in writing games.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="GETYX" id="GETYX">13.1. getyx()
-functions</a></h3>
-<p>The function <var class="LITERAL">getyx()</var> can be used to
-find out the present cursor co-ordinates. It will fill the values
-of x and y co-ordinates in the arguments given to it. Since getyx()
-is a macro you don't have to pass the address of the variables. It
-can be called as</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> getyx(win, y, x);
- /* win: window pointer
- * y, x: y, x co-ordinates will be put into this variables
- */</font>
-</pre></td>
-</tr>
-</table>
-<p>The function getparyx() gets the beginning co-ordinates of the
-sub window relative to the main window. This is some times useful
-to update a sub window. When designing fancy stuff like writing
-multiple menus, it becomes difficult to store the menu positions,
-their first option co-ordinates etc. A simple solution to this
-problem, is to create menus in sub windows and later find the
-starting co-ordinates of the menus by using getparyx().</p>
-<p>The functions getbegyx() and getmaxyx() store current window's
-beginning and maximum co-ordinates. These functions are useful in
-the same way as above in managing the windows and sub windows
-effectively.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="SCREENDUMP" id="SCREENDUMP">13.2. Screen
-Dumping</a></h3>
-<p>While writing games, some times it becomes necessary to store
-the state of the screen and restore it back to the same state. The
-function scr_dump() can be used to dump the screen contents to a
-file given as an argument. Later it can be restored by scr_restore
-function. These two simple functions can be used effectively to
-maintain a fast moving game with changing scenarios.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="WINDOWDUMP" id="WINDOWDUMP">13.3. Window
-Dumping</a></h3>
-<p>To store and restore windows, the functions <var class=
-"LITERAL">putwin()</var> and <var class="LITERAL">getwin()</var>
-can be used. <var class="LITERAL">putwin()</var> puts the present
-window state into a file, which can be later restored by
-<var class="LITERAL">getwin()</var>.</p>
-<p>The function <var class="LITERAL">copywin()</var> can be used to
-copy a window completely onto another window. It takes the source
-and destination windows as parameters and according to the
-rectangle specified, it copies the rectangular region from source
-to destination window. It's last parameter specifies whether to
-overwrite or just overlay the contents on to the destination
-window. If this argument is true, then the copying is
-non-destructive.</p>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="MISC" id="MISC">14. Miscellaneous
-features</a></h2>
-<p>Now you know enough features to write a good curses program,
-with all bells and whistles. There are some miscellaneous functions
-which are useful in various cases. Let's go headlong into some of
-those.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="CURSSET" id="CURSSET">14.1.
-curs_set()</a></h3>
-<p>This function can be used to make the cursor invisible. The
-parameter to this function should be</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> 0 : invisible or
- 1 : normal or
- 2 : very visible.</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="TEMPLEAVE" id="TEMPLEAVE">14.2.
-Temporarily Leaving Curses mode</a></h3>
-<p>Some times you may want to get back to cooked mode (normal line
-buffering mode) temporarily. In such a case you will first need to
-save the tty modes with a call to <var class=
-"LITERAL">def_prog_mode()</var> and then call <var class=
-"LITERAL">endwin()</var> to end the curses mode. This will leave
-you in the original tty mode. To get back to curses once you are
-done, call <var class="LITERAL">reset_prog_mode()</var> . This
-function returns the tty to the state stored by <var class=
-"LITERAL">def_prog_mode()</var>. Then do refresh(), and you are
-back to the curses mode. Here is an example showing the sequence of
-things to be done.</p>
-<div class="EXAMPLE"><a name="BTELE" id="BTELE"></a>
-<p><b>Example 12. Temporarily Leaving Curses Mode</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
-
-int main()
-{
- initscr(); /* Start curses mode */
- printw("Hello World !!!\n"); /* Print Hello World */
- refresh(); /* Print it on to the real screen */
- def_prog_mode(); /* Save the tty modes */
- endwin(); /* End curses mode temporarily */
- system("/bin/sh"); /* Do whatever you like in cooked mode */
- reset_prog_mode(); /* Return to the previous tty mode*/
- /* stored by def_prog_mode() */
- refresh(); /* Do refresh() to restore the */
- /* Screen contents */
- printw("Another String\n"); /* Back to curses use the full */
- refresh(); /* capabilities of curses */
- endwin(); /* End curses mode */
-
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ACSVARS" id="ACSVARS">14.3. ACS_
-variables</a></h3>
-<p>If you have ever programmed in DOS, you know about those nifty
-characters in extended character set. They are printable only on
-some terminals. NCURSES functions like <var class=
-"LITERAL">box()</var> use these characters. All these variables
-start with ACS meaning alternative character set. You might have
-noticed me using these characters in some of the programs above.
-Here's an example showing all the characters.</p>
-<div class="EXAMPLE"><a name="BACSVARS" id="BACSVARS"></a>
-<p><b>Example 13. ACS Variables Example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
-
-int main()
-{
- initscr();
-
- printw("Upper left corner "); addch(ACS_ULCORNER); printw("\n");
- printw("Lower left corner "); addch(ACS_LLCORNER); printw("\n");
- printw("Lower right corner "); addch(ACS_LRCORNER); printw("\n");
- printw("Tee pointing right "); addch(ACS_LTEE); printw("\n");
- printw("Tee pointing left "); addch(ACS_RTEE); printw("\n");
- printw("Tee pointing up "); addch(ACS_BTEE); printw("\n");
- printw("Tee pointing down "); addch(ACS_TTEE); printw("\n");
- printw("Horizontal line "); addch(ACS_HLINE); printw("\n");
- printw("Vertical line "); addch(ACS_VLINE); printw("\n");
- printw("Large Plus or cross over "); addch(ACS_PLUS); printw("\n");
- printw("Scan Line 1 "); addch(ACS_S1); printw("\n");
- printw("Scan Line 3 "); addch(ACS_S3); printw("\n");
- printw("Scan Line 7 "); addch(ACS_S7); printw("\n");
- printw("Scan Line 9 "); addch(ACS_S9); printw("\n");
- printw("Diamond "); addch(ACS_DIAMOND); printw("\n");
- printw("Checker board (stipple) "); addch(ACS_CKBOARD); printw("\n");
- printw("Degree Symbol "); addch(ACS_DEGREE); printw("\n");
- printw("Plus/Minus Symbol "); addch(ACS_PLMINUS); printw("\n");
- printw("Bullet "); addch(ACS_BULLET); printw("\n");
- printw("Arrow Pointing Left "); addch(ACS_LARROW); printw("\n");
- printw("Arrow Pointing Right "); addch(ACS_RARROW); printw("\n");
- printw("Arrow Pointing Down "); addch(ACS_DARROW); printw("\n");
- printw("Arrow Pointing Up "); addch(ACS_UARROW); printw("\n");
- printw("Board of squares "); addch(ACS_BOARD); printw("\n");
- printw("Lantern Symbol "); addch(ACS_LANTERN); printw("\n");
- printw("Solid Square Block "); addch(ACS_BLOCK); printw("\n");
- printw("Less/Equal sign "); addch(ACS_LEQUAL); printw("\n");
- printw("Greater/Equal sign "); addch(ACS_GEQUAL); printw("\n");
- printw("Pi "); addch(ACS_PI); printw("\n");
- printw("Not equal "); addch(ACS_NEQUAL); printw("\n");
- printw("UK pound sign "); addch(ACS_STERLING); printw("\n");
-
- refresh();
- getch();
- endwin();
-
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="OTHERLIB" id="OTHERLIB">15. Other
-libraries</a></h2>
-<p>Apart from the curses library, there are few text mode
-libraries, which provide more functionality and a lot of features.
-The following sections explain three standard libraries which are
-usually distributed along with curses.</p>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="PANELS" id="PANELS">16. Panel
-Library</a></h2>
-<p>Now that you are proficient in curses, you wanted to do some
-thing big. You created a lot of overlapping windows to give a
-professional windows-type look. Unfortunately, it soon becomes
-difficult to manage these. The multiple refreshes, updates plunge
-you into a nightmare. The overlapping windows create blotches,
-whenever you forget to refresh the windows in the proper order.</p>
-<p>Don't despair. There's an elegant solution provided in panels
-library. In the words of developers of ncurses</p>
-<p><em>When your interface design is such that windows may dive
-deeper into the visibility stack or pop to the top at runtime, the
-resulting book-keeping can be tedious and difficult to get right.
-Hence the panels library.</em></p>
-<p>If you have lot of overlapping windows, then panels library is
-the way to go. It obviates the need of doing series of
-wnoutrefresh(), doupdate() and relieves the burden of doing it
-correctly(bottom up). The library maintains information about the
-order of windows, their overlapping and update the screen properly.
-So why wait? Let's take a close peek into panels.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PANELBASICS" id="PANELBASICS">16.1. The
-Basics</a></h3>
-<p>Panel object is a window that is implicitly treated as part of a
-deck including all other panel objects. The deck is treated as a
-stack with the top panel being completely visible and the other
-panels may or may not be obscured according to their positions. So
-the basic idea is to create a stack of overlapping panels and use
-panels library to display them correctly. There is a function
-similar to refresh() which, when called , displays panels in the
-correct order. Functions are provided to hide or show panels, move
-panels, change its size etc.. The overlapping problem is managed by
-the panels library during all the calls to these functions.</p>
-<p>The general flow of a panel program goes like this:</p>
-<ol type="1">
-<li>
-<p>Create the windows (with newwin()) to be attached to the
-panels.</p>
-</li>
-<li>
-<p>Create panels with the chosen visibility order. Stack them up
-according to the desired visibility. The function new_panel() is
-used to created panels.</p>
-</li>
-<li>
-<p>Call update_panels() to write the panels to the virtual screen
-in correct visibility order. Do a doupdate() to show it on the
-screen.</p>
-</li>
-<li>
-<p>Mainpulate the panels with show_panel(), hide_panel(),
-move_panel() etc. Make use of helper functions like panel_hidden()
-and panel_window(). Make use of user pointer to store custom data
-for a panel. Use the functions set_panel_userptr() and
-panel_userptr() to set and get the user pointer for a panel.</p>
-</li>
-<li>
-<p>When you are done with the panel use del_panel() to delete the
-panel.</p>
-</li>
-</ol>
-<p>Let's make the concepts clear, with some programs. The following
-is a simple program which creates 3 overlapping panels and shows
-them on the screen.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="COMPILEPANELS" id="COMPILEPANELS">16.2.
-Compiling With the Panels Library</a></h3>
-<p>To use panels library functions, you have to include panel.h and
-to link the program with panels library the flag -lpanel should be
-added along with -lncurses in that order.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> #include &lt;panel.h&gt;
- .
- .
- .
-
- compile and link: gcc &lt;program file&gt; -lpanel -lncurses</font>
-</pre></td>
-</tr>
-</table>
-<div class="EXAMPLE"><a name="PPASI" id="PPASI"></a>
-<p><b>Example 14. Panel basics</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;panel.h&gt;
-
-int main()
-{ WINDOW *my_wins[3];
- PANEL *my_panels[3];
- int lines = 10, cols = 40, y = 2, x = 4, i;
-
- initscr();
- cbreak();
- noecho();
-
- /* Create windows for the panels */
- my_wins[0] = newwin(lines, cols, y, x);
- my_wins[1] = newwin(lines, cols, y + 1, x + 5);
- my_wins[2] = newwin(lines, cols, y + 2, x + 10);
-
- /*
- * Create borders around the windows so that you can see the effect
- * of panels
- */
- for(i = 0; i &lt; 3; ++i)
- box(my_wins[i], 0, 0);
-
- /* Attach a panel to each window */ /* Order is bottom up */
- my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */
- my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */
- my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */
-
- /* Update the stacking order. 2nd panel will be on top */
- update_panels();
-
- /* Show it on the screen */
- doupdate();
-
- getch();
- endwin();
-}
-</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>As you can see, above program follows a simple flow as
-explained. The windows are created with newwin() and then they are
-attached to panels with new_panel(). As we attach one panel after
-another, the stack of panels gets updated. To put them on screen
-update_panels() and doupdate() are called.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PANELBROWSING" id="PANELBROWSING">16.3.
-Panel Window Browsing</a></h3>
-<p>A slightly complicated example is given below. This program
-creates 3 windows which can be cycled through using tab. Have a
-look at the code.</p>
-<div class="EXAMPLE"><a name="PPABR" id="PPABR"></a>
-<p><b>Example 15. Panel Window Browsing Example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;panel.h&gt;
-
-#define NLINES 10
-#define NCOLS 40
-
-void init_wins(WINDOW **wins, int n);
-void win_show(WINDOW *win, char *label, int label_color);
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
-
-int main()
-{ WINDOW *my_wins[3];
- PANEL *my_panels[3];
- PANEL *top;
- int ch;
-
- /* Initialize curses */
- initscr();
- start_color();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
-
- /* Initialize all the colors */
- init_pair(1, COLOR_RED, COLOR_BLACK);
- init_pair(2, COLOR_GREEN, COLOR_BLACK);
- init_pair(3, COLOR_BLUE, COLOR_BLACK);
- init_pair(4, COLOR_CYAN, COLOR_BLACK);
-
- init_wins(my_wins, 3);
-
- /* Attach a panel to each window */ /* Order is bottom up */
- my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */
- my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */
- my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */
-
- /* Set up the user pointers to the next panel */
- set_panel_userptr(my_panels[0], my_panels[1]);
- set_panel_userptr(my_panels[1], my_panels[2]);
- set_panel_userptr(my_panels[2], my_panels[0]);
-
- /* Update the stacking order. 2nd panel will be on top */
- update_panels();
-
- /* Show it on the screen */
- attron(COLOR_PAIR(4));
- mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)");
- attroff(COLOR_PAIR(4));
- doupdate();
-
- top = my_panels[2];
- while((ch = getch()) != KEY_F(1))
- { switch(ch)
- { case 9:
- top = (PANEL *)panel_userptr(top);
- top_panel(top);
- break;
- }
- update_panels();
- doupdate();
- }
- endwin();
- return 0;
-}
-
-/* Put all the windows */
-void init_wins(WINDOW **wins, int n)
-{ int x, y, i;
- char label[80];
-
- y = 2;
- x = 10;
- for(i = 0; i &lt; n; ++i)
- { wins[i] = newwin(NLINES, NCOLS, y, x);
- sprintf(label, "Window Number %d", i + 1);
- win_show(wins[i], label, i + 1);
- y += 3;
- x += 7;
- }
-}
-
-/* Show the window with a border and a label */
-void win_show(WINDOW *win, char *label, int label_color)
-{ int startx, starty, height, width;
-
- getbegyx(win, starty, startx);
- getmaxyx(win, height, width);
-
- box(win, 0, 0);
- mvwaddch(win, 2, 0, ACS_LTEE);
- mvwhline(win, 2, 1, ACS_HLINE, width - 2);
- mvwaddch(win, 2, width - 1, ACS_RTEE);
-
- print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color));
-}
-
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
-{ int length, x, y;
- float temp;
-
- if(win == NULL)
- win = stdscr;
- getyx(win, y, x);
- if(startx != 0)
- x = startx;
- if(starty != 0)
- y = starty;
- if(width == 0)
- width = 80;
-
- length = strlen(string);
- temp = (width - length)/ 2;
- x = startx + (int)temp;
- wattron(win, color);
- mvwprintw(win, y, x, "%s", string);
- wattroff(win, color);
- refresh();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="USERPTRUSING" id="USERPTRUSING">16.4.
-Using User Pointers</a></h3>
-<p>In the above example I used user pointers to find out the next
-window in the cycle. We can attach custom information to the panel
-by specifying a user pointer, which can point to any information
-you want to store. In this case I stored the pointer to the next
-panel in the cycle. User pointer for a panel can be set with the
-function <var class="LITERAL">set_panel_userptr()</var>. It can be
-accessed using the function <var class=
-"LITERAL">panel_userptr()</var> which will return the user pointer
-for the panel given as argument. After finding the next panel in
-the cycle It's brought to the top by the function top_panel(). This
-function brings the panel given as argument to the top of the panel
-stack.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PANELMOVERESIZE" id=
-"PANELMOVERESIZE">16.5. Moving and Resizing Panels</a></h3>
-<p>The function <var class="LITERAL">move_panel()</var> can be used
-to move a panel to the desired location. It does not change the
-position of the panel in the stack. Make sure that you use
-move_panel() instead mvwin() on the window associated with the
-panel.</p>
-<p>Resizing a panel is slightly complex. There is no straight
-forward function just to resize the window associated with a panel.
-A solution to resize a panel is to create a new window with the
-desired sizes, change the window associated with the panel using
-replace_panel(). Don't forget to delete the old window. The window
-associated with a panel can be found by using the function
-panel_window().</p>
-<p>The following program shows these concepts, in supposedly simple
-program. You can cycle through the window with &lt;TAB&gt; as
-usual. To resize or move the active panel press 'r' for resize 'm'
-for moving. Then use arrow keys to resize or move it to the desired
-way and press enter to end your resizing or moving. This example
-makes use of user data to get the required data to do the
-operations.</p>
-<div class="EXAMPLE"><a name="PPARE" id="PPARE"></a>
-<p><b>Example 16. Panel Moving and Resizing example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;panel.h&gt;
-
-typedef struct _PANEL_DATA {
- int x, y, w, h;
- char label[80];
- int label_color;
- PANEL *next;
-}PANEL_DATA;
-
-#define NLINES 10
-#define NCOLS 40
-
-void init_wins(WINDOW **wins, int n);
-void win_show(WINDOW *win, char *label, int label_color);
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
-void set_user_ptrs(PANEL **panels, int n);
-
-int main()
-{ WINDOW *my_wins[3];
- PANEL *my_panels[3];
- PANEL_DATA *top;
- PANEL *stack_top;
- WINDOW *temp_win, *old_win;
- int ch;
- int newx, newy, neww, newh;
- int size = FALSE, move = FALSE;
-
- /* Initialize curses */
- initscr();
- start_color();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
-
- /* Initialize all the colors */
- init_pair(1, COLOR_RED, COLOR_BLACK);
- init_pair(2, COLOR_GREEN, COLOR_BLACK);
- init_pair(3, COLOR_BLUE, COLOR_BLACK);
- init_pair(4, COLOR_CYAN, COLOR_BLACK);
-
- init_wins(my_wins, 3);
-
- /* Attach a panel to each window */ /* Order is bottom up */
- my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */
- my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */
- my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */
-
- set_user_ptrs(my_panels, 3);
- /* Update the stacking order. 2nd panel will be on top */
- update_panels();
-
- /* Show it on the screen */
- attron(COLOR_PAIR(4));
- mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing");
- mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)");
- attroff(COLOR_PAIR(4));
- doupdate();
-
- stack_top = my_panels[2];
- top = (PANEL_DATA *)panel_userptr(stack_top);
- newx = top-&gt;x;
- newy = top-&gt;y;
- neww = top-&gt;w;
- newh = top-&gt;h;
- while((ch = getch()) != KEY_F(1))
- { switch(ch)
- { case 9: /* Tab */
- top = (PANEL_DATA *)panel_userptr(stack_top);
- top_panel(top-&gt;next);
- stack_top = top-&gt;next;
- top = (PANEL_DATA *)panel_userptr(stack_top);
- newx = top-&gt;x;
- newy = top-&gt;y;
- neww = top-&gt;w;
- newh = top-&gt;h;
- break;
- case 'r': /* Re-Size*/
- size = TRUE;
- attron(COLOR_PAIR(4));
- mvprintw(LINES - 4, 0, "Entered Resizing :Use Arrow Keys to resize and press &lt;ENTER&gt; to end resizing");
- refresh();
- attroff(COLOR_PAIR(4));
- break;
- case 'm': /* Move */
- attron(COLOR_PAIR(4));
- mvprintw(LINES - 4, 0, "Entered Moving: Use Arrow Keys to Move and press &lt;ENTER&gt; to end moving");
- refresh();
- attroff(COLOR_PAIR(4));
- move = TRUE;
- break;
- case KEY_LEFT:
- if(size == TRUE)
- { --newx;
- ++neww;
- }
- if(move == TRUE)
- --newx;
- break;
- case KEY_RIGHT:
- if(size == TRUE)
- { ++newx;
- --neww;
- }
- if(move == TRUE)
- ++newx;
- break;
- case KEY_UP:
- if(size == TRUE)
- { --newy;
- ++newh;
- }
- if(move == TRUE)
- --newy;
- break;
- case KEY_DOWN:
- if(size == TRUE)
- { ++newy;
- --newh;
- }
- if(move == TRUE)
- ++newy;
- break;
- case 10: /* Enter */
- move(LINES - 4, 0);
- clrtoeol();
- refresh();
- if(size == TRUE)
- { old_win = panel_window(stack_top);
- temp_win = newwin(newh, neww, newy, newx);
- replace_panel(stack_top, temp_win);
- win_show(temp_win, top-&gt;label, top-&gt;label_color);
- delwin(old_win);
- size = FALSE;
- }
- if(move == TRUE)
- { move_panel(stack_top, newy, newx);
- move = FALSE;
- }
- break;
-
- }
- attron(COLOR_PAIR(4));
- mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing");
- mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)");
- attroff(COLOR_PAIR(4));
- refresh();
- update_panels();
- doupdate();
- }
- endwin();
- return 0;
-}
-
-/* Put all the windows */
-void init_wins(WINDOW **wins, int n)
-{ int x, y, i;
- char label[80];
-
- y = 2;
- x = 10;
- for(i = 0; i &lt; n; ++i)
- { wins[i] = newwin(NLINES, NCOLS, y, x);
- sprintf(label, "Window Number %d", i + 1);
- win_show(wins[i], label, i + 1);
- y += 3;
- x += 7;
- }
-}
-
-/* Set the PANEL_DATA structures for individual panels */
-void set_user_ptrs(PANEL **panels, int n)
-{ PANEL_DATA *ptrs;
- WINDOW *win;
- int x, y, w, h, i;
- char temp[80];
-
- ptrs = (PANEL_DATA *)calloc(n, sizeof(PANEL_DATA));
-
- for(i = 0;i &lt; n; ++i)
- { win = panel_window(panels[i]);
- getbegyx(win, y, x);
- getmaxyx(win, h, w);
- ptrs[i].x = x;
- ptrs[i].y = y;
- ptrs[i].w = w;
- ptrs[i].h = h;
- sprintf(temp, "Window Number %d", i + 1);
- strcpy(ptrs[i].label, temp);
- ptrs[i].label_color = i + 1;
- if(i + 1 == n)
- ptrs[i].next = panels[0];
- else
- ptrs[i].next = panels[i + 1];
- set_panel_userptr(panels[i], &amp;ptrs[i]);
- }
-}
-
-/* Show the window with a border and a label */
-void win_show(WINDOW *win, char *label, int label_color)
-{ int startx, starty, height, width;
-
- getbegyx(win, starty, startx);
- getmaxyx(win, height, width);
-
- box(win, 0, 0);
- mvwaddch(win, 2, 0, ACS_LTEE);
- mvwhline(win, 2, 1, ACS_HLINE, width - 2);
- mvwaddch(win, 2, width - 1, ACS_RTEE);
-
- print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color));
-}
-
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
-{ int length, x, y;
- float temp;
-
- if(win == NULL)
- win = stdscr;
- getyx(win, y, x);
- if(startx != 0)
- x = startx;
- if(starty != 0)
- y = starty;
- if(width == 0)
- width = 80;
-
- length = strlen(string);
- temp = (width - length)/ 2;
- x = startx + (int)temp;
- wattron(win, color);
- mvwprintw(win, y, x, "%s", string);
- wattroff(win, color);
- refresh();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Concentrate on the main while loop. Once it finds out the type
-of key pressed, it takes appropriate action. If 'r' is pressed
-resizing mode is started. After this the new sizes are updated as
-the user presses the arrow keys. When the user presses
-&lt;ENTER&gt; present selection ends and panel is resized by using
-the concept explained. While in resizing mode the program doesn't
-show how the window is getting resized. It's left as an exercise to
-the reader to print a dotted border while it gets resized to a new
-position.</p>
-<p>When the user presses 'm' the move mode starts. This is a bit
-simpler than resizing. As the arrow keys are pressed the new
-position is updated and pressing of &lt;ENTER&gt; causes the panel
-to be moved by calling the function move_panel().</p>
-<p>In this program the user data which is represented as
-PANEL_DATA, plays very important role in finding the associated
-information with a panel. As written in the comments, the
-PANEL_DATA stores the panel sizes, label, label color and a pointer
-to the next panel in the cycle.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PANELSHOWHIDE" id="PANELSHOWHIDE">16.6.
-Hiding and Showing Panels</a></h3>
-<p>A Panel can be hidden by using the function hide_panel(). This
-function merely removes it form the stack of panels, thus hiding it
-on the screen once you do update_panels() and doupdate(). It
-doesn't destroy the PANEL structure associated with the hidden
-panel. It can be shown again by using the show_panel()
-function.</p>
-<p>The following program shows the hiding of panels. Press 'a' or
-'b' or 'c' to show or hide first, second and third windows
-respectively. It uses a user data with a small variable hide, which
-keeps track of whether the window is hidden or not. For some reason
-the function <var class="LITERAL">panel_hidden()</var> which tells
-whether a panel is hidden or not is not working. A bug report was
-also presented by Michael Andres <a href=
-"http://www.geocrawler.com/archives/3/344/1999/9/0/2643549/"
-target="_top">here</a></p>
-<div class="EXAMPLE"><a name="PPAHI" id="PPAHI"></a>
-<p><b>Example 17. Panel Hiding and Showing example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;panel.h&gt;
-
-typedef struct _PANEL_DATA {
- int hide; /* TRUE if panel is hidden */
-}PANEL_DATA;
-
-#define NLINES 10
-#define NCOLS 40
-
-void init_wins(WINDOW **wins, int n);
-void win_show(WINDOW *win, char *label, int label_color);
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
-
-int main()
-{ WINDOW *my_wins[3];
- PANEL *my_panels[3];
- PANEL_DATA panel_datas[3];
- PANEL_DATA *temp;
- int ch;
-
- /* Initialize curses */
- initscr();
- start_color();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
-
- /* Initialize all the colors */
- init_pair(1, COLOR_RED, COLOR_BLACK);
- init_pair(2, COLOR_GREEN, COLOR_BLACK);
- init_pair(3, COLOR_BLUE, COLOR_BLACK);
- init_pair(4, COLOR_CYAN, COLOR_BLACK);
-
- init_wins(my_wins, 3);
-
- /* Attach a panel to each window */ /* Order is bottom up */
- my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */
- my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */
- my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */
-
- /* Initialize panel datas saying that nothing is hidden */
- panel_datas[0].hide = FALSE;
- panel_datas[1].hide = FALSE;
- panel_datas[2].hide = FALSE;
-
- set_panel_userptr(my_panels[0], &amp;panel_datas[0]);
- set_panel_userptr(my_panels[1], &amp;panel_datas[1]);
- set_panel_userptr(my_panels[2], &amp;panel_datas[2]);
-
- /* Update the stacking order. 2nd panel will be on top */
- update_panels();
-
- /* Show it on the screen */
- attron(COLOR_PAIR(4));
- mvprintw(LINES - 3, 0, "Show or Hide a window with 'a'(first window) 'b'(Second Window) 'c'(Third Window)");
- mvprintw(LINES - 2, 0, "F1 to Exit");
-
- attroff(COLOR_PAIR(4));
- doupdate();
-
- while((ch = getch()) != KEY_F(1))
- { switch(ch)
- { case 'a':
- temp = (PANEL_DATA *)panel_userptr(my_panels[0]);
- if(temp-&gt;hide == FALSE)
- { hide_panel(my_panels[0]);
- temp-&gt;hide = TRUE;
- }
- else
- { show_panel(my_panels[0]);
- temp-&gt;hide = FALSE;
- }
- break;
- case 'b':
- temp = (PANEL_DATA *)panel_userptr(my_panels[1]);
- if(temp-&gt;hide == FALSE)
- { hide_panel(my_panels[1]);
- temp-&gt;hide = TRUE;
- }
- else
- { show_panel(my_panels[1]);
- temp-&gt;hide = FALSE;
- }
- break;
- case 'c':
- temp = (PANEL_DATA *)panel_userptr(my_panels[2]);
- if(temp-&gt;hide == FALSE)
- { hide_panel(my_panels[2]);
- temp-&gt;hide = TRUE;
- }
- else
- { show_panel(my_panels[2]);
- temp-&gt;hide = FALSE;
- }
- break;
- }
- update_panels();
- doupdate();
- }
- endwin();
- return 0;
-}
-
-/* Put all the windows */
-void init_wins(WINDOW **wins, int n)
-{ int x, y, i;
- char label[80];
-
- y = 2;
- x = 10;
- for(i = 0; i &lt; n; ++i)
- { wins[i] = newwin(NLINES, NCOLS, y, x);
- sprintf(label, "Window Number %d", i + 1);
- win_show(wins[i], label, i + 1);
- y += 3;
- x += 7;
- }
-}
-
-/* Show the window with a border and a label */
-void win_show(WINDOW *win, char *label, int label_color)
-{ int startx, starty, height, width;
-
- getbegyx(win, starty, startx);
- getmaxyx(win, height, width);
-
- box(win, 0, 0);
- mvwaddch(win, 2, 0, ACS_LTEE);
- mvwhline(win, 2, 1, ACS_HLINE, width - 2);
- mvwaddch(win, 2, width - 1, ACS_RTEE);
-
- print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color));
-}
-
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
-{ int length, x, y;
- float temp;
-
- if(win == NULL)
- win = stdscr;
- getyx(win, y, x);
- if(startx != 0)
- x = startx;
- if(starty != 0)
- y = starty;
- if(width == 0)
- width = 80;
-
- length = strlen(string);
- temp = (width - length)/ 2;
- x = startx + (int)temp;
- wattron(win, color);
- mvwprintw(win, y, x, "%s", string);
- wattroff(win, color);
- refresh();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PANELABOVE" id="PANELABOVE">16.7.
-panel_above() and panel_below() Functions</a></h3>
-<p>The functions <var class="LITERAL">panel_above()</var> and
-<var class="LITERAL">panel_below()</var> can be used to find out
-the panel above and below a panel. If the argument to these
-functions is NULL, then they return a pointer to bottom panel and
-top panel respectively.</p>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="MENUS" id="MENUS">17. Menus
-Library</a></h2>
-<p>The menus library provides a nice extension to basic curses,
-through which you can create menus. It provides a set of functions
-to create menus. But they have to be customized to give a nicer
-look, with colors etc. Let's get into the details.</p>
-<p>A menu is a screen display that assists the user to choose some
-subset of a given set of items. To put it simple, a menu is a
-collection of items from which one or more items can be chosen.
-Some readers might not be aware of multiple item selection
-capability. Menu library provides functionality to write menus from
-which the user can chose more than one item as the preferred
-choice. This is dealt with in a later section. Now it is time for
-some rudiments.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MENUBASICS" id="MENUBASICS">17.1. The
-Basics</a></h3>
-<p>To create menus, you first create items, and then post the menu
-to the display. After that, all the processing of user responses is
-done in an elegant function menu_driver() which is the work horse
-of any menu program.</p>
-<p>The general flow of control of a menu program looks like
-this.</p>
-<ol type="1">
-<li>
-<p>Initialize curses</p>
-</li>
-<li>
-<p>Create items using new_item(). You can specify a name and
-description for the items.</p>
-</li>
-<li>
-<p>Create the menu with new_menu() by specifying the items to be
-attached with.</p>
-</li>
-<li>
-<p>Post the menu with menu_post() and refresh the screen.</p>
-</li>
-<li>
-<p>Process the user requests with a loop and do necessary updates
-to menu with menu_driver.</p>
-</li>
-<li>
-<p>Unpost the menu with menu_unpost()</p>
-</li>
-<li>
-<p>Free the memory allocated to menu by free_menu()</p>
-</li>
-<li>
-<p>Free the memory allocated to the items with free_item()</p>
-</li>
-<li>
-<p>End curses</p>
-</li>
-</ol>
-<p>Let's see a program which prints a simple menu and updates the
-current selection with up, down arrows.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="COMPILEMENUS" id="COMPILEMENUS">17.2.
-Compiling With the Menu Library</a></h3>
-<p>To use menu library functions, you have to include menu.h and to
-link the program with menu library the flag -lmenu should be added
-along with -lncurses in that order.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> #include &lt;menu.h&gt;
- .
- .
- .
-
- compile and link: gcc &lt;program file&gt; -lmenu -lncurses</font>
-</pre></td>
-</tr>
-</table>
-<div class="EXAMPLE"><a name="MMESI" id="MMESI"></a>
-<p><b>Example 18. Menu Basics</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;curses.h&gt;
-#include &lt;menu.h&gt;
-
-#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
-#define CTRLD 4
-
-char *choices[] = {
- "Choice 1",
- "Choice 2",
- "Choice 3",
- "Choice 4",
- "Exit",
- };
-
-int main()
-{ ITEM **my_items;
- int c;
- MENU *my_menu;
- int n_choices, i;
- ITEM *cur_item;
-
-
- initscr();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
-
- n_choices = ARRAY_SIZE(choices);
- my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));
-
- for(i = 0; i &lt; n_choices; ++i)
- my_items[i] = new_item(choices[i], choices[i]);
- my_items[n_choices] = (ITEM *)NULL;
-
- my_menu = new_menu((ITEM **)my_items);
- mvprintw(LINES - 2, 0, "F1 to Exit");
- post_menu(my_menu);
- refresh();
-
- while((c = getch()) != KEY_F(1))
- { switch(c)
- { case KEY_DOWN:
- menu_driver(my_menu, REQ_DOWN_ITEM);
- break;
- case KEY_UP:
- menu_driver(my_menu, REQ_UP_ITEM);
- break;
- }
- }
-
- free_item(my_items[0]);
- free_item(my_items[1]);
- free_menu(my_menu);
- endwin();
-}
- </span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>This program demonstrates the basic concepts involved in
-creating a menu using menus library. First we create the items
-using new_item() and then attach them to the menu with new_menu()
-function. After posting the menu and refreshing the screen, the
-main processing loop starts. It reads user input and takes
-corresponding action. The function menu_driver() is the main work
-horse of the menu system. The second parameter to this function
-tells what's to be done with the menu. According to the parameter,
-menu_driver() does the corresponding task. The value can be either
-a menu navigational request, an ascii character, or a KEY_MOUSE
-special key associated with a mouse event.</p>
-<p>The menu_driver accepts following navigational requests.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">&#13; REQ_LEFT_ITEM Move left to an item.
- REQ_RIGHT_ITEM Move right to an item.
- REQ_UP_ITEM Move up to an item.
- REQ_DOWN_ITEM Move down to an item.
- REQ_SCR_ULINE Scroll up a line.
- REQ_SCR_DLINE Scroll down a line.
- REQ_SCR_DPAGE Scroll down a page.
- REQ_SCR_UPAGE Scroll up a page.
- REQ_FIRST_ITEM Move to the first item.
- REQ_LAST_ITEM Move to the last item.
- REQ_NEXT_ITEM Move to the next item.
- REQ_PREV_ITEM Move to the previous item.
- REQ_TOGGLE_ITEM Select/deselect an item.
- REQ_CLEAR_PATTERN Clear the menu pattern buffer.
- REQ_BACK_PATTERN Delete the previous character from the pattern buffer.
- REQ_NEXT_MATCH Move to the next item matching the pattern match.
- REQ_PREV_MATCH Move to the previous item matching the pattern match.&#13;</font>
-</pre></td>
-</tr>
-</table>
-<p>Don't get overwhelmed by the number of options. We will see them
-slowly one after another. The options of interest in this example
-are REQ_UP_ITEM and REQ_DOWN_ITEM. These two options when passed to
-menu_driver, menu driver updates the current item to one item up or
-down respectively.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MENUDRIVER" id="MENUDRIVER">17.3. Menu
-Driver: The work horse of the menu system</a></h3>
-<p>As you have seen in the above example, menu_driver plays an
-important role in updating the menu. It is very important to
-understand various options it takes and what they do. As explained
-above, the second parameter to menu_driver() can be either a
-navigational request, a printable character or a KEY_MOUSE key.
-Let's dissect the different navigational requests.</p>
-<ul>
-<li>
-<p><em>REQ_LEFT_ITEM and REQ_RIGHT_ITEM</em></p>
-<p>A Menu can be displayed with multiple columns for more than one
-item. This can be done by using the <var class=
-"LITERAL">menu_format()</var>function. When a multi columnar menu
-is displayed these requests cause the menu driver to move the
-current selection to left or right.</p>
-</li>
-<li>
-<p><em>REQ_UP_ITEM and REQ_DOWN_ITEM</em></p>
-<p>These two options you have seen in the above example. These
-options when given, makes the menu_driver to move the current
-selection to an item up or down.</p>
-</li>
-<li>
-<p><em>REQ_SCR_* options</em></p>
-<p>The four options REQ_SCR_ULINE, REQ_SCR_DLINE, REQ_SCR_DPAGE,
-REQ_SCR_UPAGE are related to scrolling. If all the items in the
-menu cannot be displayed in the menu sub window, then the menu is
-scrollable. These requests can be given to the menu_driver to do
-the scrolling either one line up, down or one page down or up
-respectively.</p>
-</li>
-<li>
-<p><em>REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_NEXT_ITEM and
-REQ_PREV_ITEM</em></p>
-<p>These requests are self explanatory.</p>
-</li>
-<li>
-<p><em>REQ_TOGGLE_ITEM</em></p>
-<p>This request when given, toggles the present selection. This
-option is to be used only in a multi valued menu. So to use this
-request the option O_ONEVALUE must be off. This option can be made
-off or on with set_menu_opts().</p>
-</li>
-<li>
-<p><em>Pattern Requests</em></p>
-<p>Every menu has an associated pattern buffer, which is used to
-find the nearest match to the ascii characters entered by the user.
-Whenever ascii characters are given to menu_driver, it puts in to
-the pattern buffer. It also tries to find the nearest match to the
-pattern in the items list and moves current selection to that item.
-The request REQ_CLEAR_PATTERN clears the pattern buffer. The
-request REQ_BACK_PATTERN deletes the previous character in the
-pattern buffer. In case the pattern matches more than one item then
-the matched items can be cycled through REQ_NEXT_MATCH and
-REQ_PREV_MATCH which move the current selection to the next and
-previous matches respectively.</p>
-</li>
-<li>
-<p><em>Mouse Requests</em></p>
-<p>In case of KEY_MOUSE requests, according to the mouse position
-an action is taken accordingly. The action to be taken is explained
-in the man page as,</p>
-<table border="0" bgcolor="#E0E0E0" width="90%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"><em> If the second argument is the KEY_MOUSE special key, the
- associated mouse event is translated into one of the above
- pre-defined requests. Currently only clicks in the user
- window (e.g. inside the menu display area or the decora&shy;
- tion window) are handled. If you click above the display
- region of the menu, a REQ_SCR_ULINE is generated, if you
- doubleclick a REQ_SCR_UPAGE is generated and if you
- tripleclick a REQ_FIRST_ITEM is generated. If you click
- below the display region of the menu, a REQ_SCR_DLINE is
- generated, if you doubleclick a REQ_SCR_DPAGE is generated
- and if you tripleclick a REQ_LAST_ITEM is generated. If
- you click at an item inside the display area of the menu,
- the menu cursor is positioned to that item.</em></font>
-</pre></td>
-</tr>
-</table>
-</li>
-</ul>
-<p>Each of the above requests will be explained in the following
-lines with several examples whenever appropriate.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MENUWINDOWS" id="MENUWINDOWS">17.4. Menu
-Windows</a></h3>
-<p>Every menu created is associated with a window and a sub window.
-The menu window displays any title or border associated with the
-menu. The menu sub window displays the menu items currently
-available for selection. But we didn't specify any window or sub
-window in the simple example. When a window is not specified,
-stdscr is taken as the main window, and then menu system calculates
-the sub window size required for the display of items. Then items
-are displayed in the calculated sub window. So let's play with
-these windows and display a menu with a border and a title.</p>
-<div class="EXAMPLE"><a name="MMEWI" id="MMEWI"></a>
-<p><b>Example 19. Menu Windows Usage example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;menu.h&gt;
-
-#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
-#define CTRLD 4
-
-char *choices[] = {
- "Choice 1",
- "Choice 2",
- "Choice 3",
- "Choice 4",
- "Exit",
- (char *)NULL,
- };
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
-
-int main()
-{ ITEM **my_items;
- int c;
- MENU *my_menu;
- WINDOW *my_menu_win;
- int n_choices, i;
-
- /* Initialize curses */
- initscr();
- start_color();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
- init_pair(1, COLOR_RED, COLOR_BLACK);
-
- /* Create items */
- n_choices = ARRAY_SIZE(choices);
- my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *));
- for(i = 0; i &lt; n_choices; ++i)
- my_items[i] = new_item(choices[i], choices[i]);
-
- /* Crate menu */
- my_menu = new_menu((ITEM **)my_items);
-
- /* Create the window to be associated with the menu */
- my_menu_win = newwin(10, 40, 4, 4);
- keypad(my_menu_win, TRUE);
-
- /* Set main window and sub window */
- set_menu_win(my_menu, my_menu_win);
- set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1));
-
- /* Set menu mark to the string " * " */
- set_menu_mark(my_menu, " * ");
-
- /* Print a border around the main window and print a title */
- box(my_menu_win, 0, 0);
- print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1));
- mvwaddch(my_menu_win, 2, 0, ACS_LTEE);
- mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38);
- mvwaddch(my_menu_win, 2, 39, ACS_RTEE);
- mvprintw(LINES - 2, 0, "F1 to exit");
- refresh();
-
- /* Post the menu */
- post_menu(my_menu);
- wrefresh(my_menu_win);
-
- while((c = wgetch(my_menu_win)) != KEY_F(1))
- { switch(c)
- { case KEY_DOWN:
- menu_driver(my_menu, REQ_DOWN_ITEM);
- break;
- case KEY_UP:
- menu_driver(my_menu, REQ_UP_ITEM);
- break;
- }
- wrefresh(my_menu_win);
- }
-
- /* Unpost and free all the memory taken up */
- unpost_menu(my_menu);
- free_menu(my_menu);
- for(i = 0; i &lt; n_choices; ++i)
- free_item(my_items[i]);
- endwin();
-}
-
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
-{ int length, x, y;
- float temp;
-
- if(win == NULL)
- win = stdscr;
- getyx(win, y, x);
- if(startx != 0)
- x = startx;
- if(starty != 0)
- y = starty;
- if(width == 0)
- width = 80;
-
- length = strlen(string);
- temp = (width - length)/ 2;
- x = startx + (int)temp;
- wattron(win, color);
- mvwprintw(win, y, x, "%s", string);
- wattroff(win, color);
- refresh();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>This example creates a menu with a title, border, a fancy line
-separating title and the items. As you can see, in order to attach
-a window to a menu the function set_menu_win() has to be used. Then
-we attach the sub window also. This displays the items in the sub
-window. You can also set the mark string which gets displayed to
-the left of the selected item with set_menu_mark().</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="SCROLLMENUS" id="SCROLLMENUS">17.5.
-Scrolling Menus</a></h3>
-<p>If the sub window given for a window is not big enough to show
-all the items, then the menu will be scrollable. When you are on
-the last item in the present list, if you send REQ_DOWN_ITEM, it
-gets translated into REQ_SCR_DLINE and the menu scrolls by one
-item. You can manually give REQ_SCR_ operations to do scrolling.
-Let's see how it can be done.</p>
-<div class="EXAMPLE"><a name="MMESC" id="MMESC"></a>
-<p><b>Example 20. Scrolling Menus example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;curses.h&gt;
-#include &lt;menu.h&gt;
-
-#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
-#define CTRLD 4
-
-char *choices[] = {
- "Choice 1",
- "Choice 2",
- "Choice 3",
- "Choice 4",
- "Choice 5",
- "Choice 6",
- "Choice 7",
- "Choice 8",
- "Choice 9",
- "Choice 10",
- "Exit",
- (char *)NULL,
- };
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
-
-int main()
-{ ITEM **my_items;
- int c;
- MENU *my_menu;
- WINDOW *my_menu_win;
- int n_choices, i;
-
- /* Initialize curses */
- initscr();
- start_color();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
- init_pair(1, COLOR_RED, COLOR_BLACK);
- init_pair(2, COLOR_CYAN, COLOR_BLACK);
-
- /* Create items */
- n_choices = ARRAY_SIZE(choices);
- my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *));
- for(i = 0; i &lt; n_choices; ++i)
- my_items[i] = new_item(choices[i], choices[i]);
-
- /* Crate menu */
- my_menu = new_menu((ITEM **)my_items);
-
- /* Create the window to be associated with the menu */
- my_menu_win = newwin(10, 40, 4, 4);
- keypad(my_menu_win, TRUE);
-
- /* Set main window and sub window */
- set_menu_win(my_menu, my_menu_win);
- set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1));
- set_menu_format(my_menu, 5, 1);
-
- /* Set menu mark to the string " * " */
- set_menu_mark(my_menu, " * ");
-
- /* Print a border around the main window and print a title */
- box(my_menu_win, 0, 0);
- print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1));
- mvwaddch(my_menu_win, 2, 0, ACS_LTEE);
- mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38);
- mvwaddch(my_menu_win, 2, 39, ACS_RTEE);
-
- /* Post the menu */
- post_menu(my_menu);
- wrefresh(my_menu_win);
-
- attron(COLOR_PAIR(2));
- mvprintw(LINES - 2, 0, "Use PageUp and PageDown to scoll down or up a page of items");
- mvprintw(LINES - 1, 0, "Arrow Keys to navigate (F1 to Exit)");
- attroff(COLOR_PAIR(2));
- refresh();
-
- while((c = wgetch(my_menu_win)) != KEY_F(1))
- { switch(c)
- { case KEY_DOWN:
- menu_driver(my_menu, REQ_DOWN_ITEM);
- break;
- case KEY_UP:
- menu_driver(my_menu, REQ_UP_ITEM);
- break;
- case KEY_NPAGE:
- menu_driver(my_menu, REQ_SCR_DPAGE);
- break;
- case KEY_PPAGE:
- menu_driver(my_menu, REQ_SCR_UPAGE);
- break;
- }
- wrefresh(my_menu_win);
- }
-
- /* Unpost and free all the memory taken up */
- unpost_menu(my_menu);
- free_menu(my_menu);
- for(i = 0; i &lt; n_choices; ++i)
- free_item(my_items[i]);
- endwin();
-}
-
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
-{ int length, x, y;
- float temp;
-
- if(win == NULL)
- win = stdscr;
- getyx(win, y, x);
- if(startx != 0)
- x = startx;
- if(starty != 0)
- y = starty;
- if(width == 0)
- width = 80;
-
- length = strlen(string);
- temp = (width - length)/ 2;
- x = startx + (int)temp;
- wattron(win, color);
- mvwprintw(win, y, x, "%s", string);
- wattroff(win, color);
- refresh();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>This program is self-explanatory. In this example the number of
-choices has been increased to ten, which is larger than our sub
-window size which can hold 6 items. This message has to be
-explicitly conveyed to the menu system with the function
-set_menu_format(). In here we specify the number of rows and
-columns we want to be displayed for a single page. We can specify
-any number of items to be shown, in the rows variables, if it is
-less than the height of the sub window. If the key pressed by the
-user is a PAGE UP or PAGE DOWN, the menu is scrolled a page due to
-the requests (REQ_SCR_DPAGE and REQ_SCR_UPAGE) given to
-menu_driver().</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MULTICOLUMN" id="MULTICOLUMN">17.6.
-Multi Columnar Menus</a></h3>
-<p>In the above example you have seen how to use the function
-set_menu_format(). I didn't mention what the cols variable (third
-parameter) does. Well, If your sub window is wide enough, you can
-opt to display more than one item per row. This can be specified in
-the cols variable. To make things simpler, the following example
-doesn't show descriptions for the items.</p>
-<div class="EXAMPLE"><a name="MMEMUCO" id="MMEMUCO"></a>
-<p><b>Example 21. Milt Columnar Menus Example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;curses.h&gt;
-#include &lt;menu.h&gt;
-
-#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
-#define CTRLD 4
-
-char *choices[] = {
- "Choice 1", "Choice 2", "Choice 3", "Choice 4", "Choice 5",
- "Choice 6", "Choice 7", "Choice 8", "Choice 9", "Choice 10",
- "Choice 11", "Choice 12", "Choice 13", "Choice 14", "Choice 15",
- "Choice 16", "Choice 17", "Choice 18", "Choice 19", "Choice 20",
- "Exit",
- (char *)NULL,
- };
-
-int main()
-{ ITEM **my_items;
- int c;
- MENU *my_menu;
- WINDOW *my_menu_win;
- int n_choices, i;
-
- /* Initialize curses */
- initscr();
- start_color();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
- init_pair(1, COLOR_RED, COLOR_BLACK);
- init_pair(2, COLOR_CYAN, COLOR_BLACK);
-
- /* Create items */
- n_choices = ARRAY_SIZE(choices);
- my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *));
- for(i = 0; i &lt; n_choices; ++i)
- my_items[i] = new_item(choices[i], choices[i]);
-
- /* Crate menu */
- my_menu = new_menu((ITEM **)my_items);
-
- /* Set menu option not to show the description */
- menu_opts_off(my_menu, O_SHOWDESC);
-
- /* Create the window to be associated with the menu */
- my_menu_win = newwin(10, 70, 4, 4);
- keypad(my_menu_win, TRUE);
-
- /* Set main window and sub window */
- set_menu_win(my_menu, my_menu_win);
- set_menu_sub(my_menu, derwin(my_menu_win, 6, 68, 3, 1));
- set_menu_format(my_menu, 5, 3);
- set_menu_mark(my_menu, " * ");
-
- /* Print a border around the main window and print a title */
- box(my_menu_win, 0, 0);
-
- attron(COLOR_PAIR(2));
- mvprintw(LINES - 3, 0, "Use PageUp and PageDown to scroll");
- mvprintw(LINES - 2, 0, "Use Arrow Keys to navigate (F1 to Exit)");
- attroff(COLOR_PAIR(2));
- refresh();
-
- /* Post the menu */
- post_menu(my_menu);
- wrefresh(my_menu_win);
-
- while((c = wgetch(my_menu_win)) != KEY_F(1))
- { switch(c)
- { case KEY_DOWN:
- menu_driver(my_menu, REQ_DOWN_ITEM);
- break;
- case KEY_UP:
- menu_driver(my_menu, REQ_UP_ITEM);
- break;
- case KEY_LEFT:
- menu_driver(my_menu, REQ_LEFT_ITEM);
- break;
- case KEY_RIGHT:
- menu_driver(my_menu, REQ_RIGHT_ITEM);
- break;
- case KEY_NPAGE:
- menu_driver(my_menu, REQ_SCR_DPAGE);
- break;
- case KEY_PPAGE:
- menu_driver(my_menu, REQ_SCR_UPAGE);
- break;
- }
- wrefresh(my_menu_win);
- }
-
- /* Unpost and free all the memory taken up */
- unpost_menu(my_menu);
- free_menu(my_menu);
- for(i = 0; i &lt; n_choices; ++i)
- free_item(my_items[i]);
- endwin();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Watch the function call to set_menu_format(). It specifies the
-number of columns to be 3, thus displaying 3 items per row. We have
-also switched off the showing descriptions with the function
-menu_opts_off(). There are couple of functions set_menu_opts(),
-menu_opts_on() and menu_opts() which can be used to manipulate menu
-options. The following menu options can be specified.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> O_ONEVALUE
- Only one item can be selected for this menu.
-
- O_SHOWDESC
- Display the item descriptions when the menu is
- posted.
-
- O_ROWMAJOR
- Display the menu in row-major order.
-
- O_IGNORECASE
- Ignore the case when pattern-matching.
-
- O_SHOWMATCH
- Move the cursor to within the item name while pat&shy;
- tern-matching.
-
- O_NONCYCLIC
- Don't wrap around next-item and previous-item,
- requests to the other end of the menu.</font>
-</pre></td>
-</tr>
-</table>
-<p>All options are on by default. You can switch specific
-attributes on or off with menu_opts_on() and menu_opts_off()
-functions. You can also use set_menu_opts() to directly specify the
-options. The argument to this function should be a OR ed value of
-some of those above constants. The function menu_opts() can be used
-to find out a menu's present options.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MULTIVALUEMENUS" id=
-"MULTIVALUEMENUS">17.7. Multi Valued Menus</a></h3>
-<p>You might be wondering what if you switch off the option
-O_ONEVALUE. Then the menu becomes multi-valued. That means you can
-select more than one item. This brings us to the request
-REQ_TOGGLE_ITEM. Let's see it in action.</p>
-<div class="EXAMPLE"><a name="MMETO" id="MMETO"></a>
-<p><b>Example 22. Multi Valued Menus example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;curses.h&gt;
-#include &lt;menu.h&gt;
-
-#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
-#define CTRLD 4
-
-char *choices[] = {
- "Choice 1",
- "Choice 2",
- "Choice 3",
- "Choice 4",
- "Choice 5",
- "Choice 6",
- "Choice 7",
- "Exit",
- };
-
-int main()
-{ ITEM **my_items;
- int c;
- MENU *my_menu;
- int n_choices, i;
- ITEM *cur_item;
-
- /* Initialize curses */
- initscr();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
-
- /* Initialize items */
- n_choices = ARRAY_SIZE(choices);
- my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));
- for(i = 0; i &lt; n_choices; ++i)
- my_items[i] = new_item(choices[i], choices[i]);
- my_items[n_choices] = (ITEM *)NULL;
-
- my_menu = new_menu((ITEM **)my_items);
-
- /* Make the menu multi valued */
- menu_opts_off(my_menu, O_ONEVALUE);
-
- mvprintw(LINES - 3, 0, "Use &lt;SPACE&gt; to select or unselect an item.");
- mvprintw(LINES - 2, 0, "&lt;ENTER&gt; to see presently selected items(F1 to Exit)");
- post_menu(my_menu);
- refresh();
-
- while((c = getch()) != KEY_F(1))
- { switch(c)
- { case KEY_DOWN:
- menu_driver(my_menu, REQ_DOWN_ITEM);
- break;
- case KEY_UP:
- menu_driver(my_menu, REQ_UP_ITEM);
- break;
- case ' ':
- menu_driver(my_menu, REQ_TOGGLE_ITEM);
- break;
- case 10: /* Enter */
- { char temp[200];
- ITEM **items;
-
- items = menu_items(my_menu);
- temp[0] = '\0';
- for(i = 0; i &lt; item_count(my_menu); ++i)
- if(item_value(items[i]) == TRUE)
- { strcat(temp, item_name(items[i]));
- strcat(temp, " ");
- }
- move(20, 0);
- clrtoeol();
- mvprintw(20, 0, temp);
- refresh();
- }
- break;
- }
- }
-
- free_item(my_items[0]);
- free_item(my_items[1]);
- free_menu(my_menu);
- endwin();
-}
- </span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Whew, A lot of new functions. Let's take them one after another.
-Firstly, the REQ_TOGGLE_ITEM. In a multi-valued menu, the user
-should be allowed to select or un select more than one item. The
-request REQ_TOGGLE_ITEM toggles the present selection. In this case
-when space is pressed REQ_TOGGLE_ITEM request is sent to
-menu_driver to achieve the result.</p>
-<p>Now when the user presses &lt;ENTER&gt; we show the items he
-presently selected. First we find out the items associated with the
-menu using the function menu_items(). Then we loop through the
-items to find out if the item is selected or not. The function
-item_value() returns TRUE if an item is selected. The function
-item_count() returns the number of items in the menu. The item name
-can be found with item_name(). You can also find the description
-associated with an item using item_description().</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MENUOPT" id="MENUOPT">17.8. Menu
-Options</a></h3>
-<p>Well, by this time you must be itching for some difference in
-your menu, with lots of functionality. I know. You want Colors !!!.
-You want to create nice menus similar to those text mode <a href=
-"http://www.jersey.net/~debinjoe/games/" target="_top">dos
-games</a>. The functions set_menu_fore() and set_menu_back() can be
-used to change the attribute of the selected item and unselected
-item. The names are misleading. They don't change menu's foreground
-or background which would have been useless.</p>
-<p>The function set_menu_grey() can be used to set the display
-attribute for the non-selectable items in the menu. This brings us
-to the interesting option for an item the one and only
-O_SELECTABLE. We can turn it off by the function item_opts_off()
-and after that that item is not selectable. It's like a grayed item
-in those fancy windows menus. Let's put these concepts in practice
-with this example</p>
-<div class="EXAMPLE"><a name="MMEAT" id="MMEAT"></a>
-<p><b>Example 23. Menu Options example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;menu.h&gt;
-
-#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
-#define CTRLD 4
-
-char *choices[] = {
- "Choice 1",
- "Choice 2",
- "Choice 3",
- "Choice 4",
- "Choice 5",
- "Choice 6",
- "Choice 7",
- "Exit",
- };
-
-int main()
-{ ITEM **my_items;
- int c;
- MENU *my_menu;
- int n_choices, i;
- ITEM *cur_item;
-
- /* Initialize curses */
- initscr();
- start_color();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
- init_pair(1, COLOR_RED, COLOR_BLACK);
- init_pair(2, COLOR_GREEN, COLOR_BLACK);
- init_pair(3, COLOR_MAGENTA, COLOR_BLACK);
-
- /* Initialize items */
- n_choices = ARRAY_SIZE(choices);
- my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));
- for(i = 0; i &lt; n_choices; ++i)
- my_items[i] = new_item(choices[i], choices[i]);
- my_items[n_choices] = (ITEM *)NULL;
- item_opts_off(my_items[3], O_SELECTABLE);
- item_opts_off(my_items[6], O_SELECTABLE);
-
- /* Create menu */
- my_menu = new_menu((ITEM **)my_items);
-
- /* Set fore ground and back ground of the menu */
- set_menu_fore(my_menu, COLOR_PAIR(1) | A_REVERSE);
- set_menu_back(my_menu, COLOR_PAIR(2));
- set_menu_grey(my_menu, COLOR_PAIR(3));
-
- /* Post the menu */
- mvprintw(LINES - 3, 0, "Press &lt;ENTER&gt; to see the option selected");
- mvprintw(LINES - 2, 0, "Up and Down arrow keys to naviage (F1 to Exit)");
- post_menu(my_menu);
- refresh();
-
- while((c = getch()) != KEY_F(1))
- { switch(c)
- { case KEY_DOWN:
- menu_driver(my_menu, REQ_DOWN_ITEM);
- break;
- case KEY_UP:
- menu_driver(my_menu, REQ_UP_ITEM);
- break;
- case 10: /* Enter */
- move(20, 0);
- clrtoeol();
- mvprintw(20, 0, "Item selected is : %s",
- item_name(current_item(my_menu)));
- pos_menu_cursor(my_menu);
- break;
- }
- }
- unpost_menu(my_menu);
- for(i = 0; i &lt; n_choices; ++i)
- free_item(my_items[i]);
- free_menu(my_menu);
- endwin();
-}
- </span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MENUUSERPTR" id="MENUUSERPTR">17.9. The
-useful User Pointer</a></h3>
-<p>We can associate a user pointer with each item in the menu. It
-works the same way as user pointer in panels. It's not touched by
-menu system. You can store any thing you like in that. I usually
-use it to store the function to be executed when the menu option is
-chosen (It's selected and may be the user pressed
-&lt;ENTER&gt;);</p>
-<div class="EXAMPLE"><a name="MMEUS" id="MMEUS"></a>
-<p><b>Example 24. Menu User Pointer Usage</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;curses.h&gt;
-#include &lt;menu.h&gt;
-
-#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
-#define CTRLD 4
-
-char *choices[] = {
- "Choice 1",
- "Choice 2",
- "Choice 3",
- "Choice 4",
- "Choice 5",
- "Choice 6",
- "Choice 7",
- "Exit",
- };
-void func(char *name);
-
-int main()
-{ ITEM **my_items;
- int c;
- MENU *my_menu;
- int n_choices, i;
- ITEM *cur_item;
-
- /* Initialize curses */
- initscr();
- start_color();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
- init_pair(1, COLOR_RED, COLOR_BLACK);
- init_pair(2, COLOR_GREEN, COLOR_BLACK);
- init_pair(3, COLOR_MAGENTA, COLOR_BLACK);
-
- /* Initialize items */
- n_choices = ARRAY_SIZE(choices);
- my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));
- for(i = 0; i &lt; n_choices; ++i)
- { my_items[i] = new_item(choices[i], choices[i]);
- /* Set the user pointer */
- set_item_userptr(my_items[i], func);
- }
- my_items[n_choices] = (ITEM *)NULL;
-
- /* Create menu */
- my_menu = new_menu((ITEM **)my_items);
-
- /* Post the menu */
- mvprintw(LINES - 3, 0, "Press &lt;ENTER&gt; to see the option selected");
- mvprintw(LINES - 2, 0, "Up and Down arrow keys to naviage (F1 to Exit)");
- post_menu(my_menu);
- refresh();
-
- while((c = getch()) != KEY_F(1))
- { switch(c)
- { case KEY_DOWN:
- menu_driver(my_menu, REQ_DOWN_ITEM);
- break;
- case KEY_UP:
- menu_driver(my_menu, REQ_UP_ITEM);
- break;
- case 10: /* Enter */
- { ITEM *cur;
- void (*p)(char *);
-
- cur = current_item(my_menu);
- p = item_userptr(cur);
- p((char *)item_name(cur));
- pos_menu_cursor(my_menu);
- break;
- }
- break;
- }
- }
- unpost_menu(my_menu);
- for(i = 0; i &lt; n_choices; ++i)
- free_item(my_items[i]);
- free_menu(my_menu);
- endwin();
-}
-
-void func(char *name)
-{ move(20, 0);
- clrtoeol();
- mvprintw(20, 0, "Item selected is : %s", name);
-} </span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="FORMS" id="FORMS">18. Forms
-Library</a></h2>
-<p>Well. If you have seen those forms on web pages which take input
-from users and do various kinds of things, you might be wondering
-how would any one create such forms in text mode display. It's
-quite difficult to write those nifty forms in plain ncurses. Forms
-library tries to provide a basic frame work to build and maintain
-forms with ease. It has lot of features(functions) which manage
-validation, dynamic expansion of fields etc.. Let's see it in full
-flow.</p>
-<p>A form is a collection of fields; each field can be either a
-label(static text) or a data-entry location. The forms also library
-provides functions to divide forms into multiple pages.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="FORMBASICS" id="FORMBASICS">18.1. The
-Basics</a></h3>
-<p>Forms are created in much the same way as menus. First the
-fields related to the form are created with new_field(). You can
-set options for the fields, so that they can be displayed with some
-fancy attributes, validated before the field looses focus etc..
-Then the fields are attached to form. After this, the form can be
-posted to display and is ready to receive inputs. On the similar
-lines to menu_driver(), the form is manipulated with form_driver().
-We can send requests to form_driver to move focus to a certain
-field, move cursor to end of the field etc.. After the user enters
-values in the fields and validation done, form can be unposted and
-memory allocated can be freed.</p>
-<p>The general flow of control of a forms program looks like
-this.</p>
-<ol type="1">
-<li>
-<p>Initialize curses</p>
-</li>
-<li>
-<p>Create fields using new_field(). You can specify the height and
-width of the field, and its position on the form.</p>
-</li>
-<li>
-<p>Create the forms with new_form() by specifying the fields to be
-attached with.</p>
-</li>
-<li>
-<p>Post the form with form_post() and refresh the screen.</p>
-</li>
-<li>
-<p>Process the user requests with a loop and do necessary updates
-to form with form_driver.</p>
-</li>
-<li>
-<p>Unpost the menu with form_unpost()</p>
-</li>
-<li>
-<p>Free the memory allocated to menu by free_form()</p>
-</li>
-<li>
-<p>Free the memory allocated to the items with free_field()</p>
-</li>
-<li>
-<p>End curses</p>
-</li>
-</ol>
-<p>As you can see, working with forms library is much similar to
-handling menu library. The following examples will explore various
-aspects of form processing. Let's start the journey with a simple
-example. first.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="COMPILEFORMS" id="COMPILEFORMS">18.2.
-Compiling With the Forms Library</a></h3>
-<p>To use forms library functions, you have to include form.h and
-to link the program with forms library the flag -lform should be
-added along with -lncurses in that order.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> #include &lt;form.h&gt;
- .
- .
- .
-
- compile and link: gcc &lt;program file&gt; -lform -lncurses</font>
-</pre></td>
-</tr>
-</table>
-<div class="EXAMPLE"><a name="FFOSI" id="FFOSI"></a>
-<p><b>Example 25. Forms Basics</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;form.h&gt;
-
-int main()
-{ FIELD *field[3];
- FORM *my_form;
- int ch;
-
- /* Initialize curses */
- initscr();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
-
- /* Initialize the fields */
- field[0] = new_field(1, 10, 4, 18, 0, 0);
- field[1] = new_field(1, 10, 6, 18, 0, 0);
- field[2] = NULL;
-
- /* Set field options */
- set_field_back(field[0], A_UNDERLINE); /* Print a line for the option */
- field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */
- /* Field is filled up */
- set_field_back(field[1], A_UNDERLINE);
- field_opts_off(field[1], O_AUTOSKIP);
-
- /* Create the form and post it */
- my_form = new_form(field);
- post_form(my_form);
- refresh();
-
- mvprintw(4, 10, "Value 1:");
- mvprintw(6, 10, "Value 2:");
- refresh();
-
- /* Loop through to get user requests */
- while((ch = getch()) != KEY_F(1))
- { switch(ch)
- { case KEY_DOWN:
- /* Go to next field */
- form_driver(my_form, REQ_NEXT_FIELD);
- /* Go to the end of the present buffer */
- /* Leaves nicely at the last character */
- form_driver(my_form, REQ_END_LINE);
- break;
- case KEY_UP:
- /* Go to previous field */
- form_driver(my_form, REQ_PREV_FIELD);
- form_driver(my_form, REQ_END_LINE);
- break;
- default:
- /* If this is a normal character, it gets */
- /* Printed */
- form_driver(my_form, ch);
- break;
- }
- }
-
- /* Un post form and free the memory */
- unpost_form(my_form);
- free_form(my_form);
- free_field(field[0]);
- free_field(field[1]);
-
- endwin();
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Above example is pretty straight forward. It creates two fields
-with <var class="LITERAL">new_field()</var>. new_field() takes
-height, width, starty, startx, number of offscreen rows and number
-of additional working buffers. The fifth argument number of
-offscreen rows specifies how much of the field to be shown. If it
-is zero, the entire field is always displayed otherwise the form
-will be scrollable when the user accesses not displayed parts of
-the field. The forms library allocates one buffer per field to
-store the data user enters. Using the last parameter to new_field()
-we can specify it to allocate some additional buffers. These can be
-used for any purpose you like.</p>
-<p>After creating the fields, back ground attribute of both of them
-is set to an underscore with set_field_back(). The AUTOSKIP option
-is turned off using field_opts_off(). If this option is turned on,
-focus will move to the next field in the form once the active field
-is filled up completely.</p>
-<p>After attaching the fields to the form, it is posted. Here on,
-user inputs are processed in the while loop, by making
-corresponding requests to form_driver. The details of all the
-requests to the form_driver() are explained later.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PLAYFIELDS" id="PLAYFIELDS">18.3.
-Playing with Fields</a></h3>
-<p>Each form field is associated with a lot of attributes. They can
-be manipulated to get the required effect and to have fun !!!. So
-why wait?</p>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="FETCHINFO" id="FETCHINFO">18.3.1.
-Fetching Size and Location of Field</a></h4>
-<p>The parameters we have given at the time of creation of a field
-can be retrieved with field_info(). It returns height, width,
-starty, startx, number of offscreen rows, and number of additional
-buffers into the parameters given to it. It is a sort of inverse of
-new_field().</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int field_info( FIELD *field, /* field from which to fetch */
- int *height, *int width, /* field size */
- int *top, int *left, /* upper left corner */
- int *offscreen, /* number of offscreen rows */
- int *nbuf); /* number of working buffers */</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="MOVEFIELD" id="MOVEFIELD">18.3.2. Moving
-the field</a></h4>
-<p>The location of the field can be moved to a different position
-with move_field().</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int move_field( FIELD *field, /* field to alter */
- int top, int left); /* new upper-left corner */</font>
-</pre></td>
-</tr>
-</table>
-<p>As usual, the changed position can be queried with
-field_infor().</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="JUSTIFYFIELD" id="JUSTIFYFIELD">18.3.3.
-Field Justification</a></h4>
-<p>The justification to be done for the field can be fixed using
-the function set_field_just().</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"> int set_field_just(FIELD *field, /* field to alter */
- int justmode); /* mode to set */
- int field_just(FIELD *field); /* fetch justify mode of field */</font>
-</pre></td>
-</tr>
-</table>
-<p>The justification mode valued accepted and returned by these
-functions are NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or
-JUSTIFY_CENTER.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="FIELDDISPATTRIB" id=
-"FIELDDISPATTRIB">18.3.4. Field Display Attributes</a></h4>
-<p>As you have seen, in the above example, display attribute for
-the fields can be set with set_field_fore() and setfield_back().
-These functions set foreground and background attribute of the
-fields. You can also specify a pad character which will be filled
-in the unfilled portion of the field. The pad character is set with
-a call to set_field_pad(). Default pad value is a space. The
-functions field_fore(), field_back, field_pad() can be used to
-query the present foreground, background attributes and pad
-character for the field. The following list gives the usage of
-functions.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">&#13;int set_field_fore(FIELD *field, /* field to alter */
- chtype attr); /* attribute to set */
-
-chtype field_fore(FIELD *field); /* field to query */
- /* returns foreground attribute */
-
-int set_field_back(FIELD *field, /* field to alter */
- chtype attr); /* attribute to set */
-
-chtype field_back(FIELD *field); /* field to query */
- /* returns background attribute */
-
-int set_field_pad(FIELD *field, /* field to alter */
- int pad); /* pad character to set */
-
-chtype field_pad(FIELD *field); /* field to query */
- /* returns present pad character */&#13;</font>
-</pre></td>
-</tr>
-</table>
-<p>Though above functions seem quite simple, using colors with
-set_field_fore() may be frustrating in the beginning. Let me first
-explain about foreground and background attributes of a field. The
-foreground attribute is associated with the character. That means a
-character in the field is printed with the attribute you have set
-with set_field_fore(). Background attribute is the attribute used
-to fill background of field, whether any character is there or not.
-So what about colors? Since colors are always defined in pairs,
-what is the right way to display colored fields? Here's an example
-clarifying color attributes.</p>
-<div class="EXAMPLE"><a name="FFOAT" id="FFOAT"></a>
-<p><b>Example 26. Form Attributes example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;form.h&gt;
-
-int main()
-{ FIELD *field[3];
- FORM *my_form;
- int ch;
-
- /* Initialize curses */
- initscr();
- start_color();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
-
- /* Initialize few color pairs */
- init_pair(1, COLOR_WHITE, COLOR_BLUE);
- init_pair(2, COLOR_WHITE, COLOR_BLUE);
-
- /* Initialize the fields */
- field[0] = new_field(1, 10, 4, 18, 0, 0);
- field[1] = new_field(1, 10, 6, 18, 0, 0);
- field[2] = NULL;
-
- /* Set field options */
- set_field_fore(field[0], COLOR_PAIR(1));/* Put the field with blue background */
- set_field_back(field[0], COLOR_PAIR(2));/* and white foreground (characters */
- /* are printed in white */
- field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */
- /* Field is filled up */
- set_field_back(field[1], A_UNDERLINE);
- field_opts_off(field[1], O_AUTOSKIP);
-
- /* Create the form and post it */
- my_form = new_form(field);
- post_form(my_form);
- refresh();
-
- set_current_field(my_form, field[0]); /* Set focus to the colored field */
- mvprintw(4, 10, "Value 1:");
- mvprintw(6, 10, "Value 2:");
- mvprintw(LINES - 2, 0, "Use UP, DOWN arrow keys to switch between fields");
- refresh();
-
- /* Loop through to get user requests */
- while((ch = getch()) != KEY_F(1))
- { switch(ch)
- { case KEY_DOWN:
- /* Go to next field */
- form_driver(my_form, REQ_NEXT_FIELD);
- /* Go to the end of the present buffer */
- /* Leaves nicely at the last character */
- form_driver(my_form, REQ_END_LINE);
- break;
- case KEY_UP:
- /* Go to previous field */
- form_driver(my_form, REQ_PREV_FIELD);
- form_driver(my_form, REQ_END_LINE);
- break;
- default:
- /* If this is a normal character, it gets */
- /* Printed */
- form_driver(my_form, ch);
- break;
- }
- }
-
- /* Un post form and free the memory */
- unpost_form(my_form);
- free_form(my_form);
- free_field(field[0]);
- free_field(field[1]);
-
- endwin();
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Play with the color pairs and try to understand the foreground
-and background attributes. In my programs using color attributes, I
-usually set only the background with set_field_back(). Curses
-simply doesn't allow defining individual color attributes.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="FIELDOPTIONBITS" id=
-"FIELDOPTIONBITS">18.3.5. Field Option Bits</a></h4>
-<p>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:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_field_opts(FIELD *field, /* field to alter */
- int attr); /* attribute to set */
-
-int field_opts_on(FIELD *field, /* field to alter */
- int attr); /* attributes to turn on */
-
-int field_opts_off(FIELD *field, /* field to alter */
- int attr); /* attributes to turn off */
-
-int field_opts(FIELD *field); /* field to query */ </font>
-</pre></td>
-</tr>
-</table>
-<p>The function set_field_opts() can be used to directly set
-attributes of a field or you can choose to switch a few attributes
-on and off with field_opts_on() and field_opts_off() selectively.
-Anytime you can query the attributes of a field with field_opts().
-The following is the list of available options. By default, all
-options are on.</p>
-<div class="VARIABLELIST">
-<dl>
-<dt>O_VISIBLE</dt>
-<dd>
-<p>Controls whether the field is visible on the screen. Can be used
-during form processing to hide or pop up fields depending on the
-value of parent fields.</p>
-</dd>
-<dt>O_ACTIVE</dt>
-<dd>
-<p>Controls whether the field is active during forms processing
-(i.e. visited by form navigation keys). Can be used to make labels
-or derived fields with buffer values alterable by the forms
-application, not the user.</p>
-</dd>
-<dt>O_PUBLIC</dt>
-<dd>
-<p>Controls whether data is displayed during field entry. If this
-option is turned off on a field, the library will accept and edit
-data in that field, but it will not be displayed and the visible
-field cursor will not move. You can turn off the O_PUBLIC bit to
-define password fields.</p>
-</dd>
-<dt>O_EDIT</dt>
-<dd>
-<p>Controls whether the field's data can be modified. When this
-option is off, all editing requests except <var class=
-"LITERAL">REQ_PREV_CHOICE</var> and <var class=
-"LITERAL">REQ_NEXT_CHOICE</var>will fail. Such read-only fields may
-be useful for help messages.</p>
-</dd>
-<dt>O_WRAP</dt>
-<dd>
-<p>Controls word-wrapping in multi-line fields. Normally, when any
-character of a (blank-separated) word reaches the end of the
-current line, the entire word is wrapped to the next line (assuming
-there is one). When this option is off, the word will be split
-across the line break.</p>
-</dd>
-<dt>O_BLANK</dt>
-<dd>
-<p>Controls field blanking. When this option is on, entering a
-character at the first field position erases the entire field
-(except for the just-entered character).</p>
-</dd>
-<dt>O_AUTOSKIP</dt>
-<dd>
-<p>Controls automatic skip to next field when this one fills.
-Normally, when the forms user tries to type more data into a field
-than will fit, the editing location jumps to next field. When this
-option is off, the user's cursor will hang at the end of the field.
-This option is ignored in dynamic fields that have not reached
-their size limit.</p>
-</dd>
-<dt>O_NULLOK</dt>
-<dd>
-<p>Controls whether validation is applied to blank fields.
-Normally, it is not; the user can leave a field blank without
-invoking the usual validation check on exit. If this option is off
-on a field, exit from it will invoke a validation check.</p>
-</dd>
-<dt>O_PASSOK</dt>
-<dd>
-<p>Controls whether validation occurs on every exit, or only after
-the field is modified. Normally the latter is true. Setting
-O_PASSOK may be useful if your field's validation function may
-change during forms processing.</p>
-</dd>
-<dt>O_STATIC</dt>
-<dd>
-<p>Controls whether the field is fixed to its initial dimensions.
-If you turn this off, the field becomes dynamic and will stretch to
-fit entered data.</p>
-</dd>
-</dl>
-</div>
-<p>A field's options cannot be changed while the field is currently
-selected. However, options may be changed on posted fields that are
-not current.</p>
-<p>The option values are bit-masks and can be composed with
-logical-or in the obvious way. You have seen the usage of switching
-off O_AUTOSKIP option. The following example clarifies usage of
-some more options. Other options are explained where
-appropriate.</p>
-<div class="EXAMPLE"><a name="FFOOP" id="FFOOP"></a>
-<p><b>Example 27. Field Options Usage example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;form.h&gt;
-
-#define STARTX 15
-#define STARTY 4
-#define WIDTH 25
-
-#define N_FIELDS 3
-
-int main()
-{ FIELD *field[N_FIELDS];
- FORM *my_form;
- int ch, i;
-
- /* Initialize curses */
- initscr();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
-
- /* Initialize the fields */
- for(i = 0; i &lt; N_FIELDS - 1; ++i)
- field[i] = new_field(1, WIDTH, STARTY + i * 2, STARTX, 0, 0);
- field[N_FIELDS - 1] = NULL;
-
- /* Set field options */
- set_field_back(field[1], A_UNDERLINE); /* Print a line for the option */
-
- field_opts_off(field[0], O_ACTIVE); /* This field is a static label */
- field_opts_off(field[1], O_PUBLIC); /* This filed is like a password field*/
- field_opts_off(field[1], O_AUTOSKIP); /* To avoid entering the same field */
- /* after last character is entered */
-
- /* Create the form and post it */
- my_form = new_form(field);
- post_form(my_form);
- refresh();
-
- set_field_just(field[0], JUSTIFY_CENTER); /* Center Justification */
- set_field_buffer(field[0], 0, "This is a static Field");
- /* Initialize the field */
- mvprintw(STARTY, STARTX - 10, "Field 1:");
- mvprintw(STARTY + 2, STARTX - 10, "Field 2:");
- refresh();
-
- /* Loop through to get user requests */
- while((ch = getch()) != KEY_F(1))
- { switch(ch)
- { case KEY_DOWN:
- /* Go to next field */
- form_driver(my_form, REQ_NEXT_FIELD);
- /* Go to the end of the present buffer */
- /* Leaves nicely at the last character */
- form_driver(my_form, REQ_END_LINE);
- break;
- case KEY_UP:
- /* Go to previous field */
- form_driver(my_form, REQ_PREV_FIELD);
- form_driver(my_form, REQ_END_LINE);
- break;
- default:
- /* If this is a normal character, it gets */
- /* Printed */
- form_driver(my_form, ch);
- break;
- }
- }
-
- /* Un post form and free the memory */
- unpost_form(my_form);
- free_form(my_form);
- free_field(field[0]);
- free_field(field[1]);
-
- endwin();
- return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>This example, though useless, shows the usage of options. If
-used properly, they can present information very effectively in a
-form. The second field being not O_PUBLIC, does not show the
-characters you are typing.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="FIELDSTATUS" id="FIELDSTATUS">18.3.6.
-Field Status</a></h4>
-<p>The field status specifies whether the field has got edited or
-not. It is initially set to FALSE and when user enters something
-and the data buffer gets modified it becomes TRUE. So a field's
-status can be queried to find out whether it has been modified or
-not. The following functions can assist in those operations.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_field_status(FIELD *field, /* field to alter */
- int status); /* status to set */
-
-int field_status(FIELD *field); /* fetch status of field */</font>
-</pre></td>
-</tr>
-</table>
-<p>It's better to check the field's status only after after leaving
-the field, as data buffer might not have been updated yet as the
-validation is still due. To guarantee that right status is
-returned, call field_status() either (1) in the field's exit
-validation check routine, (2) from the field's or form's
-initialization or termination hooks, or (3) just after a
-REQ_VALIDATION request has been processed by the forms driver</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="FIELDUSERPTR" id="FIELDUSERPTR">18.3.7.
-Field User Pointer</a></h4>
-<p>Every field structure contains one pointer that can be used by
-the user for various purposes. It is not touched by forms library
-and can be used for any purpose by the user. The following
-functions set and fetch user pointer.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000">int set_field_userptr(FIELD *field,
- char *userptr); /* the user pointer you wish to associate */
- /* with the field */
-
-char *field_userptr(FIELD *field); /* fetch user pointer of the field */</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="VARIABLESIZEFIELDS" id=
-"VARIABLESIZEFIELDS">18.3.8. Variable-Sized Fields</a></h4>
-<p>If you want a dynamically changing field with variable width,
-this is the feature you want to put to full use. This will allow
-the user to enter more data than the original size of the field and
-let the field grow. According to the field orientation it will
-scroll horizontally or vertically to incorporate the new data.</p>
-<p>To make a field dynamically growable, the option O_STATIC should
-be turned off. This can be done with a</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"> field_opts_off(field_pointer, O_STATIC);</font>
-</pre></td>
-</tr>
-</table>
-<p>But it's usually not advisable to allow a field to grow
-infinitely. You can set a maximum limit to the growth of the field
-with</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_max_field(FIELD *field, /* Field on which to operate */
- int max_growth); /* maximum growth allowed for the field */</font>
-</pre></td>
-</tr>
-</table>
-<p>The field info for a dynamically growable field can be retrieved
-by</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int dynamic_field_info( FIELD *field, /* Field on which to operate */
- int *prows, /* number of rows will be filled in this */
- int *pcols, /* number of columns will be filled in this*/
- int *pmax) /* maximum allowable growth will be filled */
- /* in this */</font>
-</pre></td>
-</tr>
-</table>
-Though field_info work as usual, it is advisable to use this
-function to get the proper attributes of a dynamically growable
-field.
-<p>Recall the library routine new_field; a new field created with
-height set to one will be defined to be a one line field. A new
-field created with height greater than one will be defined to be a
-multi line field.</p>
-<p>A one line field with O_STATIC turned off (dynamically growable
-field) will contain a single fixed row, but the number of columns
-can increase if the user enters more data than the initial field
-will hold. The number of columns displayed will remain fixed and
-the additional data will scroll horizontally.</p>
-<p>A multi line field with O_STATIC turned off (dynamically
-growable field) will contain a fixed number of columns, but the
-number of rows can increase if the user enters more data than the
-initial field will hold. The number of rows displayed will remain
-fixed and the additional data will scroll vertically.</p>
-<p>The above two paragraphs pretty much describe a dynamically
-growable field's behavior. The way other parts of forms library
-behaves is described below:</p>
-<ol type="1">
-<li>
-<p>The field option O_AUTOSKIP will be ignored if the option
-O_STATIC is off and there is no maximum growth specified for the
-field. Currently, O_AUTOSKIP generates an automatic REQ_NEXT_FIELD
-form driver request when the user types in the last character
-position of a field. On a growable field with no maximum growth
-specified, there is no last character position. If a maximum growth
-is specified, the O_AUTOSKIP option will work as normal if the
-field has grown to its maximum size.</p>
-</li>
-<li>
-<p>The field justification will be ignored if the option O_STATIC
-is off. Currently, set_field_just can be used to JUSTIFY_LEFT,
-JUSTIFY_RIGHT, JUSTIFY_CENTER the contents of a one line field. A
-growable one line field will, by definition, grow and scroll
-horizontally and may contain more data than can be justified. The
-return from field_just will be unchanged.</p>
-</li>
-<li>
-<p>The overloaded form driver request REQ_NEW_LINE will operate the
-same way regardless of the O_NL_OVERLOAD form option if the field
-option O_STATIC is off and there is no maximum growth specified for
-the field. Currently, if the form option O_NL_OVERLOAD is on,
-REQ_NEW_LINE implicitly generates a REQ_NEXT_FIELD if called from
-the last line of a field. If a field can grow without bound, there
-is no last line, so REQ_NEW_LINE will never implicitly generate a
-REQ_NEXT_FIELD. If a maximum growth limit is specified and the
-O_NL_OVERLOAD form option is on, REQ_NEW_LINE will only implicitly
-generate REQ_NEXT_FIELD if the field has grown to its maximum size
-and the user is on the last line.</p>
-</li>
-<li>
-<p>The library call dup_field will work as usual; it will duplicate
-the field, including the current buffer size and contents of the
-field being duplicated. Any specified maximum growth will also be
-duplicated.</p>
-</li>
-<li>
-<p>The library call link_field will work as usual; it will
-duplicate all field attributes and share buffers with the field
-being linked. If the O_STATIC field option is subsequently changed
-by a field sharing buffers, how the system reacts to an attempt to
-enter more data into the field than the buffer will currently hold
-will depend on the setting of the option in the current field.</p>
-</li>
-<li>
-<p>The library call field_info will work as usual; the variable
-nrow will contain the value of the original call to new_field. The
-user should use dynamic_field_info, described above, to query the
-current size of the buffer.</p>
-</li>
-</ol>
-<p>Some of the above points make sense only after explaining form
-driver. We will be looking into that in next few sections.</p>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="FORMWINDOWS" id="FORMWINDOWS">18.4. Form
-Windows</a></h3>
-<p>The form windows concept is pretty much similar to menu windows.
-Every form is associated with a main window and a sub window. The
-form main window displays any title or border associated or
-whatever the user wishes. Then the sub window contains all the
-fields and displays them according to their position. This gives
-the flexibility of manipulating fancy form displaying very
-easily.</p>
-<p>Since this is pretty much similar to menu windows, I am
-providing an example with out much explanation. The functions are
-similar and they work the same way.</p>
-<div class="EXAMPLE"><a name="FFOWI" id="FFOWI"></a>
-<p><b>Example 28. Form Windows Example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include &lt;form.h&gt;
-
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
-
-int main()
-{
- FIELD *field[3];
- FORM *my_form;
- WINDOW *my_form_win;
- int ch, rows, cols;
-
- /* Initialize curses */
- initscr();
- start_color();
- cbreak();
- noecho();
- keypad(stdscr, TRUE);
-
- /* Initialize few color pairs */
- init_pair(1, COLOR_RED, COLOR_BLACK);
-
- /* Initialize the fields */
- field[0] = new_field(1, 10, 6, 1, 0, 0);
- field[1] = new_field(1, 10, 8, 1, 0, 0);
- field[2] = NULL;
-
- /* Set field options */
- set_field_back(field[0], A_UNDERLINE);
- field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */
- /* Field is filled up */
- set_field_back(field[1], A_UNDERLINE);
- field_opts_off(field[1], O_AUTOSKIP);
-
- /* Create the form and post it */
- my_form = new_form(field);
-
- /* Calculate the area required for the form */
- scale_form(my_form, &amp;rows, &amp;cols);
-
- /* Create the window to be associated with the form */
- my_form_win = newwin(rows + 4, cols + 4, 4, 4);
- keypad(my_form_win, TRUE);
-
- /* Set main window and sub window */
- set_form_win(my_form, my_form_win);
- set_form_sub(my_form, derwin(my_form_win, rows, cols, 2, 2));
-
- /* Print a border around the main window and print a title */
- box(my_form_win, 0, 0);
- print_in_middle(my_form_win, 1, 0, cols + 4, "My Form", COLOR_PAIR(1));
-
- post_form(my_form);
- wrefresh(my_form_win);
-
- mvprintw(LINES - 2, 0, "Use UP, DOWN arrow keys to switch between fields");
- refresh();
-
- /* Loop through to get user requests */
- while((ch = wgetch(my_form_win)) != KEY_F(1))
- { switch(ch)
- { case KEY_DOWN:
- /* Go to next field */
- form_driver(my_form, REQ_NEXT_FIELD);
- /* Go to the end of the present buffer */
- /* Leaves nicely at the last character */
- form_driver(my_form, REQ_END_LINE);
- break;
- case KEY_UP:
- /* Go to previous field */
- form_driver(my_form, REQ_PREV_FIELD);
- form_driver(my_form, REQ_END_LINE);
- break;
- default:
- /* If this is a normal character, it gets */
- /* Printed */
- form_driver(my_form, ch);
- break;
- }
- }
-
- /* Un post form and free the memory */
- unpost_form(my_form);
- free_form(my_form);
- free_field(field[0]);
- free_field(field[1]);
-
- endwin();
- return 0;
-}
-
-void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
-{ int length, x, y;
- float temp;
-
- if(win == NULL)
- win = stdscr;
- getyx(win, y, x);
- if(startx != 0)
- x = startx;
- if(starty != 0)
- y = starty;
- if(width == 0)
- width = 80;
-
- length = strlen(string);
- temp = (width - length)/ 2;
- x = startx + (int)temp;
- wattron(win, color);
- mvwprintw(win, y, x, "%s", string);
- wattroff(win, color);
- refresh();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="FILEDVALIDATE" id="FILEDVALIDATE">18.5.
-Field Validation</a></h3>
-<p>By default, a field will accept any data input by the user. It
-is possible to attach validation to the field. Then any attempt by
-the user to leave the field, while it contains data that doesn't
-match the validation type will fail. Some validation types also
-have a character-validity check for each time a character is
-entered in the field.</p>
-<p>Validation can be attached to a field with the following
-function.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_field_type(FIELD *field, /* field to alter */
- FIELDTYPE *ftype, /* type to associate */
- ...); /* additional arguments*/</font>
-</pre></td>
-</tr>
-</table>
-Once set, the validation type for a field can be queried with
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">FIELDTYPE *field_type(FIELD *field); /* field to query */</font>
-</pre></td>
-</tr>
-</table>
-<p>The form driver validates the data in a field only when data is
-entered by the end-user. Validation does not occur when</p>
-<ul>
-<li>
-<p>the application program changes the field value by calling
-set_field_buffer.</p>
-</li>
-<li>
-<p>linked field values are changed indirectly -- by changing the
-field to which they are linked</p>
-</li>
-</ul>
-<p>The following are the pre-defined validation types. You can also
-specify custom validation, though it's a bit tricky and
-cumbersome.</p>
-<h1 class="BRIDGEHEAD"><a name="AEN1069" id=
-"AEN1069"></a>TYPE_ALPHA</h1>
-<p>This field type accepts alphabetic data; no blanks, no digits,
-no special characters (this is checked at character-entry time). It
-is set up with:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_field_type(FIELD *field, /* field to alter */
- TYPE_ALPHA, /* type to associate */
- int width); /* maximum width of field */</font>
-</pre></td>
-</tr>
-</table>
-<p>The width argument sets a minimum width of data. The user has to
-enter at-least width number of characters before he can leave the
-field. Typically you'll want to set this to the field width; if
-it's greater than the field width, the validation check will always
-fail. A minimum width of zero makes field completion optional.</p>
-<h1 class="BRIDGEHEAD"><a name="AEN1073" id=
-"AEN1073"></a>TYPE_ALNUM</h1>
-<p>This field type accepts alphabetic data and digits; no blanks,
-no special characters (this is checked at character-entry time). It
-is set up with:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_field_type(FIELD *field, /* field to alter */
- TYPE_ALNUM, /* type to associate */
- int width); /* maximum width of field */</font>
-</pre></td>
-</tr>
-</table>
-<p>The width argument sets a minimum width of data. As with
-TYPE_ALPHA, typically you'll want to set this to the field width;
-if it's greater than the field width, the validation check will
-always fail. A minimum width of zero makes field completion
-optional.</p>
-<h1 class="BRIDGEHEAD"><a name="AEN1077" id=
-"AEN1077"></a>TYPE_ENUM</h1>
-<p>This type allows you to restrict a field's values to be among a
-specified set of string values (for example, the two-letter postal
-codes for U.S. states). It is set up with:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_field_type(FIELD *field, /* field to alter */
- TYPE_ENUM, /* type to associate */
- char **valuelist; /* list of possible values */
- int checkcase; /* case-sensitive? */
- int checkunique); /* must specify uniquely? */</font>
-</pre></td>
-</tr>
-</table>
-<p>The valuelist parameter must point at a NULL-terminated list of
-valid strings. The checkcase argument, if true, makes comparison
-with the string case-sensitive.</p>
-<p>When the user exits a TYPE_ENUM field, the validation procedure
-tries to complete the data in the buffer to a valid entry. If a
-complete choice string has been entered, it is of course valid. But
-it is also possible to enter a prefix of a valid string and have it
-completed for you.</p>
-<p>By default, if you enter such a prefix and it matches more than
-one value in the string list, the prefix will be completed to the
-first matching value. But the checkunique argument, if true,
-requires prefix matches to be unique in order to be valid.</p>
-<p>The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be
-particularly useful with these fields.</p>
-<h1 class="BRIDGEHEAD"><a name="AEN1084" id=
-"AEN1084"></a>TYPE_INTEGER</h1>
-<p>This field type accepts an integer. It is set up as follows:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_field_type(FIELD *field, /* field to alter */
- TYPE_INTEGER, /* type to associate */
- int padding, /* # places to zero-pad to */
- int vmin, int vmax); /* valid range */</font>
-</pre></td>
-</tr>
-</table>
-<p>Valid characters consist of an optional leading minus and
-digits. The range check is performed on exit. If the range maximum
-is less than or equal to the minimum, the range is ignored.</p>
-<p>If the value passes its range check, it is padded with as many
-leading zero digits as necessary to meet the padding argument.</p>
-<p>A TYPE_INTEGER value buffer can conveniently be interpreted with
-the C library function atoi(3).</p>
-<h1 class="BRIDGEHEAD"><a name="AEN1090" id=
-"AEN1090"></a>TYPE_NUMERIC</h1>
-<p>This field type accepts a decimal number. It is set up as
-follows:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_field_type(FIELD *field, /* field to alter */
- TYPE_NUMERIC, /* type to associate */
- int padding, /* # places of precision */
- int vmin, int vmax); /* valid range */</font>
-</pre></td>
-</tr>
-</table>
-<p>Valid characters consist of an optional leading minus and
-digits. possibly including a decimal point. The range check is
-performed on exit. If the range maximum is less than or equal to
-the minimum, the range is ignored.</p>
-<p>If the value passes its range check, it is padded with as many
-trailing zero digits as necessary to meet the padding argument.</p>
-<p>A TYPE_NUMERIC value buffer can conveniently be interpreted with
-the C library function atof(3).</p>
-<h1 class="BRIDGEHEAD"><a name="AEN1096" id=
-"AEN1096"></a>TYPE_REGEXP</h1>
-<p>This field type accepts data matching a regular expression. It
-is set up as follows:</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_field_type(FIELD *field, /* field to alter */
- TYPE_REGEXP, /* type to associate */
- char *regexp); /* expression to match */</font>
-</pre></td>
-</tr>
-</table>
-<p>The syntax for regular expressions is that of regcomp(3). The
-check for regular-expression match is performed on exit.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="FORMDRIVER" id="FORMDRIVER">18.6. Form
-Driver: The work horse of the forms system</a></h3>
-<p>As in the menu system, form_driver() plays a very important role
-in forms system. All types of requests to forms system should be
-funneled through form_driver().</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int form_driver(FORM *form, /* form on which to operate */
- int request) /* form request code */</font>
-</pre></td>
-</tr>
-</table>
-<p>As you have seen some of the examples above, you have to be in a
-loop looking for user input and then decide whether it's a field
-data or a form request. The form requests are then passed to
-form_driver() to do the work.</p>
-<p>The requests roughly can be divided into following categories.
-Different requests and their usage is explained below:</p>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="PAGENAVREQ" id="PAGENAVREQ">18.6.1. Page
-Navigation Requests</a></h4>
-<p>These requests cause page-level moves through the form,
-triggering display of a new form screen. A form can be made of
-multiple pages. If you have a big form with lot of fields and
-logical sections, then you can divide the form into pages. The
-function set_new_page() to set a new page at the field
-specified.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">int set_new_page(FIELD *field,/* Field at which page break to be set or unset */
- bool new_page_flag); /* should be TRUE to put a break */</font>
-</pre></td>
-</tr>
-</table>
-<p>The following requests allow you to move to different pages</p>
-<ul>
-<li>
-<p><em>REQ_NEXT_PAGE</em> Move to the next form page.</p>
-</li>
-<li>
-<p><em>REQ_PREV_PAGE</em> Move to the previous form page.</p>
-</li>
-<li>
-<p><em>REQ_FIRST_PAGE</em> Move to the first form page.</p>
-</li>
-<li>
-<p><em>REQ_LAST_PAGE</em> Move to the last form page.</p>
-</li>
-</ul>
-<p>These requests treat the list as cyclic; that is, REQ_NEXT_PAGE
-from the last page goes to the first, and REQ_PREV_PAGE from the
-first page goes to the last.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="INTERFIELDNAVREQ" id=
-"INTERFIELDNAVREQ">18.6.2. Inter-Field Navigation Requests</a></h4>
-<p>These requests handle navigation between fields on the same
-page.</p>
-<ul>
-<li>
-<p><em>REQ_NEXT_FIELD</em> Move to next field.</p>
-</li>
-<li>
-<p><em>REQ_PREV_FIELD</em> Move to previous field.</p>
-</li>
-<li>
-<p><em>REQ_FIRST_FIELD</em> Move to the first field.</p>
-</li>
-<li>
-<p><em>REQ_LAST_FIELD</em> Move to the last field.</p>
-</li>
-<li>
-<p><em>REQ_SNEXT_FIELD</em> Move to sorted next field.</p>
-</li>
-<li>
-<p><em>REQ_SPREV_FIELD</em> Move to sorted previous field.</p>
-</li>
-<li>
-<p><em>REQ_SFIRST_FIELD</em> Move to the sorted first field.</p>
-</li>
-<li>
-<p><em>REQ_SLAST_FIELD</em> Move to the sorted last field.</p>
-</li>
-<li>
-<p><em>REQ_LEFT_FIELD</em> Move left to field.</p>
-</li>
-<li>
-<p><em>REQ_RIGHT_FIELD</em> Move right to field.</p>
-</li>
-<li>
-<p><em>REQ_UP_FIELD</em> Move up to field.</p>
-</li>
-<li>
-<p><em>REQ_DOWN_FIELD</em> Move down to field.</p>
-</li>
-</ul>
-<p>These requests treat the list of fields on a page as cyclic;
-that is, REQ_NEXT_FIELD from the last field goes to the first, and
-REQ_PREV_FIELD from the first field goes to the last. The order of
-the fields for these (and the REQ_FIRST_FIELD and REQ_LAST_FIELD
-requests) is simply the order of the field pointers in the form
-array (as set up by new_form() or set_form_fields()</p>
-<p>It is also possible to traverse the fields as if they had been
-sorted in screen-position order, so the sequence goes left-to-right
-and top-to-bottom. To do this, use the second group of four
-sorted-movement requests.</p>
-<p>Finally, it is possible to move between fields using visual
-directions up, down, right, and left. To accomplish this, use the
-third group of four requests. Note, however, that the position of a
-form for purposes of these requests is its upper-left corner.</p>
-<p>For example, suppose you have a multi-line field B, and two
-single-line fields A and C on the same line with B, with A to the
-left of B and C to the right of B. A REQ_MOVE_RIGHT from A will go
-to B only if A, B, and C all share the same first line; otherwise
-it will skip over B to C.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="INTRAFIELDNAVREQ" id=
-"INTRAFIELDNAVREQ">18.6.3. Intra-Field Navigation Requests</a></h4>
-<p>These requests drive movement of the edit cursor within the
-currently selected field.</p>
-<ul>
-<li>
-<p><em>REQ_NEXT_CHAR</em> Move to next character.</p>
-</li>
-<li>
-<p><em>REQ_PREV_CHAR</em> Move to previous character.</p>
-</li>
-<li>
-<p><em>REQ_NEXT_LINE</em> Move to next line.</p>
-</li>
-<li>
-<p><em>REQ_PREV_LINE</em> Move to previous line.</p>
-</li>
-<li>
-<p><em>REQ_NEXT_WORD</em> Move to next word.</p>
-</li>
-<li>
-<p><em>REQ_PREV_WORD</em> Move to previous word.</p>
-</li>
-<li>
-<p><em>REQ_BEG_FIELD</em> Move to beginning of field.</p>
-</li>
-<li>
-<p><em>REQ_END_FIELD</em> Move to end of field.</p>
-</li>
-<li>
-<p><em>REQ_BEG_LINE</em> Move to beginning of line.</p>
-</li>
-<li>
-<p><em>REQ_END_LINE</em> Move to end of line.</p>
-</li>
-<li>
-<p><em>REQ_LEFT_CHAR</em> Move left in field.</p>
-</li>
-<li>
-<p><em>REQ_RIGHT_CHAR</em> Move right in field.</p>
-</li>
-<li>
-<p><em>REQ_UP_CHAR</em> Move up in field.</p>
-</li>
-<li>
-<p><em>REQ_DOWN_CHAR</em> Move down in field.</p>
-</li>
-</ul>
-<p>Each word is separated from the previous and next characters by
-whitespace. The commands to move to beginning and end of line or
-field look for the first or last non-pad character in their
-ranges.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="SCROLLREQ" id="SCROLLREQ">18.6.4.
-Scrolling Requests</a></h4>
-<p>Fields that are dynamic and have grown and fields explicitly
-created with offscreen rows are scrollable. One-line fields scroll
-horizontally; multi-line fields scroll vertically. Most scrolling
-is triggered by editing and intra-field movement (the library
-scrolls the field to keep the cursor visible). It is possible to
-explicitly request scrolling with the following requests:</p>
-<ul>
-<li>
-<p><em>REQ_SCR_FLINE</em> Scroll vertically forward a line.</p>
-</li>
-<li>
-<p><em>REQ_SCR_BLINE</em> Scroll vertically backward a line.</p>
-</li>
-<li>
-<p><em>REQ_SCR_FPAGE</em> Scroll vertically forward a page.</p>
-</li>
-<li>
-<p><em>REQ_SCR_BPAGE</em> Scroll vertically backward a page.</p>
-</li>
-<li>
-<p><em>REQ_SCR_FHPAGE</em> Scroll vertically forward half a
-page.</p>
-</li>
-<li>
-<p><em>REQ_SCR_BHPAGE</em> Scroll vertically backward half a
-page.</p>
-</li>
-<li>
-<p><em>REQ_SCR_FCHAR</em> Scroll horizontally forward a
-character.</p>
-</li>
-<li>
-<p><em>REQ_SCR_BCHAR</em> Scroll horizontally backward a
-character.</p>
-</li>
-<li>
-<p><em>REQ_SCR_HFLINE</em> Scroll horizontally one field width
-forward.</p>
-</li>
-<li>
-<p><em>REQ_SCR_HBLINE</em> Scroll horizontally one field width
-backward.</p>
-</li>
-<li>
-<p><em>REQ_SCR_HFHALF</em> Scroll horizontally one half field width
-forward.</p>
-</li>
-<li>
-<p><em>REQ_SCR_HBHALF</em> Scroll horizontally one half field width
-backward.</p>
-</li>
-</ul>
-<p>For scrolling purposes, a page of a field is the height of its
-visible part.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="EDITREQ" id="EDITREQ">18.6.5. Editing
-Requests</a></h4>
-<p>When you pass the forms driver an ASCII character, it is treated
-as a request to add the character to the field's data buffer.
-Whether this is an insertion or a replacement depends on the
-field's edit mode (insertion is the default.</p>
-<p>The following requests support editing the field and changing
-the edit mode:</p>
-<ul>
-<li>
-<p><em>REQ_INS_MODE</em> Set insertion mode.</p>
-</li>
-<li>
-<p><em>REQ_OVL_MODE</em> Set overlay mode.</p>
-</li>
-<li>
-<p><em>REQ_NEW_LINE</em> New line request (see below for
-explanation).</p>
-</li>
-<li>
-<p><em>REQ_INS_CHAR</em> Insert space at character location.</p>
-</li>
-<li>
-<p><em>REQ_INS_LINE</em> Insert blank line at character
-location.</p>
-</li>
-<li>
-<p><em>REQ_DEL_CHAR</em> Delete character at cursor.</p>
-</li>
-<li>
-<p><em>REQ_DEL_PREV</em> Delete previous word at cursor.</p>
-</li>
-<li>
-<p><em>REQ_DEL_LINE</em> Delete line at cursor.</p>
-</li>
-<li>
-<p><em>REQ_DEL_WORD</em> Delete word at cursor.</p>
-</li>
-<li>
-<p><em>REQ_CLR_EOL</em> Clear to end of line.</p>
-</li>
-<li>
-<p><em>REQ_CLR_EOF</em> Clear to end of field.</p>
-</li>
-<li>
-<p><em>REQ_CLR_FIELD</em> Clear entire field.</p>
-</li>
-</ul>
-<p>The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is
-complicated and partly controlled by a pair of forms options. The
-special cases are triggered when the cursor is at the beginning of
-a field, or on the last line of the field.</p>
-<p>First, we consider REQ_NEW_LINE:</p>
-<p>The normal behavior of REQ_NEW_LINE in insert mode is to break
-the current line at the position of the edit cursor, inserting the
-portion of the current line after the cursor as a new line
-following the current and moving the cursor to the beginning of
-that new line (you may think of this as inserting a newline in the
-field buffer).</p>
-<p>The normal behavior of REQ_NEW_LINE in overlay mode is to clear
-the current line from the position of the edit cursor to end of
-line. The cursor is then moved to the beginning of the next
-line.</p>
-<p>However, REQ_NEW_LINE at the beginning of a field, or on the
-last line of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD
-option is off, this special action is disabled.</p>
-<p>Now, let us consider REQ_DEL_PREV:</p>
-<p>The normal behavior of REQ_DEL_PREV is to delete the previous
-character. If insert mode is on, and the cursor is at the start of
-a line, and the text on that line will fit on the previous one, it
-instead appends the contents of the current line to the previous
-one and deletes the current line (you may think of this as deleting
-a newline from the field buffer).</p>
-<p>However, REQ_DEL_PREV at the beginning of a field is instead
-treated as a REQ_PREV_FIELD.</p>
-<p>If the O_BS_OVERLOAD option is off, this special action is
-disabled and the forms driver just returns E_REQUEST_DENIED.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="ORDERREQ" id="ORDERREQ">18.6.6. Order
-Requests</a></h4>
-<p>If the type of your field is ordered, and has associated
-functions for getting the next and previous values of the type from
-a given value, there are requests that can fetch that value into
-the field buffer:</p>
-<ul>
-<li>
-<p><em>REQ_NEXT_CHOICE</em> Place the successor value of the
-current value in the buffer.</p>
-</li>
-<li>
-<p><em>REQ_PREV_CHOICE</em> Place the predecessor value of the
-current value in the buffer.</p>
-</li>
-</ul>
-<p>Of the built-in field types, only TYPE_ENUM has built-in
-successor and predecessor functions. When you define a field type
-of your own (see Custom Validation Types), you can associate our
-own ordering functions.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="APPLICCOMMANDS" id=
-"APPLICCOMMANDS">18.6.7. Application Commands</a></h4>
-<p>Form requests are represented as integers above the curses value
-greater than KEY_MAX and less than or equal to the constant
-MAX_COMMAND. A value within this range gets ignored by
-form_driver(). So this can be used for any purpose by the
-application. It can be treated as an application specific action
-and take corresponding action.</p>
-</div>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="TOOLS" id="TOOLS">19. Tools and Widget
-Libraries</a></h2>
-<p>Now that you have seen the capabilities of ncurses and its
-sister libraries, you are rolling your sleeves up and gearing for a
-project that heavily manipulates screen. But wait.. It can be
-pretty difficult to write and maintain complex GUI widgets in plain
-ncurses or even with the additional libraries. There are some
-ready-to-use tools and widget libraries that can be used instead of
-writing your own widgets. You can use some of them, get ideas from
-the code, or even extend them.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="CDK" id="CDK">19.1. CDK (Curses
-Development Kit)</a></h3>
-<p>In the author's words</p>
-<p><em>CDK stands for 'Curses Development Kit' and it currently
-contains 21 ready to use widgets which facilitate the speedy
-development of full screen curses programs.</em></p>
-<p>The kit provides some useful widgets, which can be used in your
-programs directly. It's pretty well written and the documentation
-is very good. The examples in the examples directory can be a good
-place to start for beginners. The CDK can be downloaded from
-<a href="http://invisible-island.net/cdk/" target=
-"_top">http://invisible-island.net/cdk/</a> . Follow the
-instructions in README file to install it.</p>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="WIDGETLIST" id="WIDGETLIST">19.1.1.
-Widget List</a></h4>
-<p>The following is the list of widgets provided with cdk and their
-description.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000">Widget Type Quick Description
-===========================================================================
-Alphalist Allows a user to select from a list of words, with
- the ability to narrow the search list by typing in a
- few characters of the desired word.
-Buttonbox This creates a multiple button widget.
-Calendar Creates a little simple calendar widget.
-Dialog Prompts the user with a message, and the user
- can pick an answer from the buttons provided.
-Entry Allows the user to enter various types of information.
-File Selector A file selector built from Cdk base widgets. This
- example shows how to create more complicated widgets
- using the Cdk widget library.
-Graph Draws a graph.
-Histogram Draws a histogram.
-Item List Creates a pop up field which allows the user to select
- one of several choices in a small field. Very useful
- for things like days of the week or month names.
-Label Displays messages in a pop up box, or the label can be
- considered part of the screen.
-Marquee Displays a message in a scrolling marquee.
-Matrix Creates a complex matrix with lots of options.
-Menu Creates a pull-down menu interface.
-Multiple Line Entry A multiple line entry field. Very useful
- for long fields. (like a description
- field)
-Radio List Creates a radio button list.
-Scale Creates a numeric scale. Used for allowing a user to
- pick a numeric value and restrict them to a range of
- values.
-Scrolling List Creates a scrolling list/menu list.
-Scrolling Window Creates a scrolling log file viewer. Can add
- information into the window while its running.
- A good widget for displaying the progress of
- something. (akin to a console window)
-Selection List Creates a multiple option selection list.
-Slider Akin to the scale widget, this widget provides a
- visual slide bar to represent the numeric value.
-Template Creates a entry field with character sensitive
- positions. Used for pre-formatted fields like
- dates and phone numbers.
-Viewer This is a file/information viewer. Very useful
- when you need to display loads of information.
-===========================================================================</font>
-</pre></td>
-</tr>
-</table>
-<p>A few of the widgets are modified by Thomas Dickey in recent
-versions.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="CDKATTRACT" id="CDKATTRACT">19.1.2. Some
-Attractive Features</a></h4>
-<p>Apart from making our life easier with readily usable widgets,
-cdk solves one frustrating problem with printing multi colored
-strings, justified strings elegantly. Special formatting tags can
-be embedded in the strings which are passed to CDK functions. For
-Example</p>
-<p>If the string</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">"&lt;/B/1&gt;This line should have a yellow foreground and a blue
-background.&lt;!1&gt;"</font>
-</pre></td>
-</tr>
-</table>
-<p>given as a parameter to newCDKLabel(), it prints the line with
-yellow foreground and blue background. There are other tags
-available for justifying string, embedding special drawing
-characters etc.. Please refer to the man page cdk_display(3X) for
-details. The man page explains the usage with nice examples.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="CDKCONCLUSION" id=
-"CDKCONCLUSION">19.1.3. Conclusion</a></h4>
-<p>All in all, CDK is a well-written package of widgets, which if
-used properly can form a strong frame work for developing complex
-GUI.</p>
-</div>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="DIALOG" id="DIALOG">19.2. The
-dialog</a></h3>
-<p>Long long ago, in September 1994, when few people knew linux,
-Jeff Tranter wrote an <a href=
-"http://www2.linuxjournal.com/lj-issues/issue5/2807.html" target=
-"_top">article</a> on dialog in Linux Journal. He starts the
-article with these words..</p>
-<p><em>Linux is based on the Unix operating system, but also
-features a number of unique and useful kernel features and
-application programs that often go beyond what is available under
-Unix. One little-known gem is "dialog", a utility for creating
-professional-looking dialog boxes from within shell scripts. This
-article presents a tutorial introduction to the dialog utility, and
-shows examples of how and where it can be used</em></p>
-<p>As he explains, dialog is a real gem in making
-professional-looking dialog boxes with ease. It creates a variety
-of dialog boxes, menus, check lists etc.. It is usually installed
-by default. If not, you can download it from <a href=
-"http://invisible-island.net/dialog/" target="_top">Thomas
-Dickey</a>'s site.</p>
-<p>The above-mentioned article gives a very good overview of its
-uses and capabilites. The man page has more details. It can be used
-in variety of situations. One good example is building of linux
-kernel in text mode. Linux kernel uses a modified version of dialog
-tailored for its needs.</p>
-<p>dialog was initially designed to be used with shell scripts. If
-you want to use its functionality in a c program, then you can use
-libdialog. The documentation regarding this is sparse. Definitive
-reference is the dialog.h header file which comes with the library.
-You may need to hack here and there to get the required output. The
-source is easily customizable. I have used it on a number of
-occasions by modifying the code.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PERLCURSES" id="PERLCURSES">19.3. Perl
-Curses Modules CURSES::FORM and CURSES::WIDGETS</a></h3>
-<p>The perl module Curses, Curses::Form and Curses::Widgets give
-access to curses from perl. If you have curses and basic perl is
-installed, you can get these modules from <a href=
-"http://www.cpan.org/modules/01modules.index.html" target=
-"_top">CPAN All Modules page</a>. Get the three zipped modules in
-the Curses category. Once installed you can use these modules from
-perl scripts like any other module. For more information on perl
-modules see perlmod man page. The above modules come with good
-documentation and they have some demo scripts to test the
-functionality. Though the widgets provided are very rudimentary,
-these modules provide good access to curses library from perl.</p>
-<p>Some of my code examples are converted to perl by Anuradha
-Ratnaweera and they are available in the <var class=
-"LITERAL">perl</var> directory.</p>
-<p>For more information see man pages Curses(3) , Curses::Form(3)
-and Curses::Widgets(3). These pages are installed only when the
-above modules are acquired and installed.</p>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="JUSTFORFUN" id="JUSTFORFUN">20. Just For
-Fun !!!</a></h2>
-<p>This section contains few programs written by me just for fun.
-They don't signify a better programming practice or the best way of
-using ncurses. They are provided here so as to allow beginners to
-get ideas and add more programs to this section. If you have
-written a couple of nice, simple programs in curses and want them
-to included here, contact <a href="mailto:ppadala@gmail.com"
-target="_top">me</a>.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="GAMEOFLIFE" id="GAMEOFLIFE">20.1. The
-Game of Life</a></h3>
-<p>Game of life is a wonder of math. In <a href=
-"http://www.math.com/students/wonders/life/life.html" target=
-"_top">Paul Callahan</a>'s words</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"><em>The Game of Life (or simply Life) is not a game in the conventional sense. There
-are no players, and no winning or losing. Once the "pieces" are placed in the
-starting position, the rules determine everything that happens later.
-Nevertheless, Life is full of surprises! In most cases, it is impossible to look
-at a starting position (or pattern) and see what will happen in the future. The
-only way to find out is to follow the rules of the game.</em></font>
-</pre></td>
-</tr>
-</table>
-<p>This program starts with a simple inverted U pattern and shows
-how wonderful life works. There is a lot of room for improvement in
-the program. You can let the user enter pattern of his choice or
-even take input from a file. You can also change rules and play
-with a lot of variations. Search on <a href="http://www.google.com"
-target="_top">google</a> for interesting information on game of
-life.</p>
-<p><em>File Path: JustForFun/life.c</em></p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MAGIC" id="MAGIC">20.2. Magic
-Square</a></h3>
-<p>Magic Square, another wonder of math, is very simple to
-understand but very difficult to make. In a magic square sum of the
-numbers in each row, each column is equal. Even diagnol sum can be
-equal. There are many variations which have special properties.</p>
-<p>This program creates a simple magic square of odd order.</p>
-<p><em>File Path: JustForFun/magic.c</em></p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="HANOI" id="HANOI">20.3. Towers of
-Hanoi</a></h3>
-<p>The famous towers of hanoi solver. The aim of the game is to
-move the disks on the first peg to last peg, using middle peg as a
-temporary stay. The catch is not to place a larger disk over a
-small disk at any time.</p>
-<p><em>File Path: JustForFun/hanoi.c</em></p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="QUEENS" id="QUEENS">20.4. Queens
-Puzzle</a></h3>
-<p>The objective of the famous N-Queen puzzle is to put N queens on
-a N X N chess board without attacking each other.</p>
-<p>This program solves it with a simple backtracking technique.</p>
-<p><em>File Path: JustForFun/queens.c</em></p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="SHUFFLE" id="SHUFFLE">20.5.
-Shuffle</a></h3>
-<p>A fun game, if you have time to kill.</p>
-<p><em>File Path: JustForFun/shuffle.c</em></p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="TT" id="TT">20.6. Typing Tutor</a></h3>
-<p>A simple typing tutor, I created more out of need than for ease
-of use. If you know how to put your fingers correctly on the
-keyboard, but lack practice, this can be helpful.</p>
-<p><em>File Path: JustForFun/tt.c</em></p>
-</div>
-</div>
-<div class="SECT1">
-<hr>
-<h2 class="SECT1"><a name="REF" id="REF">21. References</a></h2>
-<ul>
-<li>
-<p>NCURSES man pages</p>
-</li>
-<li>
-<p>NCURSES FAQ at <a href=
-"http://invisible-island.net/ncurses/ncurses.faq.html" target=
-"_top">http://invisible-island.net/ncurses/ncurses.faq.html</a></p>
-</li>
-<li>
-<p>Writing programs with NCURSES by Eric Raymond and Zeyd M.
-Ben-Halim at <a href=
-"http://invisible-island.net/ncurses/ncurses-intro.html" target=
-"_top">http://invisible-island.net/ncurses/ncurses-intro.html</a> -
-somewhat obsolete. I was inspired by this document and the
-structure of this HOWTO follows from the original document</p>
-</li>
-</ul>
-</div>
-</div>
-</body>
-</html>
diff --git a/contrib/ncurses/doc/html/announce.html b/contrib/ncurses/doc/html/announce.html
deleted file mode 100644
index f9dae07e5d9a..000000000000
--- a/contrib/ncurses/doc/html/announce.html
+++ /dev/null
@@ -1,600 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">
-<!--
- $Id: announce.html,v 1.51 2006/12/17 23:32:42 tom Exp $
- ****************************************************************************
- * Copyright (c) 1998-2005,2006 Free Software Foundation, Inc. *
- * *
- * Permission is hereby granted, free of charge, to any person obtaining a *
- * copy of this software and associated documentation files (the *
- * "Software"), to deal in the Software without restriction, including *
- * without limitation the rights to use, copy, modify, merge, publish, *
- * distribute, distribute with modifications, sublicense, and/or sell *
- * copies of the Software, and to permit persons to whom the Software is *
- * furnished to do so, subject to the following conditions: *
- * *
- * The above copyright notice and this permission notice shall be included *
- * in all copies or substantial portions of the Software. *
- * *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
- * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
- * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
- * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
- * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
- * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
- * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
- * *
- * Except as contained in this notice, the name(s) of the above copyright *
- * holders shall not be used in advertising or otherwise to promote the *
- * sale, use or other dealings in this Software without prior written *
- * authorization. *
- ****************************************************************************
--->
-<HTML>
-<HEAD>
-<TITLE>Announcing ncurses 5.6</TITLE>
-<link rev=made href="mailto:bug-ncurses@gnu.org">
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-</HEAD>
-<BODY>
-
-<H1>Announcing ncurses 5.6</H1>
-
-The ncurses (new curses) library is a free software emulation of
-curses in System V Release 4.0, and more. It uses terminfo format,
-supports pads and color
-and multiple highlights and forms characters and function-key mapping,
-and has all the other SYSV-curses enhancements over BSD curses.<P>
-
-In mid-June 1995, the maintainer of 4.4BSD curses declared that he
-considered 4.4BSD curses obsolete, and encouraged the keepers of
-Unix releases such as BSD/OS, FreeBSD and NetBSD to switch over to
-ncurses.<P>
-
-The ncurses code was developed under GNU/Linux.
-It has been in use for some time with OpenBSD as the system curses library,
-and on FreeBSD and NetBSD as an external package.
-It should port easily to any ANSI/POSIX-conforming UNIX.
-It has even been ported to OS/2 Warp!<P>
-
-The distribution includes the library and support utilities, including a
-terminfo compiler tic(1), a decompiler infocmp(1), clear(1), tput(1), tset(1),
-and a termcap conversion tool captoinfo(1). Full manual pages are provided for
-the library and tools.<P>
-
-The ncurses distribution is available via anonymous FTP at
-the GNU distribution site
-<A HREF="ftp://ftp.gnu.org/gnu/ncurses/">ftp://ftp.gnu.org/gnu/ncurses/</A>&nbsp;.
-<br>It is also available at
-<A HREF="ftp://invisible-island.net/ncurses/">ftp://invisible-island.net/ncurses/</A>&nbsp;.
-
-<H1>Release Notes</H1>
-
-This release is designed to be upward compatible from ncurses 5.0 through 5.5;
-very few applications will require recompilation, depending on the platform.
-These are the highlights from the change-log since ncurses 5.5 release.
-<p>
-Interface changes:
-<ul>
- <li>generate linkable stubs for some macros:
- <br>
- getbegx, getbegy, getcurx, getcury, getmaxx, getmaxy, getparx,
- getpary, getpary,
- <br>
- and (for libncursesw)
- <br>
- wgetbkgrnd
-
-</ul>
-New features and improvements:
-<ul>
- <li>library
- <ul>
- <li>support hashed databases for the terminal descriptions.
- This uses the Berkeley database, has been tested for
- several versions on different platforms.
-
- <li>add <code>use_legacy_coding()</code> function to support
- lynx's font-switching feature.
-
- <li>add extension <code>nofilter()</code>, to cancel a prior
- <code>filter()</code> call.
-
- <li>add/install a package config script, e.g.,
- <code>ncurses5-config</code> or
- <code>ncursesw5-config</code>, according to
- configuration options.
-
- <li>provide ifdef for <code>NCURSES_NOMACROS</code> which
- suppresses most macro definitions from curses.h, i.e.,
- where a macro is defined to override a function to improve
- performance.
-
- <li>make ifdef's consistent in <code>curses.h</code> for the
- extended colors so the header file can be used for the
- normal curses library. The header file installed for
- extended colors is a variation of the wide-character
- configuration.
-
- <li>improve <code>tgetstr()</code> by making the return value
- point into the user's buffer, if provided.
-
- <li>add ifdef's allowing ncurses to be built with
- <code>tparm()</code> using either varargs (the existing
- status), or using a fixed-parameter list (to match X/Open).
-
- <li>widen the test for xterm <code>kmous</code> a little to
- <code>allow</code> for other
- strings than "\E[M", e.g., for <code>xterm-sco</code>
- functionality in xterm.
-
- <li>modify <code>wgetnstr()</code> to return
- <code>KEY_RESIZE</code> if a sigwinch occurs.
-
- <li>move prototypes for wide-character trace functions from
- curses.tail to curses.wide to avoid accidental reference to
- those if <code>_XOPEN_SOURCE_EXTENDED</code> is defined
- without ensuring that &lt;wchar.h&gt; is included.
-
- <li>change the way shared libraries (other than libtool) are
- installed. Rather than copying the build-tree's libraries,
- link the shared objects into the install directory. This
- makes the <code>--with-rpath</code> option work except with
- <code>$(DESTDIR)</code>.
-
- <li>several improvements for rendering in hpterm. These are
- only available if the library is configured using
- <code>--enable-xmc-glitch</code>.
-
- <li>Add <code>NCURSES_NO_HARD_TABS</code> and
- <code>NCURSES_NO_MAGIC_COOKIE</code> environment variables
- to allow runtime suppression of the related hard-tabs and
- xmc-glitch features.
- </ul>
-
- <li>programs:
- <ul>
- <li>add new test programs: chgat.c, demo_altkeys.c,
- echochar.c, foldkeys.c, movewindow.c, redraw.c, (noting
- that existing test programs also were modified to test
- additional features).
-
- <li>modify tack to test extended capability function-key
- strings.
-
- <li>modify toe to access termcap data, e.g., via <code>cgetent()</code>
- functions, or as a text file if those are not available.
-
- <li>improve infocmp/tic <code>-f</code> option formatting.
-
- <li>add <code>toe -a</code> option, to show all databases.
- This uses new private interfaces in the ncurses library for
- iterating through the list of databases.
-
- <li>modify <code>MKfallback.sh</code> to use
- <code>tic&nbsp;-x</code> when constructing fallback tables to
- allow extended capabilities to be retrieved from a fallback entry.
- </ul>
-
- <li>terminal database
- <ul>
- <li>add terminfo entries for xfce terminal (xfce) and multi gnome terminal (mgt)
- <li>add nsterm-16color entry
- <li>updated mlterm terminfo entry
- <li>add kon, kon2 and jfbterm terminfo entry
- <li>remove invis capability from klone+sgr, mainly used by linux entry, since it does not really do this
- <li>add ka2, kb1, kb3, kc2 to vt220-keypad as an extension
- <li>add shifted up/down arrow codes to xterm-new as kind/kri strings
- <li>add hpterm-color terminfo entry
- <li>add 256color variants of terminfo entries for programs which are reported to implement this feature
- <li>correct order of use-clauses in rxvt-basic entry which made codes for f1-f4 vt100-style rather than vt220-style.
- </ul>
-</ul>
-Major bug fixes:
-<ul>
- <li>correct a typo in configure <code>--with-bool</code> option for the
- case where <code>--without-cxx</code> is used.
-
- <li>move assignment from environment variable <code>ESCDELAY</code>
- from <code>initscr()</code> down to <code>newterm()</code> so the
- environment variable affects timeouts for terminals opened with
- newterm() as well.
-
- <li>modify <code>werase</code> to clear multicolumn characters that
- extend into a derived window.
-
- <li>modify <code>wchgat()</code> to mark updated cells as changed so a
- refresh will repaint those cells.
-
- <li>correct logic in <code>wadd_wch()</code> and
- <code>wecho_wch()</code>, which did not guard against passing the
- multi-column attribute into a call on <code>waddch()</code>, e.g.,
- using data returned by <code>win_wch()</code>
-
- <li>fix redrawing of windows other than <code>stdscr</code> using
- <code>wredrawln()</code> by touching the corresponding rows in
- <code>curscr</code>.
-
- <li>reduce memory leaks in repeated calls to <code>tgetent()</code> by
- remembering the last <code>TERMINAL*</code> value allocated to hold
- the corresponding data and freeing that if the
- <code>tgetent()</code> result buffer is the same as the previous
- call.
-
- <li>modify <code>read_termtype()</code> so the <code>term_names</code>
- data is always allocated as part of the <code>str_table</code>, a
- better fix for a memory leak.
-
- <li>fix <code>wins_nwstr(),</code> which did not handle single-column
- non-8bit codes.
-
- <li>modify <code>wbkgrnd()</code> to avoid clearing the
- <code>A_CHARTEXT</code> attribute bits since those record the state
- of multicolumn characters.
-
- <li>improve <code>SIGWINCH</code> handling by postponing its effect
- during <code>newterm()</code>, etc., when allocating screens.
-
- <li>remove 970913 feature for copying subwindows as they are moved in
- <code>mvwin()</code>.
-
- <li>add checks in <code>waddchnstr()</code> and
- <code>wadd_wchnstr()</code> to stop copying when a null character
- is found.
-
- <li>add some checks to ensure current position is within scrolling
- region before scrolling on a new line.
-
- <li>add a workaround to ACS mapping to allow applications such as
- test/blue.c to use the "PC ROM" characters by masking them with
- A_ALTCHARSET. This worked up til 5.5, but was lost in the revision
- of legacy coding.
-</ul>
-
-Portability:
-<ul>
- <li>configure script:
- <ul>
- <li>new options:
- <dl>
-
- <dt>--with-hashed-db
- <dd>Use Berkeley hashed database for storing terminfo data rather than storing
- each compiled entry in a separate binary file within a directory
- tree.
-
- <dt>--without-dlsym
- <dd>Do not use <code>dlsym()</code> to load GPM dynamically.
-
- <dt>--with-valgrind
- <dd>Simplify building for testing with valgrind.
-
- <dt>--enable-wgetch-events
- <dd>Compile with experimental wgetch-events code.
-
- <dt>--enable-signed-char
- <dd>Store booleans in "signed char" rather than "char".
-
- </dl>
-
- <li>improved options:
- <dl>
-
- <dt>--disable-largefile
- <dd>make the option work both ways.
-
- <dt>--with-gpm
- <dd>The option now accepts a parameter,
- i.e., the name of the dynamic GPM library to load via
- <code>dlopen()</code>
-
- <dt>--disable-symlinks
- <dd>The option now allows one to
- disable <code>symlink()</code> in <code>tic</code> even when
- <code>link()</code> does not work.
-
- </dl>
-
- </ul>
-
- <li>other configure/build issues: <ul> <li>remove special case for
- Darwin in <code>CF_XOPEN_SOURCE</code> configure macro.
-
- <li>add configure check to ensure that <code>SIGWINCH</code> is
- defined on platforms such as OS X which exclude that when
- <code>_XOPEN_SOURCE,</code> etc., are defined
-
- <li>use ld's <code>-search_paths_first</code> option on Darwin
- to work around odd search rules on that platform.
-
- <li>improve ifdef's for <code>_POSIX_VDISABLE</code> in tset to
- work with Mac OS X.
-
- <li>modify configure script to ensure that if the C compiler is
- used rather than the loader in making shared libraries, the
- <code>$(CFLAGS)</code> variable is also used.
-
- <li>use <code>${CC}</code> rather than <code>${LD}</code> in
- shared library rules for IRIX64, Solaris to help ensure
- that initialization sections are provided for extra linkage
- requirements, e.g., of C++ applications.
-
- <li>improve some shared-library configure scripting for Linux,
- FreeBSD and NetBSD to make
- <code>--with-shlib-version</code> work.
-
- <li>split up dependency of <code>names.c</code> and
- <code>codes.c</code> in <code>ncurses/Makefile</code> to
- work with parallel make.
-
- <li>modify <code>MKlib_gen.sh</code> to change
- preprocessor-expanded <code>_Bool</code> back to <code>bool</code>.
-
- <li>modify <code>progs/Makefile.in</code> to make
- <code>tput&nbsp;init</code> work properly with cygwin,
- i.e., do not pass a <code>.exe</code> in the reference
- string used in check_aliases.
- </ul>
-
- <li>library:
- <ul>
- <li>ignore wide-acs line-drawing characters that
- <code>wcwidth()</code> claims are not one-column. This is
- a workaround for Solaris' broken locale support.
-
- <li>reduce name-pollution in <code>term.h</code> by removing
- <code>#define</code>'s for HAVE_xxx symbols.
-
- <li>fix <code>#ifdef</code> in <code>c++/internal.h</code> for
- QNX 6.1
- </ul>
-
- <li>test programs: <ul> <li>modify <code>test/configure</code> script
- to allow building test programs with PDCurses/X11.
-
- <li>modified test programs to allow some to work with NetBSD
- curses. Several do not because NetBSD curses implements a
- subset of X/Open curses, and also lacks much of SVr4
- additions. But it is enough for comparison.
-
- <li>improved <code>test/configure</code> to build test/ncurses
- on HPUX 11 using the vendor curses.
-
- <li>change configure script to produce
- <code>test/Makefile</code> from data file.
- </ul>
-</ul>
-
-<H1>Features of Ncurses</H1>
-
-The ncurses package is fully compatible with SVr4 (System V Release 4) curses:
-
-<UL>
-<LI>All 257 of the SVr4 calls have been implemented (and are documented).
-<LI>Full support for SVr4 curses features including keyboard mapping, color,
-forms-drawing with ACS characters, and automatic recognition of keypad
-and function keys.
-<LI>An emulation of the SVr4 panels library, supporting
-a stack of windows with backing store, is included.
-<LI>An emulation of the SVr4 menus library, supporting
-a uniform but flexible interface for menu programming, is included.
-<LI>An emulation of the SVr4 form library, supporting
-data collection through on-screen forms, is included.
-<LI>Binary terminfo entries generated by the ncurses tic(1) implementation
-are bit-for-bit-compatible with the entry format SVr4 curses uses.
-<LI>The utilities have options to allow you to filter terminfo
-entries for use with less capable <STRONG>curses</STRONG>/<STRONG>terminfo</STRONG>
-versions such as the HP/UX and AIX ports.</UL>
-
-The ncurses package also has many useful extensions over SVr4:
-
-<UL>
-<LI>The API is 8-bit clean and base-level conformant with the X/OPEN curses
-specification, XSI curses (that is, it implements all BASE level features,
-and most EXTENDED features).
-It includes many function calls not supported under SVr4 curses
-(but portability of all
-calls is documented so you can use the SVr4 subset only).
-<LI>Unlike SVr3 curses, ncurses can write to the rightmost-bottommost corner
-of the screen if your terminal has an insert-character capability.
-<LI>Ada95 and C++ bindings.
-<LI>Support for mouse event reporting with X Window xterm
-and FreeBSD and OS/2 console windows.
-<LI>Extended mouse support via Alessandro Rubini's gpm package.
-<LI>The function <CODE>wresize()</CODE> allows you to resize windows, preserving
-their data.
-<LI>The function <CODE>use_default_colors()</CODE> allows you to
-use the terminal's default colors for the default color pair,
-achieving the effect of transparent colors.
-<LI>The functions <CODE>keyok()</CODE>
-and <CODE>define_key()</CODE> allow
-you to better control the use of function keys,
-e.g., disabling the ncurses KEY_MOUSE,
-or by defining more than one control sequence to map to a given key code.
-<LI>Support for 16-color terminals, such as aixterm and modern xterm.
-<LI>Better cursor-movement optimization. The package now features a
-cursor-local-movement computation more efficient than either BSD's
-or System V's.
-<LI>Super hardware scrolling support. The screen-update code incorporates
-a novel, simple, and cheap algorithm that enables it to make optimal
-use of hardware scrolling, line-insertion, and line-deletion
-for screen-line movements. This algorithm is more powerful than
-the 4.4BSD curses quickch() routine.
-<LI>Real support for terminals with the magic-cookie glitch. The
-screen-update code will refrain from drawing a highlight if the magic-
-cookie unattributed spaces required just before the beginning and
-after the end would step on a non-space character. It will
-automatically shift highlight boundaries when doing so would make it
-possible to draw the highlight without changing the visual appearance
-of the screen.
-<LI>It is possible to generate the library with a list of pre-loaded
-fallback entries linked to it so that it can serve those terminal types even
-when no terminfo tree or termcap file is accessible (this may be useful
-for support of screen-oriented programs that must run in single-user mode).
-<LI>The tic(1)/captoinfo utility provided with ncurses has the
-ability to translate many termcaps from the XENIX, IBM and
-AT&amp;T extension sets.
-<LI>A BSD-like tset(1) utility is provided.
-<LI>The ncurses library and utilities will automatically read terminfo
-entries from $HOME/.terminfo if it exists, and compile to that directory
-if it exists and the user has no write access to the system directory.
-This feature makes it easier for users to have personal terminfo entries
-without giving up access to the system terminfo directory.
-<LI>You may specify a path of directories to search for compiled
-descriptions with the environment variable TERMINFO_DIRS (this
-generalizes the feature provided by TERMINFO under stock System V.)
-<LI>In terminfo source files, use capabilities may refer not just to
-other entries in the same source file (as in System V) but also to
-compiled entries in either the system terminfo directory or the user's
-$HOME/.terminfo directory.
-<LI>A script (<STRONG>capconvert</STRONG>) is provided to help BSD users
-transition from termcap to terminfo. It gathers the information in a
-TERMCAP environment variable and/or a ~/.termcap local entries file
-and converts it to an equivalent local terminfo tree under $HOME/.terminfo.
-<LI>Automatic fallback to the /etc/termcap file can be compiled in
-when it is not possible to build a terminfo tree. This feature is neither
-fast nor cheap, you don't want to use it unless you have to,
-but it's there.
-<LI>The table-of-entries utility <STRONG>toe</STRONG> makes it easy for users to
-see exactly what terminal types are available on the system.
-<LI>The library meets the XSI requirement that every macro entry
-point have a corresponding function which may be linked (and will be
-prototype-checked) if the macro definition is disabled with
-<CODE>#undef</CODE>.
-<LI>An HTML "Introduction to Programming with NCURSES" document provides
-a narrative introduction to the curses programming interface.
-</UL>
-
-<H1>State of the Package</H1>
-
-Numerous bugs present in earlier versions have been fixed; the
-library is far more reliable than it used to be. Bounds checking in many
-`dangerous' entry points has been improved. The code is now type-safe
-according to gcc -Wall. The library has been checked for malloc leaks and
-arena corruption by the Purify memory-allocation tester.<P>
-
-The ncurses code has been tested with a wide variety of applications
-including (versions starting with those noted):
-<DL>
-<DT> cdk
-<DD> Curses Development Kit
-<br>
-<A HREF="http://invisible-island.net/cdk/">http://invisible-island.net/cdk/</A>
-<br>
-<A HREF="http://www.vexus.ca/products/CDK/">http://www.vexus.ca/products/CDK/</a>
-<DT> ded
-<DD> directory-editor
-<br>
-<A HREF="http://invisible-island.net/ded/">http://invisible-island.net/ded/</A>
-<DT> dialog
-<DD> the underlying application used in Slackware's setup, and the basis
-for similar applications on GNU/Linux.
-<br>
-<A HREF="http://invisible-island.net/dialog/">http://invisible-island.net/dialog/</A>
-<DT> lynx
-<DD> the character-screen WWW browser
-<br>
-<A HREF="http://lynx.isc.org/release/">http://lynx.isc.org/release/</A>
-<DT> Midnight Commander
-<DD> file manager
-<br>
-<A HREF="http://www.ibiblio.org/mc/">http://www.ibiblio.org/mc/</A>
-<DT> mutt
-<DD> mail utility
-<br>
-<A HREF="http://www.mutt.org/">http://www.mutt.org/</A>
-<DT> ncftp
-<DD> file-transfer utility
-<br>
-<A HREF="http://www.ncftp.com/">http://www.ncftp.com/</A>
-<DT> nvi
-<DD> New vi versions 1.50 are able to use ncurses versions 1.9.7 and later.
-<br>
-<A HREF="http://www.bostic.com/vi/">http://www.bostic.com/vi/</A>
-<br>
-<DT> pinfo
-<DD> Lynx-like info browser.
-<A HREF="http://dione.ids.pl/~pborys/software/pinfo/">http://dione.ids.pl/~pborys/software/pinfo/</A>
-<DT> tin
-<DD> newsreader, supporting color, MIME
-<A HREF="http://www.tin.org/">http://www.tin.org/</A>
-<DT> vh-1.6
-<DD> Volks-Hypertext browser for the Jargon File
-<br>
-<A HREF="http://www.debian.org/Packages/unstable/text/vh.html">http://www.debian.org/Packages/unstable/text/vh.html</A>
-</DL>
-as well as some that use ncurses for the terminfo support alone:
-<DL>
-<DT> minicom
-<DD> terminal emulator
-<br>
-<A HREF="http://alioth.debian.org/projects/minicom/">
-http://alioth.debian.org/projects/minicom/</A>
-<DT> vile
-<DD> vi-like-emacs
-<br>
-<A HREF="http://invisible-island.net/vile/">http://invisible-island.net/vile/</A>
-</DL>
-<P>
-
-The ncurses distribution includes a selection of test programs (including
-a few games).
-
-<H2>Who's Who and What's What</H2>
-
-Zeyd Ben-Halim
-started it from a previous package pcurses, written by Pavel Curtis.
-Eric S. Raymond
-continued development.
-J&uuml;rgen Pfeifer wrote most of the form and menu libraries.
-Ongoing work is being done by
-<A HREF="mailto:dickey@invisible-island.net">Thomas Dickey</A>.
-Thomas Dickey
-acts as the maintainer for the Free Software Foundation,
-which holds the copyright on ncurses.
-Contact the current maintainers at
-<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>.
-<P>
-
-To join the ncurses mailing list, please write email to
-<CODE>bug-ncurses-request@gnu.org</CODE> containing the line:
-<PRE>
- subscribe &lt;name&gt;@&lt;host.domain&gt;
-</PRE>
-
-This list is open to anyone interested in helping with the development and
-testing of this package.<P>
-
-Beta versions of ncurses and patches to the current release are made available at
-<A HREF="ftp://invisible-island.net/ncurses/">ftp://invisible-island.net/ncurses/</A>&nbsp;.
-
-<H2>Future Plans</H2>
-<UL>
-<LI>Extended-level XPG4 conformance, with internationalization support.
-<LI>Ports to more systems, including DOS and Windows.
-</UL>
-We need people to help with these projects. If you are interested in working
-on them, please join the ncurses list.
-
-<H2>Other Related Resources</H2>
-
-The distribution provides a newer version of the terminfo-format
-terminal description file once maintained by
-<A HREF="http://www.catb.org/~esr/terminfo/">Eric Raymond</A>&nbsp;.
-Unlike the older version, the termcap and terminfo data are provided
-in the same file, and provides several user-definable extensions
-beyond the X/Open specification.<P>
-
-You can find lots of information on terminal-related topics
-not covered in the terminfo file at
-<A HREF="http://www.cs.utk.edu/~shuford/terminal_index.html">Richard Shuford's
-archive</A>&nbsp;.
-</BODY>
-</HTML>
-<!--
-# The following sets edit modes for GNU EMACS
-# Local Variables:
-# mode:html
-# case-fold-search:nil
-# fill-column:70
-# End:
--->
diff --git a/contrib/ncurses/doc/html/hackguide.html b/contrib/ncurses/doc/html/hackguide.html
deleted file mode 100644
index 97d1369170c1..000000000000
--- a/contrib/ncurses/doc/html/hackguide.html
+++ /dev/null
@@ -1,914 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">
-<!--
- $Id: hackguide.html,v 1.27 2005/12/24 15:37:13 tom Exp $
- ****************************************************************************
- * Copyright (c) 1998-2003,2005 Free Software Foundation, Inc. *
- * *
- * Permission is hereby granted, free of charge, to any person obtaining a *
- * copy of this software and associated documentation files (the *
- * "Software"), to deal in the Software without restriction, including *
- * without limitation the rights to use, copy, modify, merge, publish, *
- * distribute, distribute with modifications, sublicense, and/or sell *
- * copies of the Software, and to permit persons to whom the Software is *
- * furnished to do so, subject to the following conditions: *
- * *
- * The above copyright notice and this permission notice shall be included *
- * in all copies or substantial portions of the Software. *
- * *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
- * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
- * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
- * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
- * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
- * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
- * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
- * *
- * Except as contained in this notice, the name(s) of the above copyright *
- * holders shall not be used in advertising or otherwise to promote the *
- * sale, use or other dealings in this Software without prior written *
- * authorization. *
- ****************************************************************************
--->
-<HTML>
-<HEAD>
-<TITLE>A Hacker's Guide to Ncurses Internals</TITLE>
-<link rev="made" href="mailto:bugs-ncurses@gnu.org">
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-<!--
-This document is self-contained, *except* that there is one relative link to
-the ncurses-intro.html document, expected to be in the same directory with
-this one.
--->
-</HEAD>
-<BODY>
-
-<H1>A Hacker's Guide to NCURSES</H1>
-
-<H1>Contents</H1>
-<UL>
-<LI><A HREF="#abstract">Abstract</A>
-<LI><A HREF="#objective">Objective of the Package</A>
-<UL>
-<LI><A HREF="#whysvr4">Why System V Curses?</A>
-<LI><A HREF="#extensions">How to Design Extensions</A>
-</UL>
-<LI><A HREF="#portability">Portability and Configuration</A>
-<LI><A HREF="#documentation">Documentation Conventions</A>
-<LI><A HREF="#bugtrack">How to Report Bugs</A>
-<LI><A HREF="#ncurslib">A Tour of the Ncurses Library</A>
-<UL>
-<LI><A HREF="#loverview">Library Overview</A>
-<LI><A HREF="#engine">The Engine Room</A>
-<LI><A HREF="#input">Keyboard Input</A>
-<LI><A HREF="#mouse">Mouse Events</A>
-<LI><A HREF="#output">Output and Screen Updating</A>
-</UL>
-<LI><A HREF="#fmnote">The Forms and Menu Libraries</A>
-<LI><A HREF="#tic">A Tour of the Terminfo Compiler</A>
-<UL>
-<LI><A HREF="#nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A>
-<LI><A HREF="#uses">Use Capability Resolution</A>
-<LI><A HREF="#translation">Source-Form Translation</A>
-</UL>
-<LI><A HREF="#utils">Other Utilities</A>
-<LI><A HREF="#style">Style Tips for Developers</A>
-<LI><A HREF="#port">Porting Hints</A>
-</UL>
-
-<H1><A NAME="abstract">Abstract</A></H1>
-
-This document is a hacker's tour of the <STRONG>ncurses</STRONG> library and utilities.
-It discusses design philosophy, implementation methods, and the
-conventions used for coding and documentation. It is recommended
-reading for anyone who is interested in porting, extending or improving the
-package.
-
-<H1><A NAME="objective">Objective of the Package</A></H1>
-
-The objective of the <STRONG>ncurses</STRONG> package is to provide a free software API for
-character-cell terminals and terminal emulators with the following
-characteristics:
-
-<UL>
-<LI>Source-compatible with historical curses implementations (including
- the original BSD curses and System V curses.
-<LI>Conformant with the XSI Curses standard issued as part of XPG4 by
- X/Open.
-<LI>High-quality -- stable and reliable code, wide portability, good
- packaging, superior documentation.
-<LI>Featureful -- should eliminate as much of the drudgery of C interface
- programming as possible, freeing programmers to think at a higher
- level of design.
-</UL>
-
-These objectives are in priority order. So, for example, source
-compatibility with older version must trump featurefulness -- we cannot
-add features if it means breaking the portion of the API corresponding
-to historical curses versions.
-
-<H2><A NAME="whysvr4">Why System V Curses?</A></H2>
-
-We used System V curses as a model, reverse-engineering their API, in
-order to fulfill the first two objectives. <P>
-
-System V curses implementations can support BSD curses programs with
-just a recompilation, so by capturing the System V API we also
-capture BSD's. <P>
-
-More importantly for the future, the XSI Curses standard issued by 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.
-
-<H2><A NAME="extensions">How to Design Extensions</A></H2>
-
-The third objective (standards conformance) requires that it be easy to
-condition source code using <STRONG>ncurses</STRONG> so that the absence of nonstandard
-extensions does not break the code. <P>
-
-Accordingly, we have a policy of associating with each nonstandard extension
-a feature macro, so that ncurses client code can use this macro to condition
-in or out the code that requires the <STRONG>ncurses</STRONG> extension. <P>
-
-For example, there is a macro <CODE>NCURSES_MOUSE_VERSION</CODE> which XSI Curses
-does not define, but which is defined in the <STRONG>ncurses</STRONG> library header.
-You can use this to condition the calls to the mouse API calls.
-
-<H1><A NAME="portability">Portability and Configuration</A></H1>
-
-Code written for <STRONG>ncurses</STRONG> may assume an ANSI-standard C compiler and
-POSIX-compatible OS interface. It may also assume the presence of a
-System-V-compatible <EM>select(2)</EM> call. <P>
-
-We encourage (but do not require) developers to make the code friendly
-to less-capable UNIX environments wherever possible. <P>
-
-We encourage developers to support OS-specific optimizations and methods
-not available under POSIX/ANSI, provided only that:
-
-<UL>
-<LI>All such code is properly conditioned so the build process does not
- attempt to compile it under a plain ANSI/POSIX environment.
-<LI>Adding such implementation methods does not introduce incompatibilities
- in the <STRONG>ncurses</STRONG> API between platforms.
-</UL>
-
-We use GNU <CODE>autoconf(1)</CODE> as a tool to deal with portability issues.
-The right way to leverage an OS-specific feature is to modify the autoconf
-specification files (configure.in and aclocal.m4) to set up a new feature
-macro, which you then use to condition your code.
-
-<H1><A NAME="documentation">Documentation Conventions</A></H1>
-
-There are three kinds of documentation associated with this package. Each
-has a different preferred format:
-
-<UL>
-<LI>Package-internal files (README, INSTALL, TO-DO etc.)
-<LI>Manual pages.
-<LI>Everything else (i.e., narrative documentation).
-</UL>
-
-Our conventions are simple:
-<OL>
-<LI><STRONG>Maintain package-internal files in plain text.</STRONG>
- The expected viewer for them <EM>more(1)</EM> or an editor window; there's
- no point in elaborate mark-up.
-
-<LI><STRONG>Mark up manual pages in the man macros.</STRONG> These have to be viewable
- through traditional <EM>man(1)</EM> programs.
-
-<LI><STRONG>Write everything else in HTML.</STRONG>
-</OL>
-
-When in doubt, HTMLize a master and use <EM>lynx(1)</EM> to generate
-plain ASCII (as we do for the announcement document). <P>
-
-The reason for choosing HTML is that it's (a) well-adapted for on-line
-browsing through viewers that are everywhere; (b) more easily readable
-as plain text than most other mark-ups, if you don't have a viewer; and (c)
-carries enough information that you can generate a nice-looking printed
-version from it. Also, of course, it make exporting things like the
-announcement document to WWW pretty trivial.
-
-<H1><A NAME="bugtrack">How to Report Bugs</A></H1>
-
-The <A NAME="bugreport">reporting address for bugs</A> is
-<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>.
-This is a majordomo list; to join, write
-to <CODE>bug-ncurses-request@gnu.org</CODE> with a message containing the line:
-<PRE>
- subscribe &lt;name&gt;@&lt;host.domain&gt;
-</PRE>
-
-The <CODE>ncurses</CODE> code is maintained by a small group of
-volunteers. While we try our best to fix bugs promptly, we simply
-don't have a lot of hours to spend on elementary hand-holding. We rely
-on intelligent cooperation from our users. If you think you have
-found a bug in <CODE>ncurses</CODE>, there are some steps you can take
-before contacting us that will help get the bug fixed quickly. <P>
-
-In order to use our bug-fixing time efficiently, we put people who
-show us they've taken these steps at the head of our queue. This
-means that if you don't, you'll probably end up at the tail end and
-have to wait a while.
-
-<OL>
-<LI>Develop a recipe to reproduce the bug.
-<p>
-Bugs we can reproduce are likely to be fixed very quickly, often
-within days. The most effective single thing you can do to get a
-quick fix is develop a way we can duplicate the bad behavior --
-ideally, by giving us source for a small, portable test program that
-breaks the library. (Even better is a keystroke recipe using one of
-the test programs provided with the distribution.)
-
-<LI>Try to reproduce the bug on a different terminal type. <P>
-
-In our experience, most of the behaviors people report as library bugs
-are actually due to subtle problems in terminal descriptions. This is
-especially likely to be true if you're using a traditional
-asynchronous terminal or PC-based terminal emulator, rather than xterm
-or a UNIX console entry. <P>
-
-It's therefore extremely helpful if you can tell us whether or not your
-problem reproduces on other terminal types. Usually you'll have both
-a console type and xterm available; please tell us whether or not your
-bug reproduces on both. <P>
-
-If you have xterm available, it is also good to collect xterm reports for
-different window sizes. This is especially true if you normally use an
-unusual xterm window size -- a surprising number of the bugs we've seen
-are either triggered or masked by these.
-
-<LI>Generate and examine a trace file for the broken behavior. <P>
-
-Recompile your program with the debugging versions of the libraries.
-Insert a <CODE>trace()</CODE> call with the argument set to <CODE>TRACE_UPDATE</CODE>.
-(See <A HREF="ncurses-intro.html#debugging">"Writing Programs with
-NCURSES"</A> for details on trace levels.)
-Reproduce your bug, then look at the trace file to see what the library
-was actually doing. <P>
-
-Another frequent cause of apparent bugs is application coding errors
-that cause the wrong things to be put on the virtual screen. Looking
-at the virtual-screen dumps in the trace file will tell you immediately if
-this is happening, and save you from the possible embarrassment of being
-told that the bug is in your code and is your problem rather than ours. <P>
-
-If the virtual-screen dumps look correct but the bug persists, it's
-possible to crank up the trace level to give more and more information
-about the library's update actions and the control sequences it issues
-to perform them. The test directory of the distribution contains a
-tool for digesting these logs to make them less tedious to wade
-through. <P>
-
-Often you'll find terminfo problems at this stage by noticing that the
-escape sequences put out for various capabilities are wrong. If not,
-you're likely to learn enough to be able to characterize any bug in
-the screen-update logic quite exactly.
-
-<LI>Report details and symptoms, not just interpretations. <P>
-
-If you do the preceding two steps, it is very likely that you'll discover
-the nature of the problem yourself and be able to send us a fix. This
-will create happy feelings all around and earn you good karma for the first
-time you run into a bug you really can't characterize and fix yourself. <P>
-
-If you're still stuck, at least you'll know what to tell us. Remember, we
-need details. If you guess about what is safe to leave out, you are too
-likely to be wrong. <P>
-
-If your bug produces a bad update, include a trace file. Try to make
-the trace at the <EM>least</EM> voluminous level that pins down the
-bug. Logs that have been through tracemunch are OK, it doesn't throw
-away any information (actually they're better than un-munched ones because
-they're easier to read). <P>
-
-If your bug produces a core-dump, please include a symbolic stack trace
-generated by gdb(1) or your local equivalent. <P>
-
-Tell us about every terminal on which you've reproduced the bug -- and
-every terminal on which you can't. Ideally, sent us terminfo sources
-for all of these (yours might differ from ours). <P>
-
-Include your ncurses version and your OS/machine type, of course! You can
-find your ncurses version in the <CODE>curses.h</CODE> file.
-</OL>
-
-If your problem smells like a logic error or in cursor movement or
-scrolling or a bad capability, there are a couple of tiny test frames
-for the library algorithms in the progs directory that may help you
-isolate it. These are not part of the normal build, but do have their
-own make productions. <P>
-
-The most important of these is <CODE>mvcur</CODE>, a test frame for the
-cursor-movement optimization code. With this program, you can see
-directly what control sequences will be emitted for any given cursor
-movement or scroll/insert/delete operations. If you think you've got
-a bad capability identified, you can disable it and test again. The
-program is command-driven and has on-line help. <P>
-
-If you think the vertical-scroll optimization is broken, or just want to
-understand how it works better, build <CODE>hashmap</CODE> and read the
-header comments of <CODE>hardscroll.c</CODE> and <CODE>hashmap.c</CODE>; then try
-it out. You can also test the hardware-scrolling optimization separately
-with <CODE>hardscroll</CODE>. <P>
-
-<H1><A NAME="ncurslib">A Tour of the Ncurses Library</A></H1>
-
-<H2><A NAME="loverview">Library Overview</A></H2>
-
-Most of the library is superstructure -- fairly trivial convenience
-interfaces to a small set of basic functions and data structures used
-to manipulate the virtual screen (in particular, none of this code
-does any I/O except through calls to more fundamental modules
-described below). The files
-<blockquote>
-<CODE>
-lib_addch.c
-lib_bkgd.c
-lib_box.c
-lib_chgat.c
-lib_clear.c
-lib_clearok.c
-lib_clrbot.c
-lib_clreol.c
-lib_colorset.c
-lib_data.c
-lib_delch.c
-lib_delwin.c
-lib_echo.c
-lib_erase.c
-lib_gen.c
-lib_getstr.c
-lib_hline.c
-lib_immedok.c
-lib_inchstr.c
-lib_insch.c
-lib_insdel.c
-lib_insstr.c
-lib_instr.c
-lib_isendwin.c
-lib_keyname.c
-lib_leaveok.c
-lib_move.c
-lib_mvwin.c
-lib_overlay.c
-lib_pad.c
-lib_printw.c
-lib_redrawln.c
-lib_scanw.c
-lib_screen.c
-lib_scroll.c
-lib_scrollok.c
-lib_scrreg.c
-lib_set_term.c
-lib_slk.c
-lib_slkatr_set.c
-lib_slkatrof.c
-lib_slkatron.c
-lib_slkatrset.c
-lib_slkattr.c
-lib_slkclear.c
-lib_slkcolor.c
-lib_slkinit.c
-lib_slklab.c
-lib_slkrefr.c
-lib_slkset.c
-lib_slktouch.c
-lib_touch.c
-lib_unctrl.c
-lib_vline.c
-lib_wattroff.c
-lib_wattron.c
-lib_window.c
-</CODE>
-</blockquote>
-are all in this category. They are very
-unlikely to need change, barring bugs or some fundamental
-reorganization in the underlying data structures. <P>
-
-These files are used only for debugging support:
-<blockquote>
-<code>
-lib_trace.c
-lib_traceatr.c
-lib_tracebits.c
-lib_tracechr.c
-lib_tracedmp.c
-lib_tracemse.c
-trace_buf.c
-</code>
-</blockquote>
-It is rather unlikely you will ever need to change these, unless
-you want to introduce a new debug trace level for some reason.<P>
-
-There is another group of files that do direct I/O via <EM>tputs()</EM>,
-computations on the terminal capabilities, or queries to the OS
-environment, but nevertheless have only fairly low complexity. These
-include:
-<blockquote>
-<code>
-lib_acs.c
-lib_beep.c
-lib_color.c
-lib_endwin.c
-lib_initscr.c
-lib_longname.c
-lib_newterm.c
-lib_options.c
-lib_termcap.c
-lib_ti.c
-lib_tparm.c
-lib_tputs.c
-lib_vidattr.c
-read_entry.c.
-</code>
-</blockquote>
-They are likely to need revision only if
-ncurses is being ported to an environment without an underlying
-terminfo capability representation. <P>
-
-These files
-have serious hooks into
-the tty driver and signal facilities:
-<blockquote>
-<code>
-lib_kernel.c
-lib_baudrate.c
-lib_raw.c
-lib_tstp.c
-lib_twait.c
-</code>
-</blockquote>
-If you run into porting snafus
-moving the package to another UNIX, the problem is likely to be in one
-of these files.
-The file <CODE>lib_print.c</CODE> uses sleep(2) and also
-falls in this category.<P>
-
-Almost all of the real work is done in the files
-<blockquote>
-<code>
-hardscroll.c
-hashmap.c
-lib_addch.c
-lib_doupdate.c
-lib_getch.c
-lib_mouse.c
-lib_mvcur.c
-lib_refresh.c
-lib_setup.c
-lib_vidattr.c
-</code>
-</blockquote>
-Most of the algorithmic complexity in the
-library lives in these files.
-If there is a real bug in <STRONG>ncurses</STRONG> itself, it's probably here.
-We'll tour some of these files in detail
-below (see <A HREF="#engine">The Engine Room</A>). <P>
-
-Finally, there is a group of files that is actually most of the
-terminfo compiler. The reason this code lives in the <STRONG>ncurses</STRONG>
-library is to support fallback to /etc/termcap. These files include
-<blockquote>
-<code>
-alloc_entry.c
-captoinfo.c
-comp_captab.c
-comp_error.c
-comp_hash.c
-comp_parse.c
-comp_scan.c
-parse_entry.c
-read_termcap.c
-write_entry.c
-</code>
-</blockquote>
-We'll discuss these in the compiler tour.
-
-<H2><A NAME="engine">The Engine Room</A></H2>
-
-<H3><A NAME="input">Keyboard Input</A></H3>
-
-All <CODE>ncurses</CODE> input funnels through the function
-<CODE>wgetch()</CODE>, defined in <CODE>lib_getch.c</CODE>. This function is
-tricky; it has to poll for keyboard and mouse events and do a running
-match of incoming input against the set of defined special keys. <P>
-
-The central data structure in this module is a FIFO queue, used to
-match multiple-character input sequences against special-key
-capabilities; also to implement pushback via <CODE>ungetch()</CODE>. <P>
-
-The <CODE>wgetch()</CODE> code distinguishes between function key
-sequences and the same sequences typed manually by doing a timed wait
-after each input character that could lead a function key sequence.
-If the entire sequence takes less than 1 second, it is assumed to have
-been generated by a function key press. <P>
-
-Hackers bruised by previous encounters with variant <CODE>select(2)</CODE>
-calls may find the code in <CODE>lib_twait.c</CODE> interesting. It deals
-with the problem that some BSD selects don't return a reliable
-time-left value. The function <CODE>timed_wait()</CODE> effectively
-simulates a System V select.
-
-<H3><A NAME="mouse">Mouse Events</A></H3>
-
-If the mouse interface is active, <CODE>wgetch()</CODE> polls for mouse
-events each call, before it goes to the keyboard for input. It is
-up to <CODE>lib_mouse.c</CODE> how the polling is accomplished; it may vary
-for different devices. <P>
-
-Under xterm, however, mouse event notifications come in via the keyboard
-input stream. They are recognized by having the <STRONG>kmous</STRONG> capability
-as a prefix. This is kind of klugey, but trying to wire in recognition of
-a mouse key prefix without going through the function-key machinery would
-be just too painful, and this turns out to imply having the prefix somewhere
-in the function-key capabilities at terminal-type initialization. <P>
-
-This kluge only works because <STRONG>kmous</STRONG> isn't actually used by any
-historic terminal type or curses implementation we know of. Best
-guess is it's a relic of some forgotten experiment in-house at Bell
-Labs that didn't leave any traces in the publicly-distributed System V
-terminfo files. If System V or XPG4 ever gets serious about using it
-again, this kluge may have to change. <P>
-
-Here are some more details about mouse event handling: <P>
-
-The <CODE>lib_mouse()</CODE>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. <P>
-
-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:
-either (a) <CODE>_nc_mouse_event()</CODE> detects a series of incoming
-mouse reports and queues them, or (b) code in <CODE>lib_getch.c</CODE> detects the
-<STRONG>kmous</STRONG> prefix in the keyboard input stream and calls _nc_mouse_inline
-to queue up a series of adjacent mouse reports. <P>
-
-In either case, <CODE>_nc_mouse_parse()</CODE> should be called after the
-series is accepted to parse the digested mouse reports (low-level
-events) into a gesture (a high-level or composite event).
-
-<H3><A NAME="output">Output and Screen Updating</A></H3>
-
-With the single exception of character echoes during a <CODE>wgetnstr()</CODE>
-call (which simulates cooked-mode line editing in an ncurses window),
-the library normally does all its output at refresh time. <P>
-
-The main job is to go from the current state of the screen (as represented
-in the <CODE>curscr</CODE> window structure) to the desired new state (as
-represented in the <CODE>newscr</CODE> window structure), while doing as
-little I/O as possible. <P>
-
-The brains of this operation are the modules <CODE>hashmap.c</CODE>,
-<CODE>hardscroll.c</CODE> and <CODE>lib_doupdate.c</CODE>; the latter two use
-<CODE>lib_mvcur.c</CODE>. Essentially, what happens looks like this: <P>
-
-The <CODE>hashmap.c</CODE> 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. <P>
-
-The <CODE>hardscroll.c</CODE> module computes an optimum set of scroll,
-insertion, and deletion operations to make the indices match. It calls
-<CODE>_nc_mvcur_scrolln()</CODE> in <CODE>lib_mvcur.c</CODE> to do those motions. <P>
-
-Then <CODE>lib_doupdate.c</CODE> goes to work. Its job is to do line-by-line
-transformations of <CODE>curscr</CODE> lines to <CODE>newscr</CODE> lines. Its main
-tool is the routine <CODE>mvcur()</CODE> in <CODE>lib_mvcur.c</CODE>. This routine
-does cursor-movement optimization, attempting to get from given screen
-location A to given location B in the fewest output characters possible. <P>
-
-If you want to work on screen optimizations, you should use the fact
-that (in the trace-enabled version of the library) enabling the
-<CODE>TRACE_TIMES</CODE> trace level causes a report to be emitted after
-each screen update giving the elapsed time and a count of characters
-emitted during the update. You can use this to tell when an update
-optimization improves efficiency. <P>
-
-In the trace-enabled version of the library, it is also possible to disable
-and re-enable various optimizations at runtime by tweaking the variable
-<CODE>_nc_optimize_enable</CODE>. See the file <CODE>include/curses.h.in</CODE>
-for mask values, near the end.
-
-<H1><A NAME="fmnote">The Forms and Menu Libraries</A></H1>
-
-The forms and menu libraries should work reliably in any environment you
-can port ncurses to. The only portability issue anywhere in them is what
-flavor of regular expressions the built-in form field type TYPE_REGEXP
-will recognize. <P>
-
-The configuration code prefers the POSIX regex facility, modeled on
-System V's, but will settle for BSD regexps if the former isn't available. <P>
-
-Historical note: the panels code was written primarily to assist in
-porting u386mon 2.0 (comp.sources.misc v14i001-4) to systems lacking
-panels support; u386mon 2.10 and beyond use it. This version has been
-slightly cleaned up for <CODE>ncurses</CODE>.
-
-<H1><A NAME="tic">A Tour of the Terminfo Compiler</A></H1>
-
-The <STRONG>ncurses</STRONG> implementation of <STRONG>tic</STRONG> is rather complex
-internally; it has to do a trying combination of missions. This starts
-with the fact that, in addition to its normal duty of compiling
-terminfo sources into loadable terminfo binaries, it has to be able to
-handle termcap syntax and compile that too into terminfo entries. <P>
-
-The implementation therefore starts with a table-driven, dual-mode
-lexical analyzer (in <CODE>comp_scan.c</CODE>). The lexer chooses its
-mode (termcap or terminfo) based on the first `,' or `:' it finds in
-each entry. The lexer does all the work of recognizing capability
-names and values; the grammar above it is trivial, just "parse entries
-till you run out of file".
-
-<H2><A NAME="nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A></H2>
-
-Translation of most things besides <STRONG>use</STRONG> capabilities is pretty
-straightforward. The lexical analyzer's tokenizer hands each capability
-name to a hash function, which drives a table lookup. The table entry
-yields an index which is used to look up the token type in another table,
-and controls interpretation of the value. <P>
-
-One possibly interesting aspect of the implementation is the way the
-compiler tables are initialized. All the tables are generated by various
-awk/sed/sh scripts from a master table <CODE>include/Caps</CODE>; these
-scripts actually write C initializers which are linked to the compiler.
-Furthermore, the hash table is generated in the same way, so it doesn't
-have to be generated at compiler startup time (another benefit of this
-organization is that the hash table can be in shareable text space). <P>
-
-Thus, adding a new capability is usually pretty trivial, just a matter
-of adding one line to the <CODE>include/Caps</CODE> file. We'll have more
-to say about this in the section on <A HREF="#translation">Source-Form
-Translation</A>.
-
-<H2><A NAME="uses">Use Capability Resolution</A></H2>
-
-The background problem that makes <STRONG>tic</STRONG> tricky isn't the capability
-translation itself, it's the resolution of <STRONG>use</STRONG> capabilities. Older
-versions would not handle forward <STRONG>use</STRONG> references for this reason
-(that is, a using terminal always had to follow its use target in the
-source file). By doing this, they got away with a simple implementation
-tactic; compile everything as it blows by, then resolve uses from compiled
-entries. <P>
-
-This won't do for <STRONG>ncurses</STRONG>. The problem is that that the whole
-compilation process has to be embeddable in the <STRONG>ncurses</STRONG> library
-so that it can be called by the startup code to translate termcap
-entries on the fly. The embedded version can't go promiscuously writing
-everything it translates out to disk -- for one thing, it will typically
-be running with non-root permissions. <P>
-
-So our <STRONG>tic</STRONG> is designed to parse an entire terminfo file into a
-doubly-linked circular list of entry structures in-core, and then do
-<STRONG>use</STRONG> resolution in-memory before writing everything out. This
-design has other advantages: it makes forward and back use-references
-equally easy (so we get the latter for free), and it makes checking for
-name collisions before they're written out easy to do. <P>
-
-And this is exactly how the embedded version works. But the stand-alone
-user-accessible version of <STRONG>tic</STRONG> partly reverts to the historical
-strategy; it writes to disk (not keeping in core) any entry with no
-<STRONG>use</STRONG> references. <P>
-
-This is strictly a core-economy kluge, implemented because the
-terminfo master file is large enough that some core-poor systems swap
-like crazy when you compile it all in memory...there have been reports of
-this process taking <STRONG>three hours</STRONG>, rather than the twenty seconds
-or less typical on the author's development box. <P>
-
-So. The executable <STRONG>tic</STRONG> passes the entry-parser a hook that
-<EM>immediately</EM> writes out the referenced entry if it has no use
-capabilities. The compiler main loop refrains from adding the entry
-to the in-core list when this hook fires. If some other entry later
-needs to reference an entry that got written immediately, that's OK;
-the resolution code will fetch it off disk when it can't find it in
-core. <P>
-
-Name collisions will still be detected, just not as cleanly. The
-<CODE>write_entry()</CODE> code complains before overwriting an entry that
-postdates the time of <STRONG>tic</STRONG>'s first call to
-<CODE>write_entry()</CODE>, Thus it will complain about overwriting
-entries newly made during the <STRONG>tic</STRONG> run, but not about
-overwriting ones that predate it.
-
-<H2><A NAME="translation">Source-Form Translation</A></H2>
-
-Another use of <STRONG>tic</STRONG> is to do source translation between various termcap
-and terminfo formats. There are more variants out there than you might
-think; the ones we know about are described in the <STRONG>captoinfo(1)</STRONG>
-manual page. <P>
-
-The translation output code (<CODE>dump_entry()</CODE> in
-<CODE>ncurses/dump_entry.c</CODE>) is shared with the <STRONG>infocmp(1)</STRONG>
-utility. It takes the same internal representation used to generate
-the binary form and dumps it to standard output in a specified
-format. <P>
-
-The <CODE>include/Caps</CODE> file has a header comment describing ways you
-can specify source translations for nonstandard capabilities just by
-altering the master table. It's possible to set up capability aliasing
-or tell the compiler to plain ignore a given capability without writing
-any C code at all. <P>
-
-For circumstances where you need to do algorithmic translation, there
-are functions in <CODE>parse_entry.c</CODE> called after the parse of each
-entry that are specifically intended to encapsulate such
-translations. This, for example, is where the AIX <STRONG>box1</STRONG> capability
-get translated to an <STRONG>acsc</STRONG> string.
-
-<H1><A NAME="utils">Other Utilities</A></H1>
-
-The <STRONG>infocmp</STRONG> utility is just a wrapper around the same
-entry-dumping code used by <STRONG>tic</STRONG> for source translation. Perhaps
-the one interesting aspect of the code is the use of a predicate
-function passed in to <CODE>dump_entry()</CODE> to control which
-capabilities are dumped. This is necessary in order to handle both
-the ordinary De-compilation case and entry difference reporting. <P>
-
-The <STRONG>tput</STRONG> and <STRONG>clear</STRONG> utilities just do an entry load
-followed by a <CODE>tputs()</CODE> of a selected capability.
-
-<H1><A NAME="style">Style Tips for Developers</A></H1>
-
-See the TO-DO file in the top-level directory of the source distribution
-for additions that would be particularly useful. <P>
-
-The prefix <CODE>_nc_</CODE> should be used on library public functions that are
-not part of the curses API in order to prevent pollution of the
-application namespace.
-
-If you have to add to or modify the function prototypes in curses.h.in,
-read ncurses/MKlib_gen.sh first so you can avoid breaking XSI conformance.
-
-Please join the ncurses mailing list. See the INSTALL file in the
-top level of the distribution for details on the list. <P>
-
-Look for the string <CODE>FIXME</CODE> in source files to tag minor bugs
-and potential problems that could use fixing. <P>
-
-Don't try to auto-detect OS features in the main body of the C code.
-That's the job of the configuration system. <P>
-
-To hold down complexity, do make your code data-driven. Especially,
-if you can drive logic from a table filtered out of
-<CODE>include/Caps</CODE>, do it. If you find you need to augment the
-data in that file in order to generate the proper table, that's still
-preferable to ad-hoc code -- that's why the fifth field (flags) is
-there. <P>
-
-Have fun!
-
-<H1><A NAME="port">Porting Hints</A></H1>
-
-The following notes are intended to be a first step towards DOS and Macintosh
-ports of the ncurses libraries. <P>
-
-The following library modules are `pure curses'; they operate only on
-the curses internal structures, do all output through other curses
-calls (not including <CODE>tputs()</CODE> and <CODE>putp()</CODE>) and do not
-call any other UNIX routines such as signal(2) or the stdio library.
-Thus, they should not need to be modified for single-terminal
-ports.
-
-<blockquote>
-<code>
-lib_addch.c
-lib_addstr.c
-lib_bkgd.c
-lib_box.c
-lib_clear.c
-lib_clrbot.c
-lib_clreol.c
-lib_delch.c
-lib_delwin.c
-lib_erase.c
-lib_inchstr.c
-lib_insch.c
-lib_insdel.c
-lib_insstr.c
-lib_keyname.c
-lib_move.c
-lib_mvwin.c
-lib_newwin.c
-lib_overlay.c
-lib_pad.c
-lib_printw.c
-lib_refresh.c
-lib_scanw.c
-lib_scroll.c
-lib_scrreg.c
-lib_set_term.c
-lib_touch.c
-lib_tparm.c
-lib_tputs.c
-lib_unctrl.c
-lib_window.c
-panel.c
-</code>
-</blockquote>
-<P>
-
-This module is pure curses, but calls outstr():
-
-<blockquote>
-<code>
-lib_getstr.c
-</code>
-</blockquote>
-<P>
-
-These modules are pure curses, except that they use <CODE>tputs()</CODE>
-and <CODE>putp()</CODE>:
-
-<blockquote>
-<code>
-lib_beep.c
-lib_color.c
-lib_endwin.c
-lib_options.c
-lib_slk.c
-lib_vidattr.c
-</code>
-</blockquote>
-<P>
-
-This modules assist in POSIX emulation on non-POSIX systems:
-<DL>
-<DT> sigaction.c
-<DD> signal calls
-</DL>
-
-The following source files will not be needed for a
-single-terminal-type port.
-
-<blockquote>
-<code>
-alloc_entry.c
-captoinfo.c
-clear.c
-comp_captab.c
-comp_error.c
-comp_hash.c
-comp_main.c
-comp_parse.c
-comp_scan.c
-dump_entry.c
-infocmp.c
-parse_entry.c
-read_entry.c
-tput.c
-write_entry.c
-</code>
-</blockquote>
-<P>
-
-The following modules will use open()/read()/write()/close()/lseek() on files,
-but no other OS calls.
-
-<DL>
-<DT>lib_screen.c
-<DD>used to read/write screen dumps
-<DT>lib_trace.c
-<DD>used to write trace data to the logfile
-</DL>
-
-Modules that would have to be modified for a port start here: <P>
-
-The following modules are `pure curses' but contain assumptions inappropriate
-for a memory-mapped port.
-
-<dl>
-<dt>lib_longname.c<dd>assumes there may be multiple terminals
-<dt>lib_acs.c<dd>assumes acs_map as a double indirection
-<dt>lib_mvcur.c<dd>assumes cursor moves have variable cost
-<dt>lib_termcap.c<dd>assumes there may be multiple terminals
-<dt>lib_ti.c<dd>assumes there may be multiple terminals
-</dl>
-
-The following modules use UNIX-specific calls:
-
-<dl>
-<dt>lib_doupdate.c<dd>input checking
-<dt>lib_getch.c<dd>read()
-<dt>lib_initscr.c<dd>getenv()
-<dt>lib_newterm.c
-<dt>lib_baudrate.c
-<dt>lib_kernel.c<dd>various tty-manipulation and system calls
-<dt>lib_raw.c<dd>various tty-manipulation calls
-<dt>lib_setup.c<dd>various tty-manipulation calls
-<dt>lib_restart.c<dd>various tty-manipulation calls
-<dt>lib_tstp.c<dd>signal-manipulation calls
-<dt>lib_twait.c<dd>gettimeofday(), select().
-</dl>
-
-<HR>
-<ADDRESS>Eric S. Raymond &lt;esr@snark.thyrsus.com&gt;</ADDRESS>
-(Note: This is <EM>not</EM> the <A HREF="#bugtrack">bug address</A>!)
-</BODY>
-</HTML>
diff --git a/contrib/ncurses/doc/html/ncurses-intro.html b/contrib/ncurses/doc/html/ncurses-intro.html
deleted file mode 100644
index 451e7ab4d32d..000000000000
--- a/contrib/ncurses/doc/html/ncurses-intro.html
+++ /dev/null
@@ -1,2722 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">
-<!--
- $Id: ncurses-intro.html,v 1.43 2007/03/03 19:31:50 tom Exp $
- ****************************************************************************
- * Copyright (c) 1998-2006,2007 Free Software Foundation, Inc. *
- * *
- * Permission is hereby granted, free of charge, to any person obtaining a *
- * copy of this software and associated documentation files (the *
- * "Software"), to deal in the Software without restriction, including *
- * without limitation the rights to use, copy, modify, merge, publish, *
- * distribute, distribute with modifications, sublicense, and/or sell *
- * copies of the Software, and to permit persons to whom the Software is *
- * furnished to do so, subject to the following conditions: *
- * *
- * The above copyright notice and this permission notice shall be included *
- * in all copies or substantial portions of the Software. *
- * *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
- * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
- * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
- * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
- * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
- * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
- * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
- * *
- * Except as contained in this notice, the name(s) of the above copyright *
- * holders shall not be used in advertising or otherwise to promote the *
- * sale, use or other dealings in this Software without prior written *
- * authorization. *
- ****************************************************************************
--->
-<HTML>
-<HEAD>
-<TITLE>Writing Programs with NCURSES</TITLE>
-<link rev="made" href="mailto:bugs-ncurses@gnu.org">
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-</HEAD>
-<BODY>
-
-<H1>Writing Programs with NCURSES</H1>
-
-<BLOCKQUOTE>
-by Eric S. Raymond and Zeyd M. Ben-Halim<BR>
-updates since release 1.9.9e by Thomas Dickey
-</BLOCKQUOTE>
-
-<H1>Contents</H1>
-<UL>
-<LI><A HREF="#introduction">Introduction</A>
-<UL>
-<LI><A HREF="#history">A Brief History of Curses</A>
-<LI><A HREF="#scope">Scope of This Document</A>
-<LI><A HREF="#terminology">Terminology</A>
-</UL>
-<LI><A HREF="#curses">The Curses Library</A>
-<UL>
-<LI><A HREF="#overview">An Overview of Curses</A>
-<UL>
-<LI><A HREF="#compiling">Compiling Programs using Curses</A>
-<LI><A HREF="#updating">Updating the Screen</A>
-<LI><A HREF="#stdscr">Standard Windows and Function Naming Conventions</A>
-<LI><A HREF="#variables">Variables</A>
-</UL>
-<LI><A HREF="#using">Using the Library</A>
-<UL>
-<LI><A HREF="#starting">Starting up</A>
-<LI><A HREF="#output">Output</A>
-<LI><A HREF="#input">Input</A>
-<LI><A HREF="#formschars">Using Forms Characters</A>
-<LI><A HREF="#attributes">Character Attributes and Color</A>
-<LI><A HREF="#mouse">Mouse Interfacing</A>
-<LI><A HREF="#finishing">Finishing Up</A>
-</UL>
-<LI><A HREF="#functions">Function Descriptions</A>
-<UL>
-<LI><A HREF="#init">Initialization and Wrapup</A>
-<LI><A HREF="#flush">Causing Output to the Terminal</A>
-<LI><A HREF="#lowlevel">Low-Level Capability Access</A>
-<LI><A HREF="#debugging">Debugging</A>
-</UL>
-<LI><A HREF="#hints">Hints, Tips, and Tricks</A>
-<UL>
-<LI><A HREF="#caution">Some Notes of Caution</A>
-<LI><A HREF="#leaving">Temporarily Leaving ncurses Mode</A>
-<LI><A HREF="#xterm">Using <CODE>ncurses</CODE> under <CODE>xterm</CODE></A>
-<LI><A HREF="#screens">Handling Multiple Terminal Screens</A>
-<LI><A HREF="#testing">Testing for Terminal Capabilities</A>
-<LI><A HREF="#tuning">Tuning for Speed</A>
-<LI><A HREF="#special">Special Features of <CODE>ncurses</CODE></A>
-</UL>
-<LI><A HREF="#compat">Compatibility with Older Versions</A>
-<UL>
-<LI><A HREF="#refbug">Refresh of Overlapping Windows</A>
-<LI><A HREF="#backbug">Background Erase</A>
-</UL>
-<LI><A HREF="#xsifuncs">XSI Curses Conformance</A>
-</UL>
-<LI><A HREF="#panels">The Panels Library</A>
-<UL>
-<LI><A HREF="#pcompile">Compiling With the Panels Library</A>
-<LI><A HREF="#poverview">Overview of Panels</A>
-<LI><A HREF="#pstdscr">Panels, Input, and the Standard Screen</A>
-<LI><A HREF="#hiding">Hiding Panels</A>
-<LI><A HREF="#pmisc">Miscellaneous Other Facilities</A>
-</UL>
-<LI><A HREF="#menu">The Menu Library</A>
-<UL>
-<LI><A HREF="#mcompile">Compiling with the menu Library</A>
-<LI><A HREF="#moverview">Overview of Menus</A>
-<LI><A HREF="#mselect">Selecting items</A>
-<LI><A HREF="#mdisplay">Menu Display</A>
-<LI><A HREF="#mwindows">Menu Windows</A>
-<LI><A HREF="#minput">Processing Menu Input</A>
-<LI><A HREF="#mmisc">Miscellaneous Other Features</A>
-</UL>
-<LI><A HREF="#form">The Forms Library</A>
-<UL>
-<LI><A HREF="#fcompile">Compiling with the forms Library</A>
-<LI><A HREF="#foverview">Overview of Forms</A>
-<LI><A HREF="#fcreate">Creating and Freeing Fields and Forms</A>
-<LI><A HREF="#fattributes">Fetching and Changing Field Attributes</A>
-<UL>
-<LI><A HREF="#fsizes">Fetching Size and Location Data</A>
-<LI><A HREF="#flocation">Changing the Field Location</A>
-<LI><A HREF="#fjust">The Justification Attribute</A>
-<LI><A HREF="#fdispatts">Field Display Attributes</A>
-<LI><A HREF="#foptions">Field Option Bits</A>
-<LI><A HREF="#fstatus">Field Status</A>
-<LI><A HREF="#fuser">Field User Pointer</A>
-</UL>
-<LI><A HREF="#fdynamic">Variable-Sized Fields</A>
-<LI><A HREF="#fvalidation">Field Validation</A>
-<UL>
-<LI><A HREF="#ftype_alpha">TYPE_ALPHA</A>
-<LI><A HREF="#ftype_alnum">TYPE_ALNUM</A>
-<LI><A HREF="#ftype_enum">TYPE_ENUM</A>
-<LI><A HREF="#ftype_integer">TYPE_INTEGER</A>
-<LI><A HREF="#ftype_numeric">TYPE_NUMERIC</A>
-<LI><A HREF="#ftype_regexp">TYPE_REGEXP</A>
-</UL>
-<LI><A HREF="#fbuffer">Direct Field Buffer Manipulation</A>
-<LI><A HREF="#formattrs">Attributes of Forms</A>
-<LI><A HREF="#fdisplay">Control of Form Display</A>
-<LI><A HREF="#fdriver">Input Processing in the Forms Driver</A>
-<UL>
-<LI><A HREF="#fpage">Page Navigation Requests</A>
-<LI><A HREF="#ffield">Inter-Field Navigation Requests</A>
-<LI><A HREF="#fifield">Intra-Field Navigation Requests</A>
-<LI><A HREF="#fscroll">Scrolling Requests</A>
-<LI><A HREF="#fedit">Field Editing Requests</A>
-<LI><A HREF="#forder">Order Requests</A>
-<LI><A HREF="#fappcmds">Application Commands</A>
-</UL>
-<LI><A HREF="#fhooks">Field Change Hooks</A>
-<LI><A HREF="#ffocus">Field Change Commands</A>
-<LI><A HREF="#frmoptions">Form Options</A>
-<LI><A HREF="#fcustom">Custom Validation Types</A>
-<UL>
-<LI><A HREF="#flinktypes">Union Types</A>
-<LI><A HREF="#fnewtypes">New Field Types</A>
-<LI><A HREF="#fcheckargs">Validation Function Arguments</A>
-<LI><A HREF="#fcustorder">Order Functions For Custom Types</A>
-<LI><A HREF="#fcustprobs">Avoiding Problems</A>
-</UL>
-</UL>
-</UL>
-
-<HR>
-<H1><A NAME="introduction">Introduction</A></H1>
-
-This document is an introduction to programming with <CODE>curses</CODE>. It is
-not an exhaustive reference for the curses Application Programming Interface
-(API); that role is filled by the <CODE>curses</CODE> manual pages. Rather, it
-is intended to help C programmers ease into using the package. <P>
-
-This document is aimed at C applications programmers not yet specifically
-familiar with ncurses. If you are already an experienced <CODE>curses</CODE>
-programmer, you should nevertheless read the sections on
-<A HREF="#mouse">Mouse Interfacing</A>, <A HREF="#debugging">Debugging</A>,
-<A HREF="#compat">Compatibility with Older Versions</A>,
-and <A HREF="#hints">Hints, Tips, and Tricks</A>. These will bring you up
-to speed on the special features and quirks of the <CODE>ncurses</CODE>
-implementation. If you are not so experienced, keep reading. <P>
-
-The <CODE>curses</CODE> package is a subroutine library for
-terminal-independent screen-painting and input-event handling which
-presents a high level screen model to the programmer, hiding differences
-between terminal types and doing automatic optimization of output to change
-one screen full of text into another. <CODE>Curses</CODE> uses terminfo, which
-is a database format that can describe the capabilities of thousands of
-different terminals. <P>
-
-The <CODE>curses</CODE> API may seem something of an archaism on UNIX desktops
-increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX still
-supports tty lines and X supports <EM>xterm(1)</EM>; the <CODE>curses</CODE>
-API has the advantage of (a) back-portability to character-cell terminals,
-and (b) simplicity. For an application that does not require bit-mapped
-graphics and multiple fonts, an interface implementation using <CODE>curses</CODE>
-will typically be a great deal simpler and less expensive than one using an
-X toolkit.
-
-<H2><A NAME="history">A Brief History of Curses</A></H2>
-
-Historically, the first ancestor of <CODE>curses</CODE> was the routines written to
-provide screen-handling for the game <CODE>rogue</CODE>; these used the
-already-existing <CODE>termcap</CODE> database facility for describing terminal
-capabilities. These routines were abstracted into a documented library and
-first released with the early BSD UNIX versions. <P>
-
-System III UNIX from Bell Labs featured a rewritten and much-improved
-<CODE>curses</CODE> library. It introduced the terminfo format. Terminfo is based
-on Berkeley's termcap database, but contains a number of improvements and
-extensions. Parameterized capabilities strings were introduced, making it
-possible to describe multiple video attributes, and colors and to handle far
-more unusual terminals than possible with termcap. In the later AT&amp;T
-System V releases, <CODE>curses</CODE> evolved to use more facilities and offer
-more capabilities, going far beyond BSD curses in power and flexibility.
-
-<H2><A NAME="scope">Scope of This Document</A></H2>
-
-This document describes <CODE>ncurses</CODE>, a free implementation of
-the System V <CODE>curses</CODE> API with some clearly marked extensions.
-It includes the following System V curses features:
-<UL>
-<LI>Support for multiple screen highlights (BSD curses could only
-handle one `standout' highlight, usually reverse-video).
-<LI>Support for line- and box-drawing using forms characters.
-<LI>Recognition of function keys on input.
-<LI>Color support.
-<LI>Support for pads (windows of larger than screen size on which the
-screen or a subwindow defines a viewport).
-</UL>
-
-Also, this package makes use of the insert and delete line and character
-features of terminals so equipped, and determines how to optimally use these
-features with no help from the programmer. It allows arbitrary combinations of
-video attributes to be displayed, even on terminals that leave ``magic
-cookies'' on the screen to mark changes in attributes. <P>
-
-The <CODE>ncurses</CODE> package can also capture and use event reports from a
-mouse in some environments (notably, xterm under the X window system). This
-document includes tips for using the mouse. <P>
-
-The <CODE>ncurses</CODE> package was originated by Pavel Curtis. The original
-maintainer of this package is
-<A HREF="mailto:zmbenhal@netcom.com">Zeyd Ben-Halim</A>
-&lt;zmbenhal@netcom.com&gt;.
-<A HREF="mailto:esr@snark.thyrsus.com">Eric S. Raymond</A>
-&lt;esr@snark.thyrsus.com&gt;
-wrote many of the new features in versions after 1.8.1
-and wrote most of this introduction.
-J&uuml;rgen Pfeifer
-wrote all of the menu and forms code as well as the
-<A HREF="http://www.adahome.com">Ada95</A> binding.
-Ongoing work is being done by
-<A HREF="mailto:dickey@invisible-island.net">Thomas Dickey</A> (maintainer).
-Contact the current maintainers at
-<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>.
-<P>
-
-This document also describes the <A HREF="#panels">panels</A> extension library,
-similarly modeled on the SVr4 panels facility. This library allows you to
-associate backing store with each of a stack or deck of overlapping windows,
-and provides operations for moving windows around in the stack that change
-their visibility in the natural way (handling window overlaps). <P>
-
-Finally, this document describes in detail the <A HREF="#menu">menus</A> and <A
-HREF="#form">forms</A> extension libraries, also cloned from System V,
-which support easy construction and sequences of menus and fill-in
-forms.
-
-
-<H2><A NAME="terminology">Terminology</A></H2>
-
-In this document, the following terminology is used with reasonable
-consistency:
-
-<DL>
-<DT> window
-<DD>
-A data structure describing a sub-rectangle of the screen (possibly the
-entire screen). You can write to a window as though it were a miniature
-screen, scrolling independently of other windows on the physical screen.
-<DT> screens
-<DD>
-A subset of windows which are as large as the terminal screen, i.e., they start
-at the upper left hand corner and encompass the lower right hand corner. One
-of these, <CODE>stdscr</CODE>, is automatically provided for the programmer.
-<DT> terminal screen
-<DD>
-The package's idea of what the terminal display currently looks like, i.e.,
-what the user sees now. This is a special screen.
-</DL>
-
-<H1><A NAME="curses">The Curses Library</A></H1>
-
-<H2><A NAME="overview">An Overview of Curses</A></H2>
-
-<H3><A NAME="compiling">Compiling Programs using Curses</A></H3>
-
-In order to use the library, it is necessary to have certain types and
-variables defined. Therefore, the programmer must have a line:
-
-<PRE>
- #include &lt;curses.h&gt;
-</PRE>
-
-at the top of the program source. The screen package uses the Standard I/O
-library, so <CODE>&lt;curses.h&gt;</CODE> includes
-<CODE>&lt;stdio.h&gt;</CODE>. <CODE>&lt;curses.h&gt;</CODE> also includes
-<CODE>&lt;termios.h&gt;</CODE>, <CODE>&lt;termio.h&gt;</CODE>, or
-<CODE>&lt;sgtty.h&gt;</CODE> depending on your system. It is redundant (but
-harmless) for the programmer to do these includes, too. In linking with
-<CODE>curses</CODE> you need to have <CODE>-lncurses</CODE> in your LDFLAGS or on the
-command line. There is no need for any other libraries.
-
-<H3><A NAME="updating">Updating the Screen</A></H3>
-
-In order to update the screen optimally, it is necessary for the routines to
-know what the screen currently looks like and what the programmer wants it to
-look like next. For this purpose, a data type (structure) named WINDOW is
-defined which describes a window image to the routines, including its starting
-position on the screen (the (y, x) coordinates of the upper left hand corner)
-and its size. One of these (called <CODE>curscr</CODE>, for current screen) is a
-screen image of what the terminal currently looks like. Another screen (called
-<CODE>stdscr</CODE>, for standard screen) is provided by default to make changes
-on. <P>
-
-A window is a purely internal representation. It is used to build and store a
-potential image of a portion of the terminal. It doesn't bear any necessary
-relation to what is really on the terminal screen; it's more like a
-scratchpad or write buffer. <P>
-
-To make the section of physical screen corresponding to a window reflect the
-contents of the window structure, the routine <CODE>refresh()</CODE> (or
-<CODE>wrefresh()</CODE> if the window is not <CODE>stdscr</CODE>) is called. <P>
-
-A given physical screen section may be within the scope of any number of
-overlapping windows. Also, changes can be made to windows in any order,
-without regard to motion efficiency. Then, at will, the programmer can
-effectively say ``make it look like this,'' and let the package implementation
-determine the most efficient way to repaint the screen.
-
-<H3><A NAME="stdscr">Standard Windows and Function Naming Conventions</A></H3>
-
-As hinted above, the routines can use several windows, but two are
-automatically given: <CODE>curscr</CODE>, which knows what the terminal looks like,
-and <CODE>stdscr</CODE>, which is what the programmer wants the terminal to look
-like next. The user should never actually access <CODE>curscr</CODE> directly.
-Changes should be made to through the API, and then the routine
-<CODE>refresh()</CODE> (or <CODE>wrefresh()</CODE>) called. <P>
-
-Many functions are defined to use <CODE>stdscr</CODE> as a default screen. For
-example, to add a character to <CODE>stdscr</CODE>, one calls <CODE>addch()</CODE> with
-the desired character as argument. To write to a different window. use the
-routine <CODE>waddch()</CODE> (for `w'indow-specific addch()) is provided. This
-convention of prepending function names with a `w' when they are to be
-applied to specific windows is consistent. The only routines which do not
-follow it are those for which a window must always be specified. <P>
-
-In order to move the current (y, x) coordinates from one point to another, the
-routines <CODE>move()</CODE> and <CODE>wmove()</CODE> are provided. However, it is
-often desirable to first move and then perform some I/O operation. In 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
-
-<PRE>
- move(y, x);
- addch(ch);
-</PRE>
-
-can be replaced by
-
-<PRE>
- mvaddch(y, x, ch);
-</PRE>
-
-and
-
-<PRE>
- wmove(win, y, x);
- waddch(win, ch);
-</PRE>
-
-can be replaced by
-
-<PRE>
- mvwaddch(win, y, x, ch);
-</PRE>
-
-Note that the window description pointer (win) comes before the added (y, x)
-coordinates. If a function requires a window pointer, it is always the first
-parameter passed.
-
-<H3><A NAME="variables">Variables</A></H3>
-
-The <CODE>curses</CODE> library sets some variables describing the terminal
-capabilities.
-
-<PRE>
- type name description
- ------------------------------------------------------------------
- int LINES number of lines on the terminal
- int COLS number of columns on the terminal
-</PRE>
-
-The <CODE>curses.h</CODE> also introduces some <CODE>#define</CODE> constants and types
-of general usefulness:
-
-<DL>
-<DT> <CODE>bool</CODE>
-<DD> boolean type, actually a `char' (e.g., <CODE>bool doneit;</CODE>)
-<DT> <CODE>TRUE</CODE>
-<DD> boolean `true' flag (1).
-<DT> <CODE>FALSE</CODE>
-<DD> boolean `false' flag (0).
-<DT> <CODE>ERR</CODE>
-<DD> error flag returned by routines on a failure (-1).
-<DT> <CODE>OK</CODE>
-<DD> error flag returned by routines when things go right.
-</DL>
-
-<H2><A NAME="using">Using the Library</A></H2>
-
-Now we describe how to actually use the screen package. In it, we assume all
-updating, reading, etc. is applied to <CODE>stdscr</CODE>. These instructions will
-work on any window, providing you change the function names and parameters as
-mentioned above. <P>
-
-Here is a sample program to motivate the discussion:
-
-<PRE>
-#include &lt;curses.h&gt;
-#include &lt;signal.h&gt;
-
-static void finish(int sig);
-
-int
-main(int argc, char *argv[])
-{
- int num = 0;
-
- /* initialize your non-curses data structures here */
-
- (void) signal(SIGINT, finish); /* arrange interrupts to terminate */
-
- (void) initscr(); /* initialize the curses library */
- keypad(stdscr, TRUE); /* enable keyboard mapping */
- (void) nonl(); /* tell curses not to do NL-&gt;CR/NL on output */
- (void) cbreak(); /* take input chars one at a time, no wait for \n */
- (void) echo(); /* echo input - in color */
-
- if (has_colors())
- {
- start_color();
-
- /*
- * Simple color assignment, often all we need. Color pair 0 cannot
- * be redefined. This example uses the same value for the color
- * pair as for the foreground color, though of course that is not
- * necessary:
- */
- init_pair(1, COLOR_RED, COLOR_BLACK);
- init_pair(2, COLOR_GREEN, COLOR_BLACK);
- init_pair(3, COLOR_YELLOW, COLOR_BLACK);
- init_pair(4, COLOR_BLUE, COLOR_BLACK);
- init_pair(5, COLOR_CYAN, COLOR_BLACK);
- init_pair(6, COLOR_MAGENTA, COLOR_BLACK);
- init_pair(7, COLOR_WHITE, COLOR_BLACK);
- }
-
- for (;;)
- {
- int c = getch(); /* refresh, accept single keystroke of input */
- attrset(COLOR_PAIR(num % 8));
- num++;
-
- /* process the command keystroke */
- }
-
- finish(0); /* we're done */
-}
-
-static void finish(int sig)
-{
- endwin();
-
- /* do your non-curses wrapup here */
-
- exit(0);
-}
-</PRE>
-
-<H3><A NAME="starting">Starting up</A></H3>
-
-In order to use the screen package, the routines must know about terminal
-characteristics, and the space for <CODE>curscr</CODE> and <CODE>stdscr</CODE> must be
-allocated. These function <CODE>initscr()</CODE> does both these things. Since it
-must allocate space for the windows, it can overflow memory when attempting to
-do so. On the rare occasions this happens, <CODE>initscr()</CODE> will terminate
-the program with an error message. <CODE>initscr()</CODE> must always be called
-before any of the routines which affect windows are used. If it is not, the
-program will core dump as soon as either <CODE>curscr</CODE> or <CODE>stdscr</CODE> are
-referenced. However, it is usually best to wait to call it until after you are
-sure you will need it, like after checking for startup errors. Terminal status
-changing routines like <CODE>nl()</CODE> and <CODE>cbreak()</CODE> should be called
-after <CODE>initscr()</CODE>. <P>
-
-Once the screen windows have been allocated, you can set them up for
-your program. If you want to, say, allow a screen to scroll, use
-<CODE>scrollok()</CODE>. If you want the cursor to be left in place after
-the last change, use <CODE>leaveok()</CODE>. If this isn't done,
-<CODE>refresh()</CODE> will move the cursor to the window's current (y, x)
-coordinates after updating it. <P>
-
-You can create new windows of your own using the functions <CODE>newwin()</CODE>,
-<CODE>derwin()</CODE>, and <CODE>subwin()</CODE>. The routine <CODE>delwin()</CODE> will
-allow you to get rid of old windows. All the options described above can be
-applied to any window.
-
-<H3><A NAME="output">Output</A></H3>
-
-Now that we have set things up, we will want to actually update the terminal.
-The basic functions used to change what will go on a window are
-<CODE>addch()</CODE> and <CODE>move()</CODE>. <CODE>addch()</CODE> adds a character at the
-current (y, x) coordinates. <CODE>move()</CODE> changes the current (y, x)
-coordinates to whatever you want them to be. It returns <CODE>ERR</CODE> if you
-try to move off the window. As mentioned above, you can combine the two into
-<CODE>mvaddch()</CODE> to do both things at once. <P>
-
-The other output functions, such as <CODE>addstr()</CODE> and <CODE>printw()</CODE>,
-all call <CODE>addch()</CODE> to add characters to the window. <P>
-
-After you have put on the window what you want there, when you want the portion
-of the terminal covered by the window to be made to look like it, you must call
-<CODE>refresh()</CODE>. In order to optimize finding changes, <CODE>refresh()</CODE>
-assumes that any part of the window not changed since the last
-<CODE>refresh()</CODE> of that window has not been changed on the terminal, i.e.,
-that you have not refreshed a portion of the terminal with an overlapping
-window. If this is not the case, the routine <CODE>touchwin()</CODE> is provided
-to make it look like the entire window has been changed, thus making
-<CODE>refresh()</CODE> check the whole subsection of the terminal for changes. <P>
-
-If you call <CODE>wrefresh()</CODE> with <CODE>curscr</CODE> as its argument, it will
-make the screen look like <CODE>curscr</CODE> thinks it looks like. This is useful
-for implementing a command which would redraw the screen in case it get messed
-up.
-
-<H3><A NAME="input">Input</A></H3>
-
-The complementary function to <CODE>addch()</CODE> is <CODE>getch()</CODE> which, if
-echo is set, will call <CODE>addch()</CODE> to echo the character. Since the
-screen package needs to know what is on the terminal at all times, if
-characters are to be echoed, the tty must be in raw or cbreak mode. Since
-initially the terminal has echoing enabled and is in ordinary ``cooked'' mode,
-one or the other has to changed before calling <CODE>getch()</CODE>; otherwise,
-the program's output will be unpredictable. <P>
-
-When you need to accept line-oriented input in a window, the functions
-<CODE>wgetstr()</CODE> and friends are available. There is even a <CODE>wscanw()</CODE>
-function that can do <CODE>scanf()</CODE>(3)-style multi-field parsing on window
-input. These pseudo-line-oriented functions turn on echoing while they
-execute. <P>
-
-The example code above uses the call <CODE>keypad(stdscr, TRUE)</CODE> to enable
-support for function-key mapping. With this feature, the <CODE>getch()</CODE> code
-watches the input stream for character sequences that correspond to arrow and
-function keys. These sequences are returned as pseudo-character values. The
-<CODE>#define</CODE> values returned are listed in the <CODE>curses.h</CODE> The
-mapping from sequences to <CODE>#define</CODE> values is determined by
-<CODE>key_</CODE> capabilities in the terminal's terminfo entry.
-
-<H3><A NAME="formschars">Using Forms Characters</A></H3>
-
-The <CODE>addch()</CODE> function (and some others, including <CODE>box()</CODE> and
-<CODE>border()</CODE>) can accept some pseudo-character arguments which are specially
-defined by <CODE>ncurses</CODE>. These are <CODE>#define</CODE> values set up in
-the <CODE>curses.h</CODE> header; see there for a complete list (look for
-the prefix <CODE>ACS_</CODE>). <P>
-
-The most useful of the ACS defines are the forms-drawing characters. You can
-use these to draw boxes and simple graphs on the screen. If the terminal
-does not have such characters, <CODE>curses.h</CODE> will map them to a
-recognizable (though ugly) set of ASCII defaults.
-
-<H3><A NAME="attributes">Character Attributes and Color</A></H3>
-
-The <CODE>ncurses</CODE> package supports screen highlights including standout,
-reverse-video, underline, and blink. It also supports color, which is treated
-as another kind of highlight. <P>
-
-Highlights are encoded, internally, as high bits of the pseudo-character type
-(<CODE>chtype</CODE>) that <CODE>curses.h</CODE> uses to represent the contents of a
-screen cell. See the <CODE>curses.h</CODE> header file for a complete list of
-highlight mask values (look for the prefix <CODE>A_</CODE>).<P>
-
-There are two ways to make highlights. One is to logical-or the value of the
-highlights you want into the character argument of an <CODE>addch()</CODE> call,
-or any other output call that takes a <CODE>chtype</CODE> argument. <P>
-
-The other is to set the current-highlight value. This is logical-or'ed with
-any highlight you specify the first way. You do this with the functions
-<CODE>attron()</CODE>, <CODE>attroff()</CODE>, and <CODE>attrset()</CODE>; see the manual
-pages for details.
-
-Color is a special kind of highlight. The package actually thinks in terms
-of color pairs, combinations of foreground and background colors. The sample
-code above sets up eight color pairs, all of the guaranteed-available colors
-on black. Note that each color pair is, in effect, given the name of its
-foreground color. Any other range of eight non-conflicting values could
-have been used as the first arguments of the <CODE>init_pair()</CODE> values. <P>
-
-Once you've done an <CODE>init_pair()</CODE> that creates color-pair N, you can
-use <CODE>COLOR_PAIR(N)</CODE> as a highlight that invokes that particular
-color combination. Note that <CODE>COLOR_PAIR(N)</CODE>, for constant N,
-is itself a compile-time constant and can be used in initializers.
-
-<H3><A NAME="mouse">Mouse Interfacing</A></H3>
-
-The <CODE>ncurses</CODE> library also provides a mouse interface.
-<!-- The 'note' tag is not portable enough -->
-<blockquote>
-<strong>NOTE:</strong> this facility is specific to <CODE>ncurses</CODE>, 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.
-</blockquote>
-
-Presently, mouse event reporting works in the following environments:
-<ul>
-<li>xterm and similar programs such as rxvt.
-<li>Linux console, when configured with <CODE>gpm</CODE>(1), Alessandro
-Rubini's mouse server.
-<li>FreeBSD sysmouse (console)
-<li>OS/2 EMX
-</ul>
-<P>
-The mouse interface is very simple. To activate it, you use the function
-<CODE>mousemask()</CODE>, passing it as first argument a bit-mask that specifies
-what kinds of events you want your program to be able to see. It will
-return the bit-mask of events that actually become visible, which may differ
-from the argument if the mouse device is not capable of reporting some of
-the event types you specify. <P>
-
-Once the mouse is active, your application's command loop should watch
-for a return value of <CODE>KEY_MOUSE</CODE> from <CODE>wgetch()</CODE>. When
-you see this, a mouse event report has been queued. To pick it off
-the queue, use the function <CODE>getmouse()</CODE> (you must do this before
-the next <CODE>wgetch()</CODE>, otherwise another mouse event might come
-in and make the first one inaccessible). <P>
-
-Each call to <CODE>getmouse()</CODE> fills a structure (the address of which you'll
-pass it) with mouse event data. The event data includes zero-origin,
-screen-relative character-cell coordinates of the mouse pointer. It also
-includes an event mask. Bits in this mask will be set, corresponding
-to the event type being reported. <P>
-
-The mouse structure contains two additional fields which may be
-significant in the future as ncurses interfaces to new kinds of
-pointing device. In addition to x and y coordinates, there is a slot
-for a z coordinate; this might be useful with touch-screens that can
-return a pressure or duration parameter. There is also a device ID
-field, which could be used to distinguish between multiple pointing
-devices. <P>
-
-The class of visible events may be changed at any time via <CODE>mousemask()</CODE>.
-Events that can be reported include presses, releases, single-, double- and
-triple-clicks (you can set the maximum button-down time for clicks). If
-you don't make clicks visible, they will be reported as press-release
-pairs. In some environments, the event mask may include bits reporting
-the state of shift, alt, and ctrl keys on the keyboard during the event. <P>
-
-A function to check whether a mouse event fell within a given window is
-also supplied. You can use this to see whether a given window should
-consider a mouse event relevant to it. <P>
-
-Because mouse event reporting will not be available in all
-environments, it would be unwise to build <CODE>ncurses</CODE>
-applications that <EM>require</EM> the use of a mouse. Rather, you should
-use the mouse as a shortcut for point-and-shoot commands your application
-would normally accept from the keyboard. Two of the test games in the
-<CODE>ncurses</CODE> distribution (<CODE>bs</CODE> and <CODE>knight</CODE>) contain
-code that illustrates how this can be done. <P>
-
-See the manual page <CODE>curs_mouse(3X)</CODE> for full details of the
-mouse-interface functions.
-
-<H3><A NAME="finishing">Finishing Up</A></H3>
-
-In order to clean up after the <CODE>ncurses</CODE> routines, the routine
-<CODE>endwin()</CODE> is provided. It restores tty modes to what they were when
-<CODE>initscr()</CODE> was first called, and moves the cursor down to the
-lower-left corner. Thus, anytime after the call to initscr, <CODE>endwin()</CODE>
-should be called before exiting.
-
-<H2><A NAME="functions">Function Descriptions</A></H2>
-
-We describe the detailed behavior of some important curses functions here, as a
-supplement to the manual page descriptions.
-
-<H3><A NAME="init">Initialization and Wrapup</A></H3>
-
-<DL>
-<DT> <CODE>initscr()</CODE>
-<DD> The first function called should almost always be <CODE>initscr()</CODE>.
-This will determine the terminal type and
-initialize curses data structures. <CODE>initscr()</CODE> also arranges that
-the first call to <CODE>refresh()</CODE> 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 (<CODE>slk_init()</CODE>, <CODE>filter()</CODE>,
-<CODE>ripoffline()</CODE>, <CODE>use_env()</CODE>, and, if you are using multiple
-terminals, <CODE>newterm()</CODE>.)
-<DT> <CODE>endwin()</CODE>
-<DD> Your program should always call <CODE>endwin()</CODE> before exiting or
-shelling out of the program. This function will restore tty modes,
-move the cursor to the lower left corner of the screen, reset the
-terminal into the proper non-visual mode. Calling <CODE>refresh()</CODE>
-or <CODE>doupdate()</CODE> after a temporary escape from the program will
-restore the ncurses screen from before the escape.
-<DT> <CODE>newterm(type, ofp, ifp)</CODE>
-<DD> A program which outputs to more than one terminal should use
-<CODE>newterm()</CODE> instead of <CODE>initscr()</CODE>. <CODE>newterm()</CODE> should
-be called once for each terminal. It returns a variable of type
-<CODE>SCREEN *</CODE> which should be saved as a reference to that
-terminal.
-(NOTE: a SCREEN variable is not a <em>screen</em> in the sense we
-are describing in this introduction, but a collection of
-parameters used to assist in optimizing the display.)
-The arguments are the type of the terminal (a string) and
-<CODE>FILE</CODE> pointers for the output and input of the terminal. If
-type is NULL then the environment variable <CODE>$TERM</CODE> is used.
-<CODE>endwin()</CODE> should called once at wrapup time for each terminal
-opened using this function.
-<DT> <CODE>set_term(new)</CODE>
-<DD> This function is used to switch to a different terminal previously
-opened by <CODE>newterm()</CODE>. The screen reference for the new terminal
-is passed as the parameter. The previous terminal is returned by the
-function. All other calls affect only the current terminal.
-<DT> <CODE>delscreen(sp)</CODE>
-<DD> The inverse of <CODE>newterm()</CODE>; deallocates the data structures
-associated with a given <CODE>SCREEN</CODE> reference.
-</DL>
-
-<H3><A NAME="flush">Causing Output to the Terminal</A></H3>
-
-<DL>
-<DT> <CODE>refresh()</CODE> and <CODE>wrefresh(win)</CODE>
-<DD> These functions must be called to actually get any output on
-the terminal, as other routines merely manipulate data
-structures. <CODE>wrefresh()</CODE> copies the named window to the physical
-terminal screen, taking into account what is already
-there in order to do optimizations. <CODE>refresh()</CODE> does a
-refresh of <CODE>stdscr</CODE>. Unless <CODE>leaveok()</CODE> has been
-enabled, the physical cursor of the terminal is left at the
-location of the window's cursor.
-<DT> <CODE>doupdate()</CODE> and <CODE>wnoutrefresh(win)</CODE>
-<DD> These two functions allow multiple updates with more efficiency
-than wrefresh. To use them, it is important to understand how curses
-works. In addition to all the window structures, curses keeps two
-data structures representing the terminal screen: a physical screen,
-describing what is actually on the screen, and a virtual screen,
-describing what the programmer wants to have on the screen. wrefresh
-works by first copying the named window to the virtual screen
-(<CODE>wnoutrefresh()</CODE>), and then calling the routine to update the
-screen (<CODE>doupdate()</CODE>). If the programmer wishes to output
-several windows at once, a series of calls to <CODE>wrefresh</CODE> will result
-in alternating calls to <CODE>wnoutrefresh()</CODE> and <CODE>doupdate()</CODE>,
-causing several bursts of output to the screen. By calling
-<CODE>wnoutrefresh()</CODE> for each window, it is then possible to call
-<CODE>doupdate()</CODE> once, resulting in only one burst of output, with
-fewer total characters transmitted (this also avoids a visually annoying
-flicker at each update).
-</DL>
-
-<H3><A NAME="lowlevel">Low-Level Capability Access</A></H3>
-
-<DL>
-<DT> <CODE>setupterm(term, filenum, errret)</CODE>
-<DD> This routine is called to initialize a terminal's description, without setting
-up the curses screen structures or changing the tty-driver mode bits.
-<CODE>term</CODE> is the character string representing the name of the terminal
-being used. <CODE>filenum</CODE> is the UNIX file descriptor of the terminal to
-be used for output. <CODE>errret</CODE> is a pointer to an integer, in which a
-success or failure indication is returned. The values returned can be 1 (all
-is well), 0 (no such terminal), or -1 (some problem locating the terminfo
-database). <P>
-
-The value of <CODE>term</CODE> can be given as NULL, which will cause the value of
-<CODE>TERM</CODE> in the environment to be used. The <CODE>errret</CODE> pointer can
-also be given as NULL, meaning no error code is wanted. If <CODE>errret</CODE> is
-defaulted, and something goes wrong, <CODE>setupterm()</CODE> will print an
-appropriate error message and exit, rather than returning. Thus, a simple
-program can call setupterm(0, 1, 0) and not worry about initialization
-errors. <P>
-
-After the call to <CODE>setupterm()</CODE>, the global variable <CODE>cur_term</CODE> is
-set to point to the current structure of terminal capabilities. By calling
-<CODE>setupterm()</CODE> for each terminal, and saving and restoring
-<CODE>cur_term</CODE>, it is possible for a program to use two or more terminals at
-once. <CODE>Setupterm()</CODE> also stores the names section of the terminal
-description in the global character array <CODE>ttytype[]</CODE>. Subsequent calls
-to <CODE>setupterm()</CODE> will overwrite this array, so you'll have to save it
-yourself if need be.
-</DL>
-
-<H3><A NAME="debugging">Debugging</A></H3>
-
-<!-- The 'note' tag is not portable enough -->
-<blockquote>
-<strong>NOTE:</strong> These functions are not part of the standard curses API!
-</blockquote>
-
-<DL>
-<DT> <CODE>trace()</CODE>
-<DD>
-This function can be used to explicitly set a trace level. If the
-trace level is nonzero, execution of your program will generate a file
-called `trace' in the current working directory containing a report on
-the library's actions. Higher trace levels enable more detailed (and
-verbose) reporting -- see comments attached to <CODE>TRACE_</CODE> defines
-in the <CODE>curses.h</CODE> file for details. (It is also possible to set
-a trace level by assigning a trace level value to the environment variable
-<CODE>NCURSES_TRACE</CODE>).
-<DT> <CODE>_tracef()</CODE>
-<DD>
-This function can be used to output your own debugging information. It is only
-available only if you link with -lncurses_g. It can be used the same way as
-<CODE>printf()</CODE>, only it outputs a newline after the end of arguments.
-The output goes to a file called <CODE>trace</CODE> in the current directory.
-</DL>
-
-Trace logs can be difficult to interpret due to the sheer volume of
-data dumped in them. There is a script called <STRONG>tracemunch</STRONG>
-included with the <CODE>ncurses</CODE> distribution that can alleviate
-this problem somewhat; it compacts long sequences of similar operations into
-more succinct single-line pseudo-operations. These pseudo-ops can be
-distinguished by the fact that they are named in capital letters.
-
-<H2><A NAME="hints">Hints, Tips, and Tricks</A></H2>
-
-The <CODE>ncurses</CODE> manual pages are a complete reference for this library.
-In the remainder of this document, we discuss various useful methods that
-may not be obvious from the manual page descriptions.
-
-<H3><A NAME="caution">Some Notes of Caution</A></H3>
-
-If you find yourself thinking you need to use <CODE>noraw()</CODE> or
-<CODE>nocbreak()</CODE>, think again and move carefully. It's probably
-better design to use <CODE>getstr()</CODE> or one of its relatives to
-simulate cooked mode. The <CODE>noraw()</CODE> and <CODE>nocbreak()</CODE>
-functions try to restore cooked mode, but they may end up clobbering
-some control bits set before you started your application. Also, they
-have always been poorly documented, and are likely to hurt your
-application's usability with other curses libraries. <P>
-
-Bear in mind that <CODE>refresh()</CODE> is a synonym for <CODE>wrefresh(stdscr)</CODE>.
-Don't try to mix use of <CODE>stdscr</CODE> with use of windows declared
-by <CODE>newwin()</CODE>; a <CODE>refresh()</CODE> call will blow them off the
-screen. The right way to handle this is to use <CODE>subwin()</CODE>, or
-not touch <CODE>stdscr</CODE> at all and tile your screen with declared
-windows which you then <CODE>wnoutrefresh()</CODE> somewhere in your program
-event loop, with a single <CODE>doupdate()</CODE> call to trigger actual
-repainting. <P>
-
-You are much less likely to run into problems if you design your screen
-layouts to use tiled rather than overlapping windows. Historically,
-curses support for overlapping windows has been weak, fragile, and poorly
-documented. The <CODE>ncurses</CODE> library is not yet an exception to this
-rule. <P>
-
-There is a panels library included in the <CODE>ncurses</CODE>
-distribution that does a pretty good job of strengthening the
-overlapping-windows facilities. <P>
-
-Try to avoid using the global variables LINES and COLS. Use
-<CODE>getmaxyx()</CODE> on the <CODE>stdscr</CODE> 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.
-
-<H3><A NAME="leaving">Temporarily Leaving NCURSES Mode</A></H3>
-
-Sometimes you will want to write a program that spends most of its time in
-screen mode, but occasionally returns to ordinary `cooked' mode. A common
-reason for this is to support shell-out. This behavior is simple to arrange
-in <CODE>ncurses</CODE>. <P>
-
-To leave <CODE>ncurses</CODE> mode, call <CODE>endwin()</CODE> as you would if you
-were intending to terminate the program. This will take the screen back to
-cooked mode; you can do your shell-out. When you want to return to
-<CODE>ncurses</CODE> mode, simply call <CODE>refresh()</CODE> or <CODE>doupdate()</CODE>.
-This will repaint the screen. <P>
-
-There is a boolean function, <CODE>isendwin()</CODE>, which code can use to
-test whether <CODE>ncurses</CODE> screen mode is active. It returns <CODE>TRUE</CODE>
-in the interval between an <CODE>endwin()</CODE> call and the following
-<CODE>refresh()</CODE>, <CODE>FALSE</CODE> otherwise. <P>
-
-Here is some sample code for shellout:
-
-<PRE>
- addstr("Shelling out...");
- def_prog_mode(); /* save current tty modes */
- endwin(); /* restore original tty modes */
- system("sh"); /* run shell */
- addstr("returned.\n"); /* prepare return message */
- refresh(); /* restore save modes, repaint screen */
-</PRE>
-
-<H3><A NAME="xterm">Using NCURSES under XTERM</A></H3>
-
-A resize operation in X sends <CODE>SIGWINCH</CODE> to the application running
-under xterm.
-
-The easiest way to handle <CODE>SIGWINCH</CODE>
-is to do an <CODE>endwin</CODE>,
-followed by an <CODE>refresh</CODE> and a screen repaint you code
-yourself.
-The <CODE>refresh</CODE> will pick up the new screen size from the
-xterm's environment. <P>
-
-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.
-<CODE>Ncurses</CODE> provides an extension which works better, the
-<CODE>resizeterm</CODE> function. That function ensures that all windows
-are limited to the new screen dimensions, and pads <CODE>stdscr</CODE>
-with blanks if the screen is larger. <P>
-
-The <CODE>ncurses</CODE> library provides a SIGWINCH signal handler,
-which pushes a <CODE>KEY_RESIZE</CODE> via the wgetch() calls.
-When <CODE>ncurses</CODE> returns that code,
-it calls <code>resizeterm</CODE>
-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
-<CODE>KEY_RESIZE</CODE> yourself.
-
-<H3><A NAME="screens">Handling Multiple Terminal Screens</A></H3>
-
-The <CODE>initscr()</CODE> function actually calls a function named
-<CODE>newterm()</CODE> to do most of its work. If you are writing a program that
-opens multiple terminals, use <CODE>newterm()</CODE> directly. <P>
-
-For each call, you will have to specify a terminal type and a pair of file
-pointers; each call will return a screen reference, and <CODE>stdscr</CODE> will be
-set to the last one allocated. You will switch between screens with the
-<CODE>set_term</CODE> call. Note that you will also have to call
-<CODE>def_shell_mode</CODE> and <CODE>def_prog_mode</CODE> on each tty yourself.
-
-<H3><A NAME="testing">Testing for Terminal Capabilities</A></H3>
-
-Sometimes you may want to write programs that test for the presence of various
-capabilities before deciding whether to go into <CODE>ncurses</CODE> mode. An easy
-way to do this is to call <CODE>setupterm()</CODE>, then use the functions
-<CODE>tigetflag()</CODE>, <CODE>tigetnum()</CODE>, and <CODE>tigetstr()</CODE> to do your
-testing. <P>
-
-A particularly useful case of this often comes up when you want to
-test whether a given terminal type should be treated as `smart'
-(cursor-addressable) or `stupid'. The right way to test this is to see
-if the return value of <CODE>tigetstr("cup")</CODE> is non-NULL. Alternatively,
-you can include the <CODE>term.h</CODE> file and test the value of the
-macro <CODE>cursor_address</CODE>.
-
-<H3><A NAME="tuning">Tuning for Speed</A></H3>
-
-Use the <CODE>addchstr()</CODE> family of functions for fast
-screen-painting of text when you know the text doesn't contain any
-control characters. Try to make attribute changes infrequent on your
-screens. Don't use the <CODE>immedok()</CODE> option!
-
-<H3><A NAME="special">Special Features of NCURSES</A></H3>
-
-The <CODE>wresize()</CODE> function allows you to resize a window in place.
-The associated <CODE>resizeterm()</CODE> function simplifies the construction
-of <a HREF="#xterm">SIGWINCH</a> handlers, for resizing all windows. <P>
-
-The <CODE>define_key()</CODE> function allows you
-to define at runtime function-key control sequences which are not in the
-terminal description.
-The <CODE>keyok()</CODE> function allows you to temporarily
-enable or disable interpretation of any function-key control sequence. <P>
-
-The <CODE>use_default_colors()</CODE> 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. <P>
-
-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.
-
-<H2><A NAME="compat">Compatibility with Older Versions</A></H2>
-
-Despite our best efforts, there are some differences between <CODE>ncurses</CODE>
-and the (undocumented!) behavior of older curses implementations. These arise
-from ambiguities or omissions in the documentation of the API.
-
-<H3><A NAME="refbug">Refresh of Overlapping Windows</A></H3>
-
-If you define two windows A and B that overlap, and then alternately scribble
-on and refresh them, the changes made to the overlapping region under historic
-<CODE>curses</CODE> versions were often not documented precisely. <P>
-
-To understand why this is a problem, remember that screen updates are
-calculated between two representations of the <EM>entire</EM> display. The
-documentation says that when you refresh a window, it is first copied 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. <P>
-
-What happens to the overlapping region depends on what <CODE>wnoutrefresh()</CODE>
-does with its argument -- what portions of the argument window it copies to the
-virtual screen. Some implementations do "change copy", copying down only
-locations in the window that have changed (or been marked changed with
-<CODE>wtouchln()</CODE> and friends). Some implementations do "entire copy",
-copying <EM>all</EM> window locations to the virtual screen whether or not
-they have changed. <P>
-
-The <CODE>ncurses</CODE> library itself has not always been consistent on this
-score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. Versions
-1.8.6 and older, and versions 1.9.9 and newer, do change copy. <P>
-
-For most commercial curses implementations, it is not documented and not known
-for sure (at least not to the <CODE>ncurses</CODE> maintainers) whether they do
-change copy or entire copy. We know that System V release 3 curses has logic
-in it that looks like an attempt to do change copy, but the surrounding logic
-and data representations are sufficiently complex, and our knowledge
-sufficiently indirect, that it's hard to know whether this is reliable.
-
-It is not clear what the SVr4 documentation and XSI standard intend. The XSI
-Curses standard barely mentions wnoutrefresh(); the SVr4 documents seem to be
-describing entire-copy, but it is possible with some effort and straining to
-read them the other way. <P>
-
-It might therefore be unwise to rely on either behavior in programs that might
-have to be linked with other curses implementations. Instead, you can do an
-explicit <CODE>touchwin()</CODE> before the <CODE>wnoutrefresh()</CODE> call to
-guarantee an entire-contents copy anywhere. <P>
-
-The really clean way to handle this is to use the panels library. If,
-when you want a screen update, you do <CODE>update_panels()</CODE>, it will
-do all the necessary <CODE>wnoutrefresh()</CODE> calls for whatever panel
-stacking order you have defined. Then you can do one <CODE>doupdate()</CODE>
-and there will be a <EM>single</EM> burst of physical I/O that will do
-all your updates.
-
-<H3><A NAME="backbug">Background Erase</A></H3>
-
-If you have been using a very old versions of <CODE>ncurses</CODE> (1.8.7 or
-older) you may be surprised by the behavior of the erase functions. In older
-versions, erased areas of a window were filled with a blank modified by the
-window's current attribute (as set by <STRONG>wattrset()</STRONG>, <STRONG>wattron()</STRONG>,
-<STRONG>wattroff()</STRONG> and friends). <P>
-
-In newer versions, this is not so. Instead, the attribute of erased blanks
-is normal unless and until it is modified by the functions <CODE>bkgdset()</CODE>
-or <CODE>wbkgdset()</CODE>. <P>
-
-This change in behavior conforms <CODE>ncurses</CODE> to System V Release 4 and
-the XSI Curses standard.
-
-<H2><A NAME="xsifuncs">XSI Curses Conformance</A></H2>
-
-The <CODE>ncurses</CODE> library is intended to be base-level conformant with the
-XSI Curses standard from X/Open. Many extended-level features (in fact, almost
-all features not directly concerned with wide characters and
-internationalization) are also supported. <P>
-
-One effect of XSI conformance is the change in behavior described under
-<A HREF="#backbug">"Background Erase -- Compatibility with Old Versions"</A>. <P>
-
-Also, <CODE>ncurses</CODE> meets the XSI requirement that every macro
-entry point have a corresponding function which may be linked (and
-will be prototype-checked) if the macro definition is disabled with
-<CODE>#undef</CODE>.
-
-<H1><A NAME="panels">The Panels Library</A></H1>
-
-The <CODE>ncurses</CODE> library by itself provides good support for screen
-displays in which the windows are tiled (non-overlapping). In the more
-general case that windows may overlap, you have to use a series of
-<CODE>wnoutrefresh()</CODE> calls followed by a <CODE>doupdate()</CODE>, and be
-careful about the order you do the window refreshes in. It has to be
-bottom-upwards, otherwise parts of windows that should be obscured will
-show through. <P>
-
-When your interface design is such that windows may dive deeper into the
-visibility stack or pop to the top at runtime, the resulting book-keeping
-can be tedious and difficult to get right. Hence the panels library. <P>
-
-The <CODE>panel</CODE> library first appeared in AT&amp;T System V. The
-version documented here is the <CODE>panel</CODE> code distributed
-with <CODE>ncurses</CODE>.
-
-<H2><A NAME="pcompile">Compiling With the Panels Library</A></H2>
-
-Your panels-using modules must import the panels library declarations with
-
-<PRE>
- #include &lt;panel.h&gt;
-</PRE>
-
-and must be linked explicitly with the panels library using an
-<CODE>-lpanel</CODE> argument. Note that they must also link the
-<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>. Many linkers
-are two-pass and will accept either order, but it is still good practice
-to put <CODE>-lpanel</CODE> first and <CODE>-lncurses</CODE> second.
-
-<H2><A NAME="poverview">Overview of Panels</A></H2>
-
-A panel object is a window that is implicitly treated as part of a
-<DFN>deck</DFN> including all other panel objects. The deck has an implicit
-bottom-to-top visibility order. The panels library includes an update
-function (analogous to <CODE>refresh()</CODE>) that displays all panels in the
-deck in the proper order to resolve overlaps. The standard window,
-<CODE>stdscr</CODE>, is considered below all panels. <P>
-
-Details on the panels functions are available in the man pages. We'll just
-hit the highlights here. <P>
-
-You create a panel from a window by calling <CODE>new_panel()</CODE> on a
-window pointer. It then becomes the top of the deck. The panel's window
-is available as the value of <CODE>panel_window()</CODE> called with the
-panel pointer as argument.<P>
-
-You can delete a panel (removing it from the deck) with <CODE>del_panel</CODE>.
-This will not deallocate the associated window; you have to do that yourself.
-
-You can replace a panel's window with a different window by calling
-<CODE>replace_window</CODE>. The new window may be of different size;
-the panel code will re-compute all overlaps. This operation doesn't
-change the panel's position in the deck. <P>
-
-To move a panel's window, use <CODE>move_panel()</CODE>. The
-<CODE>mvwin()</CODE> function on the panel's window isn't sufficient because it
-doesn't update the panels library's representation of where the windows are.
-This operation leaves the panel's depth, contents, and size unchanged. <P>
-
-Two functions (<CODE>top_panel()</CODE>, <CODE>bottom_panel()</CODE>) are
-provided for rearranging the deck. The first pops its argument window to the
-top of the deck; the second sends it to the bottom. Either operation leaves
-the panel's screen location, contents, and size unchanged. <P>
-
-The function <CODE>update_panels()</CODE> does all the
-<CODE>wnoutrefresh()</CODE> calls needed to prepare for
-<CODE>doupdate()</CODE> (which you must call yourself, afterwards). <P>
-
-Typically, you will want to call <CODE>update_panels()</CODE> and
-<CODE>doupdate()</CODE> just before accepting command input, once in each cycle
-of interaction with the user. If you call <CODE>update_panels()</CODE> after
-each and every panel write, you'll generate a lot of unnecessary refresh
-activity and screen flicker.
-
-<H2><A NAME="pstdscr">Panels, Input, and the Standard Screen</A></H2>
-
-You shouldn't mix <CODE>wnoutrefresh()</CODE> or <CODE>wrefresh()</CODE>
-operations with panels code; this will work only if the argument window
-is either in the top panel or unobscured by any other panels. <P>
-
-The <CODE>stsdcr</CODE> window is a special case. It is considered below all
-panels. Because changes to panels may obscure parts of <CODE>stdscr</CODE>,
-though, you should call <CODE>update_panels()</CODE> before
-<CODE>doupdate()</CODE> even when you only change <CODE>stdscr</CODE>. <P>
-
-Note that <CODE>wgetch</CODE> automatically calls <CODE>wrefresh</CODE>.
-Therefore, before requesting input from a panel window, you need to be sure
-that the panel is totally unobscured. <P>
-
-There is presently no way to display changes to one obscured panel without
-repainting all panels.
-
-<H2><A NAME="hiding">Hiding Panels</A></H2>
-
-It's possible to remove a panel from the deck temporarily; use
-<CODE>hide_panel</CODE> for this. Use <CODE>show_panel()</CODE> to render it
-visible again. The predicate function <CODE>panel_hidden</CODE>
-tests whether or not a panel is hidden. <P>
-
-The <CODE>panel_update</CODE> code ignores hidden panels. You cannot do
-<CODE>top_panel()</CODE> or <CODE>bottom_panel</CODE> on a hidden panel().
-Other panels operations are applicable.
-
-<H2><A NAME="pmisc">Miscellaneous Other Facilities</A></H2>
-
-It's possible to navigate the deck using the functions
-<CODE>panel_above()</CODE> and <CODE>panel_below</CODE>. Handed a panel
-pointer, they return the panel above or below that panel. Handed
-<CODE>NULL</CODE>, they return the bottom-most or top-most panel. <P>
-
-Every panel has an associated user pointer, not used by the panel code, to
-which you can attach application data. See the man page documentation
-of <CODE>set_panel_userptr()</CODE> and <CODE>panel_userptr</CODE> for
-details.
-
-<H1><A NAME="menu">The Menu Library</A></H1>
-
-A menu is a screen display that assists the user to choose some subset
-of a given set of items. The <CODE>menu</CODE> library is a curses
-extension that supports easy programming of menu hierarchies with a
-uniform but flexible interface. <P>
-
-The <CODE>menu</CODE> library first appeared in AT&amp;T System V. The
-version documented here is the <CODE>menu</CODE> code distributed
-with <CODE>ncurses</CODE>.
-
-<H2><A NAME="mcompile">Compiling With the menu Library</A></H2>
-
-Your menu-using modules must import the menu library declarations with
-
-<PRE>
- #include &lt;menu.h&gt;
-</PRE>
-
-and must be linked explicitly with the menus library using an
-<CODE>-lmenu</CODE> argument. Note that they must also link the
-<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>. Many linkers
-are two-pass and will accept either order, but it is still good practice
-to put <CODE>-lmenu</CODE> first and <CODE>-lncurses</CODE> second.
-
-<H2><A NAME="moverview">Overview of Menus</A></H2>
-
-The menus created by this library consist of collections of
-<DFN>items</DFN> including a name string part and a description string
-part. To make menus, you create groups of these items and connect
-them with menu frame objects. <P>
-
-The menu can then by <DFN>posted</DFN>, that is written to an
-associated window. Actually, each menu has two associated windows; a
-containing window in which the programmer can scribble titles or
-borders, and a subwindow in which the menu items proper are displayed.
-If this subwindow is too small to display all the items, it will be a
-scrollable viewport on the collection of items. <P>
-
-A menu may also be <DFN>unposted</DFN> (that is, undisplayed), and finally
-freed to make the storage associated with it and its items available for
-re-use. <P>
-
-The general flow of control of a menu program looks like this:
-
-<OL>
-<LI>Initialize <CODE>curses</CODE>.
-<LI>Create the menu items, using <CODE>new_item()</CODE>.
-<LI>Create the menu using <CODE>new_menu()</CODE>.
-<LI>Post the menu using <CODE>post_menu()</CODE>.
-<LI>Refresh the screen.
-<LI>Process user requests via an input loop.
-<LI>Unpost the menu using <CODE>unpost_menu()</CODE>.
-<LI>Free the menu, using <CODE>free_menu()</CODE>.
-<LI>Free the items using <CODE>free_item()</CODE>.
-<LI>Terminate <CODE>curses</CODE>.
-</OL>
-
-<H2><A NAME="mselect">Selecting items</A></H2>
-
-Menus may be multi-valued or (the default) single-valued (see the manual
-page <CODE>menu_opts(3x)</CODE> to see how to change the default).
-Both types always have a <DFN>current item</DFN>. <P>
-
-From a single-valued menu you can read the selected value simply by looking
-at the current item. From a multi-valued menu, you get the selected set
-by looping through the items applying the <CODE>item_value()</CODE>
-predicate function. Your menu-processing code can use the function
-<CODE>set_item_value()</CODE> to flag the items in the select set. <P>
-
-Menu items can be made unselectable using <CODE>set_item_opts()</CODE>
-or <CODE>item_opts_off()</CODE> with the <CODE>O_SELECTABLE</CODE>
-argument. This is the only option so far defined for menus, but it
-is good practice to code as though other option bits might be on.
-
-<H2><A NAME="mdisplay">Menu Display</A></H2>
-
-The menu library calculates a minimum display size for your window, based
-on the following variables:
-
-<UL>
-<LI>The number and maximum length of the menu items
-<LI>Whether the O_ROWMAJOR option is enabled
-<LI>Whether display of descriptions is enabled
-<LI>Whatever menu format may have been set by the programmer
-<LI>The length of the menu mark string used for highlighting selected items
-</UL>
-
-The function <CODE>set_menu_format()</CODE> allows you to set the
-maximum size of the viewport or <DFN>menu page</DFN> that will be used
-to display menu items. You can retrieve any format associated with a
-menu with <CODE>menu_format()</CODE>. The default format is rows=16,
-columns=1. <P>
-
-The actual menu page may be smaller than the format size. This depends
-on the item number and size and whether O_ROWMAJOR is on. This option
-(on by default) causes menu items to be displayed in a `raster-scan'
-pattern, so that if more than one item will fit horizontally the first
-couple of items are side-by-side in the top row. The alternative is
-column-major display, which tries to put the first several items in
-the first column. <P>
-
-As mentioned above, a menu format not large enough to allow all items to fit
-on-screen will result in a menu display that is vertically scrollable. <P>
-You can scroll it with requests to the menu driver, which will be described
-in the section on <A HREF="#minput">menu input handling</A>. <P>
-
-Each menu has a <DFN>mark string</DFN> used to visually tag selected items;
-see the <CODE>menu_mark(3x)</CODE> manual page for details. The mark
-string length also influences the menu page size. <P>
-
-The function <CODE>scale_menu()</CODE> returns the minimum display size
-that the menu code computes from all these factors.
-
-There are other menu display attributes including a select attribute,
-an attribute for selectable items, an attribute for unselectable items,
-and a pad character used to separate item name text from description
-text. These have reasonable defaults which the library allows you to
-change (see the <CODE>menu_attribs(3x)</CODE> manual page.
-
-<H2><A NAME="mwindows">Menu Windows</A></H2>
-
-Each menu has, as mentioned previously, a pair of associated windows.
-Both these windows are painted when the menu is posted and erased when
-the menu is unposted. <P>
-
-The outer or frame window is not otherwise touched by the menu
-routines. It exists so the programmer can associate a title, a
-border, or perhaps help text with the menu and have it properly
-refreshed or erased at post/unpost time. The inner window or
-<DFN>subwindow</DFN> is where the current menu page is displayed. <P>
-
-By default, both windows are <CODE>stdscr</CODE>. You can set them with the
-functions in <CODE>menu_win(3x)</CODE>. <P>
-
-When you call <CODE>post_menu()</CODE>, you write the menu to its
-subwindow. When you call <CODE>unpost_menu()</CODE>, you erase the
-subwindow, However, neither of these actually modifies the screen. To
-do that, call <CODE>wrefresh()</CODE> or some equivalent.
-
-<H2><A NAME="minput">Processing Menu Input</A></H2>
-
-The main loop of your menu-processing code should call
-<CODE>menu_driver()</CODE> repeatedly. The first argument of this routine
-is a menu pointer; the second is a menu command code. You should write an
-input-fetching routine that maps input characters to menu command codes, and
-pass its output to <CODE>menu_driver()</CODE>. The menu command codes are
-fully documented in <CODE>menu_driver(3x)</CODE>. <P>
-
-The simplest group of command codes is <CODE>REQ_NEXT_ITEM</CODE>,
-<CODE>REQ_PREV_ITEM</CODE>, <CODE>REQ_FIRST_ITEM</CODE>,
-<CODE>REQ_LAST_ITEM</CODE>, <CODE>REQ_UP_ITEM</CODE>,
-<CODE>REQ_DOWN_ITEM</CODE>, <CODE>REQ_LEFT_ITEM</CODE>,
-<CODE>REQ_RIGHT_ITEM</CODE>. These change the currently selected
-item. These requests may cause scrolling of the menu page if it only
-partially displayed. <P>
-
-There are explicit requests for scrolling which also change the
-current item (because the select location does not change, but the
-item there does). These are <CODE>REQ_SCR_DLINE</CODE>,
-<CODE>REQ_SCR_ULINE</CODE>, <CODE>REQ_SCR_DPAGE</CODE>, and
-<CODE>REQ_SCR_UPAGE</CODE>. <P>
-
-The <CODE>REQ_TOGGLE_ITEM</CODE> selects or deselects the current item.
-It is for use in multi-valued menus; if you use it with <CODE>O_ONEVALUE</CODE>
-on, you'll get an error return (<CODE>E_REQUEST_DENIED</CODE>). <P>
-
-Each menu has an associated pattern buffer. The
-<CODE>menu_driver()</CODE> logic tries to accumulate printable ASCII
-characters passed in in that buffer; when it matches a prefix of an
-item name, that item (or the next matching item) is selected. If
-appending a character yields no new match, that character is deleted
-from the pattern buffer, and <CODE>menu_driver()</CODE> returns
-<CODE>E_NO_MATCH</CODE>. <P>
-
-Some requests change the pattern buffer directly:
-<CODE>REQ_CLEAR_PATTERN</CODE>, <CODE>REQ_BACK_PATTERN</CODE>,
-<CODE>REQ_NEXT_MATCH</CODE>, <CODE>REQ_PREV_MATCH</CODE>. The latter
-two are useful when pattern buffer input matches more than one item
-in a multi-valued menu. <P>
-
-Each successful scroll or item navigation request clears the pattern
-buffer. It is also possible to set the pattern buffer explicitly
-with <CODE>set_menu_pattern()</CODE>. <P>
-
-Finally, menu driver requests above the constant <CODE>MAX_COMMAND</CODE>
-are considered application-specific commands. The <CODE>menu_driver()</CODE>
-code ignores them and returns <CODE>E_UNKNOWN_COMMAND</CODE>.
-
-<H2><A NAME="mmisc">Miscellaneous Other Features</A></H2>
-
-Various menu options can affect the processing and visual appearance
-and input processing of menus. See <CODE>menu_opts(3x) for
-details.</CODE> <P>
-
-It is possible to change the current item from application code; this
-is useful if you want to write your own navigation requests. It is
-also possible to explicitly set the top row of the menu display. See
-<CODE>mitem_current(3x)</CODE>.
-
-If your application needs to change the menu subwindow cursor for
-any reason, <CODE>pos_menu_cursor()</CODE> will restore it to the
-correct location for continuing menu driver processing. <P>
-
-It is possible to set hooks to be called at menu initialization and
-wrapup time, and whenever the selected item changes. See
-<CODE>menu_hook(3x)</CODE>. <P>
-
-Each item, and each menu, has an associated user pointer on which you
-can hang application data. See <CODE>mitem_userptr(3x)</CODE> and
-<CODE>menu_userptr(3x)</CODE>.
-
-<H1><A NAME="form">The Forms Library</A></H1>
-
-The <CODE>form</CODE> library is a curses extension that supports easy
-programming of on-screen forms for data entry and program control. <P>
-
-The <CODE>form</CODE> library first appeared in AT&amp;T System V. The
-version documented here is the <CODE>form</CODE> code distributed
-with <CODE>ncurses</CODE>.
-
-<H2><A NAME="fcompile">Compiling With the form Library</A></H2>
-
-Your form-using modules must import the form library declarations with
-
-<PRE>
- #include &lt;form.h&gt;
-</PRE>
-
-and must be linked explicitly with the forms library using an
-<CODE>-lform</CODE> argument. Note that they must also link the
-<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>. Many linkers
-are two-pass and will accept either order, but it is still good practice
-to put <CODE>-lform</CODE> first and <CODE>-lncurses</CODE> second.
-
-<H2><A NAME="foverview">Overview of Forms</A></H2>
-
-A form is a collection of fields; each field may be either a label
-(explanatory text) or a data-entry location. Long forms may be
-segmented into pages; each entry to a new page clears the screen. <P>
-To make forms, you create groups of fields and connect them with form
-frame objects; the form library makes this relatively simple. <P>
-
-Once defined, a form can be <DFN>posted</DFN>, that is written to an
-associated window. Actually, each form has two associated windows; a
-containing window in which the programmer can scribble titles or
-borders, and a subwindow in which the form fields proper are displayed. <P>
-
-As the form user fills out the posted form, navigation and editing
-keys support movement between fields, editing keys support modifying
-field, and plain text adds to or changes data in a current field. The
-form library allows you (the forms designer) to bind each navigation
-and editing key to any keystroke accepted by <CODE>curses</CODE>
-
-Fields may have validation conditions on them, so that they check input
-data for type and value. The form library supplies a rich set of
-pre-defined field types, and makes it relatively easy to define new ones. <P>
-
-Once its transaction is completed (or aborted), a form may be
-<DFN>unposted</DFN> (that is, undisplayed), and finally freed to make
-the storage associated with it and its items available for re-use. <P>
-
-The general flow of control of a form program looks like this:
-
-<OL>
-<LI>Initialize <CODE>curses</CODE>.
-<LI>Create the form fields, using <CODE>new_field()</CODE>.
-<LI>Create the form using <CODE>new_form()</CODE>.
-<LI>Post the form using <CODE>post_form()</CODE>.
-<LI>Refresh the screen.
-<LI>Process user requests via an input loop.
-<LI>Unpost the form using <CODE>unpost_form()</CODE>.
-<LI>Free the form, using <CODE>free_form()</CODE>.
-<LI>Free the fields using <CODE>free_field()</CODE>.
-<LI>Terminate <CODE>curses</CODE>.
-</OL>
-
-Note that this looks much like a menu program; the form library handles
-tasks which are in many ways similar, and its interface was obviously
-designed to resemble that of the <A HREF="#menu">menu library</A>
-wherever possible. <P>
-
-In forms programs, however, the `process user requests' is somewhat more
-complicated than for menus. Besides menu-like navigation operations,
-the menu driver loop has to support field editing and data validation.
-
-<H2><A NAME="fcreate">Creating and Freeing Fields and Forms</A></H2>
-
-The basic function for creating fields is <CODE>new_field()</CODE>:
-
-<PRE>
-FIELD *new_field(int height, int width, /* new field size */
- int top, int left, /* upper left corner */
- int offscreen, /* number of offscreen rows */
- int nbuf); /* number of working buffers */
-</PRE>
-
-Menu items always occupy a single row, but forms fields may have
-multiple rows. So <CODE>new_field()</CODE> requires you to specify a
-width and height (the first two arguments, which mist both be greater
-than zero). <P>
-
-You must also specify the location of the field's upper left corner on
-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 <CODE>stdscr</CODE> by default but
-need not be <CODE>stdscr</CODE> if you've done an explicit
-<CODE>set_form_win()</CODE> call. <P>
-
-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
-nonzero, the form will be scrollable, with only one screen-full (initially
-the top part) displayed at any given time. If you make a field dynamic
-and grow it so it will no longer fit on the screen, the form will become
-scrollable even if the <CODE>offscreen</CODE> argument was initially zero. <P>
-
-The forms library allocates one working buffer per field; the size of
-each buffer is <CODE>((height + offscreen)*width + 1</CODE>, one character
-for each position in the field plus a NUL terminator. The sixth
-argument is the number of additional data buffers to allocate for the
-field; your application can use them for its own purposes.
-
-<PRE>
-FIELD *dup_field(FIELD *field, /* field to copy */
- int top, int left); /* location of new copy */
-</PRE>
-
-The function <CODE>dup_field()</CODE> duplicates an existing field at a
-new location. Size and buffering information are copied; some
-attribute flags and status bits are not (see the
-<CODE>form_field_new(3X)</CODE> for details).
-
-<PRE>
-FIELD *link_field(FIELD *field, /* field to copy */
- int top, int left); /* location of new copy */
-</PRE>
-
-The function <CODE>link_field()</CODE> also duplicates an existing field
-at a new location. The difference from <CODE>dup_field()</CODE> is that
-it arranges for the new field's buffer to be shared with the old one. <P>
-
-Besides the obvious use in making a field editable from two different
-form pages, linked fields give you a way to hack in dynamic labels. If
-you declare several fields linked to an original, and then make them
-inactive, changes from the original will still be propagated to the
-linked fields. <P>
-
-As with duplicated fields, linked fields have attribute bits separate
-from the original. <P>
-
-As you might guess, all these field-allocations return <CODE>NULL</CODE> if
-the field allocation is not possible due to an out-of-memory error or
-out-of-bounds arguments. <P>
-
-To connect fields to a form, use
-
-<PRE>
-FORM *new_form(FIELD **fields);
-</PRE>
-
-This function expects to see a NULL-terminated array of field pointers.
-Said fields are connected to a newly-allocated form object; its address
-is returned (or else NULL if the allocation fails). <P>
-
-Note that <CODE>new_field()</CODE> does <EM>not</EM> copy the pointer array
-into private storage; if you modify the contents of the pointer array
-during forms processing, all manner of bizarre things might happen. Also
-note that any given field may only be connected to one form. <P>
-
-The functions <CODE>free_field()</CODE> and <CODE>free_form</CODE> are available
-to free field and form objects. It is an error to attempt to free a field
-connected to a form, but not vice-versa; thus, you will generally free
-your form objects first.
-
-<H2><A NAME="fattributes">Fetching and Changing Field Attributes</A></H2>
-
-Each form field has a number of location and size attributes
-associated with it. There are other field attributes used to control
-display and editing of the field. Some (for example, the <CODE>O_STATIC</CODE> bit)
-involve sufficient complications to be covered in sections of their own
-later on. We cover the functions used to get and set several basic
-attributes here. <P>
-
-When a field is created, the attributes not specified by the
-<CODE>new_field</CODE> function are copied from an invisible system
-default field. In attribute-setting and -fetching functions, the
-argument NULL is taken to mean this field. Changes to it persist
-as defaults until your forms application terminates.
-
-<H3><A NAME="fsizes">Fetching Size and Location Data</A></H3>
-
-You can retrieve field sizes and locations through:
-
-<PRE>
-int field_info(FIELD *field, /* field from which to fetch */
- int *height, *int width, /* field size */
- int *top, int *left, /* upper left corner */
- int *offscreen, /* number of offscreen rows */
- int *nbuf); /* number of working buffers */
-</PRE>
-
-This function is a sort of inverse of <CODE>new_field()</CODE>; instead of
-setting size and location attributes of a new field, it fetches them
-from an existing one.
-
-<H3><A NAME="flocation">Changing the Field Location</A></H3>
-
-It is possible to move a field's location on the screen:
-
-<PRE>
-int move_field(FIELD *field, /* field to alter */
- int top, int left); /* new upper-left corner */
-</PRE>
-
-You can, of course. query the current location through <CODE>field_info()</CODE>.
-
-<H3><A NAME="fjust">The Justification Attribute</A></H3>
-
-One-line fields may be unjustified, justified right, justified left,
-or centered. Here is how you manipulate this attribute:
-
-<PRE>
-int set_field_just(FIELD *field, /* field to alter */
- int justmode); /* mode to set */
-
-int field_just(FIELD *field); /* fetch mode of field */
-</PRE>
-
-The mode values accepted and returned by this functions are
-preprocessor macros <CODE>NO_JUSTIFICATION</CODE>, <CODE>JUSTIFY_RIGHT</CODE>,
-<CODE>JUSTIFY_LEFT</CODE>, or <CODE>JUSTIFY_CENTER</CODE>.
-
-<H3><A NAME="fdispatts">Field Display Attributes</A></H3>
-
-For each field, you can set a foreground attribute for entered
-characters, a background attribute for the entire field, and a pad
-character for the unfilled portion of the field. You can also
-control pagination of the form. <P>
-
-This group of four field attributes controls the visual appearance
-of the field on the screen, without affecting in any way the data
-in the field buffer.
-
-<PRE>
-int set_field_fore(FIELD *field, /* field to alter */
- chtype attr); /* attribute to set */
-
-chtype field_fore(FIELD *field); /* field to query */
-
-int set_field_back(FIELD *field, /* field to alter */
- chtype attr); /* attribute to set */
-
-chtype field_back(FIELD *field); /* field to query */
-
-int set_field_pad(FIELD *field, /* field to alter */
- int pad); /* pad character to set */
-
-chtype field_pad(FIELD *field);
-
-int set_new_page(FIELD *field, /* field to alter */
- int flag); /* TRUE to force new page */
-
-chtype new_page(FIELD *field); /* field to query */
-</PRE>
-
-The attributes set and returned by the first four functions are normal
-<CODE>curses(3x)</CODE> display attribute values (<CODE>A_STANDOUT</CODE>,
-<CODE>A_BOLD</CODE>, <CODE>A_REVERSE</CODE> etc).
-
-The page bit of a field controls whether it is displayed at the start of
-a new form screen.
-
-<H3><A NAME="foptions">Field Option Bits</A></H3>
-
-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:
-
-<PRE>
-int set_field_opts(FIELD *field, /* field to alter */
- int attr); /* attribute to set */
-
-int field_opts_on(FIELD *field, /* field to alter */
- int attr); /* attributes to turn on */
-
-int field_opts_off(FIELD *field, /* field to alter */
- int attr); /* attributes to turn off */
-
-int field_opts(FIELD *field); /* field to query */
-</PRE>
-
-By default, all options are on. Here are the available option bits:
-<DL>
-<DT> O_VISIBLE
-<DD> Controls whether the field is visible on the screen. Can be used
-during form processing to hide or pop up fields depending on the value
-of parent fields.
-<DT> O_ACTIVE
-<DD> Controls whether the field is active during forms processing (i.e.
-visited by form navigation keys). Can be used to make labels or derived
-fields with buffer values alterable by the forms application, not the user.
-<DT> O_PUBLIC
-<DD> Controls whether data is displayed during field entry. If this option is
-turned off on a field, the library will accept and edit data in that field,
-but it will not be displayed and the visible field cursor will not move.
-You can turn off the O_PUBLIC bit to define password fields.
-<DT> O_EDIT
-<DD> Controls whether the field's data can be modified. When this option is
-off, all editing requests except <CODE>REQ_PREV_CHOICE</CODE> and
-<CODE>REQ_NEXT_CHOICE</CODE> will fail. Such read-only fields may be useful for
-help messages.
-<DT> O_WRAP
-<DD> Controls word-wrapping in multi-line fields. Normally, when any
-character of a (blank-separated) word reaches the end of the current line, the
-entire word is wrapped to the next line (assuming there is one). When this
-option is off, the word will be split across the line break.
-<DT> O_BLANK
-<DD> Controls field blanking. When this option is on, entering a character at
-the first field position erases the entire field (except for the just-entered
-character).
-<DT> O_AUTOSKIP
-<DD> Controls automatic skip to next field when this one fills. Normally,
-when the forms user tries to type more data into a field than will fit,
-the editing location jumps to next field. When this option is off, the
-user's cursor will hang at the end of the field. This option is ignored
-in dynamic fields that have not reached their size limit.
-<DT> O_NULLOK
-<DD> Controls whether <A HREF="#fvalidation">validation</A> is applied to
-blank fields. Normally, it is not; the user can leave a field blank
-without invoking the usual validation check on exit. If this option is
-off on a field, exit from it will invoke a validation check.
-<DT> O_PASSOK
-<DD> Controls whether validation occurs on every exit, or only after
-the field is modified. Normally the latter is true. Setting O_PASSOK
-may be useful if your field's validation function may change during
-forms processing.
-<DT> O_STATIC
-<DD> Controls whether the field is fixed to its initial dimensions. If you
-turn this off, the field becomes <A HREF="#fdynamic">dynamic</A> and will
-stretch to fit entered data.
-</DL>
-
-A field's options cannot be changed while the field is currently selected.
-However, options may be changed on posted fields that are not current. <P>
-
-The option values are bit-masks and can be composed with logical-or in
-the obvious way.
-
-<H2><A NAME="fstatus">Field Status</A></H2>
-
-Every field has a status flag, which is set to FALSE when the field is
-created and TRUE when the value in field buffer 0 changes. This flag can
-be queried and set directly:
-
-<PRE>
-int set_field_status(FIELD *field, /* field to alter */
- int status); /* mode to set */
-
-int field_status(FIELD *field); /* fetch mode of field */
-</PRE>
-
-Setting this flag under program control can be useful if you use the same
-form repeatedly, looking for modified fields each time. <P>
-
-Calling <CODE>field_status()</CODE> on a field not currently selected
-for input will return a correct value. Calling <CODE>field_status()</CODE> on a
-field that is currently selected for input may not necessarily give a
-correct field status value, because entered data isn't necessarily copied to
-buffer zero before the exit validation check.
-
-To guarantee that the returned status value reflects reality, call
-<CODE>field_status()</CODE> either (1) in the field's exit validation check
-routine, (2) from the field's or form's initialization or termination
-hooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been
-processed by the forms driver.
-
-<H2><A NAME="fuser">Field User Pointer</A></H2>
-
-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:
-
-<PRE>
-int set_field_userptr(FIELD *field, /* field to alter */
- char *userptr); /* mode to set */
-
-char *field_userptr(FIELD *field); /* fetch mode of field */
-</PRE>
-
-(Properly, this user pointer field ought to have <CODE>(void *)</CODE> type.
-The <CODE>(char *)</CODE> type is retained for System V compatibility.) <P>
-
-It is valid to set the user pointer of the default field (with a
-<CODE>set_field_userptr()</CODE> call passed a NULL field pointer.)
-When a new field is created, the default-field user pointer is copied
-to initialize the new field's user pointer.
-
-<H2><A NAME="fdynamic">Variable-Sized Fields</A></H2>
-
-Normally, a field is fixed at the size specified for it at creation
-time. If, however, you turn off its O_STATIC bit, it becomes
-<DFN>dynamic</DFN> and will automatically resize itself to accommodate
-data as it is entered. If the field has extra buffers associated with it,
-they will grow right along with the main input buffer. <P>
-
-A one-line dynamic field will have a fixed height (1) but variable
-width, scrolling horizontally to display data within the field area as
-originally dimensioned and located. A multi-line dynamic field will
-have a fixed width, but variable height (number of rows), scrolling
-vertically to display data within the field area as originally
-dimensioned and located. <P>
-
-Normally, a dynamic field is allowed to grow without limit. But it is
-possible to set an upper limit on the size of a dynamic field. You do
-it with this function:
-
-<PRE>
-int set_max_field(FIELD *field, /* field to alter (may not be NULL) */
- int max_size); /* upper limit on field size */
-</PRE>
-
-If the field is one-line, <CODE>max_size</CODE> is taken to be a column size
-limit; if it is multi-line, it is taken to be a line size limit. To disable
-any limit, use an argument of zero. The growth limit can be changed whether
-or not the O_STATIC bit is on, but has no effect until it is. <P>
-
-The following properties of a field change when it becomes dynamic:
-
-<UL>
-<LI>If there is no growth limit, there is no final position of the field;
-therefore <CODE>O_AUTOSKIP</CODE> and <CODE>O_NL_OVERLOAD</CODE> are ignored.
-<LI>Field justification will be ignored (though whatever justification is
-set up will be retained internally and can be queried).
-<LI>The <CODE>dup_field()</CODE> and <CODE>link_field()</CODE> calls copy
-dynamic-buffer sizes. If the <CODE>O_STATIC</CODE> option is set on one of a
-collection of links, buffer resizing will occur only when the field is
-edited through that link.
-<LI>The call <CODE>field_info()</CODE> will retrieve the original static size of
-the field; use <CODE>dynamic_field_info()</CODE> to get the actual dynamic size.
-</UL>
-
-<H2><A NAME="fvalidation">Field Validation</A></H2>
-
-By default, a field will accept any data that will fit in its input buffer.
-However, it is possible to attach a validation type to a field. If you do
-this, any attempt to leave the field while it contains data that doesn't
-match the validation type will fail. Some validation types also have a
-character-validity check for each time a character is entered in the field. <P>
-
-A field's validation check (if any) is not called when
-<CODE>set_field_buffer()</CODE> modifies the input buffer, nor when that buffer
-is changed through a linked field. <P>
-
-The <CODE>form</CODE> library provides a rich set of pre-defined validation
-types, and gives you the capability to define custom ones of your own. You
-can examine and change field validation attributes with the following
-functions:
-
-<PRE>
-int set_field_type(FIELD *field, /* field to alter */
- FIELDTYPE *ftype, /* type to associate */
- ...); /* additional arguments*/
-
-FIELDTYPE *field_type(FIELD *field); /* field to query */
-</PRE>
-
-The validation type of a field is considered an attribute of the field. As
-with other field attributes, Also, doing <CODE>set_field_type()</CODE> with a
-<CODE>NULL</CODE> field default will change the system default for validation of
-newly-created fields. <P>
-
-Here are the pre-defined validation types:
-
-<H3><A NAME="ftype_alpha">TYPE_ALPHA</A></H3>
-
-This field type accepts alphabetic data; no blanks, no digits, no special
-characters (this is checked at character-entry time). It is set up with:
-
-<PRE>
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_ALPHA, /* type to associate */
- int width); /* maximum width of field */
-</PRE>
-
-The <CODE>width</CODE> argument sets a minimum width of data. Typically
-you'll want to set this to the field width; if it's greater than the
-field width, the validation check will always fail. A minimum width
-of zero makes field completion optional.
-
-<H3><A NAME="ftype_alnum">TYPE_ALNUM</A></H3>
-
-This field type accepts alphabetic data and digits; no blanks, no special
-characters (this is checked at character-entry time). It is set up with:
-
-<PRE>
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_ALNUM, /* type to associate */
- int width); /* maximum width of field */
-</PRE>
-
-The <CODE>width</CODE> argument sets a minimum width of data. As with
-TYPE_ALPHA, typically you'll want to set this to the field width; if it's
-greater than the field width, the validation check will always fail. A
-minimum width of zero makes field completion optional.
-
-<H3><A NAME="ftype_enum">TYPE_ENUM</A></H3>
-
-This type allows you to restrict a field's values to be among a specified
-set of string values (for example, the two-letter postal codes for U.S.
-states). It is set up with:
-
-<PRE>
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_ENUM, /* type to associate */
- char **valuelist; /* list of possible values */
- int checkcase; /* case-sensitive? */
- int checkunique); /* must specify uniquely? */
-</PRE>
-
-The <CODE>valuelist</CODE> parameter must point at a NULL-terminated list of
-valid strings. The <CODE>checkcase</CODE> argument, if true, makes comparison
-with the string case-sensitive. <P>
-
-When the user exits a TYPE_ENUM field, the validation procedure tries to
-complete the data in the buffer to a valid entry. If a complete choice string
-has been entered, it is of course valid. But it is also possible to enter a
-prefix of a valid string and have it completed for you. <P>
-
-By default, if you enter such a prefix and it matches more than one value
-in the string list, the prefix will be completed to the first matching
-value. But the <CODE>checkunique</CODE> argument, if true, requires prefix
-matches to be unique in order to be valid. <P>
-
-The <CODE>REQ_NEXT_CHOICE</CODE> and <CODE>REQ_PREV_CHOICE</CODE> input requests
-can be particularly useful with these fields.
-
-<H3><A NAME="ftype_integer">TYPE_INTEGER</A></H3>
-
-This field type accepts an integer. It is set up as follows:
-
-<PRE>
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_INTEGER, /* type to associate */
- int padding, /* # places to zero-pad to */
- int vmin, int vmax); /* valid range */
-</PRE>
-
-Valid characters consist of an optional leading minus and digits.
-The range check is performed on exit. If the range maximum is less
-than or equal to the minimum, the range is ignored. <P>
-
-If the value passes its range check, it is padded with as many leading
-zero digits as necessary to meet the padding argument. <P>
-
-A <CODE>TYPE_INTEGER</CODE> value buffer can conveniently be interpreted
-with the C library function <CODE>atoi(3)</CODE>.
-
-<H3><A NAME="ftype_numeric">TYPE_NUMERIC</A></H3>
-
-This field type accepts a decimal number. It is set up as follows:
-
-<PRE>
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_NUMERIC, /* type to associate */
- int padding, /* # places of precision */
- double vmin, double vmax); /* valid range */
-</PRE>
-
-Valid characters consist of an optional leading minus and digits. possibly
-including a decimal point. If your system supports locale's, the decimal point
-character used must be the one defined by your locale. The range check is
-performed on exit. If the range maximum is less than or equal to the minimum,
-the range is ignored. <P>
-
-If the value passes its range check, it is padded with as many trailing
-zero digits as necessary to meet the padding argument. <P>
-
-A <CODE>TYPE_NUMERIC</CODE> value buffer can conveniently be interpreted
-with the C library function <CODE>atof(3)</CODE>.
-
-<H3><A NAME="ftype_regexp">TYPE_REGEXP</A></H3>
-
-This field type accepts data matching a regular expression. It is set up
-as follows:
-
-<PRE>
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_REGEXP, /* type to associate */
- char *regexp); /* expression to match */
-</PRE>
-
-The syntax for regular expressions is that of <CODE>regcomp(3)</CODE>.
-The check for regular-expression match is performed on exit.
-
-<H2><A NAME="fbuffer">Direct Field Buffer Manipulation</A></H2>
-
-The chief attribute of a field is its buffer contents. When a form has
-been completed, your application usually needs to know the state of each
-field buffer. You can find this out with:
-
-<PRE>
-char *field_buffer(FIELD *field, /* field to query */
- int bufindex); /* number of buffer to query */
-</PRE>
-
-Normally, the state of the zero-numbered buffer for each field is 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:
-
-<PRE>
-int set_field_buffer(FIELD *field, /* field to alter */
- int bufindex, /* number of buffer to alter */
- char *value); /* string value to set */
-</PRE>
-
-If the field is not large enough and cannot be resized to a sufficiently
-large size to contain the specified value, the value will be truncated
-to fit. <P>
-
-Calling <CODE>field_buffer()</CODE> with a null field pointer will raise an
-error. Calling <CODE>field_buffer()</CODE> on a field not currently selected
-for input will return a correct value. Calling <CODE>field_buffer()</CODE> on a
-field that is currently selected for input may not necessarily give a
-correct field buffer value, because entered data isn't necessarily copied to
-buffer zero before the exit validation check.
-
-To guarantee that the returned buffer value reflects on-screen reality,
-call <CODE>field_buffer()</CODE> either (1) in the field's exit validation
-check routine, (2) from the field's or form's initialization or termination
-hooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been processed
-by the forms driver.
-
-<H2><A NAME="formattrs">Attributes of Forms</A></H2>
-
-As with field attributes, form attributes inherit a default from a
-system default form structure. These defaults can be queried or set by
-of these functions using a form-pointer argument of <CODE>NULL</CODE>. <P>
-
-The principal attribute of a form is its field list. You can query
-and change this list with:
-
-<PRE>
-int set_form_fields(FORM *form, /* form to alter */
- FIELD **fields); /* fields to connect */
-
-char *form_fields(FORM *form); /* fetch fields of form */
-
-int field_count(FORM *form); /* count connect fields */
-</PRE>
-
-The second argument of <CODE>set_form_fields()</CODE> may be a
-NULL-terminated field pointer array like the one required by
-<CODE>new_form()</CODE>. In that case, the old fields of the form are
-disconnected but not freed (and eligible to be connected to other
-forms), then the new fields are connected. <P>
-
-It may also be null, in which case the old fields are disconnected
-(and not freed) but no new ones are connected. <P>
-
-The <CODE>field_count()</CODE> function simply counts the number of fields
-connected to a given from. It returns -1 if the form-pointer argument
-is NULL.
-
-<H2><A NAME="fdisplay">Control of Form Display</A></H2>
-
-In the overview section, you saw that to display a form you normally
-start by defining its size (and fields), posting it, and refreshing
-the screen. There is an hidden step before posting, which is the
-association of the form with a frame window (actually, a pair of
-windows) within which it will be displayed. By default, the forms
-library associates every form with the full-screen window
-<CODE>stdscr</CODE>. <P>
-
-By making this step explicit, you can associate a form with a declared
-frame window on your screen display. This can be useful if you want to
-adapt the form display to different screen sizes, dynamically tile
-forms on the screen, or use a form as part of an interface layout
-managed by <A HREF="#panels">panels</A>. <P>
-
-The two windows associated with each form have the same functions as
-their analogues in the <A HREF="#menu">menu library</A>. Both these
-windows are painted when the form is posted and erased when the form
-is unposted. <P>
-
-The outer or frame window is not otherwise touched by the form
-routines. It exists so the programmer can associate a title, a
-border, or perhaps help text with the form and have it properly
-refreshed or erased at post/unpost time. The inner window or subwindow
-is where the current form page is actually displayed. <P>
-
-In order to declare your own frame window for a form, you'll need to
-know the size of the form's bounding rectangle. You can get this
-information with:
-
-<PRE>
-int scale_form(FORM *form, /* form to query */
- int *rows, /* form rows */
- int *cols); /* form cols */
-</PRE>
-
-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:
-
-<PRE>
-int set_form_win(FORM *form, /* form to alter */
- WINDOW *win); /* frame window to connect */
-
-WINDOW *form_win(FORM *form); /* fetch frame window of form */
-
-int set_form_sub(FORM *form, /* form to alter */
- WINDOW *win); /* form subwindow to connect */
-
-WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */
-</PRE>
-
-Note that curses operations, including <CODE>refresh()</CODE>, on the form,
-should be done on the frame window, not the form subwindow. <P>
-
-It is possible to check from your application whether all of a
-scrollable field is actually displayed within the menu subwindow. Use
-these functions:
-
-<PRE>
-int data_ahead(FORM *form); /* form to be queried */
-
-int data_behind(FORM *form); /* form to be queried */
-</PRE>
-
-The function <CODE>data_ahead()</CODE> returns TRUE if (a) the current
-field is one-line and has undisplayed data off to the right, (b) the current
-field is multi-line and there is data off-screen below it. <P>
-
-The function <CODE>data_behind()</CODE> returns TRUE if the first (upper
-left hand) character position is off-screen (not being displayed). <P>
-
-Finally, there is a function to restore the form window's cursor to the
-value expected by the forms driver:
-
-<PRE>
-int pos_form_cursor(FORM *) /* form to be queried */
-</PRE>
-
-If your application changes the form window cursor, call this function before
-handing control back to the forms driver in order to re-synchronize it.
-
-<H2><A NAME="fdriver">Input Processing in the Forms Driver</A></H2>
-
-The function <CODE>form_driver()</CODE> handles virtualized input requests
-for form navigation, editing, and validation requests, just as
-<CODE>menu_driver</CODE> does for menus (see the section on <A
-HREF="#minput">menu input handling</A>).
-
-<PRE>
-int form_driver(FORM *form, /* form to pass input to */
- int request); /* form request code */
-</PRE>
-
-Your input virtualization function needs to take input and then convert it
-to either an alphanumeric character (which is treated as data to be
-entered in the currently-selected field), or a forms processing request. <P>
-
-The forms driver provides hooks (through input-validation and
-field-termination functions) with which your application code can check
-that the input taken by the driver matched what was expected.
-
-<H3><A NAME="fpage">Page Navigation Requests</A></H3>
-
-These requests cause page-level moves through the form,
-triggering display of a new form screen.
-
-<DL>
-<DT> <CODE>REQ_NEXT_PAGE</CODE>
-<DD> Move to the next form page.
-<DT> <CODE>REQ_PREV_PAGE</CODE>
-<DD> Move to the previous form page.
-<DT> <CODE>REQ_FIRST_PAGE</CODE>
-<DD> Move to the first form page.
-<DT> <CODE>REQ_LAST_PAGE</CODE>
-<DD> Move to the last form page.
-</DL>
-
-These requests treat the list as cyclic; that is, <CODE>REQ_NEXT_PAGE</CODE>
-from the last page goes to the first, and <CODE>REQ_PREV_PAGE</CODE> from
-the first page goes to the last.
-
-<H3><A NAME="ffield">Inter-Field Navigation Requests</A></H3>
-
-These requests handle navigation between fields on the same page.
-
-<DL>
-<DT> <CODE>REQ_NEXT_FIELD</CODE>
-<DD> Move to next field.
-<DT> <CODE>REQ_PREV_FIELD</CODE>
-<DD> Move to previous field.
-<DT> <CODE>REQ_FIRST_FIELD</CODE>
-<DD> Move to the first field.
-<DT> <CODE>REQ_LAST_FIELD</CODE>
-<DD> Move to the last field.
-<DT> <CODE>REQ_SNEXT_FIELD</CODE>
-<DD> Move to sorted next field.
-<DT> <CODE>REQ_SPREV_FIELD</CODE>
-<DD> Move to sorted previous field.
-<DT> <CODE>REQ_SFIRST_FIELD</CODE>
-<DD> Move to the sorted first field.
-<DT> <CODE>REQ_SLAST_FIELD</CODE>
-<DD> Move to the sorted last field.
-<DT> <CODE>REQ_LEFT_FIELD</CODE>
-<DD> Move left to field.
-<DT> <CODE>REQ_RIGHT_FIELD</CODE>
-<DD> Move right to field.
-<DT> <CODE>REQ_UP_FIELD</CODE>
-<DD> Move up to field.
-<DT> <CODE>REQ_DOWN_FIELD</CODE>
-<DD> Move down to field.
-</DL>
-
-These requests treat the list of fields on a page as cyclic; that is,
-<CODE>REQ_NEXT_FIELD</CODE> from the last field goes to the first, and
-<CODE>REQ_PREV_FIELD</CODE> from the first field goes to the last. The
-order of the fields for these (and the <CODE>REQ_FIRST_FIELD</CODE> and
-<CODE>REQ_LAST_FIELD</CODE> requests) is simply the order of the field
-pointers in the form array (as set up by <CODE>new_form()</CODE> or
-<CODE>set_form_fields()</CODE> <P>
-
-It is also possible to traverse the fields as if they had been sorted in
-screen-position order, so the sequence goes left-to-right and top-to-bottom.
-To do this, use the second group of four sorted-movement requests. <P>
-
-Finally, it is possible to move between fields using visual directions up,
-down, right, and left. To accomplish this, use the third group of four
-requests. Note, however, that the position of a form for purposes of these
-requests is its upper-left corner. <P>
-
-For example, suppose you have a multi-line field B, and two
-single-line fields A and C on the same line with B, with A to the left
-of B and C to the right of B. A <CODE>REQ_MOVE_RIGHT</CODE> from A will
-go to B only if A, B, and C <EM>all</EM> share the same first line;
-otherwise it will skip over B to C.
-
-<H3><A NAME="fifield">Intra-Field Navigation Requests</A></H3>
-
-These requests drive movement of the edit cursor within the currently
-selected field.
-
-<DL>
-<DT> <CODE>REQ_NEXT_CHAR</CODE>
-<DD> Move to next character.
-<DT> <CODE>REQ_PREV_CHAR</CODE>
-<DD> Move to previous character.
-<DT> <CODE>REQ_NEXT_LINE</CODE>
-<DD> Move to next line.
-<DT> <CODE>REQ_PREV_LINE</CODE>
-<DD> Move to previous line.
-<DT> <CODE>REQ_NEXT_WORD</CODE>
-<DD> Move to next word.
-<DT> <CODE>REQ_PREV_WORD</CODE>
-<DD> Move to previous word.
-<DT> <CODE>REQ_BEG_FIELD</CODE>
-<DD> Move to beginning of field.
-<DT> <CODE>REQ_END_FIELD</CODE>
-<DD> Move to end of field.
-<DT> <CODE>REQ_BEG_LINE</CODE>
-<DD> Move to beginning of line.
-<DT> <CODE>REQ_END_LINE</CODE>
-<DD> Move to end of line.
-<DT> <CODE>REQ_LEFT_CHAR</CODE>
-<DD> Move left in field.
-<DT> <CODE>REQ_RIGHT_CHAR</CODE>
-<DD> Move right in field.
-<DT> <CODE>REQ_UP_CHAR</CODE>
-<DD> Move up in field.
-<DT> <CODE>REQ_DOWN_CHAR</CODE>
-<DD> Move down in field.
-</DL>
-
-Each <EM>word</EM> is separated from the previous and next characters
-by whitespace. The commands to move to beginning and end of line or field
-look for the first or last non-pad character in their ranges.
-
-<H3><A NAME="fscroll">Scrolling Requests</A></H3>
-
-Fields that are dynamic and have grown and fields explicitly created
-with offscreen rows are scrollable. One-line fields scroll horizontally;
-multi-line fields scroll vertically. Most scrolling is triggered by
-editing and intra-field movement (the library scrolls the field to keep the
-cursor visible). It is possible to explicitly request scrolling with the
-following requests:
-
-<DL>
-<DT> <CODE>REQ_SCR_FLINE</CODE>
-<DD> Scroll vertically forward a line.
-<DT> <CODE>REQ_SCR_BLINE</CODE>
-<DD> Scroll vertically backward a line.
-<DT> <CODE>REQ_SCR_FPAGE</CODE>
-<DD> Scroll vertically forward a page.
-<DT> <CODE>REQ_SCR_BPAGE</CODE>
-<DD> Scroll vertically backward a page.
-<DT> <CODE>REQ_SCR_FHPAGE</CODE>
-<DD> Scroll vertically forward half a page.
-<DT> <CODE>REQ_SCR_BHPAGE</CODE>
-<DD> Scroll vertically backward half a page.
-<DT> <CODE>REQ_SCR_FCHAR</CODE>
-<DD> Scroll horizontally forward a character.
-<DT> <CODE>REQ_SCR_BCHAR</CODE>
-<DD> Scroll horizontally backward a character.
-<DT> <CODE>REQ_SCR_HFLINE</CODE>
-<DD> Scroll horizontally one field width forward.
-<DT> <CODE>REQ_SCR_HBLINE</CODE>
-<DD> Scroll horizontally one field width backward.
-<DT> <CODE>REQ_SCR_HFHALF</CODE>
-<DD> Scroll horizontally one half field width forward.
-<DT> <CODE>REQ_SCR_HBHALF</CODE>
-<DD> Scroll horizontally one half field width backward.
-</DL>
-
-For scrolling purposes, a <EM>page</EM> of a field is the height
-of its visible part.
-
-<H3><A NAME="fedit">Editing Requests</A></H3>
-
-When you pass the forms driver an ASCII character, it is treated as a
-request to add the character to the field's data buffer. Whether this
-is an insertion or a replacement depends on the field's edit mode
-(insertion is the default. <P>
-
-The following requests support editing the field and changing the edit
-mode:
-
-<DL>
-<DT> <CODE>REQ_INS_MODE</CODE>
-<DD> Set insertion mode.
-<DT> <CODE>REQ_OVL_MODE</CODE>
-<DD> Set overlay mode.
-<DT> <CODE>REQ_NEW_LINE</CODE>
-<DD> New line request (see below for explanation).
-<DT> <CODE>REQ_INS_CHAR</CODE>
-<DD> Insert space at character location.
-<DT> <CODE>REQ_INS_LINE</CODE>
-<DD> Insert blank line at character location.
-<DT> <CODE>REQ_DEL_CHAR</CODE>
-<DD> Delete character at cursor.
-<DT> <CODE>REQ_DEL_PREV</CODE>
-<DD> Delete previous word at cursor.
-<DT> <CODE>REQ_DEL_LINE</CODE>
-<DD> Delete line at cursor.
-<DT> <CODE>REQ_DEL_WORD</CODE>
-<DD> Delete word at cursor.
-<DT> <CODE>REQ_CLR_EOL</CODE>
-<DD> Clear to end of line.
-<DT> <CODE>REQ_CLR_EOF</CODE>
-<DD> Clear to end of field.
-<DT> <CODE>REQ_CLEAR_FIELD</CODE>
-<DD> Clear entire field.
-</DL>
-
-The behavior of the <CODE>REQ_NEW_LINE</CODE> and <CODE>REQ_DEL_PREV</CODE> requests
-is complicated and partly controlled by a pair of forms options.
-The special cases are triggered when the cursor is at the beginning of
-a field, or on the last line of the field. <P>
-
-First, we consider <CODE>REQ_NEW_LINE</CODE>: <P>
-
-The normal behavior of <CODE>REQ_NEW_LINE</CODE> in insert mode is to break the
-current line at the position of the edit cursor, inserting the portion of
-the current line after the cursor as a new line following the current
-and moving the cursor to the beginning of that new line (you may think
-of this as inserting a newline in the field buffer). <P>
-
-The normal behavior of <CODE>REQ_NEW_LINE</CODE> in overlay mode is to clear the
-current line from the position of the edit cursor to end of line.
-The cursor is then moved to the beginning of the next line. <P>
-
-However, <CODE>REQ_NEW_LINE</CODE> at the beginning of a field, or on the
-last line of a field, instead does a <CODE>REQ_NEXT_FIELD</CODE>.
-<CODE>O_NL_OVERLOAD</CODE> option is off, this special action is
-disabled. <P>
-
-Now, let us consider <CODE>REQ_DEL_PREV</CODE>: <P>
-
-The normal behavior of <CODE>REQ_DEL_PREV</CODE> is to delete the previous
-character. If insert mode is on, and the cursor is at the start of a
-line, and the text on that line will fit on the previous one, it
-instead appends the contents of the current line to the previous one
-and deletes the current line (you may think of this as deleting a
-newline from the field buffer). <P>
-
-However, <CODE>REQ_DEL_PREV</CODE> at the beginning of a field is instead
-treated as a <CODE>REQ_PREV_FIELD</CODE>. <P> If the
-<CODE>O_BS_OVERLOAD</CODE> option is off, this special action is
-disabled and the forms driver just returns <CODE>E_REQUEST_DENIED</CODE>. <P>
-
-See <A HREF="#frmoptions">Form Options</A> for discussion of how to set
-and clear the overload options.
-
-<H3><A NAME="forder">Order Requests</A></H3>
-
-If the type of your field is ordered, and has associated functions
-for getting the next and previous values of the type from a given value,
-there are requests that can fetch that value into the field buffer:
-
-<DL>
-<DT> <CODE>REQ_NEXT_CHOICE</CODE>
-<DD> Place the successor value of the current value in the buffer.
-<DT> <CODE>REQ_PREV_CHOICE</CODE>
-<DD> Place the predecessor value of the current value in the buffer.
-</DL>
-
-Of the built-in field types, only <CODE>TYPE_ENUM</CODE> has built-in successor
-and predecessor functions. When you define a field type of your own
-(see <A HREF="#fcustom">Custom Validation Types</A>), you can associate
-our own ordering functions.
-
-<H3><A NAME="fappcmds">Application Commands</A></H3>
-
-Form requests are represented as integers above the <CODE>curses</CODE> value
-greater than <CODE>KEY_MAX</CODE> and less than or equal to the constant
-<CODE>MAX_COMMAND</CODE>. If your input-virtualization routine returns a
-value above <CODE>MAX_COMMAND</CODE>, the forms driver will ignore it.
-
-<H2><A NAME="fhooks">Field Change Hooks</A></H2>
-
-It is possible to set function hooks to be executed whenever the
-current field or form changes. Here are the functions that support this:
-
-<PRE>
-typedef void (*HOOK)(); /* pointer to function returning void */
-
-int set_form_init(FORM *form, /* form to alter */
- HOOK hook); /* initialization hook */
-
-HOOK form_init(FORM *form); /* form to query */
-
-int set_form_term(FORM *form, /* form to alter */
- HOOK hook); /* termination hook */
-
-HOOK form_term(FORM *form); /* form to query */
-
-int set_field_init(FORM *form, /* form to alter */
- HOOK hook); /* initialization hook */
-
-HOOK field_init(FORM *form); /* form to query */
-
-int set_field_term(FORM *form, /* form to alter */
- HOOK hook); /* termination hook */
-
-HOOK field_term(FORM *form); /* form to query */
-</PRE>
-
-These functions allow you to either set or query four different hooks.
-In each of the set functions, the second argument should be the
-address of a hook function. These functions differ only in the timing
-of the hook call.
-
-<DL>
-<DT> form_init
-<DD> This hook is called when the form is posted; also, just after
-each page change operation.
-<DT> field_init
-<DD> This hook is called when the form is posted; also, just after
-each field change
-<DT> field_term
-<DD> This hook is called just after field validation; that is, just before
-the field is altered. It is also called when the form is unposted.
-<DT> form_term
-<DD> This hook is called when the form is unposted; also, just before
-each page change operation.
-</DL>
-
-Calls to these hooks may be triggered
-<OL>
-<LI>When user editing requests are processed by the forms driver
-<LI>When the current page is changed by <CODE>set_current_field()</CODE> call
-<LI>When the current field is changed by a <CODE>set_form_page()</CODE> call
-</OL>
-
-See <A NAME="ffocus">Field Change Commands</A> for discussion of the latter
-two cases. <P>
-
-You can set a default hook for all fields by passing one of the set functions
-a NULL first argument. <P>
-
-You can disable any of these hooks by (re)setting them to NULL, the default
-value.
-
-<H2><A HREF="#ffocus">Field Change Commands</A></H2>
-
-Normally, navigation through the form will be driven by the user's
-input requests. But sometimes it is useful to be able to move the
-focus for editing and viewing under control of your application, or
-ask which field it currently is in. The following functions help you
-accomplish this:
-
-<PRE>
-int set_current_field(FORM *form, /* form to alter */
- FIELD *field); /* field to shift to */
-
-FIELD *current_field(FORM *form); /* form to query */
-
-int field_index(FORM *form, /* form to query */
- FIELD *field); /* field to get index of */
-</PRE>
-
-The function <CODE>field_index()</CODE> returns the index of the given field
-in the given form's field array (the array passed to <CODE>new_form()</CODE> or
-<CODE>set_form_fields()</CODE>). <P>
-
-The initial current field of a form is the first active field on the
-first page. The function <CODE>set_form_fields()</CODE> resets this.<P>
-
-It is also possible to move around by pages.
-
-<PRE>
-int set_form_page(FORM *form, /* form to alter */
- int page); /* page to go to (0-origin) */
-
-int form_page(FORM *form); /* return form's current page */
-</PRE>
-
-The initial page of a newly-created form is 0. The function
-<CODE>set_form_fields()</CODE> resets this.
-
-<H2><A NAME="frmoptions">Form Options</A></H2>
-
-Like fields, forms may have control option bits. They can be changed
-or queried with these functions:
-
-<PRE>
-int set_form_opts(FORM *form, /* form to alter */
- int attr); /* attribute to set */
-
-int form_opts_on(FORM *form, /* form to alter */
- int attr); /* attributes to turn on */
-
-int form_opts_off(FORM *form, /* form to alter */
- int attr); /* attributes to turn off */
-
-int form_opts(FORM *form); /* form to query */
-</PRE>
-
-By default, all options are on. Here are the available option bits:
-
-<DL>
-<DT> O_NL_OVERLOAD
-<DD> Enable overloading of <CODE>REQ_NEW_LINE</CODE> as described in <A
-href="#fedit">Editing Requests</A>. The value of this option is
-ignored on dynamic fields that have not reached their size limit;
-these have no last line, so the circumstances for triggering a
-<CODE>REQ_NEXT_FIELD</CODE> never arise.
-<DT> O_BS_OVERLOAD
-<DD> Enable overloading of <CODE>REQ_DEL_PREV</CODE> as described in
-<A href="#fedit">Editing Requests</A>.
-</DL>
-
-The option values are bit-masks and can be composed with logical-or in
-the obvious way.
-
-<H2><A NAME="fcustom">Custom Validation Types</A></H2>
-
-The <CODE>form</CODE> library gives you the capability to define custom
-validation types of your own. Further, the optional additional arguments
-of <CODE>set_field_type</CODE> effectively allow you to parameterize validation
-types. Most of the complications in the validation-type interface have to
-do with the handling of the additional arguments within custom validation
-functions.
-
-<H3><A NAME="flinktypes">Union Types</A></H3>
-
-The simplest way to create a custom data type is to compose it from two
-preexisting ones:
-
-<PRE>
-FIELD *link_fieldtype(FIELDTYPE *type1,
- FIELDTYPE *type2);
-</PRE>
-
-This function creates a field type that will accept any of the values
-legal for either of its argument field types (which may be either
-predefined or programmer-defined).
-
-If a <CODE>set_field_type()</CODE> call later requires arguments, the new
-composite type expects all arguments for the first type, than all arguments
-for the second. Order functions (see <A HREF="#forder">Order Requests</A>)
-associated with the component types will work on the composite; what it does
-is check the validation function for the first type, then for the second, to
-figure what type the buffer contents should be treated as.
-
-<H3><A NAME="fnewtypes">New Field Types</A></H3>
-
-To create a field type from scratch, you need to specify one or both of the
-following things:
-
-<UL>
-<LI>A character-validation function, to check each character as it is entered.
-<LI>A field-validation function to be applied on exit from the field.
-</UL>
-
-Here's how you do that:
-<PRE>
-typedef int (*HOOK)(); /* pointer to function returning int */
-
-FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */
- HOOK c_validate) /* character validator */
-
-
-int free_fieldtype(FIELDTYPE *ftype); /* type to free */
-</PRE>
-
-At least one of the arguments of <CODE>new_fieldtype()</CODE> must be
-non-NULL. The forms driver will automatically call the new type's
-validation functions at appropriate points in processing a field of
-the new type. <P>
-
-The function <CODE>free_fieldtype()</CODE> deallocates the argument
-fieldtype, freeing all storage associated with it. <P>
-
-Normally, a field validator is called when the user attempts to
-leave the field. Its first argument is a field pointer, from which it
-can get to field buffer 0 and test it. If the function returns TRUE,
-the operation succeeds; if it returns FALSE, the edit cursor stays in
-the field. <P>
-
-A character validator gets the character passed in as a first argument.
-It too should return TRUE if the character is valid, FALSE otherwise.
-
-<H3><A NAME="fcheckargs">Validation Function Arguments</A></H3>
-
-Your field- and character- validation functions will be passed a
-second argument as well. This second argument is the address of a
-structure (which we'll call a <EM>pile</EM>) built from any of the
-field-type-specific arguments passed to <CODE>set_field_type()</CODE>. If
-no such arguments are defined for the field type, this pile pointer
-argument will be NULL. <P>
-
-In order to arrange for such arguments to be passed to your validation
-functions, you must associate a small set of storage-management functions
-with the type. The forms driver will use these to synthesize a pile
-from the trailing arguments of each <CODE>set_field_type()</CODE> argument, and
-a pointer to the pile will be passed to the validation functions. <P>
-
-Here is how you make the association:
-
-<PRE>
-typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */
-typedef void (*VOIDHOOK)(); /* pointer to function returning void */
-
-int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */
- PTRHOOK make_str, /* make structure from args */
- PTRHOOK copy_str, /* make copy of structure */
- VOIDHOOK free_str); /* free structure storage */
-</PRE>
-
-Here is how the storage-management hooks are used:
-
-<DL>
-<DT> <CODE>make_str</CODE>
-<DD> This function is called by <CODE>set_field_type()</CODE>. It gets one
-argument, a <CODE>va_list</CODE> of the type-specific arguments passed to
-<CODE>set_field_type()</CODE>. It is expected to return a pile pointer to a data
-structure that encapsulates those arguments.
-<DT> <CODE>copy_str</CODE>
-<DD> This function is called by form library functions that allocate new
-field instances. It is expected to take a pile pointer, copy the pile
-to allocated storage, and return the address of the pile copy.
-<DT> <CODE>free_str</CODE>
-<DD> This function is called by field- and type-deallocation routines in the
-library. It takes a pile pointer argument, and is expected to free the
-storage of that pile.
-</DL>
-
-The <CODE>make_str</CODE> and <CODE>copy_str</CODE> functions may return NULL to
-signal allocation failure. The library routines will that call them will
-return error indication when this happens. Thus, your validation functions
-should never see a NULL file pointer and need not check specially for it.
-
-<H3><A NAME="fcustorder">Order Functions For Custom Types</A></H3>
-
-Some custom field types are simply ordered in the same well-defined way
-that <CODE>TYPE_ENUM</CODE> is. For such types, it is possible to define
-successor and predecessor functions to support the <CODE>REQ_NEXT_CHOICE</CODE>
-and <CODE>REQ_PREV_CHOICE</CODE> requests. Here's how:
-
-<PRE>
-typedef int (*INTHOOK)(); /* pointer to function returning int */
-
-int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */
- INTHOOK succ, /* get successor value */
- INTHOOK pred); /* get predecessor value */
-</PRE>
-
-The successor and predecessor arguments will each be passed two arguments;
-a field pointer, and a pile pointer (as for the validation functions). They
-are expected to use the function <CODE>field_buffer()</CODE> to read the
-current value, and <CODE>set_field_buffer()</CODE> on buffer 0 to set the next
-or previous value. Either hook may return TRUE to indicate success (a
-legal next or previous value was set) or FALSE to indicate failure.
-
-<H3><A NAME="fcustprobs">Avoiding Problems</A></H3>
-
-The interface for defining custom types is complicated and tricky.
-Rather than attempting to create a custom type entirely from scratch,
-you should start by studying the library source code for whichever of
-the pre-defined types seems to be closest to what you want. <P>
-
-Use that code as a model, and evolve it towards what you really want.
-You will avoid many problems and annoyances that way. The code
-in the <CODE>ncurses</CODE> library has been specifically exempted from
-the package copyright to support this. <P>
-
-If your custom type defines order functions, have do something intuitive
-with a blank field. A useful convention is to make the successor of a
-blank field the types minimum value, and its predecessor the maximum.
-</BODY>
-</HTML>
diff --git a/contrib/ncurses/doc/ncurses-intro.doc b/contrib/ncurses/doc/ncurses-intro.doc
deleted file mode 100644
index 85179d166696..000000000000
--- a/contrib/ncurses/doc/ncurses-intro.doc
+++ /dev/null
@@ -1,2501 +0,0 @@
- Writing Programs with NCURSES
-
- by Eric S. Raymond and Zeyd M. Ben-Halim
- updates since release 1.9.9e by Thomas Dickey
-
- Contents
-
- * Introduction
- + A Brief History of Curses
- + Scope of This Document
- + Terminology
- * The Curses Library
- + An Overview of Curses
- o Compiling Programs using Curses
- o Updating the Screen
- o Standard Windows and Function Naming Conventions
- o Variables
- + Using the Library
- o Starting up
- o Output
- o Input
- o Using Forms Characters
- o Character Attributes and Color
- o Mouse Interfacing
- o Finishing Up
- + Function Descriptions
- o Initialization and Wrapup
- o Causing Output to the Terminal
- o Low-Level Capability Access
- o Debugging
- + Hints, Tips, and Tricks
- o Some Notes of Caution
- o Temporarily Leaving ncurses Mode
- o Using ncurses under xterm
- o Handling Multiple Terminal Screens
- o Testing for Terminal Capabilities
- o Tuning for Speed
- o Special Features of ncurses
- + Compatibility with Older Versions
- o Refresh of Overlapping Windows
- o Background Erase
- + XSI Curses Conformance
- * The Panels Library
- + Compiling With the Panels Library
- + Overview of Panels
- + Panels, Input, and the Standard Screen
- + Hiding Panels
- + Miscellaneous Other Facilities
- * The Menu Library
- + Compiling with the menu Library
- + Overview of Menus
- + Selecting items
- + Menu Display
- + Menu Windows
- + Processing Menu Input
- + Miscellaneous Other Features
- * The Forms Library
- + Compiling with the forms Library
- + Overview of Forms
- + Creating and Freeing Fields and Forms
- + Fetching and Changing Field Attributes
- o Fetching Size and Location Data
- o Changing the Field Location
- o The Justification Attribute
- o Field Display Attributes
- o Field Option Bits
- o Field Status
- o Field User Pointer
- + Variable-Sized Fields
- + Field Validation
- o TYPE_ALPHA
- o TYPE_ALNUM
- o TYPE_ENUM
- o TYPE_INTEGER
- o TYPE_NUMERIC
- o TYPE_REGEXP
- + Direct Field Buffer Manipulation
- + Attributes of Forms
- + Control of Form Display
- + Input Processing in the Forms Driver
- o Page Navigation Requests
- o Inter-Field Navigation Requests
- o Intra-Field Navigation Requests
- o Scrolling Requests
- o Field Editing Requests
- o Order Requests
- o Application Commands
- + Field Change Hooks
- + Field Change Commands
- + Form Options
- + Custom Validation Types
- o Union Types
- o New Field Types
- o Validation Function Arguments
- o Order Functions For Custom Types
- o Avoiding Problems
- _________________________________________________________________
-
- Introduction
-
- This document is an introduction to programming with curses. It is not
- an exhaustive reference for the curses Application Programming
- Interface (API); that role is filled by the curses manual pages.
- Rather, it is intended to help C programmers ease into using the
- package.
-
- This document is aimed at C applications programmers not yet
- specifically familiar with ncurses. If you are already an experienced
- curses programmer, you should nevertheless read the sections on Mouse
- Interfacing, Debugging, Compatibility with Older Versions, and Hints,
- Tips, and Tricks. These will bring you up to speed on the special
- features and quirks of the ncurses implementation. If you are not so
- experienced, keep reading.
-
- The curses package is a subroutine library for terminal-independent
- screen-painting and input-event handling which presents a high level
- screen model to the programmer, hiding differences between terminal
- types and doing automatic optimization of output to change one screen
- full of text into another. Curses uses terminfo, which is a database
- format that can describe the capabilities of thousands of different
- terminals.
-
- The curses API may seem something of an archaism on UNIX desktops
- increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX
- still supports tty lines and X supports xterm(1); the curses API has
- the advantage of (a) back-portability to character-cell terminals, and
- (b) simplicity. For an application that does not require bit-mapped
- graphics and multiple fonts, an interface implementation using curses
- will typically be a great deal simpler and less expensive than one
- using an X toolkit.
-
-A Brief History of Curses
-
- Historically, the first ancestor of curses was the routines written to
- provide screen-handling for the game rogue; these used the
- already-existing termcap database facility for describing terminal
- capabilities. These routines were abstracted into a documented library
- and first released with the early BSD UNIX versions.
-
- System III UNIX from Bell Labs featured a rewritten and much-improved
- curses library. It introduced the terminfo format. Terminfo is based
- on Berkeley's termcap database, but contains a number of improvements
- and extensions. Parameterized capabilities strings were introduced,
- making it possible to describe multiple video attributes, and colors
- and to handle far more unusual terminals than possible with termcap.
- In the later AT&T System V releases, curses evolved to use more
- facilities and offer more capabilities, going far beyond BSD curses in
- power and flexibility.
-
-Scope of This Document
-
- 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).
- * Support for line- and box-drawing using forms characters.
- * Recognition of function keys on input.
- * Color support.
- * Support for pads (windows of larger than screen size on which the
- screen or a subwindow defines a viewport).
-
- Also, this package makes use of the insert and delete line and
- character features of terminals so equipped, and determines how to
- optimally use these features with no help from the programmer. It
- allows arbitrary combinations of video attributes to be displayed,
- even on terminals that leave ``magic cookies'' on the screen to mark
- changes in attributes.
-
- The ncurses package can also capture and use event reports from a
- mouse in some environments (notably, xterm under the X window system).
- This document includes tips for using the mouse.
-
- 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. Juergen
- Pfeifer wrote all of the menu and forms code as well as the Ada95
- 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
- associate backing store with each of a stack or deck of overlapping
- windows, and provides operations for moving windows around in the
- stack that change their visibility in the natural way (handling window
- overlaps).
-
- 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.
-
-Terminology
-
- In this document, the following terminology is used with reasonable
- consistency:
-
- window
- A data structure describing a sub-rectangle of the screen
- (possibly the entire screen). You can write to a window as
- though it were a miniature screen, scrolling independently of
- other windows on the physical screen.
-
- screens
- A subset of windows which are as large as the terminal screen,
- i.e., they start at the upper left hand corner and encompass
- the lower right hand corner. One of these, stdscr, is
- automatically provided for the programmer.
-
- terminal screen
- The package's idea of what the terminal display currently looks
- like, i.e., what the user sees now. This is a special screen.
-
- The Curses Library
-
-An Overview of Curses
-
- Compiling Programs using Curses
-
- 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
- I/O library, so <curses.h> includes <stdio.h>. <curses.h> also
- includes <termios.h>, <termio.h>, or <sgtty.h> depending on your
- system. It is redundant (but harmless) for the programmer to do these
- includes, too. In linking with curses you need to have -lncurses in
- your LDFLAGS or on the command line. There is no need for any other
- libraries.
-
- Updating the Screen
-
- In order to update the screen optimally, it is necessary for the
- routines to know what the screen currently looks like and what the
- programmer wants it to look like next. For this purpose, a data type
- (structure) named WINDOW is defined which describes a window image to
- the routines, including its starting position on the screen (the (y,
- x) coordinates of the upper left hand corner) and its size. One of
- these (called curscr, for current screen) is a screen image of what
- the terminal currently looks like. Another screen (called stdscr, for
- standard screen) is provided by default to make changes on.
-
- A window is a purely internal representation. It is used to build and
- store a potential image of a portion of the terminal. It doesn't bear
- any necessary relation to what is really on the terminal screen; it's
- more like a scratchpad or write buffer.
-
- To make the section of physical screen corresponding to a window
- reflect the contents of the window structure, the routine refresh()
- (or wrefresh() if the window is not stdscr) is called.
-
- A given physical screen section may be within the scope of any number
- of overlapping windows. Also, changes can be made to windows in any
- order, without regard to motion efficiency. Then, at will, the
- programmer can effectively say ``make it look like this,'' and let the
- package implementation determine the most efficient way to repaint the
- screen.
-
- Standard Windows and Function Naming Conventions
-
- As hinted above, the routines can use several windows, but two are
- automatically given: curscr, which knows what the terminal looks like,
- and stdscr, which is what the programmer wants the terminal to look
- like next. The user should never actually access curscr directly.
- Changes should be made to through the API, and then the routine
- refresh() (or wrefresh()) called.
-
- Many functions are defined to use stdscr as a default screen. For
- example, to add a character to stdscr, one calls addch() with the
- desired character as argument. To write to a different window. use the
- routine waddch() (for `w'indow-specific addch()) is provided. This
- convention of prepending function names with a `w' when they are to be
- applied to specific windows is consistent. The only routines which do
- not follow it are those for which a window must always be specified.
-
- In order to move the current (y, x) coordinates from one point to
- another, the routines move() and wmove() are provided. However, it is
- often desirable to first move and then perform some I/O operation. In
- 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);
-
- can be replaced by
- mvaddch(y, x, ch);
-
- and
- wmove(win, y, x);
- waddch(win, ch);
-
- can be replaced by
- mvwaddch(win, y, x, ch);
-
- Note that the window description pointer (win) comes before the added
- (y, x) coordinates. If a function requires a window pointer, it is
- always the first parameter passed.
-
- Variables
-
- The curses library sets some variables describing the terminal
- capabilities.
- type name description
- ------------------------------------------------------------------
- int LINES number of lines on the terminal
- int COLS number of columns on the terminal
-
- The curses.h also introduces some #define constants and types of
- general usefulness:
-
- bool
- boolean type, actually a `char' (e.g., bool doneit;)
-
- TRUE
- boolean `true' flag (1).
-
- FALSE
- boolean `false' flag (0).
-
- ERR
- error flag returned by routines on a failure (-1).
-
- OK
- error flag returned by routines when things go right.
-
-Using the Library
-
- Now we describe how to actually use the screen package. In it, we
- assume all updating, reading, etc. is applied to stdscr. These
- instructions will work on any window, providing you change the
- function names and parameters as mentioned above.
-
- Here is a sample program to motivate the discussion:
-#include <curses.h>
-#include <signal.h>
-
-static void finish(int sig);
-
-int
-main(int argc, char *argv[])
-{
- int num = 0;
-
- /* initialize your non-curses data structures here */
-
- (void) signal(SIGINT, finish); /* arrange interrupts to terminate */
-
- (void) initscr(); /* initialize the curses library */
- keypad(stdscr, TRUE); /* enable keyboard mapping */
- (void) nonl(); /* tell curses not to do NL->CR/NL on output */
- (void) cbreak(); /* take input chars one at a time, no wait for \n */
- (void) echo(); /* echo input - in color */
-
- if (has_colors())
- {
- start_color();
-
- /*
- * Simple color assignment, often all we need. Color pair 0 cannot
- * be redefined. This example uses the same value for the color
- * pair as for the foreground color, though of course that is not
- * necessary:
- */
- init_pair(1, COLOR_RED, COLOR_BLACK);
- init_pair(2, COLOR_GREEN, COLOR_BLACK);
- init_pair(3, COLOR_YELLOW, COLOR_BLACK);
- init_pair(4, COLOR_BLUE, COLOR_BLACK);
- init_pair(5, COLOR_CYAN, COLOR_BLACK);
- init_pair(6, COLOR_MAGENTA, COLOR_BLACK);
- init_pair(7, COLOR_WHITE, COLOR_BLACK);
- }
-
- for (;;)
- {
- int c = getch(); /* refresh, accept single keystroke of input */
- attrset(COLOR_PAIR(num % 8));
- num++;
-
- /* process the command keystroke */
- }
-
- finish(0); /* we're done */
-}
-
-static void finish(int sig)
-{
- endwin();
-
- /* do your non-curses wrapup here */
-
- exit(0);
-}
-
- Starting up
-
- In order to use the screen package, the routines must know about
- terminal characteristics, and the space for curscr and stdscr must be
- allocated. These function initscr() does both these things. Since it
- must allocate space for the windows, it can overflow memory when
- attempting to do so. On the rare occasions this happens, initscr()
- will terminate the program with an error message. initscr() must
- always be called before any of the routines which affect windows are
- used. If it is not, the program will core dump as soon as either
- curscr or stdscr are referenced. However, it is usually best to wait
- to call it until after you are sure you will need it, like after
- checking for startup errors. Terminal status changing routines like
- nl() and cbreak() should be called after initscr().
-
- Once the screen windows have been allocated, you can set them up for
- your program. If you want to, say, allow a screen to scroll, use
- scrollok(). If you want the cursor to be left in place after the last
- change, use leaveok(). If this isn't done, refresh() will move the
- cursor to the window's current (y, x) coordinates after updating it.
-
- You can create new windows of your own using the functions newwin(),
- derwin(), and subwin(). The routine delwin() will allow you to get rid
- of old windows. All the options described above can be applied to any
- window.
-
- Output
-
- Now that we have set things up, we will want to actually update the
- terminal. The basic functions used to change what will go on a window
- are addch() and move(). addch() adds a character at the current (y, x)
- coordinates. move() changes the current (y, x) coordinates to whatever
- you want them to be. It returns ERR if you try to move off the window.
- As mentioned above, you can combine the two into mvaddch() to do both
- things at once.
-
- The other output functions, such as addstr() and printw(), all call
- addch() to add characters to the window.
-
- After you have put on the window what you want there, when you want
- the portion of the terminal covered by the window to be made to look
- like it, you must call refresh(). In order to optimize finding
- changes, refresh() assumes that any part of the window not changed
- since the last refresh() of that window has not been changed on the
- terminal, i.e., that you have not refreshed a portion of the terminal
- with an overlapping window. If this is not the case, the routine
- touchwin() is provided to make it look like the entire window has been
- changed, thus making refresh() check the whole subsection of the
- terminal for changes.
-
- If you call wrefresh() with curscr as its argument, it will make the
- screen look like curscr thinks it looks like. This is useful for
- implementing a command which would redraw the screen in case it get
- messed up.
-
- Input
-
- The complementary function to addch() is getch() which, if echo is
- set, will call addch() to echo the character. Since the screen package
- needs to know what is on the terminal at all times, if characters are
- to be echoed, the tty must be in raw or cbreak mode. Since initially
- the terminal has echoing enabled and is in ordinary ``cooked'' mode,
- one or the other has to changed before calling getch(); otherwise, the
- program's output will be unpredictable.
-
- When you need to accept line-oriented input in a window, the functions
- wgetstr() and friends are available. There is even a wscanw() function
- that can do scanf()(3)-style multi-field parsing on window input.
- These pseudo-line-oriented functions turn on echoing while they
- execute.
-
- The example code above uses the call keypad(stdscr, TRUE) to enable
- support for function-key mapping. With this feature, the getch() code
- watches the input stream for character sequences that correspond to
- arrow and function keys. These sequences are returned as
- pseudo-character values. The #define values returned are listed in the
- curses.h The mapping from sequences to #define values is determined by
- key_ capabilities in the terminal's terminfo entry.
-
- Using Forms Characters
-
- The addch() function (and some others, including box() and border())
- can accept some pseudo-character arguments which are specially defined
- by ncurses. These are #define values set up in the curses.h header;
- see there for a complete list (look for the prefix ACS_).
-
- The most useful of the ACS defines are the forms-drawing characters.
- You can use these to draw boxes and simple graphs on the screen. If
- the terminal does not have such characters, curses.h will map them to
- a recognizable (though ugly) set of ASCII defaults.
-
- Character Attributes and Color
-
- The ncurses package supports screen highlights including standout,
- reverse-video, underline, and blink. It also supports color, which is
- treated as another kind of highlight.
-
- Highlights are encoded, internally, as high bits of the
- pseudo-character type (chtype) that curses.h uses to represent the
- contents of a screen cell. See the curses.h header file for a complete
- list of highlight mask values (look for the prefix A_).
-
- There are two ways to make highlights. One is to logical-or the value
- of the highlights you want into the character argument of an addch()
- call, or any other output call that takes a chtype argument.
-
- The other is to set the current-highlight value. This is logical-or'ed
- with any highlight you specify the first way. You do this with the
- functions attron(), attroff(), and attrset(); see the manual pages for
- details. Color is a special kind of highlight. The package actually
- thinks in terms of color pairs, combinations of foreground and
- background colors. The sample code above sets up eight color pairs,
- all of the guaranteed-available colors on black. Note that each color
- pair is, in effect, given the name of its foreground color. Any other
- range of eight non-conflicting values could have been used as the
- first arguments of the init_pair() values.
-
- Once you've done an init_pair() that creates color-pair N, you can use
- COLOR_PAIR(N) as a highlight that invokes that particular color
- combination. Note that COLOR_PAIR(N), for constant N, is itself a
- compile-time constant and can be used in initializers.
-
- Mouse Interfacing
-
- 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.
- * FreeBSD sysmouse (console)
- * 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
- see. It will return the bit-mask of events that actually become
- visible, which may differ from the argument if the mouse device is not
- capable of reporting some of the event types you specify.
-
- Once the mouse is active, your application's command loop should watch
- for a return value of KEY_MOUSE from wgetch(). When you see this, a
- mouse event report has been queued. To pick it off the queue, use the
- function getmouse() (you must do this before the next wgetch(),
- otherwise another mouse event might come in and make the first one
- inaccessible).
-
- Each call to getmouse() fills a structure (the address of which you'll
- pass it) with mouse event data. The event data includes zero-origin,
- screen-relative character-cell coordinates of the mouse pointer. It
- also includes an event mask. Bits in this mask will be set,
- corresponding to the event type being reported.
-
- The mouse structure contains two additional fields which may be
- significant in the future as ncurses interfaces to new kinds of
- pointing device. In addition to x and y coordinates, there is a slot
- for a z coordinate; this might be useful with touch-screens that can
- return a pressure or duration parameter. There is also a device ID
- field, which could be used to distinguish between multiple pointing
- devices.
-
- The class of visible events may be changed at any time via
- mousemask(). Events that can be reported include presses, releases,
- single-, double- and triple-clicks (you can set the maximum
- button-down time for clicks). If you don't make clicks visible, they
- will be reported as press-release pairs. In some environments, the
- event mask may include bits reporting the state of shift, alt, and
- ctrl keys on the keyboard during the event.
-
- A function to check whether a mouse event fell within a given window
- is also supplied. You can use this to see whether a given window
- should consider a mouse event relevant to it.
-
- Because mouse event reporting will not be available in all
- environments, it would be unwise to build ncurses applications that
- require the use of a mouse. Rather, you should use the mouse as a
- shortcut for point-and-shoot commands your application would normally
- accept from the keyboard. Two of the test games in the ncurses
- distribution (bs and knight) contain code that illustrates how this
- can be done.
-
- See the manual page curs_mouse(3X) for full details of the
- mouse-interface functions.
-
- Finishing Up
-
- In order to clean up after the ncurses routines, the routine endwin()
- is provided. It restores tty modes to what they were when initscr()
- was first called, and moves the cursor down to the lower-left corner.
- Thus, anytime after the call to initscr, endwin() should be called
- before exiting.
-
-Function Descriptions
-
- We describe the detailed behavior of some important curses functions
- here, as a supplement to the manual page descriptions.
-
- Initialization and Wrapup
-
- initscr()
- The first function called should almost always be initscr().
- This will determine the terminal type and initialize curses
- data structures. initscr() also arranges that the first call to
- 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(), ripoffline(), use_env(),
- and, if you are using multiple terminals, newterm().)
-
- endwin()
- Your program should always call endwin() before exiting or
- shelling out of the program. This function will restore tty
- modes, move the cursor to the lower left corner of the screen,
- reset the terminal into the proper non-visual mode. Calling
- refresh() or doupdate() after a temporary escape from the
- program will restore the ncurses screen from before the escape.
-
- newterm(type, ofp, ifp)
- A program which outputs to more than one terminal should use
- newterm() instead of initscr(). newterm() should be called once
- for each terminal. It returns a variable of type SCREEN * which
- should be saved as a reference to that terminal. (NOTE: a
- SCREEN variable is not a screen in the sense we are describing
- in this introduction, but a collection of parameters used to
- assist in optimizing the display.) The arguments are the type
- of the terminal (a string) and FILE pointers for the output and
- input of the terminal. If type is NULL then the environment
- variable $TERM is used. endwin() should called once at wrapup
- time for each terminal opened using this function.
-
- set_term(new)
- This function is used to switch to a different terminal
- previously opened by newterm(). The screen reference for the
- new terminal is passed as the parameter. The previous terminal
- is returned by the function. All other calls affect only the
- current terminal.
-
- delscreen(sp)
- The inverse of newterm(); deallocates the data structures
- associated with a given SCREEN reference.
-
- Causing Output to the Terminal
-
- refresh() and wrefresh(win)
- These functions must be called to actually get any output on
- 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.
-
- doupdate() and wnoutrefresh(win)
- These two functions allow multiple updates with more efficiency
- than wrefresh. To use them, it is important to understand how
- curses works. In addition to all the window structures, curses
- keeps two data structures representing the terminal screen: a
- physical screen, describing what is actually on the screen, and
- a virtual screen, describing what the programmer wants to have
- on the screen. wrefresh works by first copying the named window
- to the virtual screen (wnoutrefresh()), and then calling the
- routine to update the screen (doupdate()). If the programmer
- wishes to output several windows at once, a series of calls to
- wrefresh will result in alternating calls to wnoutrefresh() and
- doupdate(), causing several bursts of output to the screen. By
- calling wnoutrefresh() for each window, it is then possible to
- call doupdate() once, resulting in only one burst of output,
- with fewer total characters transmitted (this also avoids a
- visually annoying flicker at each update).
-
- Low-Level Capability Access
-
- setupterm(term, filenum, errret)
- This routine is called to initialize a terminal's description,
- without setting up the curses screen structures or changing the
- tty-driver mode bits. term is the character string representing
- the name of the terminal being used. filenum is the UNIX file
- descriptor of the terminal to be used for output. errret is a
- pointer to an integer, in which a success or failure indication
- is returned. The values returned can be 1 (all is well), 0 (no
- such terminal), or -1 (some problem locating the terminfo
- database).
-
- The value of term can be given as NULL, which will cause the
- value of TERM in the environment to be used. The errret pointer
- can also be given as NULL, meaning no error code is wanted. If
- errret is defaulted, and something goes wrong, setupterm() will
- print an appropriate error message and exit, rather than
- returning. Thus, a simple program can call setupterm(0, 1, 0)
- and not worry about initialization errors.
-
- After the call to setupterm(), the global variable cur_term is
- set to point to the current structure of terminal capabilities.
- By calling setupterm() for each terminal, and saving and
- restoring cur_term, it is possible for a program to use two or
- more terminals at once. Setupterm() also stores the names
- section of the terminal description in the global character
- array ttytype[]. Subsequent calls to setupterm() will overwrite
- this array, so you'll have to save it yourself if need be.
-
- Debugging
-
- 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
- generate a file called `trace' in the current working directory
- containing a report on the library's actions. Higher trace
- levels enable more detailed (and verbose) reporting -- see
- comments attached to TRACE_ defines in the curses.h file for
- details. (It is also possible to set a trace level by assigning
- a trace level value to the environment variable NCURSES_TRACE).
-
- _tracef()
- This function can be used to output your own debugging
- information. It is only available only if you link with
- -lncurses_g. It can be used the same way as printf(), only it
- outputs a newline after the end of arguments. The output goes
- to a file called trace in the current directory.
-
- Trace logs can be difficult to interpret due to the sheer volume of
- data dumped in them. There is a script called tracemunch included with
- the ncurses distribution that can alleviate this problem somewhat; it
- compacts long sequences of similar operations into more succinct
- single-line pseudo-operations. These pseudo-ops can be distinguished
- by the fact that they are named in capital letters.
-
-Hints, Tips, and Tricks
-
- The ncurses manual pages are a complete reference for this library. In
- the remainder of this document, we discuss various useful methods that
- may not be obvious from the manual page descriptions.
-
- Some Notes of Caution
-
- If you find yourself thinking you need to use noraw() or nocbreak(),
- think again and move carefully. It's probably better design to use
- getstr() or one of its relatives to simulate cooked mode. The noraw()
- and nocbreak() functions try to restore cooked mode, but they may end
- up clobbering some control bits set before you started your
- application. Also, they have always been poorly documented, and are
- likely to hurt your application's usability with other curses
- libraries.
-
- 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.
- Historically, curses support for overlapping windows has been weak,
- fragile, and poorly documented. The ncurses library is not yet an
- exception to this rule.
-
- 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
-
- Sometimes you will want to write a program that spends most of its
- time in screen mode, but occasionally returns to ordinary `cooked'
- mode. A common reason for this is to support shell-out. This behavior
- is simple to arrange in ncurses.
-
- To leave ncurses mode, call endwin() as you would if you were
- intending to terminate the program. This will take the screen back to
- cooked mode; you can do your shell-out. When you want to return to
- ncurses mode, simply call refresh() or doupdate(). This will repaint
- the screen.
-
- There is a boolean function, isendwin(), which code can use to test
- whether ncurses screen mode is active. It returns TRUE in the interval
- between an endwin() call and the following refresh(), FALSE otherwise.
-
- Here is some sample code for shellout:
- addstr("Shelling out...");
- def_prog_mode(); /* save current tty modes */
- endwin(); /* restore original tty modes */
- system("sh"); /* run shell */
- addstr("returned.\n"); /* prepare return message */
- refresh(); /* restore save modes, repaint screen */
-
- Using NCURSES under XTERM
-
- A resize operation in X sends SIGWINCH to the application running
- 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
- 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.
-
- 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
-
- 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 will have to specify a terminal type and a pair of
- file pointers; each call will return a screen reference, and stdscr
- will be set to the last one allocated. You will switch between screens
- with the set_term call. Note that you will also have to call
- def_shell_mode and def_prog_mode on each tty yourself.
-
- Testing for Terminal Capabilities
-
- Sometimes you may 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 do your testing.
-
- A particularly useful case of this often comes up when you want to
- test whether a given terminal type should be treated as `smart'
- (cursor-addressable) or `stupid'. The right way to test this is to see
- if 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 doesn't contain any control characters.
- Try to make attribute changes infrequent on your screens. Don't use
- the immedok() option!
-
- Special Features of NCURSES
-
- 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 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
-
- Despite our best efforts, there are some differences between ncurses
- and the (undocumented!) behavior of older curses implementations.
- These arise from ambiguities or omissions in the documentation of the
- API.
-
- Refresh of Overlapping Windows
-
- If you define two windows A and B that overlap, and then alternately
- scribble on and refresh them, the changes made to the overlapping
- region under historic curses versions were often not documented
- precisely.
-
- 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 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
- copies to the virtual screen. Some implementations do "change copy",
- copying down only locations in the window that have changed (or been
- marked changed with wtouchln() and friends). Some implementations do
- "entire copy", copying all window locations to the virtual screen
- whether or not they have changed.
-
- The ncurses library itself has not always been consistent on this
- score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy.
- Versions 1.8.6 and older, and versions 1.9.9 and newer, do change
- copy.
-
- For most commercial curses implementations, it is not documented and
- not known for sure (at least not to the ncurses maintainers) whether
- they do change copy or entire copy. We know that System V release 3
- curses has logic in it that looks like an attempt to do change copy,
- but the surrounding logic and data representations are sufficiently
- complex, and our knowledge sufficiently indirect, that it's hard to
- know whether this is reliable. It is not clear what the SVr4
- documentation and XSI standard intend. The XSI Curses standard barely
- mentions wnoutrefresh(); the SVr4 documents seem to be describing
- entire-copy, but it is possible with some effort and straining to read
- them the other way.
-
- It might therefore be unwise to rely on either behavior in programs
- that might have to be linked with other curses implementations.
- Instead, you can do an explicit touchwin() before the wnoutrefresh()
- call to guarantee an entire-contents copy anywhere.
-
- 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 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.
-
- Background Erase
-
- If you have been using a very old versions of ncurses (1.8.7 or older)
- you may be surprised by the behavior of the erase functions. In older
- versions, erased areas of a window were filled with a blank modified
- by the window's current attribute (as set by wattrset(), wattron(),
- wattroff() and friends).
-
- In newer versions, this is not so. Instead, the attribute of erased
- blanks is normal unless and until it is modified by the functions
- bkgdset() or wbkgdset().
-
- This change in behavior conforms ncurses to System V Release 4 and the
- XSI Curses standard.
-
-XSI Curses Conformance
-
- The ncurses library is intended to be base-level conformant with the
- XSI Curses standard from X/Open. Many extended-level features (in
- fact, almost all features not directly concerned with wide characters
- and internationalization) are also supported.
-
- One effect of XSI conformance is the change in behavior described
- under "Background Erase -- Compatibility with Old Versions".
-
- Also, ncurses meets the XSI requirement that every macro entry point
- have a corresponding function which may be linked (and will be
- prototype-checked) if the macro definition is disabled with #undef.
-
- The Panels Library
-
- The ncurses library by itself provides good support for screen
- displays in which the windows are tiled (non-overlapping). In the more
- general case that windows may overlap, you have to use a series of
- wnoutrefresh() calls followed by a doupdate(), and be careful about
- the order you do the window refreshes in. It has to be bottom-upwards,
- otherwise parts of windows that should be obscured will show through.
-
- When your interface design is such that windows may dive deeper into
- the visibility stack or pop to the top at runtime, the resulting
- book-keeping can be tedious and difficult to get right. Hence the
- panels library.
-
- The panel library first appeared in AT&T System V. The version
- 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
- argument. Note that they must also link the ncurses library with
- -lncurses. Many linkers are two-pass and will accept either order, but
- it is still good practice to put -lpanel first and -lncurses second.
-
-Overview of Panels
-
- A panel object is a window that is implicitly treated as part of a
- deck including all other panel objects. The deck has an implicit
- bottom-to-top visibility order. The panels library includes an update
- function (analogous to refresh()) that displays all panels in the deck
- in the proper order to resolve overlaps. The standard window, stdscr,
- is considered below all panels.
-
- Details on the panels functions are available in the man pages. We'll
- just hit the highlights here.
-
- You create a panel from a window by calling new_panel() on a window
- pointer. It then becomes the top of the deck. The panel's window is
- available as the value of panel_window() called with the panel pointer
- as argument.
-
- You can delete a panel (removing it from the deck) with del_panel.
- This will not deallocate the associated window; you have to do that
- yourself. You can replace a panel's window with a different window by
- calling replace_window. The new window may be of different size; the
- panel code will re-compute all overlaps. This operation doesn't change
- the panel's position in the deck.
-
- To move a panel's window, use move_panel(). The mvwin() function on
- the panel's window isn't sufficient because it doesn't update the
- panels library's representation of where the windows are. This
- operation leaves the panel's depth, contents, and size unchanged.
-
- Two functions (top_panel(), bottom_panel()) are provided for
- rearranging the deck. The first pops its argument window to the top of
- the deck; the second sends it to the bottom. Either operation leaves
- the panel's screen location, contents, and size unchanged.
-
- The function update_panels() does all the wnoutrefresh() calls needed
- to prepare for doupdate() (which you must call yourself, afterwards).
-
- Typically, you will want to call update_panels() and doupdate() just
- before accepting command input, once in each cycle of interaction with
- the user. If you call update_panels() after each and every panel
- write, you'll generate a lot of unnecessary refresh activity and
- screen flicker.
-
-Panels, Input, and the Standard Screen
-
- You shouldn't mix wnoutrefresh() or wrefresh() operations with panels
- code; this will work only if the argument window is either in the top
- panel or unobscured by any other panels.
-
- The stsdcr window is a special case. It is considered below all
- panels. Because changes to panels may obscure parts of stdscr, though,
- you should call update_panels() before doupdate() even when you only
- change stdscr.
-
- Note that wgetch automatically calls wrefresh. Therefore, before
- requesting input from a panel window, you need to be sure that the
- panel is totally unobscured.
-
- There is presently no way to display changes to one obscured panel
- without repainting all panels.
-
-Hiding Panels
-
- It's possible to remove a panel from the deck temporarily; use
- hide_panel for this. Use show_panel() to render it visible again. The
- predicate function panel_hidden tests whether or not a panel is
- hidden.
-
- The panel_update code ignores hidden panels. You cannot do top_panel()
- or bottom_panel on a hidden panel(). Other panels operations are
- applicable.
-
-Miscellaneous Other Facilities
-
- It's possible to navigate the deck using the functions panel_above()
- and panel_below. Handed a panel pointer, they return the panel above
- or below that panel. Handed NULL, they return the bottom-most or
- top-most panel.
-
- Every panel has an associated user pointer, not used by the panel
- code, to which you can attach application data. See the man page
- documentation of set_panel_userptr() and panel_userptr for details.
-
- The Menu Library
-
- A menu is a screen display that assists the user to choose some subset
- of a given set of items. The menu library is a curses extension that
- supports easy programming of menu hierarchies with a uniform but
- flexible interface.
-
- The menu library first appeared in AT&T System V. The version
- 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
- argument. Note that they must also link the ncurses library with
- -lncurses. Many linkers are two-pass and will accept either order, but
- it is still good practice to put -lmenu first and -lncurses second.
-
-Overview of Menus
-
- The menus created by this library consist of collections of items
- including a name string part and a description string part. To make
- menus, you create groups of these items and connect them with menu
- frame objects.
-
- The menu can then by posted, that is written to an associated window.
- Actually, each menu has two associated windows; a containing window in
- which the programmer can scribble titles or borders, and a subwindow
- in which the menu items proper are displayed. If this subwindow is too
- small to display all the items, it will be a scrollable viewport on
- the collection of items.
-
- A menu may also be unposted (that is, undisplayed), and finally freed
- to make the storage associated with it and its items available for
- re-use.
-
- The general flow of control of a menu program looks like this:
- 1. Initialize curses.
- 2. Create the menu items, using new_item().
- 3. Create the menu using new_menu().
- 4. Post the menu using post_menu().
- 5. Refresh the screen.
- 6. Process user requests via an input loop.
- 7. Unpost the menu using unpost_menu().
- 8. Free the menu, using free_menu().
- 9. Free the items using free_item().
- 10. Terminate curses.
-
-Selecting items
-
- Menus may be multi-valued or (the default) single-valued (see the
- manual page menu_opts(3x) to see how to change the default). Both
- types always have a current item.
-
- From a single-valued menu you can read the selected value simply by
- looking at the current item. From a multi-valued menu, you get the
- selected set by looping through the items applying the item_value()
- predicate function. Your menu-processing code can use the function
- set_item_value() to flag the items in the select set.
-
- Menu items can be made unselectable using set_item_opts() or
- item_opts_off() with the O_SELECTABLE argument. This is the only
- option so far defined for menus, but it is good practice to code as
- though other option bits might be on.
-
-Menu Display
-
- The menu library calculates a minimum display size for your window,
- based on the following variables:
- * The number and maximum length of the menu items
- * Whether the O_ROWMAJOR option is enabled
- * Whether display of descriptions is enabled
- * Whatever menu format may have been set by the programmer
- * The length of the menu mark string used for highlighting selected
- items
-
- The function set_menu_format() allows you to set the maximum size of
- the viewport or menu page that will be used to display menu items. You
- can retrieve any format associated with a menu with menu_format(). The
- default format is rows=16, columns=1.
-
- The actual menu page may be smaller than the format size. This depends
- on the item number and size and whether O_ROWMAJOR is on. This option
- (on by default) causes menu items to be displayed in a `raster-scan'
- pattern, so that if more than one item will fit horizontally the first
- couple of items are side-by-side in the top row. The alternative is
- column-major display, which tries to put the first several items in
- the first column.
-
- As mentioned above, a menu format not large enough to allow all items
- to fit on-screen will result in a menu display that is vertically
- scrollable.
-
- You can scroll it with requests to the menu driver, which will be
- described in the section on menu input handling.
-
- Each menu has a mark string used to visually tag selected items; see
- the menu_mark(3x) manual page for details. The mark string length also
- influences the menu page size.
-
- The function scale_menu() returns the minimum display size that the
- menu code computes from all these factors. There are other menu
- display attributes including a select attribute, an attribute for
- selectable items, an attribute for unselectable items, and a pad
- character used to separate item name text from description text. These
- have reasonable defaults which the library allows you to change (see
- the menu_attribs(3x) manual page.
-
-Menu Windows
-
- Each menu has, as mentioned previously, a pair of associated windows.
- Both these windows are painted when the menu is posted and erased when
- the menu is unposted.
-
- The outer or frame window is not otherwise touched by the menu
- routines. It exists so the programmer can associate a title, a border,
- or perhaps help text with the menu and have it properly refreshed or
- erased at post/unpost time. The inner window or subwindow is where the
- current menu page is displayed.
-
- By default, both windows are stdscr. You can set them with the
- functions in menu_win(3x).
-
- 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.
-
-Processing Menu Input
-
- The main loop of your menu-processing code should call menu_driver()
- repeatedly. The first argument of this routine is a menu pointer; the
- second is a menu command code. You should write an input-fetching
- routine that maps input characters to menu command codes, and pass its
- output to menu_driver(). The menu command codes are fully documented
- in menu_driver(3x).
-
- The simplest group of command codes is REQ_NEXT_ITEM, REQ_PREV_ITEM,
- REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_UP_ITEM, REQ_DOWN_ITEM,
- REQ_LEFT_ITEM, REQ_RIGHT_ITEM. These change the currently selected
- item. These requests may cause scrolling of the menu page if it only
- partially displayed.
-
- There are explicit requests for scrolling which also change the
- current item (because the select location does not change, but the
- item there does). These are REQ_SCR_DLINE, REQ_SCR_ULINE,
- REQ_SCR_DPAGE, and REQ_SCR_UPAGE.
-
- The REQ_TOGGLE_ITEM selects or deselects the current item. It is for
- use in multi-valued menus; if you use it with O_ONEVALUE on, you'll
- get an error return (E_REQUEST_DENIED).
-
- Each menu has an associated pattern buffer. The menu_driver() logic
- tries to accumulate printable ASCII characters passed in in that
- buffer; when it matches a prefix of an item name, that item (or the
- next matching item) is selected. If appending a character yields no
- new match, that character is deleted from the pattern buffer, and
- menu_driver() returns E_NO_MATCH.
-
- Some requests change the pattern buffer directly: REQ_CLEAR_PATTERN,
- REQ_BACK_PATTERN, REQ_NEXT_MATCH, REQ_PREV_MATCH. The latter two are
- useful when pattern buffer input matches more than one item in a
- multi-valued menu.
-
- Each successful scroll or item navigation request clears the pattern
- buffer. It is also possible to set the pattern buffer explicitly with
- set_menu_pattern().
-
- Finally, menu driver requests above the constant MAX_COMMAND are
- considered application-specific commands. The menu_driver() code
- ignores them and returns E_UNKNOWN_COMMAND.
-
-Miscellaneous Other Features
-
- Various menu options can affect the processing and visual appearance
- and input processing of menus. See menu_opts(3x) for details.
-
- It is possible to change the current item from application code; this
- is useful if you want to write your own navigation requests. It is
- also possible to explicitly set the top row of the menu display. See
- mitem_current(3x). If your application needs to change the menu
- subwindow cursor for any reason, pos_menu_cursor() will restore it to
- the correct location for continuing menu driver processing.
-
- It is possible to set hooks to be called at menu initialization and
- wrapup time, and whenever the selected item changes. See
- menu_hook(3x).
-
- Each item, and each menu, has an associated user pointer on which you
- can hang application data. See mitem_userptr(3x) and menu_userptr(3x).
-
- The Forms Library
-
- The form library is a curses extension that supports easy programming
- 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 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
- argument. Note that they must also link the ncurses library with
- -lncurses. Many linkers are two-pass and will accept either order, but
- it is still good practice to put -lform first and -lncurses second.
-
-Overview of Forms
-
- A form is a collection of fields; each field may be either a label
- (explanatory text) or a data-entry location. Long forms may be
- segmented into pages; each entry to a new page clears the screen.
-
- To make forms, you create groups of fields and connect them with form
- frame objects; the form library makes this relatively simple.
-
- Once defined, a form can be posted, that is written to an associated
- window. Actually, each form has two associated windows; a containing
- window in which the programmer can scribble titles or borders, and a
- subwindow in which the form fields proper are displayed.
-
- As the form user fills out the posted form, navigation and editing
- keys support movement between fields, editing keys support modifying
- field, and plain text adds to or changes data in a current field. The
- form library allows you (the forms designer) to bind each navigation
- and editing key to any keystroke accepted by curses Fields may have
- validation conditions on them, so that they check input data for type
- and value. The form library supplies a rich set of pre-defined field
- types, and makes it relatively easy to define new ones.
-
- Once its transaction is completed (or aborted), a form may be unposted
- (that is, undisplayed), and finally freed to make the storage
- associated with it and its items available for re-use.
-
- The general flow of control of a form program looks like this:
- 1. Initialize curses.
- 2. Create the form fields, using new_field().
- 3. Create the form using new_form().
- 4. Post the form using post_form().
- 5. Refresh the screen.
- 6. Process user requests via an input loop.
- 7. Unpost the form using unpost_form().
- 8. Free the form, using free_form().
- 9. Free the fields using free_field().
- 10. Terminate curses.
-
- Note that this looks much like a menu program; the form library
- handles tasks which are in many ways similar, and its interface was
- obviously designed to resemble that of the menu library wherever
- possible.
-
- In forms programs, however, the `process user requests' is somewhat
- more complicated than for menus. Besides menu-like navigation
- operations, the menu driver loop has to support field editing and data
- validation.
-
-Creating and Freeing Fields and Forms
-
- The basic function for creating fields is new_field():
-FIELD *new_field(int height, int width, /* new field size */
- int top, int left, /* upper left corner */
- int offscreen, /* number of offscreen rows */
- int nbuf); /* number of working buffers */
-
- Menu items always occupy a single row, but forms fields may have
- multiple rows. So new_field() requires you to specify a width and
- height (the first two arguments, which mist both be greater than
- zero).
-
- You must also specify the location of the field's upper left corner on
- 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_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
- nonzero, the form will be scrollable, with only one screen-full
- (initially the top part) displayed at any given time. If you make a
- field dynamic and grow it so it will no longer fit on the screen, the
- form will become scrollable even if the offscreen argument was
- initially zero.
-
- The forms library allocates one working buffer per field; the size of
- each buffer is ((height + offscreen)*width + 1, one character for each
- position in the field plus a NUL terminator. The sixth argument is the
- number of additional data buffers to allocate for the field; your
- application can use them for its own purposes.
-FIELD *dup_field(FIELD *field, /* field to copy */
- int top, int left); /* location of new copy */
-
- The function dup_field() duplicates an existing field at a new
- location. Size and buffering information are copied; some attribute
- flags and status bits are not (see the form_field_new(3X) for
- details).
-FIELD *link_field(FIELD *field, /* field to copy */
- int top, int left); /* location of new copy */
-
- The function link_field() also duplicates an existing field at a new
- location. The difference from dup_field() is that it arranges for the
- new field's buffer to be shared with the old one.
-
- Besides the obvious use in making a field editable from two different
- form pages, linked fields give you a way to hack in dynamic labels. If
- you declare several fields linked to an original, and then make them
- inactive, changes from the original will still be propagated to the
- linked fields.
-
- As with duplicated fields, linked fields have attribute bits separate
- from the original.
-
- As you might guess, all these field-allocations return NULL if the
- field allocation is not possible due to an out-of-memory error or
- out-of-bounds arguments.
-
- To connect fields to a form, use
-FORM *new_form(FIELD **fields);
-
- This function expects to see a NULL-terminated array of field
- pointers. Said fields are connected to a newly-allocated form object;
- its address is returned (or else NULL if the allocation fails).
-
- Note that new_field() does not copy the pointer array into private
- storage; if you modify the contents of the pointer array during forms
- processing, all manner of bizarre things might happen. Also note that
- any given field may only be connected to one form.
-
- The functions free_field() and free_form are available to free field
- and form objects. It is an error to attempt to free a field connected
- to a form, but not vice-versa; thus, you will generally free your form
- objects first.
-
-Fetching and Changing Field Attributes
-
- Each form field has a number of location and size attributes
- associated with it. There are other field attributes used to control
- display and editing of the field. Some (for example, the O_STATIC bit)
- involve sufficient complications to be covered in sections of their
- own later on. We cover the functions used to get and set several basic
- attributes here.
-
- When a field is created, the attributes not specified by the new_field
- function are copied from an invisible system default field. In
- attribute-setting and -fetching functions, the argument NULL is taken
- to mean this field. Changes to it persist as defaults until your forms
- application terminates.
-
- Fetching Size and Location Data
-
- You can retrieve field sizes and locations through:
-int field_info(FIELD *field, /* field from which to fetch */
- int *height, *int width, /* field size */
- int *top, int *left, /* upper left corner */
- int *offscreen, /* number of offscreen rows */
- int *nbuf); /* number of working buffers */
-
- This function is a sort of inverse of new_field(); instead of setting
- size and location attributes of a new field, it fetches them from an
- existing one.
-
- Changing the Field Location
-
- 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 */
-
- You can, of course. query the current location through field_info().
-
- The Justification Attribute
-
- One-line fields may be unjustified, justified right, justified left,
- or centered. Here is how you manipulate this attribute:
-int set_field_just(FIELD *field, /* field to alter */
- int justmode); /* mode to set */
-
-int field_just(FIELD *field); /* fetch mode of field */
-
- The mode values accepted and returned by this functions are
- preprocessor macros NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or
- JUSTIFY_CENTER.
-
- Field Display Attributes
-
- For each field, you can set a foreground attribute for entered
- characters, a background attribute for the entire field, and a pad
- character for the unfilled portion of the field. You can also control
- pagination of the form.
-
- This group of four field attributes controls the visual appearance of
- the field on the screen, without affecting in any way the data in the
- field buffer.
-int set_field_fore(FIELD *field, /* field to alter */
- chtype attr); /* attribute to set */
-
-chtype field_fore(FIELD *field); /* field to query */
-
-int set_field_back(FIELD *field, /* field to alter */
- chtype attr); /* attribute to set */
-
-chtype field_back(FIELD *field); /* field to query */
-
-int set_field_pad(FIELD *field, /* field to alter */
- int pad); /* pad character to set */
-
-chtype field_pad(FIELD *field);
-
-int set_new_page(FIELD *field, /* field to alter */
- int flag); /* TRUE to force new page */
-
-chtype new_page(FIELD *field); /* field to query */
-
- The attributes set and returned by the first four functions are normal
- curses(3x) display attribute values (A_STANDOUT, A_BOLD, A_REVERSE
- etc). The page bit of a field controls whether it is displayed at the
- start of a new form screen.
-
- Field Option Bits
-
- 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 */
-
-int field_opts_on(FIELD *field, /* field to alter */
- int attr); /* attributes to turn on */
-
-int field_opts_off(FIELD *field, /* field to alter */
- int attr); /* attributes to turn off */
-
-int field_opts(FIELD *field); /* field to query */
-
- By default, all options are on. Here are the available option bits:
-
- O_VISIBLE
- Controls whether the field is visible on the screen. Can be
- used during form processing to hide or pop up fields depending
- on the value of parent fields.
-
- O_ACTIVE
- Controls whether the field is active during forms processing
- (i.e. visited by form navigation keys). Can be used to make
- labels or derived fields with buffer values alterable by the
- forms application, not the user.
-
- O_PUBLIC
- Controls whether data is displayed during field entry. If this
- option is turned off on a field, the library will accept and
- edit data in that field, but it will not be displayed and the
- visible field cursor will not move. You can turn off the
- O_PUBLIC bit to define password fields.
-
- O_EDIT
- Controls whether the field's data can be modified. When this
- option is off, all editing requests except REQ_PREV_CHOICE and
- REQ_NEXT_CHOICE will fail. Such read-only fields may be useful
- for help messages.
-
- O_WRAP
- Controls word-wrapping in multi-line fields. Normally, when any
- character of a (blank-separated) word reaches the end of the
- current line, the entire word is wrapped to the next line
- (assuming there is one). When this option is off, the word will
- be split across the line break.
-
- O_BLANK
- Controls field blanking. When this option is on, entering a
- character at the first field position erases the entire field
- (except for the just-entered character).
-
- O_AUTOSKIP
- Controls automatic skip to next field when this one fills.
- Normally, when the forms user tries to type more data into a
- field than will fit, the editing location jumps to next field.
- When this option is off, the user's cursor will hang at the end
- of the field. This option is ignored in dynamic fields that
- have not reached their size limit.
-
- O_NULLOK
- Controls whether validation is applied to blank fields.
- Normally, it is not; the user can leave a field blank without
- invoking the usual validation check on exit. If this option is
- off on a field, exit from it will invoke a validation check.
-
- O_PASSOK
- Controls whether validation occurs on every exit, or only after
- the field is modified. Normally the latter is true. Setting
- O_PASSOK may be useful if your field's validation function may
- change during forms processing.
-
- O_STATIC
- Controls whether the field is fixed to its initial dimensions.
- If you turn this off, the field becomes dynamic and will
- stretch to fit entered data.
-
- A field's options cannot be changed while the field is currently
- selected. However, options may be changed on posted fields that are
- not current.
-
- The option values are bit-masks and can be composed with logical-or in
- the obvious way.
-
-Field Status
-
- Every field has a status flag, which is set to FALSE when the field is
- created and TRUE when the value in field buffer 0 changes. This flag
- can be queried and set directly:
-int set_field_status(FIELD *field, /* field to alter */
- int status); /* mode to set */
-
-int field_status(FIELD *field); /* fetch mode of field */
-
- Setting this flag under program control can be useful if you use the
- same form repeatedly, looking for modified fields each time.
-
- Calling field_status() on a field not currently selected for input
- will return a correct value. Calling field_status() on a field that is
- currently selected for input may not necessarily give a correct field
- status value, because entered data isn't necessarily copied to buffer
- zero before the exit validation check. To guarantee that the returned
- status value reflects reality, call field_status() either (1) in the
- field's exit validation check routine, (2) from the field's or form's
- initialization or termination hooks, or (3) just after a
- REQ_VALIDATION request has been processed by the forms driver.
-
-Field User Pointer
-
- 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 */
-
-char *field_userptr(FIELD *field); /* fetch mode of field */
-
- (Properly, this user pointer field ought to have (void *) type. The
- (char *) type is retained for System V compatibility.)
-
- It is valid to set the user pointer of the default field (with a
- set_field_userptr() call passed a NULL field pointer.) When a new
- field is created, the default-field user pointer is copied to
- initialize the new field's user pointer.
-
-Variable-Sized Fields
-
- Normally, a field is fixed at the size specified for it at creation
- time. If, however, you turn off its O_STATIC bit, it becomes dynamic
- and will automatically resize itself to accommodate data as it is
- entered. If the field has extra buffers associated with it, they will
- grow right along with the main input buffer.
-
- A one-line dynamic field will have a fixed height (1) but variable
- width, scrolling horizontally to display data within the field area as
- originally dimensioned and located. A multi-line dynamic field will
- have a fixed width, but variable height (number of rows), scrolling
- vertically to display data within the field area as originally
- dimensioned and located.
-
- Normally, a dynamic field is allowed to grow without limit. But it is
- possible to set an upper limit on the size of a dynamic field. You do
- it with this function:
-int set_max_field(FIELD *field, /* field to alter (may not be NULL) */
- int max_size); /* upper limit on field size */
-
- If the field is one-line, max_size is taken to be a column size limit;
- if it is multi-line, it is taken to be a line size limit. To disable
- any limit, use an argument of zero. The growth limit can be changed
- whether or not the O_STATIC bit is on, but has no effect until it is.
-
- The following properties of a field change when it becomes dynamic:
- * If there is no growth limit, there is no final position of the
- field; therefore O_AUTOSKIP and O_NL_OVERLOAD are ignored.
- * Field justification will be ignored (though whatever justification
- is set up will be retained internally and can be queried).
- * The dup_field() and link_field() calls copy dynamic-buffer sizes.
- If the O_STATIC option is set on one of a collection of links,
- buffer resizing will occur only when the field is edited through
- that link.
- * The call field_info() will retrieve the original static size of
- the field; use dynamic_field_info() to get the actual dynamic
- size.
-
-Field Validation
-
- By default, a field will accept any data that will fit in its input
- buffer. However, it is possible to attach a validation type to a
- field. If you do this, any attempt to leave the field while it
- contains data that doesn't match the validation type will fail. Some
- validation types also have a character-validity check for each time a
- character is entered in the field.
-
- A field's validation check (if any) is not called when
- set_field_buffer() modifies the input buffer, nor when that buffer is
- changed through a linked field.
-
- The form library provides a rich set of pre-defined validation types,
- and gives you the capability to define custom ones of your own. You
- can examine and change field validation attributes with the following
- functions:
-int set_field_type(FIELD *field, /* field to alter */
- FIELDTYPE *ftype, /* type to associate */
- ...); /* additional arguments*/
-
-FIELDTYPE *field_type(FIELD *field); /* field to query */
-
- The validation type of a field is considered an attribute of the
- field. As with other field attributes, Also, doing set_field_type()
- with a NULL field default will change the system default for
- validation of newly-created fields.
-
- Here are the pre-defined validation types:
-
- TYPE_ALPHA
-
- This field type accepts alphabetic data; no blanks, no digits, no
- special characters (this is checked at character-entry time). It is
- set up with:
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_ALPHA, /* type to associate */
- int width); /* maximum width of field */
-
- The width argument sets a minimum width of data. Typically you'll want
- to set this to the field width; if it's greater than the field width,
- the validation check will always fail. A minimum width of zero makes
- field completion optional.
-
- TYPE_ALNUM
-
- This field type accepts alphabetic data and digits; no blanks, no
- special characters (this is checked at character-entry time). It is
- set up with:
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_ALNUM, /* type to associate */
- int width); /* maximum width of field */
-
- The width argument sets a minimum width of data. As with TYPE_ALPHA,
- typically you'll want to set this to the field width; if it's greater
- than the field width, the validation check will always fail. A minimum
- width of zero makes field completion optional.
-
- TYPE_ENUM
-
- This type allows you to restrict a field's values to be among a
- specified set of string values (for example, the two-letter postal
- codes for U.S. states). It is set up with:
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_ENUM, /* type to associate */
- char **valuelist; /* list of possible values */
- int checkcase; /* case-sensitive? */
- int checkunique); /* must specify uniquely? */
-
- The valuelist parameter must point at a NULL-terminated list of valid
- strings. The checkcase argument, if true, makes comparison with the
- string case-sensitive.
-
- When the user exits a TYPE_ENUM field, the validation procedure tries
- to complete the data in the buffer to a valid entry. If a complete
- choice string has been entered, it is of course valid. But it is also
- possible to enter a prefix of a valid string and have it completed for
- you.
-
- By default, if you enter such a prefix and it matches more than one
- value in the string list, the prefix will be completed to the first
- matching value. But the checkunique argument, if true, requires prefix
- matches to be unique in order to be valid.
-
- The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be
- particularly useful with these fields.
-
- TYPE_INTEGER
-
- This field type accepts an integer. It is set up as follows:
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_INTEGER, /* type to associate */
- int padding, /* # places to zero-pad to */
- int vmin, int vmax); /* valid range */
-
- Valid characters consist of an optional leading minus and digits. The
- range check is performed on exit. If the range maximum is less than or
- equal to the minimum, the range is ignored.
-
- If the value passes its range check, it is padded with as many leading
- zero digits as necessary to meet the padding argument.
-
- A TYPE_INTEGER value buffer can conveniently be interpreted with the C
- library function atoi(3).
-
- TYPE_NUMERIC
-
- This field type accepts a decimal number. It is set up as follows:
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_NUMERIC, /* type to associate */
- int padding, /* # places of precision */
- double vmin, double vmax); /* valid range */
-
- Valid characters consist of an optional leading minus and digits.
- possibly including a decimal point. If your system supports locale's,
- the decimal point character used must be the one defined by your
- locale. The range check is performed on exit. If the range maximum is
- less than or equal to the minimum, the range is ignored.
-
- If the value passes its range check, it is padded with as many
- trailing zero digits as necessary to meet the padding argument.
-
- A TYPE_NUMERIC value buffer can conveniently be interpreted with the C
- library function atof(3).
-
- TYPE_REGEXP
-
- This field type accepts data matching a regular expression. It is set
- up as follows:
-int set_field_type(FIELD *field, /* field to alter */
- TYPE_REGEXP, /* type to associate */
- char *regexp); /* expression to match */
-
- The syntax for regular expressions is that of regcomp(3). The check
- for regular-expression match is performed on exit.
-
-Direct Field Buffer Manipulation
-
- The chief attribute of a field is its buffer contents. When a form has
- been completed, your application usually needs to know the state of
- each field buffer. You can find this out with:
-char *field_buffer(FIELD *field, /* field to query */
- int bufindex); /* number of buffer to query */
-
- Normally, the state of the zero-numbered buffer for each field is 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 */
-
- If the field is not large enough and cannot be resized to a
- sufficiently large size to contain the specified value, the value will
- be truncated to fit.
-
- Calling field_buffer() with a null field pointer will raise an error.
- Calling field_buffer() on a field not currently selected for input
- will return a correct value. Calling field_buffer() on a field that is
- currently selected for input may not necessarily give a correct field
- buffer value, because entered data isn't necessarily copied to buffer
- zero before the exit validation check. To guarantee that the returned
- buffer value reflects on-screen reality, call field_buffer() either
- (1) in the field's exit validation check routine, (2) from the field's
- or form's initialization or termination hooks, or (3) just after a
- REQ_VALIDATION request has been processed by the forms driver.
-
-Attributes of Forms
-
- As with field attributes, form attributes inherit a default from a
- system default form structure. These defaults can be queried or set by
- of these functions using a form-pointer argument of NULL.
-
- The principal attribute of a form is its field list. You can query and
- change this list with:
-int set_form_fields(FORM *form, /* form to alter */
- FIELD **fields); /* fields to connect */
-
-char *form_fields(FORM *form); /* fetch fields of form */
-
-int field_count(FORM *form); /* count connect fields */
-
- The second argument of set_form_fields() may be a NULL-terminated
- field pointer array like the one required by new_form(). In that case,
- the old fields of the form are disconnected but not freed (and
- eligible to be connected to other forms), then the new fields are
- connected.
-
- It may also be null, in which case the old fields are disconnected
- (and not freed) but no new ones are connected.
-
- The field_count() function simply counts the number of fields
- connected to a given from. It returns -1 if the form-pointer argument
- is NULL.
-
-Control of Form Display
-
- In the overview section, you saw that to display a form you normally
- start by defining its size (and fields), posting it, and refreshing
- the screen. There is an hidden step before posting, which is the
- association of the form with a frame window (actually, a pair of
- windows) within which it will be displayed. By default, the forms
- library associates every form with the full-screen window stdscr.
-
- By making this step explicit, you can associate a form with a declared
- frame window on your screen display. This can be useful if you want to
- adapt the form display to different screen sizes, dynamically tile
- forms on the screen, or use a form as part of an interface layout
- managed by panels.
-
- The two windows associated with each form have the same functions as
- their analogues in the menu library. Both these windows are painted
- when the form is posted and erased when the form is unposted.
-
- The outer or frame window is not otherwise touched by the form
- routines. It exists so the programmer can associate a title, a border,
- or perhaps help text with the form and have it properly refreshed or
- erased at post/unpost time. The inner window or subwindow is where the
- current form page is actually displayed.
-
- In order to declare your own frame window for a form, you'll need to
- know the size of the form's bounding rectangle. You can get this
- information with:
-int scale_form(FORM *form, /* form to query */
- int *rows, /* form rows */
- int *cols); /* form cols */
-
- 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 */
-
-WINDOW *form_win(FORM *form); /* fetch frame window of form */
-
-int set_form_sub(FORM *form, /* form to alter */
- WINDOW *win); /* form subwindow to connect */
-
-WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */
-
- Note that curses operations, including refresh(), on the form, should
- be done on the frame window, not the form subwindow.
-
- It is possible to check from your application whether all of a
- scrollable field is actually displayed within the menu subwindow. Use
- these functions:
-int data_ahead(FORM *form); /* form to be queried */
-
-int data_behind(FORM *form); /* form to be queried */
-
- The function data_ahead() returns TRUE if (a) the current field is
- one-line and has undisplayed data off to the right, (b) the current
- field is multi-line and there is data off-screen below it.
-
- The function data_behind() returns TRUE if the first (upper left hand)
- character position is off-screen (not being displayed).
-
- Finally, there is a function to restore the form window's cursor to
- the value expected by the forms driver:
-int pos_form_cursor(FORM *) /* form to be queried */
-
- If your application changes the form window cursor, call this function
- before handing control back to the forms driver in order to
- re-synchronize it.
-
-Input Processing in the Forms Driver
-
- The function form_driver() handles virtualized input requests for form
- navigation, editing, and validation requests, just as menu_driver does
- for menus (see the section on menu input handling).
-int form_driver(FORM *form, /* form to pass input to */
- int request); /* form request code */
-
- Your input virtualization function needs to take input and then
- convert it to either an alphanumeric character (which is treated as
- data to be entered in the currently-selected field), or a forms
- processing request.
-
- The forms driver provides hooks (through input-validation and
- field-termination functions) with which your application code can
- check that the input taken by the driver matched what was expected.
-
- Page Navigation Requests
-
- These requests cause page-level moves through the form, triggering
- display of a new form screen.
-
- REQ_NEXT_PAGE
- Move to the next form page.
-
- REQ_PREV_PAGE
- Move to the previous form page.
-
- REQ_FIRST_PAGE
- Move to the first form page.
-
- REQ_LAST_PAGE
- Move to the last form page.
-
- These requests treat the list as cyclic; that is, REQ_NEXT_PAGE from
- the last page goes to the first, and REQ_PREV_PAGE from the first page
- goes to the last.
-
- Inter-Field Navigation Requests
-
- These requests handle navigation between fields on the same page.
-
- REQ_NEXT_FIELD
- Move to next field.
-
- REQ_PREV_FIELD
- Move to previous field.
-
- REQ_FIRST_FIELD
- Move to the first field.
-
- REQ_LAST_FIELD
- Move to the last field.
-
- REQ_SNEXT_FIELD
- Move to sorted next field.
-
- REQ_SPREV_FIELD
- Move to sorted previous field.
-
- REQ_SFIRST_FIELD
- Move to the sorted first field.
-
- REQ_SLAST_FIELD
- Move to the sorted last field.
-
- REQ_LEFT_FIELD
- Move left to field.
-
- REQ_RIGHT_FIELD
- Move right to field.
-
- REQ_UP_FIELD
- Move up to field.
-
- REQ_DOWN_FIELD
- Move down to field.
-
- These requests treat the list of fields on a page as cyclic; that is,
- REQ_NEXT_FIELD from the last field goes to the first, and
- REQ_PREV_FIELD from the first field goes to the last. The order of the
- fields for these (and the REQ_FIRST_FIELD and REQ_LAST_FIELD requests)
- is simply the order of the field pointers in the form array (as set up
- by new_form() or set_form_fields()
-
- It is also possible to traverse the fields as if they had been sorted
- in screen-position order, so the sequence goes left-to-right and
- top-to-bottom. To do this, use the second group of four
- sorted-movement requests.
-
- Finally, it is possible to move between fields using visual directions
- up, down, right, and left. To accomplish this, use the third group of
- four requests. Note, however, that the position of a form for purposes
- of these requests is its upper-left corner.
-
- For example, suppose you have a multi-line field B, and two
- single-line fields A and C on the same line with B, with A to the left
- of B and C to the right of B. A REQ_MOVE_RIGHT from A will go to B
- only if A, B, and C all share the same first line; otherwise it will
- skip over B to C.
-
- Intra-Field Navigation Requests
-
- These requests drive movement of the edit cursor within the currently
- selected field.
-
- REQ_NEXT_CHAR
- Move to next character.
-
- REQ_PREV_CHAR
- Move to previous character.
-
- REQ_NEXT_LINE
- Move to next line.
-
- REQ_PREV_LINE
- Move to previous line.
-
- REQ_NEXT_WORD
- Move to next word.
-
- REQ_PREV_WORD
- Move to previous word.
-
- REQ_BEG_FIELD
- Move to beginning of field.
-
- REQ_END_FIELD
- Move to end of field.
-
- REQ_BEG_LINE
- Move to beginning of line.
-
- REQ_END_LINE
- Move to end of line.
-
- REQ_LEFT_CHAR
- Move left in field.
-
- REQ_RIGHT_CHAR
- Move right in field.
-
- REQ_UP_CHAR
- Move up in field.
-
- REQ_DOWN_CHAR
- Move down in field.
-
- Each word is separated from the previous and next characters by
- whitespace. The commands to move to beginning and end of line or field
- look for the first or last non-pad character in their ranges.
-
- Scrolling Requests
-
- Fields that are dynamic and have grown and fields explicitly created
- with offscreen rows are scrollable. One-line fields scroll
- horizontally; multi-line fields scroll vertically. Most scrolling is
- triggered by editing and intra-field movement (the library scrolls the
- field to keep the cursor visible). It is possible to explicitly
- request scrolling with the following requests:
-
- REQ_SCR_FLINE
- Scroll vertically forward a line.
-
- REQ_SCR_BLINE
- Scroll vertically backward a line.
-
- REQ_SCR_FPAGE
- Scroll vertically forward a page.
-
- REQ_SCR_BPAGE
- Scroll vertically backward a page.
-
- REQ_SCR_FHPAGE
- Scroll vertically forward half a page.
-
- REQ_SCR_BHPAGE
- Scroll vertically backward half a page.
-
- REQ_SCR_FCHAR
- Scroll horizontally forward a character.
-
- REQ_SCR_BCHAR
- Scroll horizontally backward a character.
-
- REQ_SCR_HFLINE
- Scroll horizontally one field width forward.
-
- REQ_SCR_HBLINE
- Scroll horizontally one field width backward.
-
- REQ_SCR_HFHALF
- Scroll horizontally one half field width forward.
-
- REQ_SCR_HBHALF
- Scroll horizontally one half field width backward.
-
- For scrolling purposes, a page of a field is the height of its visible
- part.
-
- Editing Requests
-
- When you pass the forms driver an ASCII character, it is treated as a
- request to add the character to the field's data buffer. Whether this
- is an insertion or a replacement depends on the field's edit mode
- (insertion is the default.
-
- The following requests support editing the field and changing the edit
- mode:
-
- REQ_INS_MODE
- Set insertion mode.
-
- REQ_OVL_MODE
- Set overlay mode.
-
- REQ_NEW_LINE
- New line request (see below for explanation).
-
- REQ_INS_CHAR
- Insert space at character location.
-
- REQ_INS_LINE
- Insert blank line at character location.
-
- REQ_DEL_CHAR
- Delete character at cursor.
-
- REQ_DEL_PREV
- Delete previous word at cursor.
-
- REQ_DEL_LINE
- Delete line at cursor.
-
- REQ_DEL_WORD
- Delete word at cursor.
-
- REQ_CLR_EOL
- Clear to end of line.
-
- REQ_CLR_EOF
- Clear to end of field.
-
- REQ_CLEAR_FIELD
- Clear entire field.
-
- The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is
- complicated and partly controlled by a pair of forms options. The
- special cases are triggered when the cursor is at the beginning of a
- field, or on the last line of the field.
-
- First, we consider REQ_NEW_LINE:
-
- The normal behavior of REQ_NEW_LINE in insert mode is to break the
- current line at the position of the edit cursor, inserting the portion
- of the current line after the cursor as a new line following the
- current and moving the cursor to the beginning of that new line (you
- may think of this as inserting a newline in the field buffer).
-
- The normal behavior of REQ_NEW_LINE in overlay mode is to clear the
- current line from the position of the edit cursor to end of line. The
- cursor is then moved to the beginning of the next line.
-
- However, REQ_NEW_LINE at the beginning of a field, or on the last line
- of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD option is
- off, this special action is disabled.
-
- Now, let us consider REQ_DEL_PREV:
-
- The normal behavior of REQ_DEL_PREV is to delete the previous
- character. If insert mode is on, and the cursor is at the start of a
- line, and the text on that line will fit on the previous one, it
- instead appends the contents of the current line to the previous one
- and deletes the current line (you may think of this as deleting a
- newline from the field buffer).
-
- However, REQ_DEL_PREV at the beginning of a field is instead treated
- as a REQ_PREV_FIELD.
-
- If the O_BS_OVERLOAD option is off, this special action is disabled
- and the forms driver just returns E_REQUEST_DENIED.
-
- See Form Options for discussion of how to set and clear the overload
- options.
-
- Order Requests
-
- If the type of your field is ordered, and has associated functions for
- getting the next and previous values of the type from a given value,
- there are requests that can fetch that value into the field buffer:
-
- REQ_NEXT_CHOICE
- Place the successor value of the current value in the buffer.
-
- REQ_PREV_CHOICE
- Place the predecessor value of the current value in the buffer.
-
- Of the built-in field types, only TYPE_ENUM has built-in successor and
- predecessor functions. When you define a field type of your own (see
- Custom Validation Types), you can associate our own ordering
- functions.
-
- Application Commands
-
- Form requests are represented as integers above the curses value
- greater than KEY_MAX and less than or equal to the constant
- MAX_COMMAND. If your input-virtualization routine returns a value
- above MAX_COMMAND, the forms driver will ignore it.
-
-Field Change Hooks
-
- It is possible to set function hooks to be executed whenever the
- current field or form changes. Here are the functions that support
- this:
-typedef void (*HOOK)(); /* pointer to function returning void */
-
-int set_form_init(FORM *form, /* form to alter */
- HOOK hook); /* initialization hook */
-
-HOOK form_init(FORM *form); /* form to query */
-
-int set_form_term(FORM *form, /* form to alter */
- HOOK hook); /* termination hook */
-
-HOOK form_term(FORM *form); /* form to query */
-
-int set_field_init(FORM *form, /* form to alter */
- HOOK hook); /* initialization hook */
-
-HOOK field_init(FORM *form); /* form to query */
-
-int set_field_term(FORM *form, /* form to alter */
- HOOK hook); /* termination hook */
-
-HOOK field_term(FORM *form); /* form to query */
-
- These functions allow you to either set or query four different hooks.
- In each of the set functions, the second argument should be the
- address of a hook function. These functions differ only in the timing
- of the hook call.
-
- form_init
- This hook is called when the form is posted; also, just after
- each page change operation.
-
- field_init
- This hook is called when the form is posted; also, just after
- each field change
-
- field_term
- This hook is called just after field validation; that is, just
- before the field is altered. It is also called when the form is
- unposted.
-
- form_term
- This hook is called when the form is unposted; also, just
- before each page change operation.
-
- Calls to these hooks may be triggered
- 1. When user editing requests are processed by the forms driver
- 2. When the current page is changed by set_current_field() call
- 3. When the current field is changed by a set_form_page() call
-
- See Field Change Commands for discussion of the latter two cases.
-
- You can set a default hook for all fields by passing one of the set
- functions a NULL first argument.
-
- You can disable any of these hooks by (re)setting them to NULL, the
- default value.
-
-Field Change Commands
-
- Normally, navigation through the form will be driven by the user's
- input requests. But sometimes it is useful to be able to move the
- focus for editing and viewing under control of your application, or
- ask which field it currently is in. The following functions help you
- accomplish this:
-int set_current_field(FORM *form, /* form to alter */
- FIELD *field); /* field to shift to */
-
-FIELD *current_field(FORM *form); /* form to query */
-
-int field_index(FORM *form, /* form to query */
- FIELD *field); /* field to get index of */
-
- The function field_index() returns the index of the given field in the
- given form's field array (the array passed to new_form() or
- set_form_fields()).
-
- The initial current field of a form is the first active field on the
- first page. The function set_form_fields() resets this.
-
- It is also possible to move around by pages.
-int set_form_page(FORM *form, /* form to alter */
- int page); /* page to go to (0-origin) */
-
-int form_page(FORM *form); /* return form's current page */
-
- The initial page of a newly-created form is 0. The function
- set_form_fields() resets this.
-
-Form Options
-
- Like fields, forms may have control option bits. They can be changed
- or queried with these functions:
-int set_form_opts(FORM *form, /* form to alter */
- int attr); /* attribute to set */
-
-int form_opts_on(FORM *form, /* form to alter */
- int attr); /* attributes to turn on */
-
-int form_opts_off(FORM *form, /* form to alter */
- int attr); /* attributes to turn off */
-
-int form_opts(FORM *form); /* form to query */
-
- By default, all options are on. Here are the available option bits:
-
- O_NL_OVERLOAD
- Enable overloading of REQ_NEW_LINE as described in Editing
- Requests. The value of this option is ignored on dynamic fields
- that have not reached their size limit; these have no last
- line, so the circumstances for triggering a REQ_NEXT_FIELD
- never arise.
-
- O_BS_OVERLOAD
- Enable overloading of REQ_DEL_PREV as described in Editing
- Requests.
-
- The option values are bit-masks and can be composed with logical-or in
- the obvious way.
-
-Custom Validation Types
-
- The form library gives you the capability to define custom validation
- types of your own. Further, the optional additional arguments of
- set_field_type effectively allow you to parameterize validation types.
- Most of the complications in the validation-type interface have to do
- with the handling of the additional arguments within custom validation
- functions.
-
- Union Types
-
- The simplest way to create a custom data type is to compose it from
- two preexisting ones:
-FIELD *link_fieldtype(FIELDTYPE *type1,
- FIELDTYPE *type2);
-
- This function creates a field type that will accept any of the values
- legal for either of its argument field types (which may be either
- predefined or programmer-defined). If a set_field_type() call later
- requires arguments, the new composite type expects all arguments for
- the first type, than all arguments for the second. Order functions
- (see Order Requests) associated with the component types will work on
- the composite; what it does is check the validation function for the
- first type, then for the second, to figure what type the buffer
- contents should be treated as.
-
- New Field Types
-
- To create a field type from scratch, you need to specify one or both
- of the following things:
- * A character-validation function, to check each character as it is
- entered.
- * A field-validation function to be applied on exit from the field.
-
- Here's how you do that:
-typedef int (*HOOK)(); /* pointer to function returning int */
-
-FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */
- HOOK c_validate) /* character validator */
-
-
-int free_fieldtype(FIELDTYPE *ftype); /* type to free */
-
- At least one of the arguments of new_fieldtype() must be non-NULL. The
- forms driver will automatically call the new type's validation
- functions at appropriate points in processing a field of the new type.
-
- The function free_fieldtype() deallocates the argument fieldtype,
- freeing all storage associated with it.
-
- Normally, a field validator is called when the user attempts to leave
- the field. Its first argument is a field pointer, from which it can
- get to field buffer 0 and test it. If the function returns TRUE, the
- operation succeeds; if it returns FALSE, the edit cursor stays in the
- field.
-
- A character validator gets the character passed in as a first
- argument. It too should return TRUE if the character is valid, FALSE
- otherwise.
-
- Validation Function Arguments
-
- Your field- and character- validation functions will be passed a
- second argument as well. This second argument is the address of a
- structure (which we'll call a pile) built from any of the
- field-type-specific arguments passed to set_field_type(). If no such
- arguments are defined for the field type, this pile pointer argument
- will be NULL.
-
- In order to arrange for such arguments to be passed to your validation
- functions, you must associate a small set of storage-management
- functions with the type. The forms driver will use these to synthesize
- a pile from the trailing arguments of each set_field_type() argument,
- and a pointer to the pile will be passed to the validation functions.
-
- Here is how you make the association:
-typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */
-typedef void (*VOIDHOOK)(); /* pointer to function returning void */
-
-int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */
- PTRHOOK make_str, /* make structure from args */
- PTRHOOK copy_str, /* make copy of structure */
- VOIDHOOK free_str); /* free structure storage */
-
- Here is how the storage-management hooks are used:
-
- make_str
- This function is called by set_field_type(). It gets one
- argument, a va_list of the type-specific arguments passed to
- set_field_type(). It is expected to return a pile pointer to a
- data structure that encapsulates those arguments.
-
- copy_str
- This function is called by form library functions that allocate
- new field instances. It is expected to take a pile pointer,
- copy the pile to allocated storage, and return the address of
- the pile copy.
-
- free_str
- This function is called by field- and type-deallocation
- routines in the library. It takes a pile pointer argument, and
- is expected to free the storage of that pile.
-
- The make_str and copy_str functions may return NULL to signal
- allocation failure. The library routines will that call them will
- return error indication when this happens. Thus, your validation
- functions should never see a NULL file pointer and need not check
- specially for it.
-
- Order Functions For Custom Types
-
- Some custom field types are simply ordered in the same well-defined
- way that TYPE_ENUM is. For such types, it is possible to define
- successor and predecessor functions to support the REQ_NEXT_CHOICE and
- REQ_PREV_CHOICE requests. Here's how:
-typedef int (*INTHOOK)(); /* pointer to function returning int */
-
-int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */
- INTHOOK succ, /* get successor value */
- INTHOOK pred); /* get predecessor value */
-
- The successor and predecessor arguments will each be passed two
- arguments; a field pointer, and a pile pointer (as for the validation
- functions). They are expected to use the function field_buffer() to
- read the current value, and set_field_buffer() on buffer 0 to set the
- next or previous value. Either hook may return TRUE to indicate
- success (a legal next or previous value was set) or FALSE to indicate
- failure.
-
- Avoiding Problems
-
- The interface for defining custom types is complicated and tricky.
- Rather than attempting to create a custom type entirely from scratch,
- you should start by studying the library source code for whichever of
- the pre-defined types seems to be closest to what you want.
-
- Use that code as a model, and evolve it towards what you really want.
- You will avoid many problems and annoyances that way. The code in the
- ncurses library has been specifically exempted from the package
- copyright to support this.
-
- If your custom type defines order functions, have do something
- intuitive with a blank field. A useful convention is to make the
- successor of a blank field the types minimum value, and its
- predecessor the maximum.