diff options
| author | Todd C. Miller <millert@cvs.openbsd.org> | 1999-01-18 19:25:58 +0000 |
|---|---|---|
| committer | Todd C. Miller <millert@cvs.openbsd.org> | 1999-01-18 19:25:58 +0000 |
| commit | 5861cd0870348bb21c127f1e8a25582f485018a5 (patch) | |
| tree | 2b15b140b9df7713d4d92e8a56695522cf542b36 /lib | |
| parent | 2ab6a45cb794e8f5ff7b3d8c9fe25b0ef0f5b669 (diff) | |
ncurses docs in html
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/libcurses/doc/Makefile | 14 | ||||
| -rw-r--r-- | lib/libcurses/doc/hackguide.html | 883 | ||||
| -rw-r--r-- | lib/libcurses/doc/ncurses-intro.html | 2682 |
3 files changed, 3579 insertions, 0 deletions
diff --git a/lib/libcurses/doc/Makefile b/lib/libcurses/doc/Makefile new file mode 100644 index 00000000000..38c3bcc5a99 --- /dev/null +++ b/lib/libcurses/doc/Makefile @@ -0,0 +1,14 @@ +# $OpenBSD: Makefile,v 1.1 1999/01/18 19:25:56 millert Exp $ + +FILES= hackguide.html ncurses-intro.html + +all: + @echo nothing to do + +install: + for f in ${FILES}; do \ + ${INSTALL} ${INSTALL_COPY} -m 444 -o $(BINOWN) -g $(BINGRP) \ + ${.CURDIR}/$$f ${DESTDIR}/usr/share/doc/html/curses/$$f; \ + done + +.include <bsd.own.mk> diff --git a/lib/libcurses/doc/hackguide.html b/lib/libcurses/doc/hackguide.html new file mode 100644 index 00000000000..aa010f393db --- /dev/null +++ b/lib/libcurses/doc/hackguide.html @@ -0,0 +1,883 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN"> +<!-- + $Id: hackguide.html,v 1.1 1999/01/18 19:25:56 millert Exp $ +--> +<HTML> +<HEAD> +<TITLE>A Hacker's Guide to Ncurses Internals</TITLE> +<link rev="made" href="mailto:bugs-ncurses@gnu.org"> +<!-- +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> +<P> +<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><UL> +</UL> +<LI><A HREF="#documentation">Documentation Conventions</A> +<P> +<LI><A HREF="#bugtrack">How to Report Bugs</A> +<P> +<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> +<P> +<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> +<P> +<LI><A HREF="#style">Style Tips for Developers</A> +<P> +<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. <P> + +<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: <P> + +<UL> +<LI>Source-compatible with historical curses implementations (including + the original BSD curses and System V curses. +<P> +<LI>Conformant with the XSI Curses standard issued as part of XPG4 by + X/Open. +<P> +<LI>High-quality -- stable and reliable code, wide portability, good + packaging, superior documentation. +<P> +<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. <P> + +<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. <P> + +<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. <P> + +<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: <P> + +<UL> +<LI>All such code is properly conditioned so the build process does not + attempt to compile it under a plain ANSI/POSIX environment. +<P> +<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. <P> + +<H1><A NAME="documentation">Documentation Conventions</A></H1> + +There are three kinds of documentation associated with this package. Each +has a different preferred format: <P> + +<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: <P> +<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. <P> + +<LI><STRONG>Mark up manual pages in the man macros.</STRONG> These have to be viewable + through traditional <EM>man(1)</EM> programs. <P> + +<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.<P> + +<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 <name>@<host.domain> +</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. <P> + +<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.) <P> + +<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. <P> + +<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. <P> + +<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> + +There's one other interactive tester, <CODE>tctest</CODE>, that exercises +translation between termcap and terminfo formats. If you have a serious +need to run this, you probably belong on our development team! <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 +</blockquote></code> +It is rather unlikely you will ever need to change these, unless +you want to introduce a new debug trace level for some reasoon.<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. +</blockquote></code> +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 +</blockquote></code> +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 +</blockquote></code> +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 +</blockquote></code> +We'll discuss these in the compiler tour. <P> + +<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. <P> + +<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). <P> + +<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 posible. <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. <P> + +<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>. <P> + +<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". <P> + +<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>. <P> + +<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. <P> + +<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.<P> + +<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. <P> + +<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! <P> + +<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. <P> + +<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 +</blockquote></code> +<P> + +This module is pure curses, but calls outstr(): <P> + +<blockquote><code> +lib_getstr.c +</blockquote></code> +<P> + +These modules are pure curses, except that they use <CODE>tputs()</CODE> +and <CODE>putp()</CODE>: <P> + +<blockquote><code> +lib_beep.c +lib_color.c +lib_endwin.c +lib_options.c +lib_slk.c +lib_vidattr.c +</blockquote></code> +<P> + +This modules assist in POSIX emulation on non-POSIX systems: <P> +<DL> +<DT> sigaction.c +<DD> signal calls +</DL> + +The following source files will not be needed for a +single-terminal-type port. <P> + +<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 +</blockquote></code> +<P> + +The following modules will use open()/read()/write()/close()/lseek() on files, +but no other OS calls. <P> + +<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. <P> + +<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 <esr@snark.thyrsus.com></ADDRESS> +(Note: This is <EM>not</EM> the <A HREF="#bugtrack">bug address</A>!) +</BODY> +</HTML> diff --git a/lib/libcurses/doc/ncurses-intro.html b/lib/libcurses/doc/ncurses-intro.html new file mode 100644 index 00000000000..b4d14538ad1 --- /dev/null +++ b/lib/libcurses/doc/ncurses-intro.html @@ -0,0 +1,2682 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN"> +<!-- + $Id: ncurses-intro.html,v 1.1 1999/01/18 19:25:57 millert Exp $ +--> +<HTML> +<HEAD> +<TITLE>Writing Programs with NCURSES</TITLE> +<link rev="made" href="mailto:bugs-ncurses@gnu.org"> +</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. <P> + +<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&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.<P> + +<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: <P> +<UL> +<LI>Support for multiple screen highlights (BSD curses could only +handle one `standout' highlight, usually reverse-video). <P> +<LI>Support for line- and box-drawing using forms characters. <P> +<LI>Recognition of function keys on input. <P> +<LI>Color support. <P> +<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> +<zmbenhal@netcom.com>. +<A HREF="mailto:esr@snark.thyrsus.com">Eric S. Raymond</A> +<esr@snark.thyrsus.com> +wrote many of the new features in versions after 1.8.1 +and wrote most of this introduction. +<A HREF="mailto:Juergen.Pfeifer@T-Online.de">Jürgen Pfeifer</A> +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@clark.net">Thomas Dickey</A> +and +<A HREF="mailto:Juergen.Pfeifer@T-Online.de">Jürgen Pfeifer</A>. +<A HREF="mailto:florian@gnu.org">Florian La Roche</A> +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> + +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. <P> + + +<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. <P> +<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. <P> +<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 <curses.h> +</PRE> + +at the top of the program source. The screen package uses the Standard I/O +library, so <CODE><curses.h></CODE> includes +<CODE><stdio.h></CODE>. <CODE><curses.h></CODE> also includes +<CODE><termios.h></CODE>, <CODE><termio.h></CODE>, or +<CODE><sgtty.h></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. <P> + +<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. <P> + +<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: <P> + +<PRE> +#include <curses.h> +#include <signal.h> + +static void finish(int sig); + +main(int argc, char *argv[]) +{ + /* 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) noecho(); /* don't echo input */ + + if (has_colors()) + { + start_color(); + + /* + * Simple color assignment, often all we need. + */ + init_pair(COLOR_BLACK, COLOR_BLACK, COLOR_BLACK); + init_pair(COLOR_GREEN, COLOR_GREEN, COLOR_BLACK); + init_pair(COLOR_RED, COLOR_RED, COLOR_BLACK); + init_pair(COLOR_CYAN, COLOR_CYAN, COLOR_BLACK); + init_pair(COLOR_WHITE, COLOR_WHITE, COLOR_BLACK); + init_pair(COLOR_MAGENTA, COLOR_MAGENTA, COLOR_BLACK); + init_pair(COLOR_BLUE, COLOR_BLUE, COLOR_BLACK); + init_pair(COLOR_YELLOW, COLOR_YELLOW, COLOR_BLACK); + } + + for (;;) + { + int c = getch(); /* refresh, accept single keystroke of input */ + + /* 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. <P> + +<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. <P> + +<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. <P> + +<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. <P> + +<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. <P> + +<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>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. <P> + +<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. <P> + +<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>ripofflines()</CODE>, <CODE>use_env()</CODE>, and, if you are using multiple +terminals, <CODE>newterm()</CODE>.) <P> +<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. <P> +<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. 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. <P> +<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. <P> +<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. <P> +<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.<P> + +<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. <P> + +<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. <P> + +<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 SIGWINCH to the application running under xterm. +The <CODE>ncurses</CODE> library provides an experimental signal +handler, but in general does not catch this signal, because it cannot +know how you want the screen re-painted. You will usually have to write the +SIGWINCH handler yourself. Ncurses can give you some help. <P> + +The easiest way to code your SIGWINCH handler is to have it 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> + +Finally, ncurses can be configured to provide its own SIGWINCH handler, +based on <CODE>resizeterm</CODE>. + +<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. <P> + +<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>. <P> + +<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! <P> + +<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 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>wnoutrfresh()</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. <P> + +<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. <P> + +<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>. <P> + +<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&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 <panel.h> +</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. <P> + +<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. <P> + +<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. <P> + +<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. <P> + +<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&T System V. The +version documented here is the <CODE>menu</CODE> code distributed +with <CODE>ncurses</CODE>. <P> + +<H2><A NAME="mcompile">Compiling With the menu Library</A></H2> + +Your menu-using modules must import the menu library declarations with + +<PRE> + #include <menu.h> +</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>menu_post()</CODE>. +<LI>Refresh the screen. +<LI>Process user requests via an input loop. +<LI>Unpost the menu using <CODE>menu_unpost()</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. <P> + +<H2><A NAME="mdisplay">Menu Display</A></H2> + +The menu library calculates a minimum display size for your window, based +on the following variables: <P> + +<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. <P> + +<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>menu_post()</CODE>, you write the menu to its +subwindow. When you call <CODE>menu_unpost()</CODE>, you erase the +subwindow, However, neither of these actually modifies the screen. To +do that, call <CODE>wrefresh()</CODE> or some equivalent. <P> + +<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>. <P> + +<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&T System V. The +version documented here is the <CODE>form</CODE> code distributed +with <CODE>ncurses</CODE>. <P> + +<H2><A NAME="fcompile">Compiling With the form Library</A></H2> + +Your form-using modules must import the form library declarations with + +<PRE> + #include <form.h> +</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. <P> + +<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>form_post()</CODE>. +<LI>Refresh the screen. +<LI>Process user requests via an input loop. +<LI>Unpost the form using <CODE>form_unpost()</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. <P> + +<H2><A NAME="fcreate">Creating and Freeing Fields and Forms</A></H2> + +The basic function for creating fields is <CODE>new_field()</CODE>: <P> + +<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_window()</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. <P> + +<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). <P> + +<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 <P> + +<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. <P> + +<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. <P> + +<H3><A NAME="fsizes">Fetching Size and Location Data</A></H3> + +You can retrieve field sizes and locations through: <P> + +<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. <P> + +<H3><A NAME="flocation">Changing the Field Location</A></H3> + +It is possible to move a field's location on the screen: <P> + +<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: <P> + +<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>. <P> + +<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. <P> + +<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. <P> + +<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. <P> + +<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: <P> + +<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. <P> + +<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. <P> + +<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: <P> + +<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: <P> + +<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: <P> + +<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: <P> + +<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. <P> + +<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: <P> + +<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. <P> + +<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: <P> + +<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. <P> + +<H3><A NAME="ftype_integer">TYPE_INTEGER</A></H3> + +This field type accepts an integer. It is set up as follows: <P> + +<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: <P> + +<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: <P> + +<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: <P> + +<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. <P> + +<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: <P> + +<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. <P> + +<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: <P> + +<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: <P> + +<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: <P> + +<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. <P> + +<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>). <P> + +<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. <P> + +<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. <P> + +<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. <P> + +<H3><A NAME="#ffield">Inter-Field Navigation Requests</A></H3> + +These requests handle navigation between fields on the same page. <P> + +<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. +<P> +<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. +<P> +<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. <P> + +<H3><A NAME="#fifield">Intra-Field Navigation Requests</A></H3> + +These requests drive movement of the edit cursor within the currently +selected field. <P> + +<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. <P> + +<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: +<P> + +<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. <P> + +<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: <P> + +<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. <P> + +<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: <P> + +<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. <P> + +<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. <P> + +<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: <P> + +<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. <P> + +<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. <P> +<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. <P> + +<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: <P> + +<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. <P> + +<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. <P> + +<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: <P> + +<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 +NAME="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 NAME="fedit">Editing Requests</A>. +</DL> + +The option values are bit-masks and can be composed with logical-or in +the obvious way. <P> + +<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. <P> + +<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: <P> + +<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. <P> + +<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: <P> + +<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: <P> +<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. <P> + +<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: <P> + +<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: <P> + +<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. <P> + +<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: <P> + +<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. <P> + +<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> |