diff options
Diffstat (limited to 'contrib/ncurses/doc')
| -rw-r--r-- | contrib/ncurses/doc/hackguide.doc | 682 | ||||
| -rw-r--r-- | contrib/ncurses/doc/html/NCURSES-Programming-HOWTO.html | 6413 | ||||
| -rw-r--r-- | contrib/ncurses/doc/html/announce.html | 600 | ||||
| -rw-r--r-- | contrib/ncurses/doc/html/hackguide.html | 914 | ||||
| -rw-r--r-- | contrib/ncurses/doc/html/ncurses-intro.html | 2722 | ||||
| -rw-r--r-- | contrib/ncurses/doc/ncurses-intro.doc | 2501 |
6 files changed, 0 insertions, 13832 deletions
diff --git a/contrib/ncurses/doc/hackguide.doc b/contrib/ncurses/doc/hackguide.doc deleted file mode 100644 index 8e0ba5c..0000000 --- a/contrib/ncurses/doc/hackguide.doc +++ /dev/null @@ -1,682 +0,0 @@ - A Hacker's Guide to NCURSES - - Contents - - * Abstract - * Objective of the Package - + Why System V Curses? - + How to Design Extensions - * Portability and Configuration - * Documentation Conventions - * How to Report Bugs - * A Tour of the Ncurses Library - + Library Overview - + The Engine Room - + Keyboard Input - + Mouse Events - + Output and Screen Updating - * The Forms and Menu Libraries - * A Tour of the Terminfo Compiler - + Translation of Non-use Capabilities - + Use Capability Resolution - + Source-Form Translation - * Other Utilities - * Style Tips for Developers - * Porting Hints - - Abstract - - This document is a hacker's tour of the ncurses library and utilities. - It discusses design philosophy, implementation methods, and the - conventions used for coding and documentation. It is recommended - reading for anyone who is interested in porting, extending or - improving the package. - - Objective of the Package - - The objective of the ncurses package is to provide a free software API - for character-cell terminals and terminal emulators with the following - characteristics: - * Source-compatible with historical curses implementations - (including the original BSD curses and System V curses. - * Conformant with the XSI Curses standard issued as part of XPG4 by - X/Open. - * High-quality -- stable and reliable code, wide portability, good - packaging, superior documentation. - * Featureful -- should eliminate as much of the drudgery of C - interface programming as possible, freeing programmers to think at - a higher level of design. - - These objectives are in priority order. So, for example, source - compatibility with older version must trump featurefulness -- we - cannot add features if it means breaking the portion of the API - corresponding to historical curses versions. - -Why System V Curses? - - We used System V curses as a model, reverse-engineering their API, in - order to fulfill the first two objectives. - - System V curses implementations can support BSD curses programs with - just a recompilation, so by capturing the System V API we also capture - BSD's. - - More importantly for the future, the XSI Curses standard issued by - X/Open is explicitly and closely modeled on System V. So conformance - with System V took us most of the way to base-level XSI conformance. - -How to Design Extensions - - The third objective (standards conformance) requires that it be easy - to condition source code using ncurses so that the absence of - nonstandard extensions does not break the code. - - Accordingly, we have a policy of associating with each nonstandard - extension a feature macro, so that ncurses client code can use this - macro to condition in or out the code that requires the ncurses - extension. - - For example, there is a macro NCURSES_MOUSE_VERSION which XSI Curses - does not define, but which is defined in the ncurses library header. - You can use this to condition the calls to the mouse API calls. - - Portability and Configuration - - Code written for ncurses may assume an ANSI-standard C compiler and - POSIX-compatible OS interface. It may also assume the presence of a - System-V-compatible select(2) call. - - We encourage (but do not require) developers to make the code friendly - to less-capable UNIX environments wherever possible. - - We encourage developers to support OS-specific optimizations and - methods not available under POSIX/ANSI, provided only that: - * All such code is properly conditioned so the build process does - not attempt to compile it under a plain ANSI/POSIX environment. - * Adding such implementation methods does not introduce - incompatibilities in the ncurses API between platforms. - - We use GNU autoconf(1) as a tool to deal with portability issues. The - right way to leverage an OS-specific feature is to modify the autoconf - specification files (configure.in and aclocal.m4) to set up a new - feature macro, which you then use to condition your code. - - Documentation Conventions - - There are three kinds of documentation associated with this package. - Each has a different preferred format: - * Package-internal files (README, INSTALL, TO-DO etc.) - * Manual pages. - * Everything else (i.e., narrative documentation). - - Our conventions are simple: - 1. Maintain package-internal files in plain text. The expected viewer - for them more(1) or an editor window; there's no point in - elaborate mark-up. - 2. Mark up manual pages in the man macros. These have to be viewable - through traditional man(1) programs. - 3. Write everything else in HTML. - - When in doubt, HTMLize a master and use lynx(1) to generate plain - ASCII (as we do for the announcement document). - - The reason for choosing HTML is that it's (a) well-adapted for on-line - browsing through viewers that are everywhere; (b) more easily readable - as plain text than most other mark-ups, if you don't have a viewer; - and (c) carries enough information that you can generate a - nice-looking printed version from it. Also, of course, it make - exporting things like the announcement document to WWW pretty trivial. - - How to Report Bugs - - The reporting address for bugs is bug-ncurses@gnu.org. This is a - majordomo list; to join, write to bug-ncurses-request@gnu.org with a - message containing the line: - subscribe <name>@<host.domain> - - The ncurses code is maintained by a small group of volunteers. While - we try our best to fix bugs promptly, we simply don't have a lot of - hours to spend on elementary hand-holding. We rely on intelligent - cooperation from our users. If you think you have found a bug in - ncurses, there are some steps you can take before contacting us that - will help get the bug fixed quickly. - - In order to use our bug-fixing time efficiently, we put people who - show us they've taken these steps at the head of our queue. This means - that if you don't, you'll probably end up at the tail end and have to - wait a while. - 1. Develop a recipe to reproduce the bug. - Bugs we can reproduce are likely to be fixed very quickly, often - within days. The most effective single thing you can do to get a - quick fix is develop a way we can duplicate the bad behavior -- - ideally, by giving us source for a small, portable test program - that breaks the library. (Even better is a keystroke recipe using - one of the test programs provided with the distribution.) - 2. Try to reproduce the bug on a different terminal type. - In our experience, most of the behaviors people report as library - bugs are actually due to subtle problems in terminal descriptions. - This is especially likely to be true if you're using a traditional - asynchronous terminal or PC-based terminal emulator, rather than - xterm or a UNIX console entry. - It's therefore extremely helpful if you can tell us whether or not - your problem reproduces on other terminal types. Usually you'll - have both a console type and xterm available; please tell us - whether or not your bug reproduces on both. - If you have xterm available, it is also good to collect xterm - reports for different window sizes. This is especially true if you - normally use an unusual xterm window size -- a surprising number - of the bugs we've seen are either triggered or masked by these. - 3. Generate and examine a trace file for the broken behavior. - Recompile your program with the debugging versions of the - libraries. Insert a trace() call with the argument set to - TRACE_UPDATE. (See "Writing Programs with NCURSES" for details on - trace levels.) Reproduce your bug, then look at the trace file to - see what the library was actually doing. - Another frequent cause of apparent bugs is application coding - errors that cause the wrong things to be put on the virtual - screen. Looking at the virtual-screen dumps in the trace file will - tell you immediately if this is happening, and save you from the - possible embarrassment of being told that the bug is in your code - and is your problem rather than ours. - If the virtual-screen dumps look correct but the bug persists, - it's possible to crank up the trace level to give more and more - information about the library's update actions and the control - sequences it issues to perform them. The test directory of the - distribution contains a tool for digesting these logs to make them - less tedious to wade through. - Often you'll find terminfo problems at this stage by noticing that - the escape sequences put out for various capabilities are wrong. - If not, you're likely to learn enough to be able to characterize - any bug in the screen-update logic quite exactly. - 4. Report details and symptoms, not just interpretations. - If you do the preceding two steps, it is very likely that you'll - discover the nature of the problem yourself and be able to send us - a fix. This will create happy feelings all around and earn you - good karma for the first time you run into a bug you really can't - characterize and fix yourself. - If you're still stuck, at least you'll know what to tell us. - Remember, we need details. If you guess about what is safe to - leave out, you are too likely to be wrong. - If your bug produces a bad update, include a trace file. Try to - make the trace at the least voluminous level that pins down the - bug. Logs that have been through tracemunch are OK, it doesn't - throw away any information (actually they're better than - un-munched ones because they're easier to read). - If your bug produces a core-dump, please include a symbolic stack - trace generated by gdb(1) or your local equivalent. - Tell us about every terminal on which you've reproduced the bug -- - and every terminal on which you can't. Ideally, sent us terminfo - sources for all of these (yours might differ from ours). - Include your ncurses version and your OS/machine type, of course! - You can find your ncurses version in the curses.h file. - - If your problem smells like a logic error or in cursor movement or - scrolling or a bad capability, there are a couple of tiny test frames - for the library algorithms in the progs directory that may help you - isolate it. These are not part of the normal build, but do have their - own make productions. - - The most important of these is mvcur, a test frame for the - cursor-movement optimization code. With this program, you can see - directly what control sequences will be emitted for any given cursor - movement or scroll/insert/delete operations. If you think you've got a - bad capability identified, you can disable it and test again. The - program is command-driven and has on-line help. - - If you think the vertical-scroll optimization is broken, or just want - to understand how it works better, build hashmap and read the header - comments of hardscroll.c and hashmap.c; then try it out. You can also - test the hardware-scrolling optimization separately with hardscroll. - - A Tour of the Ncurses Library - -Library Overview - - Most of the library is superstructure -- fairly trivial convenience - interfaces to a small set of basic functions and data structures used - to manipulate the virtual screen (in particular, none of this code - does any I/O except through calls to more fundamental modules - described below). The files - - lib_addch.c lib_bkgd.c lib_box.c lib_chgat.c lib_clear.c - lib_clearok.c lib_clrbot.c lib_clreol.c lib_colorset.c lib_data.c - lib_delch.c lib_delwin.c lib_echo.c lib_erase.c lib_gen.c - lib_getstr.c lib_hline.c lib_immedok.c lib_inchstr.c lib_insch.c - lib_insdel.c lib_insstr.c lib_instr.c lib_isendwin.c lib_keyname.c - lib_leaveok.c lib_move.c lib_mvwin.c lib_overlay.c lib_pad.c - lib_printw.c lib_redrawln.c lib_scanw.c lib_screen.c lib_scroll.c - lib_scrollok.c lib_scrreg.c lib_set_term.c lib_slk.c - lib_slkatr_set.c lib_slkatrof.c lib_slkatron.c lib_slkatrset.c - lib_slkattr.c lib_slkclear.c lib_slkcolor.c lib_slkinit.c - lib_slklab.c lib_slkrefr.c lib_slkset.c lib_slktouch.c lib_touch.c - lib_unctrl.c lib_vline.c lib_wattroff.c lib_wattron.c lib_window.c - - are all in this category. They are very unlikely to need change, - barring bugs or some fundamental reorganization in the underlying data - structures. - - These files are used only for debugging support: - - lib_trace.c lib_traceatr.c lib_tracebits.c lib_tracechr.c - lib_tracedmp.c lib_tracemse.c trace_buf.c - - It is rather unlikely you will ever need to change these, unless you - want to introduce a new debug trace level for some reason. - - There is another group of files that do direct I/O via tputs(), - computations on the terminal capabilities, or queries to the OS - environment, but nevertheless have only fairly low complexity. These - include: - - lib_acs.c lib_beep.c lib_color.c lib_endwin.c lib_initscr.c - lib_longname.c lib_newterm.c lib_options.c lib_termcap.c lib_ti.c - lib_tparm.c lib_tputs.c lib_vidattr.c read_entry.c. - - They are likely to need revision only if ncurses is being ported to an - environment without an underlying terminfo capability representation. - - These files have serious hooks into the tty driver and signal - facilities: - - lib_kernel.c lib_baudrate.c lib_raw.c lib_tstp.c lib_twait.c - - If you run into porting snafus moving the package to another UNIX, the - problem is likely to be in one of these files. The file lib_print.c - uses sleep(2) and also falls in this category. - - Almost all of the real work is done in the files - - hardscroll.c hashmap.c lib_addch.c lib_doupdate.c lib_getch.c - lib_mouse.c lib_mvcur.c lib_refresh.c lib_setup.c lib_vidattr.c - - Most of the algorithmic complexity in the library lives in these - files. If there is a real bug in ncurses itself, it's probably here. - We'll tour some of these files in detail below (see The Engine Room). - - Finally, there is a group of files that is actually most of the - terminfo compiler. The reason this code lives in the ncurses library - is to support fallback to /etc/termcap. These files include - - alloc_entry.c captoinfo.c comp_captab.c comp_error.c comp_hash.c - comp_parse.c comp_scan.c parse_entry.c read_termcap.c write_entry.c - - We'll discuss these in the compiler tour. - -The Engine Room - - Keyboard Input - - All ncurses input funnels through the function wgetch(), defined in - lib_getch.c. This function is tricky; it has to poll for keyboard and - mouse events and do a running match of incoming input against the set - of defined special keys. - - The central data structure in this module is a FIFO queue, used to - match multiple-character input sequences against special-key - capabilities; also to implement pushback via ungetch(). - - The wgetch() code distinguishes between function key sequences and the - same sequences typed manually by doing a timed wait after each input - character that could lead a function key sequence. If the entire - sequence takes less than 1 second, it is assumed to have been - generated by a function key press. - - Hackers bruised by previous encounters with variant select(2) calls - may find the code in lib_twait.c interesting. It deals with the - problem that some BSD selects don't return a reliable time-left value. - The function timed_wait() effectively simulates a System V select. - - Mouse Events - - If the mouse interface is active, wgetch() polls for mouse events each - call, before it goes to the keyboard for input. It is up to - lib_mouse.c how the polling is accomplished; it may vary for different - devices. - - Under xterm, however, mouse event notifications come in via the - keyboard input stream. They are recognized by having the kmous - capability as a prefix. This is kind of klugey, but trying to wire in - recognition of a mouse key prefix without going through the - function-key machinery would be just too painful, and this turns out - to imply having the prefix somewhere in the function-key capabilities - at terminal-type initialization. - - This kluge only works because kmous isn't actually used by any - historic terminal type or curses implementation we know of. Best guess - is it's a relic of some forgotten experiment in-house at Bell Labs - that didn't leave any traces in the publicly-distributed System V - terminfo files. If System V or XPG4 ever gets serious about using it - again, this kluge may have to change. - - Here are some more details about mouse event handling: - - The lib_mouse()code is logically split into a lower level that accepts - event reports in a device-dependent format and an upper level that - parses mouse gestures and filters events. The mediating data structure - is a circular queue of event structures. - - Functionally, the lower level's job is to pick up primitive events and - put them on the circular queue. This can happen in one of two ways: - either (a) _nc_mouse_event() detects a series of incoming mouse - reports and queues them, or (b) code in lib_getch.c detects the kmous - prefix in the keyboard input stream and calls _nc_mouse_inline to - queue up a series of adjacent mouse reports. - - In either case, _nc_mouse_parse() should be called after the series is - accepted to parse the digested mouse reports (low-level events) into a - gesture (a high-level or composite event). - - Output and Screen Updating - - With the single exception of character echoes during a wgetnstr() call - (which simulates cooked-mode line editing in an ncurses window), the - library normally does all its output at refresh time. - - The main job is to go from the current state of the screen (as - represented in the curscr window structure) to the desired new state - (as represented in the newscr window structure), while doing as little - I/O as possible. - - The brains of this operation are the modules hashmap.c, hardscroll.c - and lib_doupdate.c; the latter two use lib_mvcur.c. Essentially, what - happens looks like this: - - The hashmap.c module tries to detect vertical motion changes between - the real and virtual screens. This information is represented by the - oldindex members in the newscr structure. These are modified by - vertical-motion and clear operations, and both are re-initialized - after each update. To this change-journalling information, the hashmap - code adds deductions made using a modified Heckel algorithm on hash - values generated from the line contents. - - The hardscroll.c module computes an optimum set of scroll, insertion, - and deletion operations to make the indices match. It calls - _nc_mvcur_scrolln() in lib_mvcur.c to do those motions. - - Then lib_doupdate.c goes to work. Its job is to do line-by-line - transformations of curscr lines to newscr lines. Its main tool is the - routine mvcur() in lib_mvcur.c. This routine does cursor-movement - optimization, attempting to get from given screen location A to given - location B in the fewest output characters possible. - - If you want to work on screen optimizations, you should use the fact - that (in the trace-enabled version of the library) enabling the - TRACE_TIMES trace level causes a report to be emitted after each - screen update giving the elapsed time and a count of characters - emitted during the update. You can use this to tell when an update - optimization improves efficiency. - - In the trace-enabled version of the library, it is also possible to - disable and re-enable various optimizations at runtime by tweaking the - variable _nc_optimize_enable. See the file include/curses.h.in for - mask values, near the end. - - The Forms and Menu Libraries - - The forms and menu libraries should work reliably in any environment - you can port ncurses to. The only portability issue anywhere in them - is what flavor of regular expressions the built-in form field type - TYPE_REGEXP will recognize. - - The configuration code prefers the POSIX regex facility, modeled on - System V's, but will settle for BSD regexps if the former isn't - available. - - Historical note: the panels code was written primarily to assist in - porting u386mon 2.0 (comp.sources.misc v14i001-4) to systems lacking - panels support; u386mon 2.10 and beyond use it. This version has been - slightly cleaned up for ncurses. - - A Tour of the Terminfo Compiler - - The ncurses implementation of tic is rather complex internally; it has - to do a trying combination of missions. This starts with the fact - that, in addition to its normal duty of compiling terminfo sources - into loadable terminfo binaries, it has to be able to handle termcap - syntax and compile that too into terminfo entries. - - The implementation therefore starts with a table-driven, dual-mode - lexical analyzer (in comp_scan.c). The lexer chooses its mode (termcap - or terminfo) based on the first `,' or `:' it finds in each entry. The - lexer does all the work of recognizing capability names and values; - the grammar above it is trivial, just "parse entries till you run out - of file". - -Translation of Non-use Capabilities - - Translation of most things besides use capabilities is pretty - straightforward. The lexical analyzer's tokenizer hands each - capability name to a hash function, which drives a table lookup. The - table entry yields an index which is used to look up the token type in - another table, and controls interpretation of the value. - - One possibly interesting aspect of the implementation is the way the - compiler tables are initialized. All the tables are generated by - various awk/sed/sh scripts from a master table include/Caps; these - scripts actually write C initializers which are linked to the - compiler. Furthermore, the hash table is generated in the same way, so - it doesn't have to be generated at compiler startup time (another - benefit of this organization is that the hash table can be in - shareable text space). - - Thus, adding a new capability is usually pretty trivial, just a matter - of adding one line to the include/Caps file. We'll have more to say - about this in the section on Source-Form Translation. - -Use Capability Resolution - - The background problem that makes tic tricky isn't the capability - translation itself, it's the resolution of use capabilities. Older - versions would not handle forward use references for this reason (that - is, a using terminal always had to follow its use target in the source - file). By doing this, they got away with a simple implementation - tactic; compile everything as it blows by, then resolve uses from - compiled entries. - - This won't do for ncurses. The problem is that that the whole - compilation process has to be embeddable in the ncurses library so - that it can be called by the startup code to translate termcap entries - on the fly. The embedded version can't go promiscuously writing - everything it translates out to disk -- for one thing, it will - typically be running with non-root permissions. - - So our tic is designed to parse an entire terminfo file into a - doubly-linked circular list of entry structures in-core, and then do - use resolution in-memory before writing everything out. This design - has other advantages: it makes forward and back use-references equally - easy (so we get the latter for free), and it makes checking for name - collisions before they're written out easy to do. - - And this is exactly how the embedded version works. But the - stand-alone user-accessible version of tic partly reverts to the - historical strategy; it writes to disk (not keeping in core) any entry - with no use references. - - This is strictly a core-economy kluge, implemented because the - terminfo master file is large enough that some core-poor systems swap - like crazy when you compile it all in memory...there have been reports - of this process taking three hours, rather than the twenty seconds or - less typical on the author's development box. - - So. The executable tic passes the entry-parser a hook that immediately - writes out the referenced entry if it has no use capabilities. The - compiler main loop refrains from adding the entry to the in-core list - when this hook fires. If some other entry later needs to reference an - entry that got written immediately, that's OK; the resolution code - will fetch it off disk when it can't find it in core. - - Name collisions will still be detected, just not as cleanly. The - write_entry() code complains before overwriting an entry that - postdates the time of tic's first call to write_entry(), Thus it will - complain about overwriting entries newly made during the tic run, but - not about overwriting ones that predate it. - -Source-Form Translation - - Another use of tic is to do source translation between various termcap - and terminfo formats. There are more variants out there than you might - think; the ones we know about are described in the captoinfo(1) manual - page. - - The translation output code (dump_entry() in ncurses/dump_entry.c) is - shared with the infocmp(1) utility. It takes the same internal - representation used to generate the binary form and dumps it to - standard output in a specified format. - - The include/Caps file has a header comment describing ways you can - specify source translations for nonstandard capabilities just by - altering the master table. It's possible to set up capability aliasing - or tell the compiler to plain ignore a given capability without - writing any C code at all. - - For circumstances where you need to do algorithmic translation, there - are functions in parse_entry.c called after the parse of each entry - that are specifically intended to encapsulate such translations. This, - for example, is where the AIX box1 capability get translated to an - acsc string. - - Other Utilities - - The infocmp utility is just a wrapper around the same entry-dumping - code used by tic for source translation. Perhaps the one interesting - aspect of the code is the use of a predicate function passed in to - dump_entry() to control which capabilities are dumped. This is - necessary in order to handle both the ordinary De-compilation case and - entry difference reporting. - - The tput and clear utilities just do an entry load followed by a - tputs() of a selected capability. - - Style Tips for Developers - - See the TO-DO file in the top-level directory of the source - distribution for additions that would be particularly useful. - - The prefix _nc_ should be used on library public functions that are - not part of the curses API in order to prevent pollution of the - application namespace. If you have to add to or modify the function - prototypes in curses.h.in, read ncurses/MKlib_gen.sh first so you can - avoid breaking XSI conformance. Please join the ncurses mailing list. - See the INSTALL file in the top level of the distribution for details - on the list. - - Look for the string FIXME in source files to tag minor bugs and - potential problems that could use fixing. - - Don't try to auto-detect OS features in the main body of the C code. - That's the job of the configuration system. - - To hold down complexity, do make your code data-driven. Especially, if - you can drive logic from a table filtered out of include/Caps, do it. - If you find you need to augment the data in that file in order to - generate the proper table, that's still preferable to ad-hoc code -- - that's why the fifth field (flags) is there. - - Have fun! - - Porting Hints - - The following notes are intended to be a first step towards DOS and - Macintosh ports of the ncurses libraries. - - The following library modules are `pure curses'; they operate only on - the curses internal structures, do all output through other curses - calls (not including tputs() and putp()) and do not call any other - UNIX routines such as signal(2) or the stdio library. Thus, they - should not need to be modified for single-terminal ports. - - lib_addch.c lib_addstr.c lib_bkgd.c lib_box.c lib_clear.c - lib_clrbot.c lib_clreol.c lib_delch.c lib_delwin.c lib_erase.c - lib_inchstr.c lib_insch.c lib_insdel.c lib_insstr.c lib_keyname.c - lib_move.c lib_mvwin.c lib_newwin.c lib_overlay.c lib_pad.c - lib_printw.c lib_refresh.c lib_scanw.c lib_scroll.c lib_scrreg.c - lib_set_term.c lib_touch.c lib_tparm.c lib_tputs.c lib_unctrl.c - lib_window.c panel.c - - This module is pure curses, but calls outstr(): - - lib_getstr.c - - These modules are pure curses, except that they use tputs() and - putp(): - - lib_beep.c lib_color.c lib_endwin.c lib_options.c lib_slk.c - lib_vidattr.c - - This modules assist in POSIX emulation on non-POSIX systems: - - sigaction.c - signal calls - - The following source files will not be needed for a - single-terminal-type port. - - alloc_entry.c captoinfo.c clear.c comp_captab.c comp_error.c - comp_hash.c comp_main.c comp_parse.c comp_scan.c dump_entry.c - infocmp.c parse_entry.c read_entry.c tput.c write_entry.c - - The following modules will use open()/read()/write()/close()/lseek() - on files, but no other OS calls. - - lib_screen.c - used to read/write screen dumps - - lib_trace.c - used to write trace data to the logfile - - Modules that would have to be modified for a port start here: - - The following modules are `pure curses' but contain assumptions - inappropriate for a memory-mapped port. - - lib_longname.c - assumes there may be multiple terminals - - lib_acs.c - assumes acs_map as a double indirection - - lib_mvcur.c - assumes cursor moves have variable cost - - lib_termcap.c - assumes there may be multiple terminals - - lib_ti.c - assumes there may be multiple terminals - - The following modules use UNIX-specific calls: - - lib_doupdate.c - input checking - - lib_getch.c - read() - - lib_initscr.c - getenv() - - lib_newterm.c - lib_baudrate.c - lib_kernel.c - various tty-manipulation and system calls - - lib_raw.c - various tty-manipulation calls - - lib_setup.c - various tty-manipulation calls - - lib_restart.c - various tty-manipulation calls - - lib_tstp.c - signal-manipulation calls - - lib_twait.c - gettimeofday(), select(). - _________________________________________________________________ - - - Eric S. Raymond <esr@snark.thyrsus.com> - - (Note: This is not the bug address!) diff --git a/contrib/ncurses/doc/html/NCURSES-Programming-HOWTO.html b/contrib/ncurses/doc/html/NCURSES-Programming-HOWTO.html deleted file mode 100644 index 3a10106..0000000 --- a/contrib/ncurses/doc/html/NCURSES-Programming-HOWTO.html +++ /dev/null @@ -1,6413 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html> -<head> -<meta name="generator" content= -"HTML Tidy for Linux/x86 (vers 1st December 2004), see www.w3.org"> -<title>NCURSES Programming HOWTO</title> -<meta name="GENERATOR" content= -"Modular DocBook HTML Stylesheet Version 1.7"> -</head> -<body class="ARTICLE" bgcolor="#FFFFFF" text="#000000" link= -"#0000FF" vlink="#840084" alink="#0000FF"> -<div class="ARTICLE"> -<div class="TITLEPAGE"> -<h1 class="TITLE"><a name="AEN2" id="AEN2">NCURSES Programming -HOWTO</a></h1> -<h3 class="AUTHOR"><a name="AEN4" id="AEN4">Pradeep Padala</a></h3> -<div class="AFFILIATION"> -<div class="ADDRESS"> -<p class="ADDRESS"><code class="EMAIL"><<a href= -"mailto:ppadala@gmail.com">ppadala@gmail.com</a>></code></p> -</div> -</div> -<p class="PUBDATE">v1.9, 2005-06-20<br></p> -<div class="REVHISTORY"> -<table width="100%" border="0"> -<tr> -<th align="left" valign="top" colspan="3"><b>Revision -History</b></th> -</tr> -<tr> -<td align="left">Revision 1.9</td> -<td align="left">2005-06-20</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">The license has been changed to the -MIT-style license used by NCURSES. Note that the programs are also -re-licensed under this.</td> -</tr> -<tr> -<td align="left">Revision 1.8</td> -<td align="left">2005-06-17</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">Lots of updates. Added references and -perl examples. Changes to examples. Many grammatical and stylistic -changes to the content. Changes to NCURSES history.</td> -</tr> -<tr> -<td align="left">Revision 1.7.1</td> -<td align="left">2002-06-25</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">Added a README file for building and -instructions for building from source.</td> -</tr> -<tr> -<td align="left">Revision 1.7</td> -<td align="left">2002-06-25</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">Added "Other formats" section and made -a lot of fancy changes to the programs. Inlining of programs is -gone.</td> -</tr> -<tr> -<td align="left">Revision 1.6.1</td> -<td align="left">2002-02-24</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">Removed the old Changelog section, -cleaned the makefiles</td> -</tr> -<tr> -<td align="left">Revision 1.6</td> -<td align="left">2002-02-16</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">Corrected a lot of spelling mistakes, -added ACS variables section</td> -</tr> -<tr> -<td align="left">Revision 1.5</td> -<td align="left">2002-01-05</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">Changed structure to present proper -TOC</td> -</tr> -<tr> -<td align="left">Revision 1.3.1</td> -<td align="left">2001-07-26</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">Corrected maintainers paragraph, -Corrected stable release number</td> -</tr> -<tr> -<td align="left">Revision 1.3</td> -<td align="left">2001-07-24</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">Added copyright notices to main -document (LDP license) and programs (GPL), Corrected -printw_example.</td> -</tr> -<tr> -<td align="left">Revision 1.2</td> -<td align="left">2001-06-05</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">Incorporated ravi's changes. Mainly to -introduction, menu, form, justforfun sections</td> -</tr> -<tr> -<td align="left">Revision 1.1</td> -<td align="left">2001-05-22</td> -<td align="left">Revised by: ppadala</td> -</tr> -<tr> -<td align="left" colspan="3">Added "a word about window" section, -Added scanw_example.</td> -</tr> -</table> -</div> -<div> -<div class="ABSTRACT"><a name="AEN67" id="AEN67"></a> -<p><em>This document is intended to be an "All in One" guide for -programming with ncurses and its sister libraries. We graduate from -a simple "Hello World" program to more complex form manipulation. -No prior experience in ncurses is assumed. Send comments to -<a href="mailto:ppadala@gmail.com" target="_top">this -address</a></em></p> -</div> -</div> -<hr></div> -<div class="TOC"> -<dl> -<dt><b>Table of Contents</b></dt> -<dt>1. <a href="#INTRO">Introduction</a></dt> -<dd> -<dl> -<dt>1.1. <a href="#WHATIS">What is NCURSES?</a></dt> -<dt>1.2. <a href="#WHATCANWEDO">What we can do with -NCURSES</a></dt> -<dt>1.3. <a href="#WHERETOGETIT">Where to get it</a></dt> -<dt>1.4. <a href="#PURPOSE">Purpose/Scope of the document</a></dt> -<dt>1.5. <a href="#ABOUTPROGRAMS">About the Programs</a></dt> -<dt>1.6. <a href="#OTHERFORMATS">Other Formats of the -document</a></dt> -<dt>1.7. <a href="#CREDITS">Credits</a></dt> -<dt>1.8. <a href="#WISHLIST">Wish List</a></dt> -<dt>1.9. <a href="#COPYRIGHT">Copyright</a></dt> -</dl> -</dd> -<dt>2. <a href="#HELLOWORLD">Hello World !!!</a></dt> -<dd> -<dl> -<dt>2.1. <a href="#COMPILECURSES">Compiling With the NCURSES -Library</a></dt> -<dt>2.2. <a href="#DISSECTION">Dissection</a></dt> -</dl> -</dd> -<dt>3. <a href="#GORY">The Gory Details</a></dt> -<dt>4. <a href="#INIT">Initialization</a></dt> -<dd> -<dl> -<dt>4.1. <a href="#ABOUTINIT">Initialization functions</a></dt> -<dt>4.2. <a href="#RAWCBREAK">raw() and cbreak()</a></dt> -<dt>4.3. <a href="#ECHONOECHO">echo() and noecho()</a></dt> -<dt>4.4. <a href="#KEYPAD">keypad()</a></dt> -<dt>4.5. <a href="#HALFDELAY">halfdelay()</a></dt> -<dt>4.6. <a href="#MISCINIT">Miscellaneous Initialization -functions</a></dt> -<dt>4.7. <a href="#INITEX">An Example</a></dt> -</dl> -</dd> -<dt>5. <a href="#AWORDWINDOWS">A Word about Windows</a></dt> -<dt>6. <a href="#PRINTW">Output functions</a></dt> -<dd> -<dl> -<dt>6.1. <a href="#ADDCHCLASS">addch() class of functions</a></dt> -<dt>6.2. <a href="#AEN298">mvaddch(), waddch() and -mvwaddch()</a></dt> -<dt>6.3. <a href="#PRINTWCLASS">printw() class of -functions</a></dt> -<dt>6.4. <a href="#ADDSTRCLASS">addstr() class of -functions</a></dt> -<dt>6.5. <a href="#ACAUTION">A word of caution</a></dt> -</dl> -</dd> -<dt>7. <a href="#SCANW">Input functions</a></dt> -<dd> -<dl> -<dt>7.1. <a href="#GETCHCLASS">getch() class of functions</a></dt> -<dt>7.2. <a href="#SCANWCLASS">scanw() class of functions</a></dt> -<dt>7.3. <a href="#GETSTRCLASS">getstr() class of -functions</a></dt> -<dt>7.4. <a href="#GETSTREX">Some examples</a></dt> -</dl> -</dd> -<dt>8. <a href="#ATTRIB">Attributes</a></dt> -<dd> -<dl> -<dt>8.1. <a href="#ATTRIBDETAILS">The details</a></dt> -<dt>8.2. <a href="#ATTRONVSATTRSET">attron() vs attrset()</a></dt> -<dt>8.3. <a href="#ATTR_GET">attr_get()</a></dt> -<dt>8.4. <a href="#ATTR_FUNCS">attr_ functions</a></dt> -<dt>8.5. <a href="#WATTRFUNCS">wattr functions</a></dt> -<dt>8.6. <a href="#CHGAT">chgat() functions</a></dt> -</dl> -</dd> -<dt>9. <a href="#WINDOWS">Windows</a></dt> -<dd> -<dl> -<dt>9.1. <a href="#WINDOWBASICS">The basics</a></dt> -<dt>9.2. <a href="#LETBEWINDOW">Let there be a Window !!!</a></dt> -<dt>9.3. <a href="#BORDEREXEXPL">Explanation</a></dt> -<dt>9.4. <a href="#OTHERSTUFF">The other stuff in the -example</a></dt> -<dt>9.5. <a href="#OTHERBORDERFUNCS">Other Border -functions</a></dt> -</dl> -</dd> -<dt>10. <a href="#COLOR">Colors</a></dt> -<dd> -<dl> -<dt>10.1. <a href="#COLORBASICS">The basics</a></dt> -<dt>10.2. <a href="#CHANGECOLORDEFS">Changing Color -Definitions</a></dt> -<dt>10.3. <a href="#COLORCONTENT">Color Content</a></dt> -</dl> -</dd> -<dt>11. <a href="#KEYS">Interfacing with the key board</a></dt> -<dd> -<dl> -<dt>11.1. <a href="#KEYSBASICS">The Basics</a></dt> -<dt>11.2. <a href="#SIMPLEKEYEX">A Simple Key Usage -example</a></dt> -</dl> -</dd> -<dt>12. <a href="#MOUSE">Interfacing with the mouse</a></dt> -<dd> -<dl> -<dt>12.1. <a href="#MOUSEBASICS">The Basics</a></dt> -<dt>12.2. <a href="#GETTINGEVENTS">Getting the events</a></dt> -<dt>12.3. <a href="#MOUSETOGETHER">Putting it all Together</a></dt> -<dt>12.4. <a href="#MISCMOUSEFUNCS">Miscellaneous -Functions</a></dt> -</dl> -</dd> -<dt>13. <a href="#SCREEN">Screen Manipulation</a></dt> -<dd> -<dl> -<dt>13.1. <a href="#GETYX">getyx() functions</a></dt> -<dt>13.2. <a href="#SCREENDUMP">Screen Dumping</a></dt> -<dt>13.3. <a href="#WINDOWDUMP">Window Dumping</a></dt> -</dl> -</dd> -<dt>14. <a href="#MISC">Miscellaneous features</a></dt> -<dd> -<dl> -<dt>14.1. <a href="#CURSSET">curs_set()</a></dt> -<dt>14.2. <a href="#TEMPLEAVE">Temporarily Leaving Curses -mode</a></dt> -<dt>14.3. <a href="#ACSVARS">ACS_ variables</a></dt> -</dl> -</dd> -<dt>15. <a href="#OTHERLIB">Other libraries</a></dt> -<dt>16. <a href="#PANELS">Panel Library</a></dt> -<dd> -<dl> -<dt>16.1. <a href="#PANELBASICS">The Basics</a></dt> -<dt>16.2. <a href="#COMPILEPANELS">Compiling With the Panels -Library</a></dt> -<dt>16.3. <a href="#PANELBROWSING">Panel Window Browsing</a></dt> -<dt>16.4. <a href="#USERPTRUSING">Using User Pointers</a></dt> -<dt>16.5. <a href="#PANELMOVERESIZE">Moving and Resizing -Panels</a></dt> -<dt>16.6. <a href="#PANELSHOWHIDE">Hiding and Showing -Panels</a></dt> -<dt>16.7. <a href="#PANELABOVE">panel_above() and panel_below() -Functions</a></dt> -</dl> -</dd> -<dt>17. <a href="#MENUS">Menus Library</a></dt> -<dd> -<dl> -<dt>17.1. <a href="#MENUBASICS">The Basics</a></dt> -<dt>17.2. <a href="#COMPILEMENUS">Compiling With the Menu -Library</a></dt> -<dt>17.3. <a href="#MENUDRIVER">Menu Driver: The work horse of the -menu system</a></dt> -<dt>17.4. <a href="#MENUWINDOWS">Menu Windows</a></dt> -<dt>17.5. <a href="#SCROLLMENUS">Scrolling Menus</a></dt> -<dt>17.6. <a href="#MULTICOLUMN">Multi Columnar Menus</a></dt> -<dt>17.7. <a href="#MULTIVALUEMENUS">Multi Valued Menus</a></dt> -<dt>17.8. <a href="#MENUOPT">Menu Options</a></dt> -<dt>17.9. <a href="#MENUUSERPTR">The useful User Pointer</a></dt> -</dl> -</dd> -<dt>18. <a href="#FORMS">Forms Library</a></dt> -<dd> -<dl> -<dt>18.1. <a href="#FORMBASICS">The Basics</a></dt> -<dt>18.2. <a href="#COMPILEFORMS">Compiling With the Forms -Library</a></dt> -<dt>18.3. <a href="#PLAYFIELDS">Playing with Fields</a></dt> -<dt>18.4. <a href="#FORMWINDOWS">Form Windows</a></dt> -<dt>18.5. <a href="#FILEDVALIDATE">Field Validation</a></dt> -<dt>18.6. <a href="#FORMDRIVER">Form Driver: The work horse of the -forms system</a></dt> -</dl> -</dd> -<dt>19. <a href="#TOOLS">Tools and Widget Libraries</a></dt> -<dd> -<dl> -<dt>19.1. <a href="#CDK">CDK (Curses Development Kit)</a></dt> -<dt>19.2. <a href="#DIALOG">The dialog</a></dt> -<dt>19.3. <a href="#PERLCURSES">Perl Curses Modules CURSES::FORM -and CURSES::WIDGETS</a></dt> -</dl> -</dd> -<dt>20. <a href="#JUSTFORFUN">Just For Fun !!!</a></dt> -<dd> -<dl> -<dt>20.1. <a href="#GAMEOFLIFE">The Game of Life</a></dt> -<dt>20.2. <a href="#MAGIC">Magic Square</a></dt> -<dt>20.3. <a href="#HANOI">Towers of Hanoi</a></dt> -<dt>20.4. <a href="#QUEENS">Queens Puzzle</a></dt> -<dt>20.5. <a href="#SHUFFLE">Shuffle</a></dt> -<dt>20.6. <a href="#TT">Typing Tutor</a></dt> -</dl> -</dd> -<dt>21. <a href="#REF">References</a></dt> -</dl> -</div> -<div class="SECT1"> -<h2 class="SECT1"><a name="INTRO" id="INTRO">1. -Introduction</a></h2> -<p>In the olden days of teletype terminals, terminals were away -from computers and were connected to them through serial cables. -The terminals could be configured by sending a series of bytes. All -the capabilities (such as moving the cursor to a new location, -erasing part of the screen, scrolling the screen, changing modes -etc.) of terminals could be accessed through these series of bytes. -These control seeuqnces are usually called escape sequences, -because they start with an escape(0x1B) character. Even today, with -proper emulation, we can send escape sequences to the emulator and -achieve the same effect on a terminal window.</p> -<p>Suppose you wanted to print a line in color. Try typing this on -your console.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000">echo "^[[0;31;40mIn Color"</font> -</pre></td> -</tr> -</table> -<p>The first character is an escape character, which looks like two -characters ^ and [. To be able to print it, you have to press -CTRL+V and then the ESC key. All the others are normal printable -characters. You should be able to see the string "In Color" in red. -It stays that way and to revert back to the original mode type -this.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000">echo "^[[0;37;40m"</font> -</pre></td> -</tr> -</table> -<p>Now, what do these magic characters mean? Difficult to -comprehend? They might even be different for different terminals. -So the designers of UNIX invented a mechanism named <var class= -"LITERAL">termcap</var>. It is a file that lists all the -capabilities of a particular terminal, along with the escape -sequences needed to achieve a particular effect. In the later -years, this was replaced by <var class="LITERAL">terminfo</var>. -Without delving too much into details, this mechanism allows -application programs to query the terminfo database and obtain the -control characters to be sent to a terminal or terminal -emulator.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="WHATIS" id="WHATIS">1.1. What is -NCURSES?</a></h3> -<p>You might be wondering, what the import of all this technical -gibberish is. In the above scenario, every application program is -supposed to query the terminfo and perform the necessary stuff -(sending control characters etc.). It soon became difficult to -manage this complexity and this gave birth to 'CURSES'. Curses is a -pun on the name "cursor optimization". The Curses library forms a -wrapper over working with raw terminal codes, and provides highly -flexible and efficient API (Application Programming Interface). It -provides functions to move the cursor, create windows, produce -colors, play with mouse etc. The application programs need not -worry about the underlying terminal capabilities.</p> -<p>So what is NCURSES? NCURSES is a clone of the original System V -Release 4.0 (SVr4) curses. It is a freely distributable library, -fully compatible with older version of curses. In short, it is a -library of functions that manages an application's display on -character-cell terminals. In the remainder of the document, the -terms curses and ncurses are used interchangeably.</p> -<p>A detailed history of NCURSES can be found in the NEWS file from -the source distribution. The current package is maintained by -<a href="mailto:dickey@his.com" target="_top">Thomas Dickey</a>. -You can contact the maintainers at <a href= -"mailto:bug-ncurses@gnu.org" target= -"_top">bug-ncurses@gnu.org</a>.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="WHATCANWEDO" id="WHATCANWEDO">1.2. What -we can do with NCURSES</a></h3> -<p>NCURSES not only creates a wrapper over terminal capabilities, -but also gives a robust framework to create nice looking UI (User -Interface)s in text mode. It provides functions to create windows -etc. Its sister libraries panel, menu and form provide an extension -to the basic curses library. These libraries usually come along -with curses. One can create applications that contain multiple -windows, menus, panels and forms. Windows can be managed -independently, can provide 'scrollability' and even can be -hidden.</p> -<p>Menus provide the user with an easy command selection option. -Forms allow the creation of easy-to-use data entry and display -windows. Panels extend the capabilities of ncurses to deal with -overlapping and stacked windows.</p> -<p>These are just some of the basic things we can do with ncurses. -As we move along, We will see all the capabilities of these -libraries.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="WHERETOGETIT" id="WHERETOGETIT">1.3. -Where to get it</a></h3> -<p>All right, now that you know what you can do with ncurses, you -must be rearing to get started. NCURSES is usually shipped with -your installation. In case you don't have the library or want to -compile it on your own, read on.</p> -<p><em>Compiling the package</em></p> -<p>NCURSES can be obtained from <a href= -"ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz" target= -"_top">ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz</a> or any -of the ftp sites mentioned in <a href= -"http://www.gnu.org/order/ftp.html" target= -"_top">http://www.gnu.org/order/ftp.html</a>.</p> -<p>Read the README and INSTALL files for details on to how to -install it. It usually involves the following operations.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"> tar zxvf ncurses<version>.tar.gz # unzip and untar the archive - cd ncurses<version> # cd to the directory - ./configure # configure the build according to your - # environment - make # make it - su root # become root - make install # install it</font> -</pre></td> -</tr> -</table> -<p><em>Using the RPM</em></p> -<p>NCURSES RPM can be found and downloaded from <a href= -"http://rpmfind.net" target="_top">http://rpmfind.net</a> . The RPM -can be installed with the following command after becoming -root.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> rpm -i <downloaded rpm></font> -</pre></td> -</tr> -</table> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="PURPOSE" id="PURPOSE">1.4. Purpose/Scope -of the document</a></h3> -<p>This document is intended to be a "All in One" guide for -programming with ncurses and its sister libraries. We graduate from -a simple "Hello World" program to more complex form manipulation. -No prior experience in ncurses is assumed. The writing is informal, -but a lot of detail is provided for each of the examples.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ABOUTPROGRAMS" id="ABOUTPROGRAMS">1.5. -About the Programs</a></h3> -<p>All the programs in the document are available in zipped form -<a href= -"http://www.tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs.tar.gz" -target="_top">here</a>. Unzip and untar it. The directory structure -looks like this.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000">ncurses - | - |----> JustForFun -- just for fun programs - |----> basics -- basic programs - |----> demo -- output files go into this directory after make - | | - | |----> exe -- exe files of all example programs - |----> forms -- programs related to form library - |----> menus -- programs related to menus library - |----> panels -- programs related to panels library - |----> perl -- perl equivalents of the examples (contributed - | by Anuradha Ratnaweera) - |----> Makefile -- the top level Makefile - |----> README -- the top level README file. contains instructions - |----> COPYING -- copyright notice</font> -</pre></td> -</tr> -</table> -<p>The individual directories contain the following files.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000">Description of files in each directory --------------------------------------- -JustForFun - | - |----> hanoi.c -- The Towers of Hanoi Solver - |----> life.c -- The Game of Life demo - |----> magic.c -- An Odd Order Magic Square builder - |----> queens.c -- The famous N-Queens Solver - |----> shuffle.c -- A fun game, if you have time to kill - |----> tt.c -- A very trivial typing tutor - - basics - | - |----> acs_vars.c -- ACS_ variables example - |----> hello_world.c -- Simple "Hello World" Program - |----> init_func_example.c -- Initialization functions example - |----> key_code.c -- Shows the scan code of the key pressed - |----> mouse_menu.c -- A menu accessible by mouse - |----> other_border.c -- Shows usage of other border functions apa - | -- rt from box() - |----> printw_example.c -- A very simple printw() example - |----> scanw_example.c -- A very simple getstr() example - |----> simple_attr.c -- A program that can print a c file with - | -- comments in attribute - |----> simple_color.c -- A simple example demonstrating colors - |----> simple_key.c -- A menu accessible with keyboard UP, DOWN - | -- arrows - |----> temp_leave.c -- Demonstrates temporarily leaving curses mode - |----> win_border.c -- Shows Creation of windows and borders - |----> with_chgat.c -- chgat() usage example - - forms - | - |----> form_attrib.c -- Usage of field attributes - |----> form_options.c -- Usage of field options - |----> form_simple.c -- A simple form example - |----> form_win.c -- Demo of windows associated with forms - - menus - | - |----> menu_attrib.c -- Usage of menu attributes - |----> menu_item_data.c -- Usage of item_name() etc.. functions - |----> menu_multi_column.c -- Creates multi columnar menus - |----> menu_scroll.c -- Demonstrates scrolling capability of menus - |----> menu_simple.c -- A simple menu accessed by arrow keys - |----> menu_toggle.c -- Creates multi valued menus and explains - | -- REQ_TOGGLE_ITEM - |----> menu_userptr.c -- Usage of user pointer - |----> menu_win.c -- Demo of windows associated with menus - - panels - | - |----> panel_browse.c -- Panel browsing through tab. Usage of user - | -- pointer - |----> panel_hide.c -- Hiding and Un hiding of panels - |----> panel_resize.c -- Moving and resizing of panels - |----> panel_simple.c -- A simple panel example - - perl - |----> 01-10.pl -- Perl equivalents of first ten example programs</font> -</pre></td> -</tr> -</table> -<p>There is a top level Makefile included in the main directory. It -builds all the files and puts the ready-to-use exes in demo/exe -directory. You can also do selective make by going into the -corresponding directory. Each directory contains a README file -explaining the purpose of each c file in the directory.</p> -<p>For every example, I have included path name for the file -relative to the examples directory.</p> -<p>If you prefer browsing individual programs, point your browser -to <a href= -"http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/" -target= -"_top">http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/</a></p> -<p>All the programs are released under the same license that is -used by ncurses (MIT-style). This gives you the ability to do -pretty much anything other than claiming them as yours. Feel free -to use them in your programs as appropriate.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="OTHERFORMATS" id="OTHERFORMATS">1.6. -Other Formats of the document</a></h3> -<p>This howto is also availabe in various other formats on the -tldp.org site. Here are the links to other formats of this -document.</p> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="LISTFORMATS" id="LISTFORMATS">1.6.1. -Readily available formats from tldp.org</a></h4> -<ul> -<li> -<p><a href= -"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/pdf/NCURSES-Programming-HOWTO.pdf" -target="_top">Acrobat PDF Format</a></p> -</li> -<li> -<p><a href= -"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/ps/NCURSES-Programming-HOWTO.ps.gz" -target="_top">PostScript Format</a></p> -</li> -<li> -<p><a href= -"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html/NCURSES-Programming-HOWTO-html.tar.gz" -target="_top">In Multiple HTML pages</a></p> -</li> -<li> -<p><a href= -"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/NCURSES-Programming-HOWTO.html" -target="_top">In One big HTML format</a></p> -</li> -</ul> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="BUILDSOURCE" id="BUILDSOURCE">1.6.2. -Building from source</a></h4> -<p>If above links are broken or if you want to experiment with sgml -read on.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"> Get both the source and the tar,gzipped programs, available at - http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/ - NCURSES-HOWTO/NCURSES-Programming-HOWTO.sgml - http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/ - NCURSES-HOWTO/ncurses_programs.tar.gz - - Unzip ncurses_programs.tar.gz with - tar zxvf ncurses_programs.tar.gz - - Use jade to create various formats. For example if you just want to create - the multiple html files, you would use - jade -t sgml -i html -d <path to docbook html stylesheet> - NCURSES-Programming-HOWTO.sgml - to get pdf, first create a single html file of the HOWTO with - jade -t sgml -i html -d <path to docbook html stylesheet> -V nochunks - NCURSES-Programming-HOWTO.sgml > NCURSES-ONE-BIG-FILE.html - then use htmldoc to get pdf file with - htmldoc --size universal -t pdf --firstpage p1 -f <output file name.pdf> - NCURSES-ONE-BIG-FILE.html - for ps, you would use - htmldoc --size universal -t ps --firstpage p1 -f <output file name.ps> - NCURSES-ONE-BIG-FILE.html</font> -</pre></td> -</tr> -</table> -<p>See <a href="http://www.tldp.org/LDP/LDP-Author-Guide/" target= -"_top">LDP Author guide</a> for more details. If all else failes, -mail me at <a href="ppadala@gmail.com" target= -"_top">ppadala@gmail.com</a></p> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="CREDITS" id="CREDITS">1.7. -Credits</a></h3> -<p>I thank <a href="mailto:sharath_1@usa.net" target= -"_top">Sharath</a> and Emre Akbas for helping me with few sections. -The introduction was initially written by sharath. I rewrote it -with few excerpts taken from his initial work. Emre helped in -writing printw and scanw sections.</p> -<p>Perl equivalents of the example programs are contributed by -<a href="mailto:Aratnaweera@virtusa.com" target="_top">Anuradha -Ratnaweera</a>.</p> -<p>Then comes <a href="mailto:parimi@ece.arizona.edu" target= -"_top">Ravi Parimi</a>, my dearest friend, who has been on this -project before even one line was written. He constantly bombarded -me with suggestions and patiently reviewed the whole text. He also -checked each program on Linux and Solaris.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="WISHLIST" id="WISHLIST">1.8. Wish -List</a></h3> -<p>This is the wish list, in the order of priority. If you have a -wish or you want to work on completing the wish, mail <a href= -"mailto:ppadala@gmail.com" target="_top">me</a>.</p> -<ul> -<li> -<p>Add examples to last parts of forms section.</p> -</li> -<li> -<p>Prepare a Demo showing all the programs and allow the user to -browse through description of each program. Let the user compile -and see the program in action. A dialog based interface is -preferred.</p> -</li> -<li> -<p>Add debug info. _tracef, _tracemouse stuff.</p> -</li> -<li> -<p>Accessing termcap, terminfo using functions provided by ncurses -package.</p> -</li> -<li> -<p>Working on two terminals simultaneously.</p> -</li> -<li> -<p>Add more stuff to miscellaneous section.</p> -</li> -</ul> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="COPYRIGHT" id="COPYRIGHT">1.9. -Copyright</a></h3> -<p>Copyright © 2001 by Pradeep Padala.</p> -<p>Permission is hereby granted, free of charge, to any person -obtaining a copy of this software and associated documentation -files (the "Software"), to deal in the Software without -restriction, including without limitation the rights to use, copy, -modify, merge, publish, distribute, distribute with modifications, -sublicense, and/or sell copies of the Software, and to permit -persons to whom the Software is furnished to do so, subject to the -following conditions:</p> -<p>The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software.</p> -<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -NONINFRINGEMENT. IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE -LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE.</p> -<p>Except as contained in this notice, the name(s) of the above -copyright holders shall not be used in advertising or otherwise to -promote the sale, use or other dealings in this Software without -prior written authorization.</p> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="HELLOWORLD" id="HELLOWORLD">2. Hello -World !!!</a></h2> -<p>Welcome to the world of curses. Before we plunge into the -library and look into its various features, let's write a simple -program and say hello to the world.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="COMPILECURSES" id="COMPILECURSES">2.1. -Compiling With the NCURSES Library</a></h3> -<p>To use ncurses library functions, you have to include ncurses.h -in your programs. To link the program with ncurses the flag --lncurses should be added.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> #include <ncurses.h> - . - . - . - - compile and link: gcc <program file> -lncurses</font> -</pre></td> -</tr> -</table> -<div class="EXAMPLE"><a name="BHW" id="BHW"></a> -<p><b>Example 1. The Hello World !!! Program</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> - -int main() -{ - initscr(); /* Start curses mode */ - printw("Hello World !!!"); /* Print Hello World */ - refresh(); /* Print it on to the real screen */ - getch(); /* Wait for user input */ - endwin(); /* End curses mode */ - - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="DISSECTION" id="DISSECTION">2.2. -Dissection</a></h3> -<p>The above program prints "Hello World !!!" to the screen and -exits. This program shows how to initialize curses and do screen -manipulation and end curses mode. Let's dissect it line by -line.</p> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="ABOUT-INITSCR" id="ABOUT-INITSCR">2.2.1. -About initscr()</a></h4> -<p>The function initscr() initializes the terminal in curses mode. -In some implementations, it clears the screen and presents a blank -screen. To do any screen manipulation using curses package this has -to be called first. This function initializes the curses system and -allocates memory for our present window (called <var class= -"LITERAL">stdscr</var>) and some other data-structures. Under -extreme cases this function might fail due to insufficient memory -to allocate memory for curses library's data structures.</p> -<p>After this is done, we can do a variety of initializations to -customize our curses settings. These details will be explained -<a href="#INIT">later</a> .</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="MYST-REFRESH" id="MYST-REFRESH">2.2.2. -The mysterious refresh()</a></h4> -<p>The next line printw prints the string "Hello World !!!" on to -the screen. This function is analogous to normal printf in all -respects except that it prints the data on a window called stdscr -at the current (y,x) co-ordinates. Since our present co-ordinates -are at 0,0 the string is printed at the left hand corner of the -window.</p> -<p>This brings us to that mysterious refresh(). Well, when we -called printw the data is actually written to an imaginary window, -which is not updated on the screen yet. The job of printw is to -update a few flags and data structures and write the data to a -buffer corresponding to stdscr. In order to show it on the screen, -we need to call refresh() and tell the curses system to dump the -contents on the screen.</p> -<p>The philosophy behind all this is to allow the programmer to do -multiple updates on the imaginary screen or windows and do a -refresh once all his screen update is done. refresh() checks the -window and updates only the portion which has been changed. This -improves performance and offers greater flexibility too. But, it is -sometimes frustrating to beginners. A common mistake committed by -beginners is to forget to call refresh() after they did some update -through printw() class of functions. I still forget to add it -sometimes :-)</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="ABOUT-ENDWIN" id="ABOUT-ENDWIN">2.2.3. -About endwin()</a></h4> -<p>And finally don't forget to end the curses mode. Otherwise your -terminal might behave strangely after the program quits. endwin() -frees the memory taken by curses sub-system and its data structures -and puts the terminal in normal mode. This function must be called -after you are done with the curses mode.</p> -</div> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="GORY" id="GORY">3. The Gory -Details</a></h2> -<p>Now that we have seen how to write a simple curses program let's -get into the details. There are many functions that help customize -what you see on screen and many features which can be put to full -use.</p> -<p>Here we go...</p> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="INIT" id="INIT">4. -Initialization</a></h2> -<p>We now know that to initialize curses system the function -initscr() has to be called. There are functions which can be called -after this initialization to customize our curses session. We may -ask the curses system to set the terminal in raw mode or initialize -color or initialize the mouse etc.. Let's discuss some of the -functions that are normally called immediately after initscr();</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ABOUTINIT" id="ABOUTINIT">4.1. -Initialization functions</a></h3> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="RAWCBREAK" id="RAWCBREAK">4.2. raw() and -cbreak()</a></h3> -<p>Normally the terminal driver buffers the characters a user types -until a new line or carriage return is encountered. But most -programs require that the characters be available as soon as the -user types them. The above two functions are used to disable line -buffering. The difference between these two functions is in the way -control characters like suspend (CTRL-Z), interrupt and quit -(CTRL-C) are passed to the program. In the raw() mode these -characters are directly passed to the program without generating a -signal. In the <var class="LITERAL">cbreak()</var> mode these -control characters are interpreted as any other character by the -terminal driver. I personally prefer to use raw() as I can exercise -greater control over what the user does.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ECHONOECHO" id="ECHONOECHO">4.3. echo() -and noecho()</a></h3> -<p>These functions control the echoing of characters typed by the -user to the terminal. <var class="LITERAL">noecho()</var> switches -off echoing. The reason you might want to do this is to gain more -control over echoing or to suppress unnecessary echoing while -taking input from the user through the getch() etc. functions. Most -of the interactive programs call <var class= -"LITERAL">noecho()</var> at initialization and do the echoing of -characters in a controlled manner. It gives the programmer the -flexibility of echoing characters at any place in the window -without updating current (y,x) co-ordinates.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="KEYPAD" id="KEYPAD">4.4. -keypad()</a></h3> -<p>This is my favorite initialization function. It enables the -reading of function keys like F1, F2, arrow keys etc. Almost every -interactive program enables this, as arrow keys are a major part of -any User Interface. Do <var class="LITERAL">keypad(stdscr, -TRUE)</var> to enable this feature for the regular screen (stdscr). -You will learn more about key management in later sections of this -document.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="HALFDELAY" id="HALFDELAY">4.5. -halfdelay()</a></h3> -<p>This function, though not used very often, is a useful one at -times. halfdelay()is called to enable the half-delay mode, which is -similar to the cbreak() mode in that characters typed are -immediately available to program. However, it waits for 'X' tenths -of a second for input and then returns ERR, if no input is -available. 'X' is the timeout value passed to the function -halfdelay(). This function is useful when you want to ask the user -for input, and if he doesn't respond with in certain time, we can -do some thing else. One possible example is a timeout at the -password prompt.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MISCINIT" id="MISCINIT">4.6. -Miscellaneous Initialization functions</a></h3> -<p>There are few more functions which are called at initialization -to customize curses behavior. They are not used as extensively as -those mentioned above. Some of them are explained where -appropriate.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="INITEX" id="INITEX">4.7. An -Example</a></h3> -<p>Let's write a program which will clarify the usage of these -functions.</p> -<div class="EXAMPLE"><a name="BINFU" id="BINFU"></a> -<p><b>Example 2. Initialization Function Usage example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> - -int main() -{ int ch; - - initscr(); /* Start curses mode */ - raw(); /* Line buffering disabled */ - keypad(stdscr, TRUE); /* We get F1, F2 etc.. */ - noecho(); /* Don't echo() while we do getch */ - - printw("Type any character to see it in bold\n"); - ch = getch(); /* If raw() hadn't been called - * we have to press enter before it - * gets to the program */ - if(ch == KEY_F(1)) /* Without keypad enabled this will */ - printw("F1 Key pressed");/* not get to us either */ - /* Without noecho() some ugly escape - * charachters might have been printed - * on screen */ - else - { printw("The pressed key is "); - attron(A_BOLD); - printw("%c", ch); - attroff(A_BOLD); - } - refresh(); /* Print it on to the real screen */ - getch(); /* Wait for user input */ - endwin(); /* End curses mode */ - - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>This program is self-explanatory. But I used functions which -aren't explained yet. The function <var class= -"LITERAL">getch()</var> is used to get a character from user. It is -equivalent to normal <var class="LITERAL">getchar()</var> except -that we can disable the line buffering to avoid <enter> after -input. Look for more about <var class="LITERAL">getch()</var>and -reading keys in the <a href="#KEYS">key management section</a> . -The functions attron and attroff are used to switch some attributes -on and off respectively. In the example I used them to print the -character in bold. These functions are explained in detail -later.</p> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="AWORDWINDOWS" id="AWORDWINDOWS">5. A -Word about Windows</a></h2> -<p>Before we plunge into the myriad ncurses functions, let me clear -few things about windows. Windows are explained in detail in -following <a href="#WINDOWS">sections</a></p> -<p>A Window is an imaginary screen defined by curses system. A -window does not mean a bordered window which you usually see on -Win9X platforms. When curses is initialized, it creates a default -window named <var class="LITERAL">stdscr</var> which represents -your 80x25 (or the size of window in which you are running) screen. -If you are doing simple tasks like printing few strings, reading -input etc., you can safely use this single window for all of your -purposes. You can also create windows and call functions which -explicitly work on the specified window.</p> -<p>For example, if you call</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> printw("Hi There !!!"); - refresh();</font> -</pre></td> -</tr> -</table> -<p>It prints the string on stdscr at the present cursor position. -Similarly the call to refresh(), works on stdscr only.</p> -<p>Say you have created <a href="#WINDOWS">windows</a> then you -have to call a function with a 'w' added to the usual function.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> wprintw(win, "Hi There !!!"); - wrefresh(win);</font> -</pre></td> -</tr> -</table> -<p>As you will see in the rest of the document, naming of functions -follow the same convention. For each function there usually are -three more functions.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"> printw(string); /* Print on stdscr at present cursor position */ - mvprintw(y, x, string);/* Move to (y, x) then print string */ - wprintw(win, string); /* Print on window win at present cursor position */ - /* in the window */ - mvwprintw(win, y, x, string); /* Move to (y, x) relative to window */ - /* co-ordinates and then print */</font> -</pre></td> -</tr> -</table> -<p>Usually the w-less functions are macros which expand to -corresponding w-function with stdscr as the window parameter.</p> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="PRINTW" id="PRINTW">6. Output -functions</a></h2> -<p>I guess you can't wait any more to see some action. Back to our -odyssey of curses functions. Now that curses is initialized, let's -interact with world.</p> -<p>There are three classes of functions which you can use to do -output on screen.</p> -<ol type="1"> -<li> -<p>addch() class: Print single character with attributes</p> -</li> -<li> -<p>printw() class: Print formatted output similar to printf()</p> -</li> -<li> -<p>addstr() class: Print strings</p> -</li> -</ol> -<p>These functions can be used interchangeably and it's a matter of -style as to which class is used. Let's see each one in detail.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ADDCHCLASS" id="ADDCHCLASS">6.1. addch() -class of functions</a></h3> -<p>These functions put a single character into the current cursor -location and advance the position of the cursor. You can give the -character to be printed but they usually are used to print a -character with some attributes. Attributes are explained in detail -in later <a href="#ATTRIB">sections</a> of the document. If a -character is associated with an attribute(bold, reverse video -etc.), when curses prints the character, it is printed in that -attribute.</p> -<p>In order to combine a character with some attributes, you have -two options:</p> -<ul> -<li> -<p>By OR'ing a single character with the desired attribute macros. -These attribute macros could be found in the header file -<var class="LITERAL">ncurses.h</var>. For example, you want to -print a character ch(of type char) bold and underlined, you would -call addch() as below.</p> -<table border="0" bgcolor="#E0E0E0" width="90%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> addch(ch | A_BOLD | A_UNDERLINE);</font> -</pre></td> -</tr> -</table> -</li> -<li> -<p>By using functions like <var class= -"LITERAL">attrset(),attron(),attroff()</var>. These functions are -explained in the <a href="#ATTRIB">Attributes</a> section. Briefly, -they manipulate the current attributes of the given window. Once -set, the character printed in the window are associated with the -attributes until it is turned off.</p> -</li> -</ul> -<p>Additionally, <var class="LITERAL">curses</var> provides some -special characters for character-based graphics. You can draw -tables, horizontal or vertical lines, etc. You can find all -avaliable characters in the header file <var class= -"LITERAL">ncurses.h</var>. Try looking for macros beginning with -<var class="LITERAL">ACS_</var> in this file.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="AEN298" id="AEN298">6.2. mvaddch(), -waddch() and mvwaddch()</a></h3> -<p><var class="LITERAL">mvaddch()</var> is used to move the cursor -to a given point, and then print. Thus, the calls:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"> move(row,col); /* moves the cursor to row<em>th</em> row and col<em>th</em> column */ - addch(ch);</font> -</pre></td> -</tr> -</table> -can be replaced by -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> mvaddch(row,col,ch);</font> -</pre></td> -</tr> -</table> -<p><var class="LITERAL">waddch()</var> is similar to <var class= -"LITERAL">addch()</var>, except that it adds a character into the -given window. (Note that <var class="LITERAL">addch()</var> adds a -character into the window <var class="LITERAL">stdscr</var>.)</p> -<p>In a similar fashion <var class="LITERAL">mvwaddch()</var> -function is used to add a character into the given window at the -given coordinates.</p> -<p>Now, we are familiar with the basic output function <var class= -"LITERAL">addch()</var>. But, if we want to print a string, it -would be very annoying to print it character by character. -Fortunately, <var class="LITERAL">ncurses</var> provides -<var class="LITERAL">printf</var><em>-like</em> or <var class= -"LITERAL">puts</var><em>-like</em> functions.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="PRINTWCLASS" id="PRINTWCLASS">6.3. -printw() class of functions</a></h3> -<p>These functions are similar to <var class= -"LITERAL">printf()</var> with the added capability of printing at -any position on the screen.</p> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="PRINTWMVPRINTW" id= -"PRINTWMVPRINTW">6.3.1. printw() and mvprintw</a></h4> -<p>These two functions work much like <var class= -"LITERAL">printf()</var>. <var class="LITERAL">mvprintw()</var> can -be used to move the cursor to a position and then print. If you -want to move the cursor first and then print using <var class= -"LITERAL">printw()</var> function, use <var class= -"LITERAL">move()</var> first and then use <var class= -"LITERAL">printw()</var> though I see no point why one should avoid -using <var class="LITERAL">mvprintw()</var>, you have the -flexibility to manipulate.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="WPRINTWMVWPRINTW" id= -"WPRINTWMVWPRINTW">6.3.2. wprintw() and mvwprintw</a></h4> -<p>These two functions are similar to above two except that they -print in the corresponding window given as argument.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="VWPRINTW" id="VWPRINTW">6.3.3. -vwprintw()</a></h4> -<p>This function is similar to <var class= -"LITERAL">vprintf()</var>. This can be used when variable number of -arguments are to be printed.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="SIMPLEPRINTWEX" id= -"SIMPLEPRINTWEX">6.3.4. A Simple printw example</a></h4> -<div class="EXAMPLE"><a name="BPREX" id="BPREX"></a> -<p><b>Example 3. A Simple printw example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> /* ncurses.h includes stdio.h */ -#include <string.h> - -int main() -{ - char mesg[]="Just a string"; /* message to be appeared on the screen */ - int row,col; /* to store the number of rows and * - * the number of colums of the screen */ - initscr(); /* start the curses mode */ - getmaxyx(stdscr,row,col); /* get the number of rows and columns */ - mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg); - /* print the message at the center of the screen */ - mvprintw(row-2,0,"This screen has %d rows and %d columns\n",row,col); - printw("Try resizing your window(if possible) and then run this program again"); - refresh(); - getch(); - endwin(); - - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>Above program demonstrates how easy it is to use <var class= -"LITERAL">printw</var>. You just feed the coordinates and the -message to be appeared on the screen, then it does what you -want.</p> -<p>The above program introduces us to a new function <var class= -"LITERAL">getmaxyx()</var>, a macro defined in <var class= -"LITERAL">ncurses.h</var>. It gives the number of columns and the -number of rows in a given window. <var class= -"LITERAL">getmaxyx()</var> does this by updating the variables -given to it. Since <var class="LITERAL">getmaxyx()</var> is not a -function we don't pass pointers to it, we just give two integer -variables.</p> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ADDSTRCLASS" id="ADDSTRCLASS">6.4. -addstr() class of functions</a></h3> -<p><var class="LITERAL">addstr()</var> is used to put a character -string into a given window. This function is similar to calling -<var class="LITERAL">addch()</var> once for each character in a -given string. This is true for all output functions. There are -other functions from this family such as <var class= -"LITERAL">mvaddstr(),mvwaddstr()</var> and <var class= -"LITERAL">waddstr()</var>, which obey the naming convention of -curses.(e.g. mvaddstr() is similar to the respective calls move() -and then addstr().) Another function of this family is addnstr(), -which takes an integer parameter(say n) additionally. This function -puts at most n characters into the screen. If n is negative, then -the entire string will be added.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ACAUTION" id="ACAUTION">6.5. A word of -caution</a></h3> -<p>All these functions take y co-ordinate first and then x in their -arguments. A common mistake by beginners is to pass x,y in that -order. If you are doing too many manipulations of (y,x) -co-ordinates, think of dividing the screen into windows and -manipulate each one separately. Windows are explained in the -<a href="#WINDOWS">windows</a> section.</p> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="SCANW" id="SCANW">7. Input -functions</a></h2> -<p>Well, printing without taking input, is boring. Let's see -functions which allow us to get input from user. These functions -also can be divided into three categories.</p> -<ol type="1"> -<li> -<p>getch() class: Get a character</p> -</li> -<li> -<p>scanw() class: Get formatted input</p> -</li> -<li> -<p>getstr() class: Get strings</p> -</li> -</ol> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="GETCHCLASS" id="GETCHCLASS">7.1. getch() -class of functions</a></h3> -<p>These functions read a single character from the terminal. But -there are several subtle facts to consider. For example if you -don't use the function cbreak(), curses will not read your input -characters contiguously but will begin read them only after a new -line or an EOF is encountered. In order to avoid this, the cbreak() -function must used so that characters are immediately available to -your program. Another widely used function is noecho(). As the name -suggests, when this function is set (used), the characters that are -keyed in by the user will not show up on the screen. The two -functions cbreak() and noecho() are typical examples of key -management. Functions of this genre are explained in the <a href= -"#KEYS">key management section</a> .</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="SCANWCLASS" id="SCANWCLASS">7.2. scanw() -class of functions</a></h3> -<p>These functions are similar to <var class= -"LITERAL">scanf()</var> with the added capability of getting the -input from any location on the screen.</p> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="SCANWMVSCANW" id="SCANWMVSCANW">7.2.1. -scanw() and mvscanw</a></h4> -<p>The usage of these functions is similar to that of <var class= -"LITERAL">sscanf()</var>, where the line to be scanned is provided -by <var class="LITERAL">wgetstr()</var> function. That is, these -functions call to <var class="LITERAL">wgetstr()</var> -function(explained below) and uses the resulting line for a -scan.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="WSCANWMVWSCANW" id= -"WSCANWMVWSCANW">7.2.2. wscanw() and mvwscanw()</a></h4> -<p>These are similar to above two functions except that they read -from a window, which is supplied as one of the arguments to these -functions.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="VWSCANW" id="VWSCANW">7.2.3. -vwscanw()</a></h4> -<p>This function is similar to <var class="LITERAL">vscanf()</var>. -This can be used when a variable number of arguments are to be -scanned.</p> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="GETSTRCLASS" id="GETSTRCLASS">7.3. -getstr() class of functions</a></h3> -<p>These functions are used to get strings from the terminal. In -essence, this function performs the same task as would be achieved -by a series of calls to <var class="LITERAL">getch()</var> until a -newline, carriage return, or end-of-file is received. The resulting -string of characters are pointed to by <var class= -"LITERAL">str</var>, which is a character pointer provided by the -user.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="GETSTREX" id="GETSTREX">7.4. Some -examples</a></h3> -<div class="EXAMPLE"><a name="BSCEX" id="BSCEX"></a> -<p><b>Example 4. A Simple scanw example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> /* ncurses.h includes stdio.h */ -#include <string.h> - -int main() -{ - char mesg[]="Enter a string: "; /* message to be appeared on the screen */ - char str[80]; - int row,col; /* to store the number of rows and * - * the number of colums of the screen */ - initscr(); /* start the curses mode */ - getmaxyx(stdscr,row,col); /* get the number of rows and columns */ - mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg); - /* print the message at the center of the screen */ - getstr(str); - mvprintw(LINES - 2, 0, "You Entered: %s", str); - getch(); - endwin(); - - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="ATTRIB" id="ATTRIB">8. -Attributes</a></h2> -<p>We have seen an example of how attributes can be used to print -characters with some special effects. Attributes, when set -prudently, can present information in an easy, understandable -manner. The following program takes a C file as input and prints -the file with comments in bold. Scan through the code.</p> -<div class="EXAMPLE"><a name="BSIAT" id="BSIAT"></a> -<p><b>Example 5. A Simple Attributes example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">/* pager functionality by Joseph Spainhour" <spainhou@bellsouth.net> */ -#include <ncurses.h> -#include <stdlib.h> - -int main(int argc, char *argv[]) -{ - int ch, prev, row, col; - prev = EOF; - FILE *fp; - int y, x; - - if(argc != 2) - { - printf("Usage: %s <a c file name>\n", argv[0]); - exit(1); - } - fp = fopen(argv[1], "r"); - if(fp == NULL) - { - perror("Cannot open input file"); - exit(1); - } - initscr(); /* Start curses mode */ - getmaxyx(stdscr, row, col); /* find the boundaries of the screeen */ - while((ch = fgetc(fp)) != EOF) /* read the file till we reach the end */ - { - getyx(stdscr, y, x); /* get the current curser position */ - if(y == (row - 1)) /* are we are at the end of the screen */ - { - printw("<-Press Any Key->"); /* tell the user to press a key */ - getch(); - clear(); /* clear the screen */ - move(0, 0); /* start at the beginning of the screen */ - } - if(prev == '/' && ch == '*') /* If it is / and * then only - * switch bold on */ - { - attron(A_BOLD); /* cut bold on */ - getyx(stdscr, y, x); /* get the current curser position */ - move(y, x - 1); /* back up one space */ - printw("%c%c", '/', ch); /* The actual printing is done here */ - } - else - printw("%c", ch); - refresh(); - if(prev == '*' && ch == '/') - attroff(A_BOLD); /* Switch it off once we got * - * and then / */ - prev = ch; - } - endwin(); /* End curses mode */ - fclose(fp); - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>Don't worry about all those initialization and other crap. -Concentrate on the while loop. It reads each character in the file -and searches for the pattern /*. Once it spots the pattern, it -switches the BOLD attribute on with <var class= -"LITERAL">attron()</var> . When we get the pattern */ it is -switched off by <var class="LITERAL">attroff()</var> .</p> -<p>The above program also introduces us to two useful functions -<var class="LITERAL">getyx()</var> and <var class= -"LITERAL">move()</var>. The first function gets the co-ordinates of -the present cursor into the variables y, x. Since getyx() is a -macro we don't have to pass pointers to variables. The function -<var class="LITERAL">move()</var> moves the cursor to the -co-ordinates given to it.</p> -<p>The above program is really a simple one which doesn't do much. -On these lines one could write a more useful program which reads a -C file, parses it and prints it in different colors. One could even -extend it to other languages as well.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ATTRIBDETAILS" id="ATTRIBDETAILS">8.1. -The details</a></h3> -<p>Let's get into more details of attributes. The functions -<var class="LITERAL">attron(), attroff(), attrset()</var> , and -their sister functions <var class="LITERAL">attr_get()</var> etc.. -can be used to switch attributes on/off , get attributes and -produce a colorful display.</p> -<p>The functions attron and attroff take a bit-mask of attributes -and switch them on or off, respectively. The following video -attributes, which are defined in <curses.h> can be passed to -these functions.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> - A_NORMAL Normal display (no highlight) - A_STANDOUT Best highlighting mode of the terminal. - A_UNDERLINE Underlining - A_REVERSE Reverse video - A_BLINK Blinking - A_DIM Half bright - A_BOLD Extra bright or bold - A_PROTECT Protected mode - A_INVIS Invisible or blank mode - A_ALTCHARSET Alternate character set - A_CHARTEXT Bit-mask to extract a character - COLOR_PAIR(n) Color-pair number n - </font> -</pre></td> -</tr> -</table> -<p>The last one is the most colorful one :-) Colors are explained -in the <a href="#color" target="_top">next sections</a>.</p> -<p>We can OR(|) any number of above attributes to get a combined -effect. If you wanted reverse video with blinking characters you -can use</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> attron(A_REVERSE | A_BLINK);</font> -</pre></td> -</tr> -</table> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ATTRONVSATTRSET" id= -"ATTRONVSATTRSET">8.2. attron() vs attrset()</a></h3> -<p>Then what is the difference between attron() and attrset()? -attrset sets the attributes of window whereas attron just switches -on the attribute given to it. So attrset() fully overrides whatever -attributes the window previously had and sets it to the new -attribute(s). Similarly attroff() just switches off the -attribute(s) given to it as an argument. This gives us the -flexibility of managing attributes easily.But if you use them -carelessly you may loose track of what attributes the window has -and garble the display. This is especially true while managing -menus with colors and highlighting. So decide on a consistent -policy and stick to it. You can always use <var class= -"LITERAL">standend()</var> which is equivalent to <var class= -"LITERAL">attrset(A_NORMAL)</var> which turns off all attributes -and brings you to normal mode.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ATTR_GET" id="ATTR_GET">8.3. -attr_get()</a></h3> -<p>The function attr_get() gets the current attributes and color -pair of the window. Though we might not use this as often as the -above functions, this is useful in scanning areas of screen. Say we -wanted to do some complex update on screen and we are not sure what -attribute each character is associated with. Then this function can -be used with either attrset or attron to produce the desired -effect.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ATTR_FUNCS" id="ATTR_FUNCS">8.4. attr_ -functions</a></h3> -<p>There are series of functions like attr_set(), attr_on etc.. -These are similar to above functions except that they take -parameters of type <var class="LITERAL">attr_t</var>.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="WATTRFUNCS" id="WATTRFUNCS">8.5. wattr -functions</a></h3> -<p>For each of the above functions we have a corresponding function -with 'w' which operates on a particular window. The above functions -operate on stdscr.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="CHGAT" id="CHGAT">8.6. chgat() -functions</a></h3> -<p>The function chgat() is listed in the end of the man page -curs_attr. It actually is a useful one. This function can be used -to set attributes for a group of characters without moving. I mean -it !!! without moving the cursor :-) It changes the attributes of a -given number of characters starting at the current cursor -location.</p> -<p>We can give -1 as the character count to update till end of -line. If you want to change attributes of characters from current -position to end of line, just use this.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> chgat(-1, A_REVERSE, 0, NULL);</font> -</pre></td> -</tr> -</table> -<p>This function is useful when changing attributes for characters -that are already on the screen. Move to the character from which -you want to change and change the attribute.</p> -<p>Other functions wchgat(), mvchgat(), wchgat() behave similarly -except that the w functions operate on the particular window. The -mv functions first move the cursor then perform the work given to -them. Actually chgat is a macro which is replaced by a wchgat() -with stdscr as the window. Most of the "w-less" functions are -macros.</p> -<div class="EXAMPLE"><a name="BWICH" id="BWICH"></a> -<p><b>Example 6. Chgat() Usage example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> - -int main(int argc, char *argv[]) -{ initscr(); /* Start curses mode */ - start_color(); /* Start color functionality */ - - init_pair(1, COLOR_CYAN, COLOR_BLACK); - printw("A Big string which i didn't care to type fully "); - mvchgat(0, 0, -1, A_BLINK, 1, NULL); - /* - * First two parameters specify the position at which to start - * Third parameter number of characters to update. -1 means till - * end of line - * Forth parameter is the normal attribute you wanted to give - * to the charcter - * Fifth is the color index. It is the index given during init_pair() - * use 0 if you didn't want color - * Sixth one is always NULL - */ - refresh(); - getch(); - endwin(); /* End curses mode */ - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>This example also introduces us to the color world of curses. -Colors will be explained in detail later. Use 0 for no color.</p> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="WINDOWS" id="WINDOWS">9. -Windows</a></h2> -<p>Windows form the most important concept in curses. You have seen -the standard window stdscr above where all the functions implicitly -operated on this window. Now to make design even a simplest GUI, -you need to resort to windows. The main reason you may want to use -windows is to manipulate parts of the screen separately, for better -efficiency, by updating only the windows that need to be changed -and for a better design. I would say the last reason is the most -important in going for windows. You should always strive for a -better and easy-to-manage design in your programs. If you are -writing big, complex GUIs this is of pivotal importance before you -start doing anything.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="WINDOWBASICS" id="WINDOWBASICS">9.1. The -basics</a></h3> -<p>A Window can be created by calling the function <var class= -"LITERAL">newwin()</var>. It doesn't create any thing on the screen -actually. It allocates memory for a structure to manipulate the -window and updates the structure with data regarding the window -like it's size, beginy, beginx etc.. Hence in curses, a window is -just an abstraction of an imaginary window, which can be -manipulated independent of other parts of screen. The function -newwin() returns a pointer to structure WINDOW, which can be passed -to window related functions like wprintw() etc.. Finally the window -can be destroyed with delwin(). It will deallocate the memory -associated with the window structure.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="LETBEWINDOW" id="LETBEWINDOW">9.2. Let -there be a Window !!!</a></h3> -<p>What fun is it, if a window is created and we can't see it. So -the fun part begins by displaying the window. The function -<var class="LITERAL">box()</var> can be used to draw a border -around the window. Let's explore these functions in more detail in -this example.</p> -<div class="EXAMPLE"><a name="BWIBO" id="BWIBO"></a> -<p><b>Example 7. Window Border example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> - - -WINDOW *create_newwin(int height, int width, int starty, int startx); -void destroy_win(WINDOW *local_win); - -int main(int argc, char *argv[]) -{ WINDOW *my_win; - int startx, starty, width, height; - int ch; - - initscr(); /* Start curses mode */ - cbreak(); /* Line buffering disabled, Pass on - * everty thing to me */ - keypad(stdscr, TRUE); /* I need that nifty F1 */ - - height = 3; - width = 10; - starty = (LINES - height) / 2; /* Calculating for a center placement */ - startx = (COLS - width) / 2; /* of the window */ - printw("Press F1 to exit"); - refresh(); - my_win = create_newwin(height, width, starty, startx); - - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case KEY_LEFT: - destroy_win(my_win); - my_win = create_newwin(height, width, starty,--startx); - break; - case KEY_RIGHT: - destroy_win(my_win); - my_win = create_newwin(height, width, starty,++startx); - break; - case KEY_UP: - destroy_win(my_win); - my_win = create_newwin(height, width, --starty,startx); - break; - case KEY_DOWN: - destroy_win(my_win); - my_win = create_newwin(height, width, ++starty,startx); - break; - } - } - - endwin(); /* End curses mode */ - return 0; -} - -WINDOW *create_newwin(int height, int width, int starty, int startx) -{ WINDOW *local_win; - - local_win = newwin(height, width, starty, startx); - box(local_win, 0 , 0); /* 0, 0 gives default characters - * for the vertical and horizontal - * lines */ - wrefresh(local_win); /* Show that box */ - - return local_win; -} - -void destroy_win(WINDOW *local_win) -{ - /* box(local_win, ' ', ' '); : This won't produce the desired - * result of erasing the window. It will leave it's four corners - * and so an ugly remnant of window. - */ - wborder(local_win, ' ', ' ', ' ',' ',' ',' ',' ',' '); - /* The parameters taken are - * 1. win: the window on which to operate - * 2. ls: character to be used for the left side of the window - * 3. rs: character to be used for the right side of the window - * 4. ts: character to be used for the top side of the window - * 5. bs: character to be used for the bottom side of the window - * 6. tl: character to be used for the top left corner of the window - * 7. tr: character to be used for the top right corner of the window - * 8. bl: character to be used for the bottom left corner of the window - * 9. br: character to be used for the bottom right corner of the window - */ - wrefresh(local_win); - delwin(local_win); -}</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="BORDEREXEXPL" id="BORDEREXEXPL">9.3. -Explanation</a></h3> -<p>Don't scream. I know it's a big example. But I have to explain -some important things here :-). This program creates a rectangular -window that can be moved with left, right, up, down arrow keys. It -repeatedly creates and destroys windows as user press a key. Don't -go beyond the screen limits. Checking for those limits is left as -an exercise for the reader. Let's dissect it by line by line.</p> -<p>The <var class="LITERAL">create_newwin()</var> function creates -a window with <var class="LITERAL">newwin()</var> and displays a -border around it with box. The function <var class= -"LITERAL">destroy_win()</var> first erases the window from screen -by painting a border with ' ' character and then calling -<var class="LITERAL">delwin()</var> to deallocate memory related to -it. Depending on the key the user presses, starty or startx is -changed and a new window is created.</p> -<p>In the destroy_win, as you can see, I used wborder instead of -box. The reason is written in the comments (You missed it. I know. -Read the code :-)). wborder draws a border around the window with -the characters given to it as the 4 corner points and the 4 lines. -To put it clearly, if you have called wborder as below:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"> wborder(win, '|', '|', '-', '-', '+', '+', '+', '+');</font> -</pre></td> -</tr> -</table> -<p>it produces some thing like</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> +------------+ - | | - | | - | | - | | - | | - | | - +------------+</font> -</pre></td> -</tr> -</table> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="OTHERSTUFF" id="OTHERSTUFF">9.4. The -other stuff in the example</a></h3> -<p>You can also see in the above examples, that I have used the -variables COLS, LINES which are initialized to the screen sizes -after initscr(). They can be useful in finding screen dimensions -and finding the center co-ordinate of the screen as above. The -function <var class="LITERAL">getch()</var> as usual gets the key -from keyboard and according to the key it does the corresponding -work. This type of switch- case is very common in any GUI based -programs.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="OTHERBORDERFUNCS" id= -"OTHERBORDERFUNCS">9.5. Other Border functions</a></h3> -<p>Above program is grossly inefficient in that with each press of -a key, a window is destroyed and another is created. So let's write -a more efficient program which uses other border related -functions.</p> -<p>The following program uses <var class="LITERAL">mvhline()</var> -and <var class="LITERAL">mvvline()</var> to achieve similar effect. -These two functions are simple. They create a horizontal or -vertical line of the specified length at the specified -position.</p> -<div class="EXAMPLE"><a name="BOTBO" id="BOTBO"></a> -<p><b>Example 8. More border functions</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> - -typedef struct _win_border_struct { - chtype ls, rs, ts, bs, - tl, tr, bl, br; -}WIN_BORDER; - -typedef struct _WIN_struct { - - int startx, starty; - int height, width; - WIN_BORDER border; -}WIN; - -void init_win_params(WIN *p_win); -void print_win_params(WIN *p_win); -void create_box(WIN *win, bool flag); - -int main(int argc, char *argv[]) -{ WIN win; - int ch; - - initscr(); /* Start curses mode */ - start_color(); /* Start the color functionality */ - cbreak(); /* Line buffering disabled, Pass on - * everty thing to me */ - keypad(stdscr, TRUE); /* I need that nifty F1 */ - noecho(); - init_pair(1, COLOR_CYAN, COLOR_BLACK); - - /* Initialize the window parameters */ - init_win_params(&win); - print_win_params(&win); - - attron(COLOR_PAIR(1)); - printw("Press F1 to exit"); - refresh(); - attroff(COLOR_PAIR(1)); - - create_box(&win, TRUE); - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case KEY_LEFT: - create_box(&win, FALSE); - --win.startx; - create_box(&win, TRUE); - break; - case KEY_RIGHT: - create_box(&win, FALSE); - ++win.startx; - create_box(&win, TRUE); - break; - case KEY_UP: - create_box(&win, FALSE); - --win.starty; - create_box(&win, TRUE); - break; - case KEY_DOWN: - create_box(&win, FALSE); - ++win.starty; - create_box(&win, TRUE); - break; - } - } - endwin(); /* End curses mode */ - return 0; -} -void init_win_params(WIN *p_win) -{ - p_win->height = 3; - p_win->width = 10; - p_win->starty = (LINES - p_win->height)/2; - p_win->startx = (COLS - p_win->width)/2; - - p_win->border.ls = '|'; - p_win->border.rs = '|'; - p_win->border.ts = '-'; - p_win->border.bs = '-'; - p_win->border.tl = '+'; - p_win->border.tr = '+'; - p_win->border.bl = '+'; - p_win->border.br = '+'; - -} -void print_win_params(WIN *p_win) -{ -#ifdef _DEBUG - mvprintw(25, 0, "%d %d %d %d", p_win->startx, p_win->starty, - p_win->width, p_win->height); - refresh(); -#endif -} -void create_box(WIN *p_win, bool flag) -{ int i, j; - int x, y, w, h; - - x = p_win->startx; - y = p_win->starty; - w = p_win->width; - h = p_win->height; - - if(flag == TRUE) - { mvaddch(y, x, p_win->border.tl); - mvaddch(y, x + w, p_win->border.tr); - mvaddch(y + h, x, p_win->border.bl); - mvaddch(y + h, x + w, p_win->border.br); - mvhline(y, x + 1, p_win->border.ts, w - 1); - mvhline(y + h, x + 1, p_win->border.bs, w - 1); - mvvline(y + 1, x, p_win->border.ls, h - 1); - mvvline(y + 1, x + w, p_win->border.rs, h - 1); - - } - else - for(j = y; j <= y + h; ++j) - for(i = x; i <= x + w; ++i) - mvaddch(j, i, ' '); - - refresh(); - -}</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="COLOR" id="COLOR">10. Colors</a></h2> -<div class="SECT2"> -<h3 class="SECT2"><a name="COLORBASICS" id="COLORBASICS">10.1. The -basics</a></h3> -<p>Life seems dull with no colors. Curses has a nice mechanism to -handle colors. Let's get into the thick of the things with a small -program.</p> -<div class="EXAMPLE"><a name="BSICO" id="BSICO"></a> -<p><b>Example 9. A Simple Color example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> - -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string); -int main(int argc, char *argv[]) -{ initscr(); /* Start curses mode */ - if(has_colors() == FALSE) - { endwin(); - printf("Your terminal does not support color\n"); - exit(1); - } - start_color(); /* Start color */ - init_pair(1, COLOR_RED, COLOR_BLACK); - - attron(COLOR_PAIR(1)); - print_in_middle(stdscr, LINES / 2, 0, 0, "Viola !!! In color ..."); - attroff(COLOR_PAIR(1)); - getch(); - endwin(); -} -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - mvwprintw(win, y, x, "%s", string); - refresh(); -} -</span></font> -</pre></td> -</tr> -</table> -</div> -<p>As you can see, to start using color, you should first call the -function <var class="LITERAL">start_color()</var>. After that, you -can use color capabilities of your terminals using various -functions. To find out whether a terminal has color capabilities or -not, you can use <var class="LITERAL">has_colors()</var> function, -which returns FALSE if the terminal does not support color.</p> -<p>Curses initializes all the colors supported by terminal when -start_color() is called. These can be accessed by the define -constants like <var class="LITERAL">COLOR_BLACK</var> etc. Now to -actually start using colors, you have to define pairs. Colors are -always used in pairs. That means you have to use the function -<var class="LITERAL">init_pair()</var> to define the foreground and -background for the pair number you give. After that that pair -number can be used as a normal attribute with <var class= -"LITERAL">COLOR_PAIR()</var>function. This may seem to be -cumbersome at first. But this elegant solution allows us to manage -color pairs very easily. To appreciate it, you have to look into -the the source code of "dialog", a utility for displaying dialog -boxes from shell scripts. The developers have defined foreground -and background combinations for all the colors they might need and -initialized at the beginning. This makes it very easy to set -attributes just by accessing a pair which we already have defined -as a constant.</p> -<p>The following colors are defined in <var class= -"LITERAL">curses.h</var>. You can use these as parameters for -various color functions.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> COLOR_BLACK 0 - COLOR_RED 1 - COLOR_GREEN 2 - COLOR_YELLOW 3 - COLOR_BLUE 4 - COLOR_MAGENTA 5 - COLOR_CYAN 6 - COLOR_WHITE 7</font> -</pre></td> -</tr> -</table> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="CHANGECOLORDEFS" id= -"CHANGECOLORDEFS">10.2. Changing Color Definitions</a></h3> -<p>The function <var class="LITERAL">init_color()</var>can be used -to change the rgb values for the colors defined by curses -initially. Say you wanted to lighten the intensity of red color by -a minuscule. Then you can use this function as</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> init_color(COLOR_RED, 700, 0, 0); - /* param 1 : color name - * param 2, 3, 4 : rgb content min = 0, max = 1000 */</font> -</pre></td> -</tr> -</table> -<p>If your terminal cannot change the color definitions, the -function returns ERR. The function <var class= -"LITERAL">can_change_color()</var> can be used to find out whether -the terminal has the capability of changing color content or not. -The rgb content is scaled from 0 to 1000. Initially RED color is -defined with content 1000(r), 0(g), 0(b).</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="COLORCONTENT" id="COLORCONTENT">10.3. -Color Content</a></h3> -<p>The functions <var class="LITERAL">color_content()</var> and -<var class="LITERAL">pair_content()</var> can be used to find the -color content and foreground, background combination for the -pair.</p> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="KEYS" id="KEYS">11. Interfacing with the -key board</a></h2> -<div class="SECT2"> -<h3 class="SECT2"><a name="KEYSBASICS" id="KEYSBASICS">11.1. The -Basics</a></h3> -<p>No GUI is complete without a strong user interface and to -interact with the user, a curses program should be sensitive to key -presses or the mouse actions done by the user. Let's deal with the -keys first.</p> -<p>As you have seen in almost all of the above examples, it's very -easy to get key input from the user. A simple way of getting key -presses is to use <var class="LITERAL">getch()</var> function. The -cbreak mode should be enabled to read keys when you are interested -in reading individual key hits rather than complete lines of text -(which usually end with a carriage return). keypad should be -enabled to get the Functions keys, arrow keys etc. See the -initialization section for details.</p> -<p><var class="LITERAL">getch()</var> returns an integer -corresponding to the key pressed. If it is a normal character, the -integer value will be equivalent to the character. Otherwise it -returns a number which can be matched with the constants defined in -<var class="LITERAL">curses.h</var>. For example if the user -presses F1, the integer returned is 265. This can be checked using -the macro KEY_F() defined in curses.h. This makes reading keys -portable and easy to manage.</p> -<p>For example, if you call getch() like this</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> int ch; - - ch = getch();</font> -</pre></td> -</tr> -</table> -<p>getch() will wait for the user to press a key, (unless you -specified a timeout) and when user presses a key, the corresponding -integer is returned. Then you can check the value returned with the -constants defined in curses.h to match against the keys you -want.</p> -<p>The following code piece will do that job.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> if(ch == KEY_LEFT) - printw("Left arrow is pressed\n");</font> -</pre></td> -</tr> -</table> -<p>Let's write a small program which creates a menu which can be -navigated by up and down arrows.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="SIMPLEKEYEX" id="SIMPLEKEYEX">11.2. A -Simple Key Usage example</a></h3> -<div class="EXAMPLE"><a name="BSIKE" id="BSIKE"></a> -<p><b>Example 10. A Simple Key Usage example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <stdio.h> -#include <ncurses.h> - -#define WIDTH 30 -#define HEIGHT 10 - -int startx = 0; -int starty = 0; - -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Exit", - }; -int n_choices = sizeof(choices) / sizeof(char *); -void print_menu(WINDOW *menu_win, int highlight); - -int main() -{ WINDOW *menu_win; - int highlight = 1; - int choice = 0; - int c; - - initscr(); - clear(); - noecho(); - cbreak(); /* Line buffering disabled. pass on everything */ - startx = (80 - WIDTH) / 2; - starty = (24 - HEIGHT) / 2; - - menu_win = newwin(HEIGHT, WIDTH, starty, startx); - keypad(menu_win, TRUE); - mvprintw(0, 0, "Use arrow keys to go up and down, Press enter to select a choice"); - refresh(); - print_menu(menu_win, highlight); - while(1) - { c = wgetch(menu_win); - switch(c) - { case KEY_UP: - if(highlight == 1) - highlight = n_choices; - else - --highlight; - break; - case KEY_DOWN: - if(highlight == n_choices) - highlight = 1; - else - ++highlight; - break; - case 10: - choice = highlight; - break; - default: - mvprintw(24, 0, "Charcter pressed is = %3d Hopefully it can be printed as '%c'", c, c); - refresh(); - break; - } - print_menu(menu_win, highlight); - if(choice != 0) /* User did a choice come out of the infinite loop */ - break; - } - mvprintw(23, 0, "You chose choice %d with choice string %s\n", choice, choices[choice - 1]); - clrtoeol(); - refresh(); - endwin(); - return 0; -} - - -void print_menu(WINDOW *menu_win, int highlight) -{ - int x, y, i; - - x = 2; - y = 2; - box(menu_win, 0, 0); - for(i = 0; i < n_choices; ++i) - { if(highlight == i + 1) /* High light the present choice */ - { wattron(menu_win, A_REVERSE); - mvwprintw(menu_win, y, x, "%s", choices[i]); - wattroff(menu_win, A_REVERSE); - } - else - mvwprintw(menu_win, y, x, "%s", choices[i]); - ++y; - } - wrefresh(menu_win); -} -</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="MOUSE" id="MOUSE">12. Interfacing with -the mouse</a></h2> -<p>Now that you have seen how to get keys, lets do the same thing -from mouse. Usually each UI allows the user to interact with both -keyboard and mouse.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MOUSEBASICS" id="MOUSEBASICS">12.1. The -Basics</a></h3> -<p>Before you do any thing else, the events you want to receive -have to be enabled with <var class="LITERAL">mousemask()</var>.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"> mousemask( mmask_t newmask, /* The events you want to listen to */ - mmask_t *oldmask) /* The old events mask */</font> -</pre></td> -</tr> -</table> -<p>The first parameter to above function is a bit mask of events -you would like to listen. By default, all the events are turned -off. The bit mask <var class="LITERAL">ALL_MOUSE_EVENTS</var> can -be used to get all the events.</p> -<p>The following are all the event masks:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> Name Description - --------------------------------------------------------------------- - BUTTON1_PRESSED mouse button 1 down - BUTTON1_RELEASED mouse button 1 up - BUTTON1_CLICKED mouse button 1 clicked - BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked - BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked - BUTTON2_PRESSED mouse button 2 down - BUTTON2_RELEASED mouse button 2 up - BUTTON2_CLICKED mouse button 2 clicked - BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked - BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked - BUTTON3_PRESSED mouse button 3 down - BUTTON3_RELEASED mouse button 3 up - BUTTON3_CLICKED mouse button 3 clicked - BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked - BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked - BUTTON4_PRESSED mouse button 4 down - BUTTON4_RELEASED mouse button 4 up - BUTTON4_CLICKED mouse button 4 clicked - BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked - BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked - BUTTON_SHIFT shift was down during button state change - BUTTON_CTRL control was down during button state change - BUTTON_ALT alt was down during button state change - ALL_MOUSE_EVENTS report all button state changes - REPORT_MOUSE_POSITION report mouse movement</font> -</pre></td> -</tr> -</table> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="GETTINGEVENTS" id="GETTINGEVENTS">12.2. -Getting the events</a></h3> -<p>Once a class of mouse events have been enabled, getch() class of -functions return KEY_MOUSE every time some mouse event happens. -Then the mouse event can be retrieved with <var class= -"LITERAL">getmouse()</var>.</p> -<p>The code approximately looks like this:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> MEVENT event; - - ch = getch(); - if(ch == KEY_MOUSE) - if(getmouse(&event) == OK) - . /* Do some thing with the event */ - . - .</font> -</pre></td> -</tr> -</table> -<p>getmouse() returns the event into the pointer given to it. It's -a structure which contains</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> typedef struct - { - short id; /* ID to distinguish multiple devices */ - int x, y, z; /* event coordinates */ - mmask_t bstate; /* button state bits */ - } </font> -</pre></td> -</tr> -</table> -<p>The <var class="LITERAL">bstate</var> is the main variable we -are interested in. It tells the button state of the mouse.</p> -<p>Then with a code snippet like the following, we can find out -what happened.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> if(event.bstate & BUTTON1_PRESSED) - printw("Left Button Pressed");</font> -</pre></td> -</tr> -</table> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MOUSETOGETHER" id="MOUSETOGETHER">12.3. -Putting it all Together</a></h3> -<p>That's pretty much interfacing with mouse. Let's create the same -menu and enable mouse interaction. To make things simpler, key -handling is removed.</p> -<div class="EXAMPLE"><a name="BMOME" id="BMOME"></a> -<p><b>Example 11. Access the menu with mouse !!!</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> - -#define WIDTH 30 -#define HEIGHT 10 - -int startx = 0; -int starty = 0; - -char *choices[] = { "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Exit", - }; - -int n_choices = sizeof(choices) / sizeof(char *); - -void print_menu(WINDOW *menu_win, int highlight); -void report_choice(int mouse_x, int mouse_y, int *p_choice); - -int main() -{ int c, choice = 0; - WINDOW *menu_win; - MEVENT event; - - /* Initialize curses */ - initscr(); - clear(); - noecho(); - cbreak(); //Line buffering disabled. pass on everything - - /* Try to put the window in the middle of screen */ - startx = (80 - WIDTH) / 2; - starty = (24 - HEIGHT) / 2; - - attron(A_REVERSE); - mvprintw(23, 1, "Click on Exit to quit (Works best in a virtual console)"); - refresh(); - attroff(A_REVERSE); - - /* Print the menu for the first time */ - menu_win = newwin(HEIGHT, WIDTH, starty, startx); - print_menu(menu_win, 1); - /* Get all the mouse events */ - mousemask(ALL_MOUSE_EVENTS, NULL); - - while(1) - { c = wgetch(menu_win); - switch(c) - { case KEY_MOUSE: - if(getmouse(&event) == OK) - { /* When the user clicks left mouse button */ - if(event.bstate & BUTTON1_PRESSED) - { report_choice(event.x + 1, event.y + 1, &choice); - if(choice == -1) //Exit chosen - goto end; - mvprintw(22, 1, "Choice made is : %d String Chosen is \"%10s\"", choice, choices[choice - 1]); - refresh(); - } - } - print_menu(menu_win, choice); - break; - } - } -end: - endwin(); - return 0; -} - - -void print_menu(WINDOW *menu_win, int highlight) -{ - int x, y, i; - - x = 2; - y = 2; - box(menu_win, 0, 0); - for(i = 0; i < n_choices; ++i) - { if(highlight == i + 1) - { wattron(menu_win, A_REVERSE); - mvwprintw(menu_win, y, x, "%s", choices[i]); - wattroff(menu_win, A_REVERSE); - } - else - mvwprintw(menu_win, y, x, "%s", choices[i]); - ++y; - } - wrefresh(menu_win); -} - -/* Report the choice according to mouse position */ -void report_choice(int mouse_x, int mouse_y, int *p_choice) -{ int i,j, choice; - - i = startx + 2; - j = starty + 3; - - for(choice = 0; choice < n_choices; ++choice) - if(mouse_y == j + choice && mouse_x >= i && mouse_x <= i + strlen(choices[choice])) - { if(choice == n_choices - 1) - *p_choice = -1; - else - *p_choice = choice + 1; - break; - } -}</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MISCMOUSEFUNCS" id= -"MISCMOUSEFUNCS">12.4. Miscellaneous Functions</a></h3> -<p>The functions mouse_trafo() and wmouse_trafo() can be used to -convert to mouse co-ordinates to screen relative co-ordinates. See -curs_mouse(3X) man page for details.</p> -<p>The mouseinterval function sets the maximum time (in thousands -of a second) that can elapse between press and release events in -order for them to be recognized as a click. This function returns -the previous interval value. The default is one fifth of a -second.</p> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="SCREEN" id="SCREEN">13. Screen -Manipulation</a></h2> -<p>In this section, we will look into some functions, which allow -us to manage the screen efficiently and to write some fancy -programs. This is especially important in writing games.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="GETYX" id="GETYX">13.1. getyx() -functions</a></h3> -<p>The function <var class="LITERAL">getyx()</var> can be used to -find out the present cursor co-ordinates. It will fill the values -of x and y co-ordinates in the arguments given to it. Since getyx() -is a macro you don't have to pass the address of the variables. It -can be called as</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> getyx(win, y, x); - /* win: window pointer - * y, x: y, x co-ordinates will be put into this variables - */</font> -</pre></td> -</tr> -</table> -<p>The function getparyx() gets the beginning co-ordinates of the -sub window relative to the main window. This is some times useful -to update a sub window. When designing fancy stuff like writing -multiple menus, it becomes difficult to store the menu positions, -their first option co-ordinates etc. A simple solution to this -problem, is to create menus in sub windows and later find the -starting co-ordinates of the menus by using getparyx().</p> -<p>The functions getbegyx() and getmaxyx() store current window's -beginning and maximum co-ordinates. These functions are useful in -the same way as above in managing the windows and sub windows -effectively.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="SCREENDUMP" id="SCREENDUMP">13.2. Screen -Dumping</a></h3> -<p>While writing games, some times it becomes necessary to store -the state of the screen and restore it back to the same state. The -function scr_dump() can be used to dump the screen contents to a -file given as an argument. Later it can be restored by scr_restore -function. These two simple functions can be used effectively to -maintain a fast moving game with changing scenarios.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="WINDOWDUMP" id="WINDOWDUMP">13.3. Window -Dumping</a></h3> -<p>To store and restore windows, the functions <var class= -"LITERAL">putwin()</var> and <var class="LITERAL">getwin()</var> -can be used. <var class="LITERAL">putwin()</var> puts the present -window state into a file, which can be later restored by -<var class="LITERAL">getwin()</var>.</p> -<p>The function <var class="LITERAL">copywin()</var> can be used to -copy a window completely onto another window. It takes the source -and destination windows as parameters and according to the -rectangle specified, it copies the rectangular region from source -to destination window. It's last parameter specifies whether to -overwrite or just overlay the contents on to the destination -window. If this argument is true, then the copying is -non-destructive.</p> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="MISC" id="MISC">14. Miscellaneous -features</a></h2> -<p>Now you know enough features to write a good curses program, -with all bells and whistles. There are some miscellaneous functions -which are useful in various cases. Let's go headlong into some of -those.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="CURSSET" id="CURSSET">14.1. -curs_set()</a></h3> -<p>This function can be used to make the cursor invisible. The -parameter to this function should be</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> 0 : invisible or - 1 : normal or - 2 : very visible.</font> -</pre></td> -</tr> -</table> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="TEMPLEAVE" id="TEMPLEAVE">14.2. -Temporarily Leaving Curses mode</a></h3> -<p>Some times you may want to get back to cooked mode (normal line -buffering mode) temporarily. In such a case you will first need to -save the tty modes with a call to <var class= -"LITERAL">def_prog_mode()</var> and then call <var class= -"LITERAL">endwin()</var> to end the curses mode. This will leave -you in the original tty mode. To get back to curses once you are -done, call <var class="LITERAL">reset_prog_mode()</var> . This -function returns the tty to the state stored by <var class= -"LITERAL">def_prog_mode()</var>. Then do refresh(), and you are -back to the curses mode. Here is an example showing the sequence of -things to be done.</p> -<div class="EXAMPLE"><a name="BTELE" id="BTELE"></a> -<p><b>Example 12. Temporarily Leaving Curses Mode</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> - -int main() -{ - initscr(); /* Start curses mode */ - printw("Hello World !!!\n"); /* Print Hello World */ - refresh(); /* Print it on to the real screen */ - def_prog_mode(); /* Save the tty modes */ - endwin(); /* End curses mode temporarily */ - system("/bin/sh"); /* Do whatever you like in cooked mode */ - reset_prog_mode(); /* Return to the previous tty mode*/ - /* stored by def_prog_mode() */ - refresh(); /* Do refresh() to restore the */ - /* Screen contents */ - printw("Another String\n"); /* Back to curses use the full */ - refresh(); /* capabilities of curses */ - endwin(); /* End curses mode */ - - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="ACSVARS" id="ACSVARS">14.3. ACS_ -variables</a></h3> -<p>If you have ever programmed in DOS, you know about those nifty -characters in extended character set. They are printable only on -some terminals. NCURSES functions like <var class= -"LITERAL">box()</var> use these characters. All these variables -start with ACS meaning alternative character set. You might have -noticed me using these characters in some of the programs above. -Here's an example showing all the characters.</p> -<div class="EXAMPLE"><a name="BACSVARS" id="BACSVARS"></a> -<p><b>Example 13. ACS Variables Example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <ncurses.h> - -int main() -{ - initscr(); - - printw("Upper left corner "); addch(ACS_ULCORNER); printw("\n"); - printw("Lower left corner "); addch(ACS_LLCORNER); printw("\n"); - printw("Lower right corner "); addch(ACS_LRCORNER); printw("\n"); - printw("Tee pointing right "); addch(ACS_LTEE); printw("\n"); - printw("Tee pointing left "); addch(ACS_RTEE); printw("\n"); - printw("Tee pointing up "); addch(ACS_BTEE); printw("\n"); - printw("Tee pointing down "); addch(ACS_TTEE); printw("\n"); - printw("Horizontal line "); addch(ACS_HLINE); printw("\n"); - printw("Vertical line "); addch(ACS_VLINE); printw("\n"); - printw("Large Plus or cross over "); addch(ACS_PLUS); printw("\n"); - printw("Scan Line 1 "); addch(ACS_S1); printw("\n"); - printw("Scan Line 3 "); addch(ACS_S3); printw("\n"); - printw("Scan Line 7 "); addch(ACS_S7); printw("\n"); - printw("Scan Line 9 "); addch(ACS_S9); printw("\n"); - printw("Diamond "); addch(ACS_DIAMOND); printw("\n"); - printw("Checker board (stipple) "); addch(ACS_CKBOARD); printw("\n"); - printw("Degree Symbol "); addch(ACS_DEGREE); printw("\n"); - printw("Plus/Minus Symbol "); addch(ACS_PLMINUS); printw("\n"); - printw("Bullet "); addch(ACS_BULLET); printw("\n"); - printw("Arrow Pointing Left "); addch(ACS_LARROW); printw("\n"); - printw("Arrow Pointing Right "); addch(ACS_RARROW); printw("\n"); - printw("Arrow Pointing Down "); addch(ACS_DARROW); printw("\n"); - printw("Arrow Pointing Up "); addch(ACS_UARROW); printw("\n"); - printw("Board of squares "); addch(ACS_BOARD); printw("\n"); - printw("Lantern Symbol "); addch(ACS_LANTERN); printw("\n"); - printw("Solid Square Block "); addch(ACS_BLOCK); printw("\n"); - printw("Less/Equal sign "); addch(ACS_LEQUAL); printw("\n"); - printw("Greater/Equal sign "); addch(ACS_GEQUAL); printw("\n"); - printw("Pi "); addch(ACS_PI); printw("\n"); - printw("Not equal "); addch(ACS_NEQUAL); printw("\n"); - printw("UK pound sign "); addch(ACS_STERLING); printw("\n"); - - refresh(); - getch(); - endwin(); - - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="OTHERLIB" id="OTHERLIB">15. Other -libraries</a></h2> -<p>Apart from the curses library, there are few text mode -libraries, which provide more functionality and a lot of features. -The following sections explain three standard libraries which are -usually distributed along with curses.</p> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="PANELS" id="PANELS">16. Panel -Library</a></h2> -<p>Now that you are proficient in curses, you wanted to do some -thing big. You created a lot of overlapping windows to give a -professional windows-type look. Unfortunately, it soon becomes -difficult to manage these. The multiple refreshes, updates plunge -you into a nightmare. The overlapping windows create blotches, -whenever you forget to refresh the windows in the proper order.</p> -<p>Don't despair. There's an elegant solution provided in panels -library. In the words of developers of ncurses</p> -<p><em>When your interface design is such that windows may dive -deeper into the visibility stack or pop to the top at runtime, the -resulting book-keeping can be tedious and difficult to get right. -Hence the panels library.</em></p> -<p>If you have lot of overlapping windows, then panels library is -the way to go. It obviates the need of doing series of -wnoutrefresh(), doupdate() and relieves the burden of doing it -correctly(bottom up). The library maintains information about the -order of windows, their overlapping and update the screen properly. -So why wait? Let's take a close peek into panels.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="PANELBASICS" id="PANELBASICS">16.1. The -Basics</a></h3> -<p>Panel object is a window that is implicitly treated as part of a -deck including all other panel objects. The deck is treated as a -stack with the top panel being completely visible and the other -panels may or may not be obscured according to their positions. So -the basic idea is to create a stack of overlapping panels and use -panels library to display them correctly. There is a function -similar to refresh() which, when called , displays panels in the -correct order. Functions are provided to hide or show panels, move -panels, change its size etc.. The overlapping problem is managed by -the panels library during all the calls to these functions.</p> -<p>The general flow of a panel program goes like this:</p> -<ol type="1"> -<li> -<p>Create the windows (with newwin()) to be attached to the -panels.</p> -</li> -<li> -<p>Create panels with the chosen visibility order. Stack them up -according to the desired visibility. The function new_panel() is -used to created panels.</p> -</li> -<li> -<p>Call update_panels() to write the panels to the virtual screen -in correct visibility order. Do a doupdate() to show it on the -screen.</p> -</li> -<li> -<p>Mainpulate the panels with show_panel(), hide_panel(), -move_panel() etc. Make use of helper functions like panel_hidden() -and panel_window(). Make use of user pointer to store custom data -for a panel. Use the functions set_panel_userptr() and -panel_userptr() to set and get the user pointer for a panel.</p> -</li> -<li> -<p>When you are done with the panel use del_panel() to delete the -panel.</p> -</li> -</ol> -<p>Let's make the concepts clear, with some programs. The following -is a simple program which creates 3 overlapping panels and shows -them on the screen.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="COMPILEPANELS" id="COMPILEPANELS">16.2. -Compiling With the Panels Library</a></h3> -<p>To use panels library functions, you have to include panel.h and -to link the program with panels library the flag -lpanel should be -added along with -lncurses in that order.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> #include <panel.h> - . - . - . - - compile and link: gcc <program file> -lpanel -lncurses</font> -</pre></td> -</tr> -</table> -<div class="EXAMPLE"><a name="PPASI" id="PPASI"></a> -<p><b>Example 14. Panel basics</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <panel.h> - -int main() -{ WINDOW *my_wins[3]; - PANEL *my_panels[3]; - int lines = 10, cols = 40, y = 2, x = 4, i; - - initscr(); - cbreak(); - noecho(); - - /* Create windows for the panels */ - my_wins[0] = newwin(lines, cols, y, x); - my_wins[1] = newwin(lines, cols, y + 1, x + 5); - my_wins[2] = newwin(lines, cols, y + 2, x + 10); - - /* - * Create borders around the windows so that you can see the effect - * of panels - */ - for(i = 0; i < 3; ++i) - box(my_wins[i], 0, 0); - - /* Attach a panel to each window */ /* Order is bottom up */ - my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ - my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ - my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ - - /* Update the stacking order. 2nd panel will be on top */ - update_panels(); - - /* Show it on the screen */ - doupdate(); - - getch(); - endwin(); -} -</span></font> -</pre></td> -</tr> -</table> -</div> -<p>As you can see, above program follows a simple flow as -explained. The windows are created with newwin() and then they are -attached to panels with new_panel(). As we attach one panel after -another, the stack of panels gets updated. To put them on screen -update_panels() and doupdate() are called.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="PANELBROWSING" id="PANELBROWSING">16.3. -Panel Window Browsing</a></h3> -<p>A slightly complicated example is given below. This program -creates 3 windows which can be cycled through using tab. Have a -look at the code.</p> -<div class="EXAMPLE"><a name="PPABR" id="PPABR"></a> -<p><b>Example 15. Panel Window Browsing Example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <panel.h> - -#define NLINES 10 -#define NCOLS 40 - -void init_wins(WINDOW **wins, int n); -void win_show(WINDOW *win, char *label, int label_color); -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); - -int main() -{ WINDOW *my_wins[3]; - PANEL *my_panels[3]; - PANEL *top; - int ch; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize all the colors */ - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_BLUE, COLOR_BLACK); - init_pair(4, COLOR_CYAN, COLOR_BLACK); - - init_wins(my_wins, 3); - - /* Attach a panel to each window */ /* Order is bottom up */ - my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ - my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ - my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ - - /* Set up the user pointers to the next panel */ - set_panel_userptr(my_panels[0], my_panels[1]); - set_panel_userptr(my_panels[1], my_panels[2]); - set_panel_userptr(my_panels[2], my_panels[0]); - - /* Update the stacking order. 2nd panel will be on top */ - update_panels(); - - /* Show it on the screen */ - attron(COLOR_PAIR(4)); - mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)"); - attroff(COLOR_PAIR(4)); - doupdate(); - - top = my_panels[2]; - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case 9: - top = (PANEL *)panel_userptr(top); - top_panel(top); - break; - } - update_panels(); - doupdate(); - } - endwin(); - return 0; -} - -/* Put all the windows */ -void init_wins(WINDOW **wins, int n) -{ int x, y, i; - char label[80]; - - y = 2; - x = 10; - for(i = 0; i < n; ++i) - { wins[i] = newwin(NLINES, NCOLS, y, x); - sprintf(label, "Window Number %d", i + 1); - win_show(wins[i], label, i + 1); - y += 3; - x += 7; - } -} - -/* Show the window with a border and a label */ -void win_show(WINDOW *win, char *label, int label_color) -{ int startx, starty, height, width; - - getbegyx(win, starty, startx); - getmaxyx(win, height, width); - - box(win, 0, 0); - mvwaddch(win, 2, 0, ACS_LTEE); - mvwhline(win, 2, 1, ACS_HLINE, width - 2); - mvwaddch(win, 2, width - 1, ACS_RTEE); - - print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color)); -} - -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); -}</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="USERPTRUSING" id="USERPTRUSING">16.4. -Using User Pointers</a></h3> -<p>In the above example I used user pointers to find out the next -window in the cycle. We can attach custom information to the panel -by specifying a user pointer, which can point to any information -you want to store. In this case I stored the pointer to the next -panel in the cycle. User pointer for a panel can be set with the -function <var class="LITERAL">set_panel_userptr()</var>. It can be -accessed using the function <var class= -"LITERAL">panel_userptr()</var> which will return the user pointer -for the panel given as argument. After finding the next panel in -the cycle It's brought to the top by the function top_panel(). This -function brings the panel given as argument to the top of the panel -stack.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="PANELMOVERESIZE" id= -"PANELMOVERESIZE">16.5. Moving and Resizing Panels</a></h3> -<p>The function <var class="LITERAL">move_panel()</var> can be used -to move a panel to the desired location. It does not change the -position of the panel in the stack. Make sure that you use -move_panel() instead mvwin() on the window associated with the -panel.</p> -<p>Resizing a panel is slightly complex. There is no straight -forward function just to resize the window associated with a panel. -A solution to resize a panel is to create a new window with the -desired sizes, change the window associated with the panel using -replace_panel(). Don't forget to delete the old window. The window -associated with a panel can be found by using the function -panel_window().</p> -<p>The following program shows these concepts, in supposedly simple -program. You can cycle through the window with <TAB> as -usual. To resize or move the active panel press 'r' for resize 'm' -for moving. Then use arrow keys to resize or move it to the desired -way and press enter to end your resizing or moving. This example -makes use of user data to get the required data to do the -operations.</p> -<div class="EXAMPLE"><a name="PPARE" id="PPARE"></a> -<p><b>Example 16. Panel Moving and Resizing example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <panel.h> - -typedef struct _PANEL_DATA { - int x, y, w, h; - char label[80]; - int label_color; - PANEL *next; -}PANEL_DATA; - -#define NLINES 10 -#define NCOLS 40 - -void init_wins(WINDOW **wins, int n); -void win_show(WINDOW *win, char *label, int label_color); -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); -void set_user_ptrs(PANEL **panels, int n); - -int main() -{ WINDOW *my_wins[3]; - PANEL *my_panels[3]; - PANEL_DATA *top; - PANEL *stack_top; - WINDOW *temp_win, *old_win; - int ch; - int newx, newy, neww, newh; - int size = FALSE, move = FALSE; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize all the colors */ - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_BLUE, COLOR_BLACK); - init_pair(4, COLOR_CYAN, COLOR_BLACK); - - init_wins(my_wins, 3); - - /* Attach a panel to each window */ /* Order is bottom up */ - my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ - my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ - my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ - - set_user_ptrs(my_panels, 3); - /* Update the stacking order. 2nd panel will be on top */ - update_panels(); - - /* Show it on the screen */ - attron(COLOR_PAIR(4)); - mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing"); - mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)"); - attroff(COLOR_PAIR(4)); - doupdate(); - - stack_top = my_panels[2]; - top = (PANEL_DATA *)panel_userptr(stack_top); - newx = top->x; - newy = top->y; - neww = top->w; - newh = top->h; - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case 9: /* Tab */ - top = (PANEL_DATA *)panel_userptr(stack_top); - top_panel(top->next); - stack_top = top->next; - top = (PANEL_DATA *)panel_userptr(stack_top); - newx = top->x; - newy = top->y; - neww = top->w; - newh = top->h; - break; - case 'r': /* Re-Size*/ - size = TRUE; - attron(COLOR_PAIR(4)); - mvprintw(LINES - 4, 0, "Entered Resizing :Use Arrow Keys to resize and press <ENTER> to end resizing"); - refresh(); - attroff(COLOR_PAIR(4)); - break; - case 'm': /* Move */ - attron(COLOR_PAIR(4)); - mvprintw(LINES - 4, 0, "Entered Moving: Use Arrow Keys to Move and press <ENTER> to end moving"); - refresh(); - attroff(COLOR_PAIR(4)); - move = TRUE; - break; - case KEY_LEFT: - if(size == TRUE) - { --newx; - ++neww; - } - if(move == TRUE) - --newx; - break; - case KEY_RIGHT: - if(size == TRUE) - { ++newx; - --neww; - } - if(move == TRUE) - ++newx; - break; - case KEY_UP: - if(size == TRUE) - { --newy; - ++newh; - } - if(move == TRUE) - --newy; - break; - case KEY_DOWN: - if(size == TRUE) - { ++newy; - --newh; - } - if(move == TRUE) - ++newy; - break; - case 10: /* Enter */ - move(LINES - 4, 0); - clrtoeol(); - refresh(); - if(size == TRUE) - { old_win = panel_window(stack_top); - temp_win = newwin(newh, neww, newy, newx); - replace_panel(stack_top, temp_win); - win_show(temp_win, top->label, top->label_color); - delwin(old_win); - size = FALSE; - } - if(move == TRUE) - { move_panel(stack_top, newy, newx); - move = FALSE; - } - break; - - } - attron(COLOR_PAIR(4)); - mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing"); - mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)"); - attroff(COLOR_PAIR(4)); - refresh(); - update_panels(); - doupdate(); - } - endwin(); - return 0; -} - -/* Put all the windows */ -void init_wins(WINDOW **wins, int n) -{ int x, y, i; - char label[80]; - - y = 2; - x = 10; - for(i = 0; i < n; ++i) - { wins[i] = newwin(NLINES, NCOLS, y, x); - sprintf(label, "Window Number %d", i + 1); - win_show(wins[i], label, i + 1); - y += 3; - x += 7; - } -} - -/* Set the PANEL_DATA structures for individual panels */ -void set_user_ptrs(PANEL **panels, int n) -{ PANEL_DATA *ptrs; - WINDOW *win; - int x, y, w, h, i; - char temp[80]; - - ptrs = (PANEL_DATA *)calloc(n, sizeof(PANEL_DATA)); - - for(i = 0;i < n; ++i) - { win = panel_window(panels[i]); - getbegyx(win, y, x); - getmaxyx(win, h, w); - ptrs[i].x = x; - ptrs[i].y = y; - ptrs[i].w = w; - ptrs[i].h = h; - sprintf(temp, "Window Number %d", i + 1); - strcpy(ptrs[i].label, temp); - ptrs[i].label_color = i + 1; - if(i + 1 == n) - ptrs[i].next = panels[0]; - else - ptrs[i].next = panels[i + 1]; - set_panel_userptr(panels[i], &ptrs[i]); - } -} - -/* Show the window with a border and a label */ -void win_show(WINDOW *win, char *label, int label_color) -{ int startx, starty, height, width; - - getbegyx(win, starty, startx); - getmaxyx(win, height, width); - - box(win, 0, 0); - mvwaddch(win, 2, 0, ACS_LTEE); - mvwhline(win, 2, 1, ACS_HLINE, width - 2); - mvwaddch(win, 2, width - 1, ACS_RTEE); - - print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color)); -} - -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>Concentrate on the main while loop. Once it finds out the type -of key pressed, it takes appropriate action. If 'r' is pressed -resizing mode is started. After this the new sizes are updated as -the user presses the arrow keys. When the user presses -<ENTER> present selection ends and panel is resized by using -the concept explained. While in resizing mode the program doesn't -show how the window is getting resized. It's left as an exercise to -the reader to print a dotted border while it gets resized to a new -position.</p> -<p>When the user presses 'm' the move mode starts. This is a bit -simpler than resizing. As the arrow keys are pressed the new -position is updated and pressing of <ENTER> causes the panel -to be moved by calling the function move_panel().</p> -<p>In this program the user data which is represented as -PANEL_DATA, plays very important role in finding the associated -information with a panel. As written in the comments, the -PANEL_DATA stores the panel sizes, label, label color and a pointer -to the next panel in the cycle.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="PANELSHOWHIDE" id="PANELSHOWHIDE">16.6. -Hiding and Showing Panels</a></h3> -<p>A Panel can be hidden by using the function hide_panel(). This -function merely removes it form the stack of panels, thus hiding it -on the screen once you do update_panels() and doupdate(). It -doesn't destroy the PANEL structure associated with the hidden -panel. It can be shown again by using the show_panel() -function.</p> -<p>The following program shows the hiding of panels. Press 'a' or -'b' or 'c' to show or hide first, second and third windows -respectively. It uses a user data with a small variable hide, which -keeps track of whether the window is hidden or not. For some reason -the function <var class="LITERAL">panel_hidden()</var> which tells -whether a panel is hidden or not is not working. A bug report was -also presented by Michael Andres <a href= -"http://www.geocrawler.com/archives/3/344/1999/9/0/2643549/" -target="_top">here</a></p> -<div class="EXAMPLE"><a name="PPAHI" id="PPAHI"></a> -<p><b>Example 17. Panel Hiding and Showing example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <panel.h> - -typedef struct _PANEL_DATA { - int hide; /* TRUE if panel is hidden */ -}PANEL_DATA; - -#define NLINES 10 -#define NCOLS 40 - -void init_wins(WINDOW **wins, int n); -void win_show(WINDOW *win, char *label, int label_color); -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); - -int main() -{ WINDOW *my_wins[3]; - PANEL *my_panels[3]; - PANEL_DATA panel_datas[3]; - PANEL_DATA *temp; - int ch; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize all the colors */ - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_BLUE, COLOR_BLACK); - init_pair(4, COLOR_CYAN, COLOR_BLACK); - - init_wins(my_wins, 3); - - /* Attach a panel to each window */ /* Order is bottom up */ - my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ - my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ - my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ - - /* Initialize panel datas saying that nothing is hidden */ - panel_datas[0].hide = FALSE; - panel_datas[1].hide = FALSE; - panel_datas[2].hide = FALSE; - - set_panel_userptr(my_panels[0], &panel_datas[0]); - set_panel_userptr(my_panels[1], &panel_datas[1]); - set_panel_userptr(my_panels[2], &panel_datas[2]); - - /* Update the stacking order. 2nd panel will be on top */ - update_panels(); - - /* Show it on the screen */ - attron(COLOR_PAIR(4)); - mvprintw(LINES - 3, 0, "Show or Hide a window with 'a'(first window) 'b'(Second Window) 'c'(Third Window)"); - mvprintw(LINES - 2, 0, "F1 to Exit"); - - attroff(COLOR_PAIR(4)); - doupdate(); - - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case 'a': - temp = (PANEL_DATA *)panel_userptr(my_panels[0]); - if(temp->hide == FALSE) - { hide_panel(my_panels[0]); - temp->hide = TRUE; - } - else - { show_panel(my_panels[0]); - temp->hide = FALSE; - } - break; - case 'b': - temp = (PANEL_DATA *)panel_userptr(my_panels[1]); - if(temp->hide == FALSE) - { hide_panel(my_panels[1]); - temp->hide = TRUE; - } - else - { show_panel(my_panels[1]); - temp->hide = FALSE; - } - break; - case 'c': - temp = (PANEL_DATA *)panel_userptr(my_panels[2]); - if(temp->hide == FALSE) - { hide_panel(my_panels[2]); - temp->hide = TRUE; - } - else - { show_panel(my_panels[2]); - temp->hide = FALSE; - } - break; - } - update_panels(); - doupdate(); - } - endwin(); - return 0; -} - -/* Put all the windows */ -void init_wins(WINDOW **wins, int n) -{ int x, y, i; - char label[80]; - - y = 2; - x = 10; - for(i = 0; i < n; ++i) - { wins[i] = newwin(NLINES, NCOLS, y, x); - sprintf(label, "Window Number %d", i + 1); - win_show(wins[i], label, i + 1); - y += 3; - x += 7; - } -} - -/* Show the window with a border and a label */ -void win_show(WINDOW *win, char *label, int label_color) -{ int startx, starty, height, width; - - getbegyx(win, starty, startx); - getmaxyx(win, height, width); - - box(win, 0, 0); - mvwaddch(win, 2, 0, ACS_LTEE); - mvwhline(win, 2, 1, ACS_HLINE, width - 2); - mvwaddch(win, 2, width - 1, ACS_RTEE); - - print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color)); -} - -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); -}</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="PANELABOVE" id="PANELABOVE">16.7. -panel_above() and panel_below() Functions</a></h3> -<p>The functions <var class="LITERAL">panel_above()</var> and -<var class="LITERAL">panel_below()</var> can be used to find out -the panel above and below a panel. If the argument to these -functions is NULL, then they return a pointer to bottom panel and -top panel respectively.</p> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="MENUS" id="MENUS">17. Menus -Library</a></h2> -<p>The menus library provides a nice extension to basic curses, -through which you can create menus. It provides a set of functions -to create menus. But they have to be customized to give a nicer -look, with colors etc. Let's get into the details.</p> -<p>A menu is a screen display that assists the user to choose some -subset of a given set of items. To put it simple, a menu is a -collection of items from which one or more items can be chosen. -Some readers might not be aware of multiple item selection -capability. Menu library provides functionality to write menus from -which the user can chose more than one item as the preferred -choice. This is dealt with in a later section. Now it is time for -some rudiments.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MENUBASICS" id="MENUBASICS">17.1. The -Basics</a></h3> -<p>To create menus, you first create items, and then post the menu -to the display. After that, all the processing of user responses is -done in an elegant function menu_driver() which is the work horse -of any menu program.</p> -<p>The general flow of control of a menu program looks like -this.</p> -<ol type="1"> -<li> -<p>Initialize curses</p> -</li> -<li> -<p>Create items using new_item(). You can specify a name and -description for the items.</p> -</li> -<li> -<p>Create the menu with new_menu() by specifying the items to be -attached with.</p> -</li> -<li> -<p>Post the menu with menu_post() and refresh the screen.</p> -</li> -<li> -<p>Process the user requests with a loop and do necessary updates -to menu with menu_driver.</p> -</li> -<li> -<p>Unpost the menu with menu_unpost()</p> -</li> -<li> -<p>Free the memory allocated to menu by free_menu()</p> -</li> -<li> -<p>Free the memory allocated to the items with free_item()</p> -</li> -<li> -<p>End curses</p> -</li> -</ol> -<p>Let's see a program which prints a simple menu and updates the -current selection with up, down arrows.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="COMPILEMENUS" id="COMPILEMENUS">17.2. -Compiling With the Menu Library</a></h3> -<p>To use menu library functions, you have to include menu.h and to -link the program with menu library the flag -lmenu should be added -along with -lncurses in that order.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> #include <menu.h> - . - . - . - - compile and link: gcc <program file> -lmenu -lncurses</font> -</pre></td> -</tr> -</table> -<div class="EXAMPLE"><a name="MMESI" id="MMESI"></a> -<p><b>Example 18. Menu Basics</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <curses.h> -#include <menu.h> - -#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) -#define CTRLD 4 - -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Exit", - }; - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - int n_choices, i; - ITEM *cur_item; - - - initscr(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *)); - - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - my_items[n_choices] = (ITEM *)NULL; - - my_menu = new_menu((ITEM **)my_items); - mvprintw(LINES - 2, 0, "F1 to Exit"); - post_menu(my_menu); - refresh(); - - while((c = getch()) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - } - } - - free_item(my_items[0]); - free_item(my_items[1]); - free_menu(my_menu); - endwin(); -} - </span></font> -</pre></td> -</tr> -</table> -</div> -<p>This program demonstrates the basic concepts involved in -creating a menu using menus library. First we create the items -using new_item() and then attach them to the menu with new_menu() -function. After posting the menu and refreshing the screen, the -main processing loop starts. It reads user input and takes -corresponding action. The function menu_driver() is the main work -horse of the menu system. The second parameter to this function -tells what's to be done with the menu. According to the parameter, -menu_driver() does the corresponding task. The value can be either -a menu navigational request, an ascii character, or a KEY_MOUSE -special key associated with a mouse event.</p> -<p>The menu_driver accepts following navigational requests.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"> REQ_LEFT_ITEM Move left to an item. - REQ_RIGHT_ITEM Move right to an item. - REQ_UP_ITEM Move up to an item. - REQ_DOWN_ITEM Move down to an item. - REQ_SCR_ULINE Scroll up a line. - REQ_SCR_DLINE Scroll down a line. - REQ_SCR_DPAGE Scroll down a page. - REQ_SCR_UPAGE Scroll up a page. - REQ_FIRST_ITEM Move to the first item. - REQ_LAST_ITEM Move to the last item. - REQ_NEXT_ITEM Move to the next item. - REQ_PREV_ITEM Move to the previous item. - REQ_TOGGLE_ITEM Select/deselect an item. - REQ_CLEAR_PATTERN Clear the menu pattern buffer. - REQ_BACK_PATTERN Delete the previous character from the pattern buffer. - REQ_NEXT_MATCH Move to the next item matching the pattern match. - REQ_PREV_MATCH Move to the previous item matching the pattern match. </font> -</pre></td> -</tr> -</table> -<p>Don't get overwhelmed by the number of options. We will see them -slowly one after another. The options of interest in this example -are REQ_UP_ITEM and REQ_DOWN_ITEM. These two options when passed to -menu_driver, menu driver updates the current item to one item up or -down respectively.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MENUDRIVER" id="MENUDRIVER">17.3. Menu -Driver: The work horse of the menu system</a></h3> -<p>As you have seen in the above example, menu_driver plays an -important role in updating the menu. It is very important to -understand various options it takes and what they do. As explained -above, the second parameter to menu_driver() can be either a -navigational request, a printable character or a KEY_MOUSE key. -Let's dissect the different navigational requests.</p> -<ul> -<li> -<p><em>REQ_LEFT_ITEM and REQ_RIGHT_ITEM</em></p> -<p>A Menu can be displayed with multiple columns for more than one -item. This can be done by using the <var class= -"LITERAL">menu_format()</var>function. When a multi columnar menu -is displayed these requests cause the menu driver to move the -current selection to left or right.</p> -</li> -<li> -<p><em>REQ_UP_ITEM and REQ_DOWN_ITEM</em></p> -<p>These two options you have seen in the above example. These -options when given, makes the menu_driver to move the current -selection to an item up or down.</p> -</li> -<li> -<p><em>REQ_SCR_* options</em></p> -<p>The four options REQ_SCR_ULINE, REQ_SCR_DLINE, REQ_SCR_DPAGE, -REQ_SCR_UPAGE are related to scrolling. If all the items in the -menu cannot be displayed in the menu sub window, then the menu is -scrollable. These requests can be given to the menu_driver to do -the scrolling either one line up, down or one page down or up -respectively.</p> -</li> -<li> -<p><em>REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_NEXT_ITEM and -REQ_PREV_ITEM</em></p> -<p>These requests are self explanatory.</p> -</li> -<li> -<p><em>REQ_TOGGLE_ITEM</em></p> -<p>This request when given, toggles the present selection. This -option is to be used only in a multi valued menu. So to use this -request the option O_ONEVALUE must be off. This option can be made -off or on with set_menu_opts().</p> -</li> -<li> -<p><em>Pattern Requests</em></p> -<p>Every menu has an associated pattern buffer, which is used to -find the nearest match to the ascii characters entered by the user. -Whenever ascii characters are given to menu_driver, it puts in to -the pattern buffer. It also tries to find the nearest match to the -pattern in the items list and moves current selection to that item. -The request REQ_CLEAR_PATTERN clears the pattern buffer. The -request REQ_BACK_PATTERN deletes the previous character in the -pattern buffer. In case the pattern matches more than one item then -the matched items can be cycled through REQ_NEXT_MATCH and -REQ_PREV_MATCH which move the current selection to the next and -previous matches respectively.</p> -</li> -<li> -<p><em>Mouse Requests</em></p> -<p>In case of KEY_MOUSE requests, according to the mouse position -an action is taken accordingly. The action to be taken is explained -in the man page as,</p> -<table border="0" bgcolor="#E0E0E0" width="90%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"><em> If the second argument is the KEY_MOUSE special key, the - associated mouse event is translated into one of the above - pre-defined requests. Currently only clicks in the user - window (e.g. inside the menu display area or the decora­ - tion window) are handled. If you click above the display - region of the menu, a REQ_SCR_ULINE is generated, if you - doubleclick a REQ_SCR_UPAGE is generated and if you - tripleclick a REQ_FIRST_ITEM is generated. If you click - below the display region of the menu, a REQ_SCR_DLINE is - generated, if you doubleclick a REQ_SCR_DPAGE is generated - and if you tripleclick a REQ_LAST_ITEM is generated. If - you click at an item inside the display area of the menu, - the menu cursor is positioned to that item.</em></font> -</pre></td> -</tr> -</table> -</li> -</ul> -<p>Each of the above requests will be explained in the following -lines with several examples whenever appropriate.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MENUWINDOWS" id="MENUWINDOWS">17.4. Menu -Windows</a></h3> -<p>Every menu created is associated with a window and a sub window. -The menu window displays any title or border associated with the -menu. The menu sub window displays the menu items currently -available for selection. But we didn't specify any window or sub -window in the simple example. When a window is not specified, -stdscr is taken as the main window, and then menu system calculates -the sub window size required for the display of items. Then items -are displayed in the calculated sub window. So let's play with -these windows and display a menu with a border and a title.</p> -<div class="EXAMPLE"><a name="MMEWI" id="MMEWI"></a> -<p><b>Example 19. Menu Windows Usage example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <menu.h> - -#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) -#define CTRLD 4 - -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Exit", - (char *)NULL, - }; -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - WINDOW *my_menu_win; - int n_choices, i; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - init_pair(1, COLOR_RED, COLOR_BLACK); - - /* Create items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - - /* Crate menu */ - my_menu = new_menu((ITEM **)my_items); - - /* Create the window to be associated with the menu */ - my_menu_win = newwin(10, 40, 4, 4); - keypad(my_menu_win, TRUE); - - /* Set main window and sub window */ - set_menu_win(my_menu, my_menu_win); - set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1)); - - /* Set menu mark to the string " * " */ - set_menu_mark(my_menu, " * "); - - /* Print a border around the main window and print a title */ - box(my_menu_win, 0, 0); - print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1)); - mvwaddch(my_menu_win, 2, 0, ACS_LTEE); - mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38); - mvwaddch(my_menu_win, 2, 39, ACS_RTEE); - mvprintw(LINES - 2, 0, "F1 to exit"); - refresh(); - - /* Post the menu */ - post_menu(my_menu); - wrefresh(my_menu_win); - - while((c = wgetch(my_menu_win)) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - } - wrefresh(my_menu_win); - } - - /* Unpost and free all the memory taken up */ - unpost_menu(my_menu); - free_menu(my_menu); - for(i = 0; i < n_choices; ++i) - free_item(my_items[i]); - endwin(); -} - -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>This example creates a menu with a title, border, a fancy line -separating title and the items. As you can see, in order to attach -a window to a menu the function set_menu_win() has to be used. Then -we attach the sub window also. This displays the items in the sub -window. You can also set the mark string which gets displayed to -the left of the selected item with set_menu_mark().</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="SCROLLMENUS" id="SCROLLMENUS">17.5. -Scrolling Menus</a></h3> -<p>If the sub window given for a window is not big enough to show -all the items, then the menu will be scrollable. When you are on -the last item in the present list, if you send REQ_DOWN_ITEM, it -gets translated into REQ_SCR_DLINE and the menu scrolls by one -item. You can manually give REQ_SCR_ operations to do scrolling. -Let's see how it can be done.</p> -<div class="EXAMPLE"><a name="MMESC" id="MMESC"></a> -<p><b>Example 20. Scrolling Menus example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <curses.h> -#include <menu.h> - -#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) -#define CTRLD 4 - -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Choice 5", - "Choice 6", - "Choice 7", - "Choice 8", - "Choice 9", - "Choice 10", - "Exit", - (char *)NULL, - }; -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - WINDOW *my_menu_win; - int n_choices, i; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_CYAN, COLOR_BLACK); - - /* Create items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - - /* Crate menu */ - my_menu = new_menu((ITEM **)my_items); - - /* Create the window to be associated with the menu */ - my_menu_win = newwin(10, 40, 4, 4); - keypad(my_menu_win, TRUE); - - /* Set main window and sub window */ - set_menu_win(my_menu, my_menu_win); - set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1)); - set_menu_format(my_menu, 5, 1); - - /* Set menu mark to the string " * " */ - set_menu_mark(my_menu, " * "); - - /* Print a border around the main window and print a title */ - box(my_menu_win, 0, 0); - print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1)); - mvwaddch(my_menu_win, 2, 0, ACS_LTEE); - mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38); - mvwaddch(my_menu_win, 2, 39, ACS_RTEE); - - /* Post the menu */ - post_menu(my_menu); - wrefresh(my_menu_win); - - attron(COLOR_PAIR(2)); - mvprintw(LINES - 2, 0, "Use PageUp and PageDown to scoll down or up a page of items"); - mvprintw(LINES - 1, 0, "Arrow Keys to navigate (F1 to Exit)"); - attroff(COLOR_PAIR(2)); - refresh(); - - while((c = wgetch(my_menu_win)) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - case KEY_NPAGE: - menu_driver(my_menu, REQ_SCR_DPAGE); - break; - case KEY_PPAGE: - menu_driver(my_menu, REQ_SCR_UPAGE); - break; - } - wrefresh(my_menu_win); - } - - /* Unpost and free all the memory taken up */ - unpost_menu(my_menu); - free_menu(my_menu); - for(i = 0; i < n_choices; ++i) - free_item(my_items[i]); - endwin(); -} - -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>This program is self-explanatory. In this example the number of -choices has been increased to ten, which is larger than our sub -window size which can hold 6 items. This message has to be -explicitly conveyed to the menu system with the function -set_menu_format(). In here we specify the number of rows and -columns we want to be displayed for a single page. We can specify -any number of items to be shown, in the rows variables, if it is -less than the height of the sub window. If the key pressed by the -user is a PAGE UP or PAGE DOWN, the menu is scrolled a page due to -the requests (REQ_SCR_DPAGE and REQ_SCR_UPAGE) given to -menu_driver().</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MULTICOLUMN" id="MULTICOLUMN">17.6. -Multi Columnar Menus</a></h3> -<p>In the above example you have seen how to use the function -set_menu_format(). I didn't mention what the cols variable (third -parameter) does. Well, If your sub window is wide enough, you can -opt to display more than one item per row. This can be specified in -the cols variable. To make things simpler, the following example -doesn't show descriptions for the items.</p> -<div class="EXAMPLE"><a name="MMEMUCO" id="MMEMUCO"></a> -<p><b>Example 21. Milt Columnar Menus Example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <curses.h> -#include <menu.h> - -#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) -#define CTRLD 4 - -char *choices[] = { - "Choice 1", "Choice 2", "Choice 3", "Choice 4", "Choice 5", - "Choice 6", "Choice 7", "Choice 8", "Choice 9", "Choice 10", - "Choice 11", "Choice 12", "Choice 13", "Choice 14", "Choice 15", - "Choice 16", "Choice 17", "Choice 18", "Choice 19", "Choice 20", - "Exit", - (char *)NULL, - }; - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - WINDOW *my_menu_win; - int n_choices, i; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_CYAN, COLOR_BLACK); - - /* Create items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - - /* Crate menu */ - my_menu = new_menu((ITEM **)my_items); - - /* Set menu option not to show the description */ - menu_opts_off(my_menu, O_SHOWDESC); - - /* Create the window to be associated with the menu */ - my_menu_win = newwin(10, 70, 4, 4); - keypad(my_menu_win, TRUE); - - /* Set main window and sub window */ - set_menu_win(my_menu, my_menu_win); - set_menu_sub(my_menu, derwin(my_menu_win, 6, 68, 3, 1)); - set_menu_format(my_menu, 5, 3); - set_menu_mark(my_menu, " * "); - - /* Print a border around the main window and print a title */ - box(my_menu_win, 0, 0); - - attron(COLOR_PAIR(2)); - mvprintw(LINES - 3, 0, "Use PageUp and PageDown to scroll"); - mvprintw(LINES - 2, 0, "Use Arrow Keys to navigate (F1 to Exit)"); - attroff(COLOR_PAIR(2)); - refresh(); - - /* Post the menu */ - post_menu(my_menu); - wrefresh(my_menu_win); - - while((c = wgetch(my_menu_win)) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - case KEY_LEFT: - menu_driver(my_menu, REQ_LEFT_ITEM); - break; - case KEY_RIGHT: - menu_driver(my_menu, REQ_RIGHT_ITEM); - break; - case KEY_NPAGE: - menu_driver(my_menu, REQ_SCR_DPAGE); - break; - case KEY_PPAGE: - menu_driver(my_menu, REQ_SCR_UPAGE); - break; - } - wrefresh(my_menu_win); - } - - /* Unpost and free all the memory taken up */ - unpost_menu(my_menu); - free_menu(my_menu); - for(i = 0; i < n_choices; ++i) - free_item(my_items[i]); - endwin(); -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>Watch the function call to set_menu_format(). It specifies the -number of columns to be 3, thus displaying 3 items per row. We have -also switched off the showing descriptions with the function -menu_opts_off(). There are couple of functions set_menu_opts(), -menu_opts_on() and menu_opts() which can be used to manipulate menu -options. The following menu options can be specified.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> O_ONEVALUE - Only one item can be selected for this menu. - - O_SHOWDESC - Display the item descriptions when the menu is - posted. - - O_ROWMAJOR - Display the menu in row-major order. - - O_IGNORECASE - Ignore the case when pattern-matching. - - O_SHOWMATCH - Move the cursor to within the item name while pat­ - tern-matching. - - O_NONCYCLIC - Don't wrap around next-item and previous-item, - requests to the other end of the menu.</font> -</pre></td> -</tr> -</table> -<p>All options are on by default. You can switch specific -attributes on or off with menu_opts_on() and menu_opts_off() -functions. You can also use set_menu_opts() to directly specify the -options. The argument to this function should be a OR ed value of -some of those above constants. The function menu_opts() can be used -to find out a menu's present options.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MULTIVALUEMENUS" id= -"MULTIVALUEMENUS">17.7. Multi Valued Menus</a></h3> -<p>You might be wondering what if you switch off the option -O_ONEVALUE. Then the menu becomes multi-valued. That means you can -select more than one item. This brings us to the request -REQ_TOGGLE_ITEM. Let's see it in action.</p> -<div class="EXAMPLE"><a name="MMETO" id="MMETO"></a> -<p><b>Example 22. Multi Valued Menus example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <curses.h> -#include <menu.h> - -#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) -#define CTRLD 4 - -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Choice 5", - "Choice 6", - "Choice 7", - "Exit", - }; - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - int n_choices, i; - ITEM *cur_item; - - /* Initialize curses */ - initscr(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - my_items[n_choices] = (ITEM *)NULL; - - my_menu = new_menu((ITEM **)my_items); - - /* Make the menu multi valued */ - menu_opts_off(my_menu, O_ONEVALUE); - - mvprintw(LINES - 3, 0, "Use <SPACE> to select or unselect an item."); - mvprintw(LINES - 2, 0, "<ENTER> to see presently selected items(F1 to Exit)"); - post_menu(my_menu); - refresh(); - - while((c = getch()) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - case ' ': - menu_driver(my_menu, REQ_TOGGLE_ITEM); - break; - case 10: /* Enter */ - { char temp[200]; - ITEM **items; - - items = menu_items(my_menu); - temp[0] = '\0'; - for(i = 0; i < item_count(my_menu); ++i) - if(item_value(items[i]) == TRUE) - { strcat(temp, item_name(items[i])); - strcat(temp, " "); - } - move(20, 0); - clrtoeol(); - mvprintw(20, 0, temp); - refresh(); - } - break; - } - } - - free_item(my_items[0]); - free_item(my_items[1]); - free_menu(my_menu); - endwin(); -} - </span></font> -</pre></td> -</tr> -</table> -</div> -<p>Whew, A lot of new functions. Let's take them one after another. -Firstly, the REQ_TOGGLE_ITEM. In a multi-valued menu, the user -should be allowed to select or un select more than one item. The -request REQ_TOGGLE_ITEM toggles the present selection. In this case -when space is pressed REQ_TOGGLE_ITEM request is sent to -menu_driver to achieve the result.</p> -<p>Now when the user presses <ENTER> we show the items he -presently selected. First we find out the items associated with the -menu using the function menu_items(). Then we loop through the -items to find out if the item is selected or not. The function -item_value() returns TRUE if an item is selected. The function -item_count() returns the number of items in the menu. The item name -can be found with item_name(). You can also find the description -associated with an item using item_description().</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MENUOPT" id="MENUOPT">17.8. Menu -Options</a></h3> -<p>Well, by this time you must be itching for some difference in -your menu, with lots of functionality. I know. You want Colors !!!. -You want to create nice menus similar to those text mode <a href= -"http://www.jersey.net/~debinjoe/games/" target="_top">dos -games</a>. The functions set_menu_fore() and set_menu_back() can be -used to change the attribute of the selected item and unselected -item. The names are misleading. They don't change menu's foreground -or background which would have been useless.</p> -<p>The function set_menu_grey() can be used to set the display -attribute for the non-selectable items in the menu. This brings us -to the interesting option for an item the one and only -O_SELECTABLE. We can turn it off by the function item_opts_off() -and after that that item is not selectable. It's like a grayed item -in those fancy windows menus. Let's put these concepts in practice -with this example</p> -<div class="EXAMPLE"><a name="MMEAT" id="MMEAT"></a> -<p><b>Example 23. Menu Options example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <menu.h> - -#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) -#define CTRLD 4 - -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Choice 5", - "Choice 6", - "Choice 7", - "Exit", - }; - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - int n_choices, i; - ITEM *cur_item; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_MAGENTA, COLOR_BLACK); - - /* Initialize items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - my_items[n_choices] = (ITEM *)NULL; - item_opts_off(my_items[3], O_SELECTABLE); - item_opts_off(my_items[6], O_SELECTABLE); - - /* Create menu */ - my_menu = new_menu((ITEM **)my_items); - - /* Set fore ground and back ground of the menu */ - set_menu_fore(my_menu, COLOR_PAIR(1) | A_REVERSE); - set_menu_back(my_menu, COLOR_PAIR(2)); - set_menu_grey(my_menu, COLOR_PAIR(3)); - - /* Post the menu */ - mvprintw(LINES - 3, 0, "Press <ENTER> to see the option selected"); - mvprintw(LINES - 2, 0, "Up and Down arrow keys to naviage (F1 to Exit)"); - post_menu(my_menu); - refresh(); - - while((c = getch()) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - case 10: /* Enter */ - move(20, 0); - clrtoeol(); - mvprintw(20, 0, "Item selected is : %s", - item_name(current_item(my_menu))); - pos_menu_cursor(my_menu); - break; - } - } - unpost_menu(my_menu); - for(i = 0; i < n_choices; ++i) - free_item(my_items[i]); - free_menu(my_menu); - endwin(); -} - </span></font> -</pre></td> -</tr> -</table> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MENUUSERPTR" id="MENUUSERPTR">17.9. The -useful User Pointer</a></h3> -<p>We can associate a user pointer with each item in the menu. It -works the same way as user pointer in panels. It's not touched by -menu system. You can store any thing you like in that. I usually -use it to store the function to be executed when the menu option is -chosen (It's selected and may be the user pressed -<ENTER>);</p> -<div class="EXAMPLE"><a name="MMEUS" id="MMEUS"></a> -<p><b>Example 24. Menu User Pointer Usage</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <curses.h> -#include <menu.h> - -#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) -#define CTRLD 4 - -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Choice 5", - "Choice 6", - "Choice 7", - "Exit", - }; -void func(char *name); - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - int n_choices, i; - ITEM *cur_item; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_MAGENTA, COLOR_BLACK); - - /* Initialize items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - { my_items[i] = new_item(choices[i], choices[i]); - /* Set the user pointer */ - set_item_userptr(my_items[i], func); - } - my_items[n_choices] = (ITEM *)NULL; - - /* Create menu */ - my_menu = new_menu((ITEM **)my_items); - - /* Post the menu */ - mvprintw(LINES - 3, 0, "Press <ENTER> to see the option selected"); - mvprintw(LINES - 2, 0, "Up and Down arrow keys to naviage (F1 to Exit)"); - post_menu(my_menu); - refresh(); - - while((c = getch()) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - case 10: /* Enter */ - { ITEM *cur; - void (*p)(char *); - - cur = current_item(my_menu); - p = item_userptr(cur); - p((char *)item_name(cur)); - pos_menu_cursor(my_menu); - break; - } - break; - } - } - unpost_menu(my_menu); - for(i = 0; i < n_choices; ++i) - free_item(my_items[i]); - free_menu(my_menu); - endwin(); -} - -void func(char *name) -{ move(20, 0); - clrtoeol(); - mvprintw(20, 0, "Item selected is : %s", name); -} </span></font> -</pre></td> -</tr> -</table> -</div> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="FORMS" id="FORMS">18. Forms -Library</a></h2> -<p>Well. If you have seen those forms on web pages which take input -from users and do various kinds of things, you might be wondering -how would any one create such forms in text mode display. It's -quite difficult to write those nifty forms in plain ncurses. Forms -library tries to provide a basic frame work to build and maintain -forms with ease. It has lot of features(functions) which manage -validation, dynamic expansion of fields etc.. Let's see it in full -flow.</p> -<p>A form is a collection of fields; each field can be either a -label(static text) or a data-entry location. The forms also library -provides functions to divide forms into multiple pages.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="FORMBASICS" id="FORMBASICS">18.1. The -Basics</a></h3> -<p>Forms are created in much the same way as menus. First the -fields related to the form are created with new_field(). You can -set options for the fields, so that they can be displayed with some -fancy attributes, validated before the field looses focus etc.. -Then the fields are attached to form. After this, the form can be -posted to display and is ready to receive inputs. On the similar -lines to menu_driver(), the form is manipulated with form_driver(). -We can send requests to form_driver to move focus to a certain -field, move cursor to end of the field etc.. After the user enters -values in the fields and validation done, form can be unposted and -memory allocated can be freed.</p> -<p>The general flow of control of a forms program looks like -this.</p> -<ol type="1"> -<li> -<p>Initialize curses</p> -</li> -<li> -<p>Create fields using new_field(). You can specify the height and -width of the field, and its position on the form.</p> -</li> -<li> -<p>Create the forms with new_form() by specifying the fields to be -attached with.</p> -</li> -<li> -<p>Post the form with form_post() and refresh the screen.</p> -</li> -<li> -<p>Process the user requests with a loop and do necessary updates -to form with form_driver.</p> -</li> -<li> -<p>Unpost the menu with form_unpost()</p> -</li> -<li> -<p>Free the memory allocated to menu by free_form()</p> -</li> -<li> -<p>Free the memory allocated to the items with free_field()</p> -</li> -<li> -<p>End curses</p> -</li> -</ol> -<p>As you can see, working with forms library is much similar to -handling menu library. The following examples will explore various -aspects of form processing. Let's start the journey with a simple -example. first.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="COMPILEFORMS" id="COMPILEFORMS">18.2. -Compiling With the Forms Library</a></h3> -<p>To use forms library functions, you have to include form.h and -to link the program with forms library the flag -lform should be -added along with -lncurses in that order.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"> #include <form.h> - . - . - . - - compile and link: gcc <program file> -lform -lncurses</font> -</pre></td> -</tr> -</table> -<div class="EXAMPLE"><a name="FFOSI" id="FFOSI"></a> -<p><b>Example 25. Forms Basics</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <form.h> - -int main() -{ FIELD *field[3]; - FORM *my_form; - int ch; - - /* Initialize curses */ - initscr(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize the fields */ - field[0] = new_field(1, 10, 4, 18, 0, 0); - field[1] = new_field(1, 10, 6, 18, 0, 0); - field[2] = NULL; - - /* Set field options */ - set_field_back(field[0], A_UNDERLINE); /* Print a line for the option */ - field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */ - /* Field is filled up */ - set_field_back(field[1], A_UNDERLINE); - field_opts_off(field[1], O_AUTOSKIP); - - /* Create the form and post it */ - my_form = new_form(field); - post_form(my_form); - refresh(); - - mvprintw(4, 10, "Value 1:"); - mvprintw(6, 10, "Value 2:"); - refresh(); - - /* Loop through to get user requests */ - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case KEY_DOWN: - /* Go to next field */ - form_driver(my_form, REQ_NEXT_FIELD); - /* Go to the end of the present buffer */ - /* Leaves nicely at the last character */ - form_driver(my_form, REQ_END_LINE); - break; - case KEY_UP: - /* Go to previous field */ - form_driver(my_form, REQ_PREV_FIELD); - form_driver(my_form, REQ_END_LINE); - break; - default: - /* If this is a normal character, it gets */ - /* Printed */ - form_driver(my_form, ch); - break; - } - } - - /* Un post form and free the memory */ - unpost_form(my_form); - free_form(my_form); - free_field(field[0]); - free_field(field[1]); - - endwin(); - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>Above example is pretty straight forward. It creates two fields -with <var class="LITERAL">new_field()</var>. new_field() takes -height, width, starty, startx, number of offscreen rows and number -of additional working buffers. The fifth argument number of -offscreen rows specifies how much of the field to be shown. If it -is zero, the entire field is always displayed otherwise the form -will be scrollable when the user accesses not displayed parts of -the field. The forms library allocates one buffer per field to -store the data user enters. Using the last parameter to new_field() -we can specify it to allocate some additional buffers. These can be -used for any purpose you like.</p> -<p>After creating the fields, back ground attribute of both of them -is set to an underscore with set_field_back(). The AUTOSKIP option -is turned off using field_opts_off(). If this option is turned on, -focus will move to the next field in the form once the active field -is filled up completely.</p> -<p>After attaching the fields to the form, it is posted. Here on, -user inputs are processed in the while loop, by making -corresponding requests to form_driver. The details of all the -requests to the form_driver() are explained later.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="PLAYFIELDS" id="PLAYFIELDS">18.3. -Playing with Fields</a></h3> -<p>Each form field is associated with a lot of attributes. They can -be manipulated to get the required effect and to have fun !!!. So -why wait?</p> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="FETCHINFO" id="FETCHINFO">18.3.1. -Fetching Size and Location of Field</a></h4> -<p>The parameters we have given at the time of creation of a field -can be retrieved with field_info(). It returns height, width, -starty, startx, number of offscreen rows, and number of additional -buffers into the parameters given to it. It is a sort of inverse of -new_field().</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int field_info( FIELD *field, /* field from which to fetch */ - int *height, *int width, /* field size */ - int *top, int *left, /* upper left corner */ - int *offscreen, /* number of offscreen rows */ - int *nbuf); /* number of working buffers */</font> -</pre></td> -</tr> -</table> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="MOVEFIELD" id="MOVEFIELD">18.3.2. Moving -the field</a></h4> -<p>The location of the field can be moved to a different position -with move_field().</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int move_field( FIELD *field, /* field to alter */ - int top, int left); /* new upper-left corner */</font> -</pre></td> -</tr> -</table> -<p>As usual, the changed position can be queried with -field_infor().</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="JUSTIFYFIELD" id="JUSTIFYFIELD">18.3.3. -Field Justification</a></h4> -<p>The justification to be done for the field can be fixed using -the function set_field_just().</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"> int set_field_just(FIELD *field, /* field to alter */ - int justmode); /* mode to set */ - int field_just(FIELD *field); /* fetch justify mode of field */</font> -</pre></td> -</tr> -</table> -<p>The justification mode valued accepted and returned by these -functions are NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or -JUSTIFY_CENTER.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="FIELDDISPATTRIB" id= -"FIELDDISPATTRIB">18.3.4. Field Display Attributes</a></h4> -<p>As you have seen, in the above example, display attribute for -the fields can be set with set_field_fore() and setfield_back(). -These functions set foreground and background attribute of the -fields. You can also specify a pad character which will be filled -in the unfilled portion of the field. The pad character is set with -a call to set_field_pad(). Default pad value is a space. The -functions field_fore(), field_back, field_pad() can be used to -query the present foreground, background attributes and pad -character for the field. The following list gives the usage of -functions.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"> int set_field_fore(FIELD *field, /* field to alter */ - chtype attr); /* attribute to set */ - -chtype field_fore(FIELD *field); /* field to query */ - /* returns foreground attribute */ - -int set_field_back(FIELD *field, /* field to alter */ - chtype attr); /* attribute to set */ - -chtype field_back(FIELD *field); /* field to query */ - /* returns background attribute */ - -int set_field_pad(FIELD *field, /* field to alter */ - int pad); /* pad character to set */ - -chtype field_pad(FIELD *field); /* field to query */ - /* returns present pad character */ </font> -</pre></td> -</tr> -</table> -<p>Though above functions seem quite simple, using colors with -set_field_fore() may be frustrating in the beginning. Let me first -explain about foreground and background attributes of a field. The -foreground attribute is associated with the character. That means a -character in the field is printed with the attribute you have set -with set_field_fore(). Background attribute is the attribute used -to fill background of field, whether any character is there or not. -So what about colors? Since colors are always defined in pairs, -what is the right way to display colored fields? Here's an example -clarifying color attributes.</p> -<div class="EXAMPLE"><a name="FFOAT" id="FFOAT"></a> -<p><b>Example 26. Form Attributes example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <form.h> - -int main() -{ FIELD *field[3]; - FORM *my_form; - int ch; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize few color pairs */ - init_pair(1, COLOR_WHITE, COLOR_BLUE); - init_pair(2, COLOR_WHITE, COLOR_BLUE); - - /* Initialize the fields */ - field[0] = new_field(1, 10, 4, 18, 0, 0); - field[1] = new_field(1, 10, 6, 18, 0, 0); - field[2] = NULL; - - /* Set field options */ - set_field_fore(field[0], COLOR_PAIR(1));/* Put the field with blue background */ - set_field_back(field[0], COLOR_PAIR(2));/* and white foreground (characters */ - /* are printed in white */ - field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */ - /* Field is filled up */ - set_field_back(field[1], A_UNDERLINE); - field_opts_off(field[1], O_AUTOSKIP); - - /* Create the form and post it */ - my_form = new_form(field); - post_form(my_form); - refresh(); - - set_current_field(my_form, field[0]); /* Set focus to the colored field */ - mvprintw(4, 10, "Value 1:"); - mvprintw(6, 10, "Value 2:"); - mvprintw(LINES - 2, 0, "Use UP, DOWN arrow keys to switch between fields"); - refresh(); - - /* Loop through to get user requests */ - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case KEY_DOWN: - /* Go to next field */ - form_driver(my_form, REQ_NEXT_FIELD); - /* Go to the end of the present buffer */ - /* Leaves nicely at the last character */ - form_driver(my_form, REQ_END_LINE); - break; - case KEY_UP: - /* Go to previous field */ - form_driver(my_form, REQ_PREV_FIELD); - form_driver(my_form, REQ_END_LINE); - break; - default: - /* If this is a normal character, it gets */ - /* Printed */ - form_driver(my_form, ch); - break; - } - } - - /* Un post form and free the memory */ - unpost_form(my_form); - free_form(my_form); - free_field(field[0]); - free_field(field[1]); - - endwin(); - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>Play with the color pairs and try to understand the foreground -and background attributes. In my programs using color attributes, I -usually set only the background with set_field_back(). Curses -simply doesn't allow defining individual color attributes.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="FIELDOPTIONBITS" id= -"FIELDOPTIONBITS">18.3.5. Field Option Bits</a></h4> -<p>There is also a large collection of field option bits you can -set to control various aspects of forms processing. You can -manipulate them with these functions:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_field_opts(FIELD *field, /* field to alter */ - int attr); /* attribute to set */ - -int field_opts_on(FIELD *field, /* field to alter */ - int attr); /* attributes to turn on */ - -int field_opts_off(FIELD *field, /* field to alter */ - int attr); /* attributes to turn off */ - -int field_opts(FIELD *field); /* field to query */ </font> -</pre></td> -</tr> -</table> -<p>The function set_field_opts() can be used to directly set -attributes of a field or you can choose to switch a few attributes -on and off with field_opts_on() and field_opts_off() selectively. -Anytime you can query the attributes of a field with field_opts(). -The following is the list of available options. By default, all -options are on.</p> -<div class="VARIABLELIST"> -<dl> -<dt>O_VISIBLE</dt> -<dd> -<p>Controls whether the field is visible on the screen. Can be used -during form processing to hide or pop up fields depending on the -value of parent fields.</p> -</dd> -<dt>O_ACTIVE</dt> -<dd> -<p>Controls whether the field is active during forms processing -(i.e. visited by form navigation keys). Can be used to make labels -or derived fields with buffer values alterable by the forms -application, not the user.</p> -</dd> -<dt>O_PUBLIC</dt> -<dd> -<p>Controls whether data is displayed during field entry. If this -option is turned off on a field, the library will accept and edit -data in that field, but it will not be displayed and the visible -field cursor will not move. You can turn off the O_PUBLIC bit to -define password fields.</p> -</dd> -<dt>O_EDIT</dt> -<dd> -<p>Controls whether the field's data can be modified. When this -option is off, all editing requests except <var class= -"LITERAL">REQ_PREV_CHOICE</var> and <var class= -"LITERAL">REQ_NEXT_CHOICE</var>will fail. Such read-only fields may -be useful for help messages.</p> -</dd> -<dt>O_WRAP</dt> -<dd> -<p>Controls word-wrapping in multi-line fields. Normally, when any -character of a (blank-separated) word reaches the end of the -current line, the entire word is wrapped to the next line (assuming -there is one). When this option is off, the word will be split -across the line break.</p> -</dd> -<dt>O_BLANK</dt> -<dd> -<p>Controls field blanking. When this option is on, entering a -character at the first field position erases the entire field -(except for the just-entered character).</p> -</dd> -<dt>O_AUTOSKIP</dt> -<dd> -<p>Controls automatic skip to next field when this one fills. -Normally, when the forms user tries to type more data into a field -than will fit, the editing location jumps to next field. When this -option is off, the user's cursor will hang at the end of the field. -This option is ignored in dynamic fields that have not reached -their size limit.</p> -</dd> -<dt>O_NULLOK</dt> -<dd> -<p>Controls whether validation is applied to blank fields. -Normally, it is not; the user can leave a field blank without -invoking the usual validation check on exit. If this option is off -on a field, exit from it will invoke a validation check.</p> -</dd> -<dt>O_PASSOK</dt> -<dd> -<p>Controls whether validation occurs on every exit, or only after -the field is modified. Normally the latter is true. Setting -O_PASSOK may be useful if your field's validation function may -change during forms processing.</p> -</dd> -<dt>O_STATIC</dt> -<dd> -<p>Controls whether the field is fixed to its initial dimensions. -If you turn this off, the field becomes dynamic and will stretch to -fit entered data.</p> -</dd> -</dl> -</div> -<p>A field's options cannot be changed while the field is currently -selected. However, options may be changed on posted fields that are -not current.</p> -<p>The option values are bit-masks and can be composed with -logical-or in the obvious way. You have seen the usage of switching -off O_AUTOSKIP option. The following example clarifies usage of -some more options. Other options are explained where -appropriate.</p> -<div class="EXAMPLE"><a name="FFOOP" id="FFOOP"></a> -<p><b>Example 27. Field Options Usage example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <form.h> - -#define STARTX 15 -#define STARTY 4 -#define WIDTH 25 - -#define N_FIELDS 3 - -int main() -{ FIELD *field[N_FIELDS]; - FORM *my_form; - int ch, i; - - /* Initialize curses */ - initscr(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize the fields */ - for(i = 0; i < N_FIELDS - 1; ++i) - field[i] = new_field(1, WIDTH, STARTY + i * 2, STARTX, 0, 0); - field[N_FIELDS - 1] = NULL; - - /* Set field options */ - set_field_back(field[1], A_UNDERLINE); /* Print a line for the option */ - - field_opts_off(field[0], O_ACTIVE); /* This field is a static label */ - field_opts_off(field[1], O_PUBLIC); /* This filed is like a password field*/ - field_opts_off(field[1], O_AUTOSKIP); /* To avoid entering the same field */ - /* after last character is entered */ - - /* Create the form and post it */ - my_form = new_form(field); - post_form(my_form); - refresh(); - - set_field_just(field[0], JUSTIFY_CENTER); /* Center Justification */ - set_field_buffer(field[0], 0, "This is a static Field"); - /* Initialize the field */ - mvprintw(STARTY, STARTX - 10, "Field 1:"); - mvprintw(STARTY + 2, STARTX - 10, "Field 2:"); - refresh(); - - /* Loop through to get user requests */ - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case KEY_DOWN: - /* Go to next field */ - form_driver(my_form, REQ_NEXT_FIELD); - /* Go to the end of the present buffer */ - /* Leaves nicely at the last character */ - form_driver(my_form, REQ_END_LINE); - break; - case KEY_UP: - /* Go to previous field */ - form_driver(my_form, REQ_PREV_FIELD); - form_driver(my_form, REQ_END_LINE); - break; - default: - /* If this is a normal character, it gets */ - /* Printed */ - form_driver(my_form, ch); - break; - } - } - - /* Un post form and free the memory */ - unpost_form(my_form); - free_form(my_form); - free_field(field[0]); - free_field(field[1]); - - endwin(); - return 0; -}</span></font> -</pre></td> -</tr> -</table> -</div> -<p>This example, though useless, shows the usage of options. If -used properly, they can present information very effectively in a -form. The second field being not O_PUBLIC, does not show the -characters you are typing.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="FIELDSTATUS" id="FIELDSTATUS">18.3.6. -Field Status</a></h4> -<p>The field status specifies whether the field has got edited or -not. It is initially set to FALSE and when user enters something -and the data buffer gets modified it becomes TRUE. So a field's -status can be queried to find out whether it has been modified or -not. The following functions can assist in those operations.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_field_status(FIELD *field, /* field to alter */ - int status); /* status to set */ - -int field_status(FIELD *field); /* fetch status of field */</font> -</pre></td> -</tr> -</table> -<p>It's better to check the field's status only after after leaving -the field, as data buffer might not have been updated yet as the -validation is still due. To guarantee that right status is -returned, call field_status() either (1) in the field's exit -validation check routine, (2) from the field's or form's -initialization or termination hooks, or (3) just after a -REQ_VALIDATION request has been processed by the forms driver</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="FIELDUSERPTR" id="FIELDUSERPTR">18.3.7. -Field User Pointer</a></h4> -<p>Every field structure contains one pointer that can be used by -the user for various purposes. It is not touched by forms library -and can be used for any purpose by the user. The following -functions set and fetch user pointer.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000">int set_field_userptr(FIELD *field, - char *userptr); /* the user pointer you wish to associate */ - /* with the field */ - -char *field_userptr(FIELD *field); /* fetch user pointer of the field */</font> -</pre></td> -</tr> -</table> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="VARIABLESIZEFIELDS" id= -"VARIABLESIZEFIELDS">18.3.8. Variable-Sized Fields</a></h4> -<p>If you want a dynamically changing field with variable width, -this is the feature you want to put to full use. This will allow -the user to enter more data than the original size of the field and -let the field grow. According to the field orientation it will -scroll horizontally or vertically to incorporate the new data.</p> -<p>To make a field dynamically growable, the option O_STATIC should -be turned off. This can be done with a</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"> field_opts_off(field_pointer, O_STATIC);</font> -</pre></td> -</tr> -</table> -<p>But it's usually not advisable to allow a field to grow -infinitely. You can set a maximum limit to the growth of the field -with</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_max_field(FIELD *field, /* Field on which to operate */ - int max_growth); /* maximum growth allowed for the field */</font> -</pre></td> -</tr> -</table> -<p>The field info for a dynamically growable field can be retrieved -by</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int dynamic_field_info( FIELD *field, /* Field on which to operate */ - int *prows, /* number of rows will be filled in this */ - int *pcols, /* number of columns will be filled in this*/ - int *pmax) /* maximum allowable growth will be filled */ - /* in this */</font> -</pre></td> -</tr> -</table> -Though field_info work as usual, it is advisable to use this -function to get the proper attributes of a dynamically growable -field. -<p>Recall the library routine new_field; a new field created with -height set to one will be defined to be a one line field. A new -field created with height greater than one will be defined to be a -multi line field.</p> -<p>A one line field with O_STATIC turned off (dynamically growable -field) will contain a single fixed row, but the number of columns -can increase if the user enters more data than the initial field -will hold. The number of columns displayed will remain fixed and -the additional data will scroll horizontally.</p> -<p>A multi line field with O_STATIC turned off (dynamically -growable field) will contain a fixed number of columns, but the -number of rows can increase if the user enters more data than the -initial field will hold. The number of rows displayed will remain -fixed and the additional data will scroll vertically.</p> -<p>The above two paragraphs pretty much describe a dynamically -growable field's behavior. The way other parts of forms library -behaves is described below:</p> -<ol type="1"> -<li> -<p>The field option O_AUTOSKIP will be ignored if the option -O_STATIC is off and there is no maximum growth specified for the -field. Currently, O_AUTOSKIP generates an automatic REQ_NEXT_FIELD -form driver request when the user types in the last character -position of a field. On a growable field with no maximum growth -specified, there is no last character position. If a maximum growth -is specified, the O_AUTOSKIP option will work as normal if the -field has grown to its maximum size.</p> -</li> -<li> -<p>The field justification will be ignored if the option O_STATIC -is off. Currently, set_field_just can be used to JUSTIFY_LEFT, -JUSTIFY_RIGHT, JUSTIFY_CENTER the contents of a one line field. A -growable one line field will, by definition, grow and scroll -horizontally and may contain more data than can be justified. The -return from field_just will be unchanged.</p> -</li> -<li> -<p>The overloaded form driver request REQ_NEW_LINE will operate the -same way regardless of the O_NL_OVERLOAD form option if the field -option O_STATIC is off and there is no maximum growth specified for -the field. Currently, if the form option O_NL_OVERLOAD is on, -REQ_NEW_LINE implicitly generates a REQ_NEXT_FIELD if called from -the last line of a field. If a field can grow without bound, there -is no last line, so REQ_NEW_LINE will never implicitly generate a -REQ_NEXT_FIELD. If a maximum growth limit is specified and the -O_NL_OVERLOAD form option is on, REQ_NEW_LINE will only implicitly -generate REQ_NEXT_FIELD if the field has grown to its maximum size -and the user is on the last line.</p> -</li> -<li> -<p>The library call dup_field will work as usual; it will duplicate -the field, including the current buffer size and contents of the -field being duplicated. Any specified maximum growth will also be -duplicated.</p> -</li> -<li> -<p>The library call link_field will work as usual; it will -duplicate all field attributes and share buffers with the field -being linked. If the O_STATIC field option is subsequently changed -by a field sharing buffers, how the system reacts to an attempt to -enter more data into the field than the buffer will currently hold -will depend on the setting of the option in the current field.</p> -</li> -<li> -<p>The library call field_info will work as usual; the variable -nrow will contain the value of the original call to new_field. The -user should use dynamic_field_info, described above, to query the -current size of the buffer.</p> -</li> -</ol> -<p>Some of the above points make sense only after explaining form -driver. We will be looking into that in next few sections.</p> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="FORMWINDOWS" id="FORMWINDOWS">18.4. Form -Windows</a></h3> -<p>The form windows concept is pretty much similar to menu windows. -Every form is associated with a main window and a sub window. The -form main window displays any title or border associated or -whatever the user wishes. Then the sub window contains all the -fields and displays them according to their position. This gives -the flexibility of manipulating fancy form displaying very -easily.</p> -<p>Since this is pretty much similar to menu windows, I am -providing an example with out much explanation. The functions are -similar and they work the same way.</p> -<div class="EXAMPLE"><a name="FFOWI" id="FFOWI"></a> -<p><b>Example 28. Form Windows Example</b></p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000"><span class= -"INLINEMEDIAOBJECT">#include <form.h> - -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); - -int main() -{ - FIELD *field[3]; - FORM *my_form; - WINDOW *my_form_win; - int ch, rows, cols; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize few color pairs */ - init_pair(1, COLOR_RED, COLOR_BLACK); - - /* Initialize the fields */ - field[0] = new_field(1, 10, 6, 1, 0, 0); - field[1] = new_field(1, 10, 8, 1, 0, 0); - field[2] = NULL; - - /* Set field options */ - set_field_back(field[0], A_UNDERLINE); - field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */ - /* Field is filled up */ - set_field_back(field[1], A_UNDERLINE); - field_opts_off(field[1], O_AUTOSKIP); - - /* Create the form and post it */ - my_form = new_form(field); - - /* Calculate the area required for the form */ - scale_form(my_form, &rows, &cols); - - /* Create the window to be associated with the form */ - my_form_win = newwin(rows + 4, cols + 4, 4, 4); - keypad(my_form_win, TRUE); - - /* Set main window and sub window */ - set_form_win(my_form, my_form_win); - set_form_sub(my_form, derwin(my_form_win, rows, cols, 2, 2)); - - /* Print a border around the main window and print a title */ - box(my_form_win, 0, 0); - print_in_middle(my_form_win, 1, 0, cols + 4, "My Form", COLOR_PAIR(1)); - - post_form(my_form); - wrefresh(my_form_win); - - mvprintw(LINES - 2, 0, "Use UP, DOWN arrow keys to switch between fields"); - refresh(); - - /* Loop through to get user requests */ - while((ch = wgetch(my_form_win)) != KEY_F(1)) - { switch(ch) - { case KEY_DOWN: - /* Go to next field */ - form_driver(my_form, REQ_NEXT_FIELD); - /* Go to the end of the present buffer */ - /* Leaves nicely at the last character */ - form_driver(my_form, REQ_END_LINE); - break; - case KEY_UP: - /* Go to previous field */ - form_driver(my_form, REQ_PREV_FIELD); - form_driver(my_form, REQ_END_LINE); - break; - default: - /* If this is a normal character, it gets */ - /* Printed */ - form_driver(my_form, ch); - break; - } - } - - /* Un post form and free the memory */ - unpost_form(my_form); - free_form(my_form); - free_field(field[0]); - free_field(field[1]); - - endwin(); - return 0; -} - -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); -}</span></font> -</pre></td> -</tr> -</table> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="FILEDVALIDATE" id="FILEDVALIDATE">18.5. -Field Validation</a></h3> -<p>By default, a field will accept any data input by the user. It -is possible to attach validation to the field. Then any attempt by -the user to leave the field, while it contains data that doesn't -match the validation type will fail. Some validation types also -have a character-validity check for each time a character is -entered in the field.</p> -<p>Validation can be attached to a field with the following -function.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_field_type(FIELD *field, /* field to alter */ - FIELDTYPE *ftype, /* type to associate */ - ...); /* additional arguments*/</font> -</pre></td> -</tr> -</table> -Once set, the validation type for a field can be queried with -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">FIELDTYPE *field_type(FIELD *field); /* field to query */</font> -</pre></td> -</tr> -</table> -<p>The form driver validates the data in a field only when data is -entered by the end-user. Validation does not occur when</p> -<ul> -<li> -<p>the application program changes the field value by calling -set_field_buffer.</p> -</li> -<li> -<p>linked field values are changed indirectly -- by changing the -field to which they are linked</p> -</li> -</ul> -<p>The following are the pre-defined validation types. You can also -specify custom validation, though it's a bit tricky and -cumbersome.</p> -<h1 class="BRIDGEHEAD"><a name="AEN1069" id= -"AEN1069"></a>TYPE_ALPHA</h1> -<p>This field type accepts alphabetic data; no blanks, no digits, -no special characters (this is checked at character-entry time). It -is set up with:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_field_type(FIELD *field, /* field to alter */ - TYPE_ALPHA, /* type to associate */ - int width); /* maximum width of field */</font> -</pre></td> -</tr> -</table> -<p>The width argument sets a minimum width of data. The user has to -enter at-least width number of characters before he can leave the -field. Typically you'll want to set this to the field width; if -it's greater than the field width, the validation check will always -fail. A minimum width of zero makes field completion optional.</p> -<h1 class="BRIDGEHEAD"><a name="AEN1073" id= -"AEN1073"></a>TYPE_ALNUM</h1> -<p>This field type accepts alphabetic data and digits; no blanks, -no special characters (this is checked at character-entry time). It -is set up with:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_field_type(FIELD *field, /* field to alter */ - TYPE_ALNUM, /* type to associate */ - int width); /* maximum width of field */</font> -</pre></td> -</tr> -</table> -<p>The width argument sets a minimum width of data. As with -TYPE_ALPHA, typically you'll want to set this to the field width; -if it's greater than the field width, the validation check will -always fail. A minimum width of zero makes field completion -optional.</p> -<h1 class="BRIDGEHEAD"><a name="AEN1077" id= -"AEN1077"></a>TYPE_ENUM</h1> -<p>This type allows you to restrict a field's values to be among a -specified set of string values (for example, the two-letter postal -codes for U.S. states). It is set up with:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_field_type(FIELD *field, /* field to alter */ - TYPE_ENUM, /* type to associate */ - char **valuelist; /* list of possible values */ - int checkcase; /* case-sensitive? */ - int checkunique); /* must specify uniquely? */</font> -</pre></td> -</tr> -</table> -<p>The valuelist parameter must point at a NULL-terminated list of -valid strings. The checkcase argument, if true, makes comparison -with the string case-sensitive.</p> -<p>When the user exits a TYPE_ENUM field, the validation procedure -tries to complete the data in the buffer to a valid entry. If a -complete choice string has been entered, it is of course valid. But -it is also possible to enter a prefix of a valid string and have it -completed for you.</p> -<p>By default, if you enter such a prefix and it matches more than -one value in the string list, the prefix will be completed to the -first matching value. But the checkunique argument, if true, -requires prefix matches to be unique in order to be valid.</p> -<p>The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be -particularly useful with these fields.</p> -<h1 class="BRIDGEHEAD"><a name="AEN1084" id= -"AEN1084"></a>TYPE_INTEGER</h1> -<p>This field type accepts an integer. It is set up as follows:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_field_type(FIELD *field, /* field to alter */ - TYPE_INTEGER, /* type to associate */ - int padding, /* # places to zero-pad to */ - int vmin, int vmax); /* valid range */</font> -</pre></td> -</tr> -</table> -<p>Valid characters consist of an optional leading minus and -digits. The range check is performed on exit. If the range maximum -is less than or equal to the minimum, the range is ignored.</p> -<p>If the value passes its range check, it is padded with as many -leading zero digits as necessary to meet the padding argument.</p> -<p>A TYPE_INTEGER value buffer can conveniently be interpreted with -the C library function atoi(3).</p> -<h1 class="BRIDGEHEAD"><a name="AEN1090" id= -"AEN1090"></a>TYPE_NUMERIC</h1> -<p>This field type accepts a decimal number. It is set up as -follows:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_field_type(FIELD *field, /* field to alter */ - TYPE_NUMERIC, /* type to associate */ - int padding, /* # places of precision */ - int vmin, int vmax); /* valid range */</font> -</pre></td> -</tr> -</table> -<p>Valid characters consist of an optional leading minus and -digits. possibly including a decimal point. The range check is -performed on exit. If the range maximum is less than or equal to -the minimum, the range is ignored.</p> -<p>If the value passes its range check, it is padded with as many -trailing zero digits as necessary to meet the padding argument.</p> -<p>A TYPE_NUMERIC value buffer can conveniently be interpreted with -the C library function atof(3).</p> -<h1 class="BRIDGEHEAD"><a name="AEN1096" id= -"AEN1096"></a>TYPE_REGEXP</h1> -<p>This field type accepts data matching a regular expression. It -is set up as follows:</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_field_type(FIELD *field, /* field to alter */ - TYPE_REGEXP, /* type to associate */ - char *regexp); /* expression to match */</font> -</pre></td> -</tr> -</table> -<p>The syntax for regular expressions is that of regcomp(3). The -check for regular-expression match is performed on exit.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="FORMDRIVER" id="FORMDRIVER">18.6. Form -Driver: The work horse of the forms system</a></h3> -<p>As in the menu system, form_driver() plays a very important role -in forms system. All types of requests to forms system should be -funneled through form_driver().</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int form_driver(FORM *form, /* form on which to operate */ - int request) /* form request code */</font> -</pre></td> -</tr> -</table> -<p>As you have seen some of the examples above, you have to be in a -loop looking for user input and then decide whether it's a field -data or a form request. The form requests are then passed to -form_driver() to do the work.</p> -<p>The requests roughly can be divided into following categories. -Different requests and their usage is explained below:</p> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="PAGENAVREQ" id="PAGENAVREQ">18.6.1. Page -Navigation Requests</a></h4> -<p>These requests cause page-level moves through the form, -triggering display of a new form screen. A form can be made of -multiple pages. If you have a big form with lot of fields and -logical sections, then you can divide the form into pages. The -function set_new_page() to set a new page at the field -specified.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">int set_new_page(FIELD *field,/* Field at which page break to be set or unset */ - bool new_page_flag); /* should be TRUE to put a break */</font> -</pre></td> -</tr> -</table> -<p>The following requests allow you to move to different pages</p> -<ul> -<li> -<p><em>REQ_NEXT_PAGE</em> Move to the next form page.</p> -</li> -<li> -<p><em>REQ_PREV_PAGE</em> Move to the previous form page.</p> -</li> -<li> -<p><em>REQ_FIRST_PAGE</em> Move to the first form page.</p> -</li> -<li> -<p><em>REQ_LAST_PAGE</em> Move to the last form page.</p> -</li> -</ul> -<p>These requests treat the list as cyclic; that is, REQ_NEXT_PAGE -from the last page goes to the first, and REQ_PREV_PAGE from the -first page goes to the last.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="INTERFIELDNAVREQ" id= -"INTERFIELDNAVREQ">18.6.2. Inter-Field Navigation Requests</a></h4> -<p>These requests handle navigation between fields on the same -page.</p> -<ul> -<li> -<p><em>REQ_NEXT_FIELD</em> Move to next field.</p> -</li> -<li> -<p><em>REQ_PREV_FIELD</em> Move to previous field.</p> -</li> -<li> -<p><em>REQ_FIRST_FIELD</em> Move to the first field.</p> -</li> -<li> -<p><em>REQ_LAST_FIELD</em> Move to the last field.</p> -</li> -<li> -<p><em>REQ_SNEXT_FIELD</em> Move to sorted next field.</p> -</li> -<li> -<p><em>REQ_SPREV_FIELD</em> Move to sorted previous field.</p> -</li> -<li> -<p><em>REQ_SFIRST_FIELD</em> Move to the sorted first field.</p> -</li> -<li> -<p><em>REQ_SLAST_FIELD</em> Move to the sorted last field.</p> -</li> -<li> -<p><em>REQ_LEFT_FIELD</em> Move left to field.</p> -</li> -<li> -<p><em>REQ_RIGHT_FIELD</em> Move right to field.</p> -</li> -<li> -<p><em>REQ_UP_FIELD</em> Move up to field.</p> -</li> -<li> -<p><em>REQ_DOWN_FIELD</em> Move down to field.</p> -</li> -</ul> -<p>These requests treat the list of fields on a page as cyclic; -that is, REQ_NEXT_FIELD from the last field goes to the first, and -REQ_PREV_FIELD from the first field goes to the last. The order of -the fields for these (and the REQ_FIRST_FIELD and REQ_LAST_FIELD -requests) is simply the order of the field pointers in the form -array (as set up by new_form() or set_form_fields()</p> -<p>It is also possible to traverse the fields as if they had been -sorted in screen-position order, so the sequence goes left-to-right -and top-to-bottom. To do this, use the second group of four -sorted-movement requests.</p> -<p>Finally, it is possible to move between fields using visual -directions up, down, right, and left. To accomplish this, use the -third group of four requests. Note, however, that the position of a -form for purposes of these requests is its upper-left corner.</p> -<p>For example, suppose you have a multi-line field B, and two -single-line fields A and C on the same line with B, with A to the -left of B and C to the right of B. A REQ_MOVE_RIGHT from A will go -to B only if A, B, and C all share the same first line; otherwise -it will skip over B to C.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="INTRAFIELDNAVREQ" id= -"INTRAFIELDNAVREQ">18.6.3. Intra-Field Navigation Requests</a></h4> -<p>These requests drive movement of the edit cursor within the -currently selected field.</p> -<ul> -<li> -<p><em>REQ_NEXT_CHAR</em> Move to next character.</p> -</li> -<li> -<p><em>REQ_PREV_CHAR</em> Move to previous character.</p> -</li> -<li> -<p><em>REQ_NEXT_LINE</em> Move to next line.</p> -</li> -<li> -<p><em>REQ_PREV_LINE</em> Move to previous line.</p> -</li> -<li> -<p><em>REQ_NEXT_WORD</em> Move to next word.</p> -</li> -<li> -<p><em>REQ_PREV_WORD</em> Move to previous word.</p> -</li> -<li> -<p><em>REQ_BEG_FIELD</em> Move to beginning of field.</p> -</li> -<li> -<p><em>REQ_END_FIELD</em> Move to end of field.</p> -</li> -<li> -<p><em>REQ_BEG_LINE</em> Move to beginning of line.</p> -</li> -<li> -<p><em>REQ_END_LINE</em> Move to end of line.</p> -</li> -<li> -<p><em>REQ_LEFT_CHAR</em> Move left in field.</p> -</li> -<li> -<p><em>REQ_RIGHT_CHAR</em> Move right in field.</p> -</li> -<li> -<p><em>REQ_UP_CHAR</em> Move up in field.</p> -</li> -<li> -<p><em>REQ_DOWN_CHAR</em> Move down in field.</p> -</li> -</ul> -<p>Each word is separated from the previous and next characters by -whitespace. The commands to move to beginning and end of line or -field look for the first or last non-pad character in their -ranges.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="SCROLLREQ" id="SCROLLREQ">18.6.4. -Scrolling Requests</a></h4> -<p>Fields that are dynamic and have grown and fields explicitly -created with offscreen rows are scrollable. One-line fields scroll -horizontally; multi-line fields scroll vertically. Most scrolling -is triggered by editing and intra-field movement (the library -scrolls the field to keep the cursor visible). It is possible to -explicitly request scrolling with the following requests:</p> -<ul> -<li> -<p><em>REQ_SCR_FLINE</em> Scroll vertically forward a line.</p> -</li> -<li> -<p><em>REQ_SCR_BLINE</em> Scroll vertically backward a line.</p> -</li> -<li> -<p><em>REQ_SCR_FPAGE</em> Scroll vertically forward a page.</p> -</li> -<li> -<p><em>REQ_SCR_BPAGE</em> Scroll vertically backward a page.</p> -</li> -<li> -<p><em>REQ_SCR_FHPAGE</em> Scroll vertically forward half a -page.</p> -</li> -<li> -<p><em>REQ_SCR_BHPAGE</em> Scroll vertically backward half a -page.</p> -</li> -<li> -<p><em>REQ_SCR_FCHAR</em> Scroll horizontally forward a -character.</p> -</li> -<li> -<p><em>REQ_SCR_BCHAR</em> Scroll horizontally backward a -character.</p> -</li> -<li> -<p><em>REQ_SCR_HFLINE</em> Scroll horizontally one field width -forward.</p> -</li> -<li> -<p><em>REQ_SCR_HBLINE</em> Scroll horizontally one field width -backward.</p> -</li> -<li> -<p><em>REQ_SCR_HFHALF</em> Scroll horizontally one half field width -forward.</p> -</li> -<li> -<p><em>REQ_SCR_HBHALF</em> Scroll horizontally one half field width -backward.</p> -</li> -</ul> -<p>For scrolling purposes, a page of a field is the height of its -visible part.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="EDITREQ" id="EDITREQ">18.6.5. Editing -Requests</a></h4> -<p>When you pass the forms driver an ASCII character, it is treated -as a request to add the character to the field's data buffer. -Whether this is an insertion or a replacement depends on the -field's edit mode (insertion is the default.</p> -<p>The following requests support editing the field and changing -the edit mode:</p> -<ul> -<li> -<p><em>REQ_INS_MODE</em> Set insertion mode.</p> -</li> -<li> -<p><em>REQ_OVL_MODE</em> Set overlay mode.</p> -</li> -<li> -<p><em>REQ_NEW_LINE</em> New line request (see below for -explanation).</p> -</li> -<li> -<p><em>REQ_INS_CHAR</em> Insert space at character location.</p> -</li> -<li> -<p><em>REQ_INS_LINE</em> Insert blank line at character -location.</p> -</li> -<li> -<p><em>REQ_DEL_CHAR</em> Delete character at cursor.</p> -</li> -<li> -<p><em>REQ_DEL_PREV</em> Delete previous word at cursor.</p> -</li> -<li> -<p><em>REQ_DEL_LINE</em> Delete line at cursor.</p> -</li> -<li> -<p><em>REQ_DEL_WORD</em> Delete word at cursor.</p> -</li> -<li> -<p><em>REQ_CLR_EOL</em> Clear to end of line.</p> -</li> -<li> -<p><em>REQ_CLR_EOF</em> Clear to end of field.</p> -</li> -<li> -<p><em>REQ_CLR_FIELD</em> Clear entire field.</p> -</li> -</ul> -<p>The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is -complicated and partly controlled by a pair of forms options. The -special cases are triggered when the cursor is at the beginning of -a field, or on the last line of the field.</p> -<p>First, we consider REQ_NEW_LINE:</p> -<p>The normal behavior of REQ_NEW_LINE in insert mode is to break -the current line at the position of the edit cursor, inserting the -portion of the current line after the cursor as a new line -following the current and moving the cursor to the beginning of -that new line (you may think of this as inserting a newline in the -field buffer).</p> -<p>The normal behavior of REQ_NEW_LINE in overlay mode is to clear -the current line from the position of the edit cursor to end of -line. The cursor is then moved to the beginning of the next -line.</p> -<p>However, REQ_NEW_LINE at the beginning of a field, or on the -last line of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD -option is off, this special action is disabled.</p> -<p>Now, let us consider REQ_DEL_PREV:</p> -<p>The normal behavior of REQ_DEL_PREV is to delete the previous -character. If insert mode is on, and the cursor is at the start of -a line, and the text on that line will fit on the previous one, it -instead appends the contents of the current line to the previous -one and deletes the current line (you may think of this as deleting -a newline from the field buffer).</p> -<p>However, REQ_DEL_PREV at the beginning of a field is instead -treated as a REQ_PREV_FIELD.</p> -<p>If the O_BS_OVERLOAD option is off, this special action is -disabled and the forms driver just returns E_REQUEST_DENIED.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="ORDERREQ" id="ORDERREQ">18.6.6. Order -Requests</a></h4> -<p>If the type of your field is ordered, and has associated -functions for getting the next and previous values of the type from -a given value, there are requests that can fetch that value into -the field buffer:</p> -<ul> -<li> -<p><em>REQ_NEXT_CHOICE</em> Place the successor value of the -current value in the buffer.</p> -</li> -<li> -<p><em>REQ_PREV_CHOICE</em> Place the predecessor value of the -current value in the buffer.</p> -</li> -</ul> -<p>Of the built-in field types, only TYPE_ENUM has built-in -successor and predecessor functions. When you define a field type -of your own (see Custom Validation Types), you can associate our -own ordering functions.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="APPLICCOMMANDS" id= -"APPLICCOMMANDS">18.6.7. Application Commands</a></h4> -<p>Form requests are represented as integers above the curses value -greater than KEY_MAX and less than or equal to the constant -MAX_COMMAND. A value within this range gets ignored by -form_driver(). So this can be used for any purpose by the -application. It can be treated as an application specific action -and take corresponding action.</p> -</div> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="TOOLS" id="TOOLS">19. Tools and Widget -Libraries</a></h2> -<p>Now that you have seen the capabilities of ncurses and its -sister libraries, you are rolling your sleeves up and gearing for a -project that heavily manipulates screen. But wait.. It can be -pretty difficult to write and maintain complex GUI widgets in plain -ncurses or even with the additional libraries. There are some -ready-to-use tools and widget libraries that can be used instead of -writing your own widgets. You can use some of them, get ideas from -the code, or even extend them.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="CDK" id="CDK">19.1. CDK (Curses -Development Kit)</a></h3> -<p>In the author's words</p> -<p><em>CDK stands for 'Curses Development Kit' and it currently -contains 21 ready to use widgets which facilitate the speedy -development of full screen curses programs.</em></p> -<p>The kit provides some useful widgets, which can be used in your -programs directly. It's pretty well written and the documentation -is very good. The examples in the examples directory can be a good -place to start for beginners. The CDK can be downloaded from -<a href="http://invisible-island.net/cdk/" target= -"_top">http://invisible-island.net/cdk/</a> . Follow the -instructions in README file to install it.</p> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="WIDGETLIST" id="WIDGETLIST">19.1.1. -Widget List</a></h4> -<p>The following is the list of widgets provided with cdk and their -description.</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color="#000000">Widget Type Quick Description -=========================================================================== -Alphalist Allows a user to select from a list of words, with - the ability to narrow the search list by typing in a - few characters of the desired word. -Buttonbox This creates a multiple button widget. -Calendar Creates a little simple calendar widget. -Dialog Prompts the user with a message, and the user - can pick an answer from the buttons provided. -Entry Allows the user to enter various types of information. -File Selector A file selector built from Cdk base widgets. This - example shows how to create more complicated widgets - using the Cdk widget library. -Graph Draws a graph. -Histogram Draws a histogram. -Item List Creates a pop up field which allows the user to select - one of several choices in a small field. Very useful - for things like days of the week or month names. -Label Displays messages in a pop up box, or the label can be - considered part of the screen. -Marquee Displays a message in a scrolling marquee. -Matrix Creates a complex matrix with lots of options. -Menu Creates a pull-down menu interface. -Multiple Line Entry A multiple line entry field. Very useful - for long fields. (like a description - field) -Radio List Creates a radio button list. -Scale Creates a numeric scale. Used for allowing a user to - pick a numeric value and restrict them to a range of - values. -Scrolling List Creates a scrolling list/menu list. -Scrolling Window Creates a scrolling log file viewer. Can add - information into the window while its running. - A good widget for displaying the progress of - something. (akin to a console window) -Selection List Creates a multiple option selection list. -Slider Akin to the scale widget, this widget provides a - visual slide bar to represent the numeric value. -Template Creates a entry field with character sensitive - positions. Used for pre-formatted fields like - dates and phone numbers. -Viewer This is a file/information viewer. Very useful - when you need to display loads of information. -===========================================================================</font> -</pre></td> -</tr> -</table> -<p>A few of the widgets are modified by Thomas Dickey in recent -versions.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="CDKATTRACT" id="CDKATTRACT">19.1.2. Some -Attractive Features</a></h4> -<p>Apart from making our life easier with readily usable widgets, -cdk solves one frustrating problem with printing multi colored -strings, justified strings elegantly. Special formatting tags can -be embedded in the strings which are passed to CDK functions. For -Example</p> -<p>If the string</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000">"</B/1>This line should have a yellow foreground and a blue -background.<!1>"</font> -</pre></td> -</tr> -</table> -<p>given as a parameter to newCDKLabel(), it prints the line with -yellow foreground and blue background. There are other tags -available for justifying string, embedding special drawing -characters etc.. Please refer to the man page cdk_display(3X) for -details. The man page explains the usage with nice examples.</p> -</div> -<div class="SECT3"> -<hr> -<h4 class="SECT3"><a name="CDKCONCLUSION" id= -"CDKCONCLUSION">19.1.3. Conclusion</a></h4> -<p>All in all, CDK is a well-written package of widgets, which if -used properly can form a strong frame work for developing complex -GUI.</p> -</div> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="DIALOG" id="DIALOG">19.2. The -dialog</a></h3> -<p>Long long ago, in September 1994, when few people knew linux, -Jeff Tranter wrote an <a href= -"http://www2.linuxjournal.com/lj-issues/issue5/2807.html" target= -"_top">article</a> on dialog in Linux Journal. He starts the -article with these words..</p> -<p><em>Linux is based on the Unix operating system, but also -features a number of unique and useful kernel features and -application programs that often go beyond what is available under -Unix. One little-known gem is "dialog", a utility for creating -professional-looking dialog boxes from within shell scripts. This -article presents a tutorial introduction to the dialog utility, and -shows examples of how and where it can be used</em></p> -<p>As he explains, dialog is a real gem in making -professional-looking dialog boxes with ease. It creates a variety -of dialog boxes, menus, check lists etc.. It is usually installed -by default. If not, you can download it from <a href= -"http://invisible-island.net/dialog/" target="_top">Thomas -Dickey</a>'s site.</p> -<p>The above-mentioned article gives a very good overview of its -uses and capabilites. The man page has more details. It can be used -in variety of situations. One good example is building of linux -kernel in text mode. Linux kernel uses a modified version of dialog -tailored for its needs.</p> -<p>dialog was initially designed to be used with shell scripts. If -you want to use its functionality in a c program, then you can use -libdialog. The documentation regarding this is sparse. Definitive -reference is the dialog.h header file which comes with the library. -You may need to hack here and there to get the required output. The -source is easily customizable. I have used it on a number of -occasions by modifying the code.</p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="PERLCURSES" id="PERLCURSES">19.3. Perl -Curses Modules CURSES::FORM and CURSES::WIDGETS</a></h3> -<p>The perl module Curses, Curses::Form and Curses::Widgets give -access to curses from perl. If you have curses and basic perl is -installed, you can get these modules from <a href= -"http://www.cpan.org/modules/01modules.index.html" target= -"_top">CPAN All Modules page</a>. Get the three zipped modules in -the Curses category. Once installed you can use these modules from -perl scripts like any other module. For more information on perl -modules see perlmod man page. The above modules come with good -documentation and they have some demo scripts to test the -functionality. Though the widgets provided are very rudimentary, -these modules provide good access to curses library from perl.</p> -<p>Some of my code examples are converted to perl by Anuradha -Ratnaweera and they are available in the <var class= -"LITERAL">perl</var> directory.</p> -<p>For more information see man pages Curses(3) , Curses::Form(3) -and Curses::Widgets(3). These pages are installed only when the -above modules are acquired and installed.</p> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="JUSTFORFUN" id="JUSTFORFUN">20. Just For -Fun !!!</a></h2> -<p>This section contains few programs written by me just for fun. -They don't signify a better programming practice or the best way of -using ncurses. They are provided here so as to allow beginners to -get ideas and add more programs to this section. If you have -written a couple of nice, simple programs in curses and want them -to included here, contact <a href="mailto:ppadala@gmail.com" -target="_top">me</a>.</p> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="GAMEOFLIFE" id="GAMEOFLIFE">20.1. The -Game of Life</a></h3> -<p>Game of life is a wonder of math. In <a href= -"http://www.math.com/students/wonders/life/life.html" target= -"_top">Paul Callahan</a>'s words</p> -<table border="0" bgcolor="#E0E0E0" width="100%"> -<tr> -<td> -<pre class="PROGRAMLISTING"> -<font color= -"#000000"><em>The Game of Life (or simply Life) is not a game in the conventional sense. There -are no players, and no winning or losing. Once the "pieces" are placed in the -starting position, the rules determine everything that happens later. -Nevertheless, Life is full of surprises! In most cases, it is impossible to look -at a starting position (or pattern) and see what will happen in the future. The -only way to find out is to follow the rules of the game.</em></font> -</pre></td> -</tr> -</table> -<p>This program starts with a simple inverted U pattern and shows -how wonderful life works. There is a lot of room for improvement in -the program. You can let the user enter pattern of his choice or -even take input from a file. You can also change rules and play -with a lot of variations. Search on <a href="http://www.google.com" -target="_top">google</a> for interesting information on game of -life.</p> -<p><em>File Path: JustForFun/life.c</em></p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="MAGIC" id="MAGIC">20.2. Magic -Square</a></h3> -<p>Magic Square, another wonder of math, is very simple to -understand but very difficult to make. In a magic square sum of the -numbers in each row, each column is equal. Even diagnol sum can be -equal. There are many variations which have special properties.</p> -<p>This program creates a simple magic square of odd order.</p> -<p><em>File Path: JustForFun/magic.c</em></p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="HANOI" id="HANOI">20.3. Towers of -Hanoi</a></h3> -<p>The famous towers of hanoi solver. The aim of the game is to -move the disks on the first peg to last peg, using middle peg as a -temporary stay. The catch is not to place a larger disk over a -small disk at any time.</p> -<p><em>File Path: JustForFun/hanoi.c</em></p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="QUEENS" id="QUEENS">20.4. Queens -Puzzle</a></h3> -<p>The objective of the famous N-Queen puzzle is to put N queens on -a N X N chess board without attacking each other.</p> -<p>This program solves it with a simple backtracking technique.</p> -<p><em>File Path: JustForFun/queens.c</em></p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="SHUFFLE" id="SHUFFLE">20.5. -Shuffle</a></h3> -<p>A fun game, if you have time to kill.</p> -<p><em>File Path: JustForFun/shuffle.c</em></p> -</div> -<div class="SECT2"> -<hr> -<h3 class="SECT2"><a name="TT" id="TT">20.6. Typing Tutor</a></h3> -<p>A simple typing tutor, I created more out of need than for ease -of use. If you know how to put your fingers correctly on the -keyboard, but lack practice, this can be helpful.</p> -<p><em>File Path: JustForFun/tt.c</em></p> -</div> -</div> -<div class="SECT1"> -<hr> -<h2 class="SECT1"><a name="REF" id="REF">21. References</a></h2> -<ul> -<li> -<p>NCURSES man pages</p> -</li> -<li> -<p>NCURSES FAQ at <a href= -"http://invisible-island.net/ncurses/ncurses.faq.html" target= -"_top">http://invisible-island.net/ncurses/ncurses.faq.html</a></p> -</li> -<li> -<p>Writing programs with NCURSES by Eric Raymond and Zeyd M. -Ben-Halim at <a href= -"http://invisible-island.net/ncurses/ncurses-intro.html" target= -"_top">http://invisible-island.net/ncurses/ncurses-intro.html</a> - -somewhat obsolete. I was inspired by this document and the -structure of this HOWTO follows from the original document</p> -</li> -</ul> -</div> -</div> -</body> -</html> diff --git a/contrib/ncurses/doc/html/announce.html b/contrib/ncurses/doc/html/announce.html deleted file mode 100644 index f9dae07..0000000 --- a/contrib/ncurses/doc/html/announce.html +++ /dev/null @@ -1,600 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN"> -<!-- - $Id: announce.html,v 1.51 2006/12/17 23:32:42 tom Exp $ - **************************************************************************** - * Copyright (c) 1998-2005,2006 Free Software Foundation, Inc. * - * * - * Permission is hereby granted, free of charge, to any person obtaining a * - * copy of this software and associated documentation files (the * - * "Software"), to deal in the Software without restriction, including * - * without limitation the rights to use, copy, modify, merge, publish, * - * distribute, distribute with modifications, sublicense, and/or sell * - * copies of the Software, and to permit persons to whom the Software is * - * furnished to do so, subject to the following conditions: * - * * - * The above copyright notice and this permission notice shall be included * - * in all copies or substantial portions of the Software. * - * * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * - * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * - * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * - * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * - * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * - * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * - * * - * Except as contained in this notice, the name(s) of the above copyright * - * holders shall not be used in advertising or otherwise to promote the * - * sale, use or other dealings in this Software without prior written * - * authorization. * - **************************************************************************** ---> -<HTML> -<HEAD> -<TITLE>Announcing ncurses 5.6</TITLE> -<link rev=made href="mailto:bug-ncurses@gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -</HEAD> -<BODY> - -<H1>Announcing ncurses 5.6</H1> - -The ncurses (new curses) library is a free software emulation of -curses in System V Release 4.0, and more. It uses terminfo format, -supports pads and color -and multiple highlights and forms characters and function-key mapping, -and has all the other SYSV-curses enhancements over BSD curses.<P> - -In mid-June 1995, the maintainer of 4.4BSD curses declared that he -considered 4.4BSD curses obsolete, and encouraged the keepers of -Unix releases such as BSD/OS, FreeBSD and NetBSD to switch over to -ncurses.<P> - -The ncurses code was developed under GNU/Linux. -It has been in use for some time with OpenBSD as the system curses library, -and on FreeBSD and NetBSD as an external package. -It should port easily to any ANSI/POSIX-conforming UNIX. -It has even been ported to OS/2 Warp!<P> - -The distribution includes the library and support utilities, including a -terminfo compiler tic(1), a decompiler infocmp(1), clear(1), tput(1), tset(1), -and a termcap conversion tool captoinfo(1). Full manual pages are provided for -the library and tools.<P> - -The ncurses distribution is available via anonymous FTP at -the GNU distribution site -<A HREF="ftp://ftp.gnu.org/gnu/ncurses/">ftp://ftp.gnu.org/gnu/ncurses/</A> . -<br>It is also available at -<A HREF="ftp://invisible-island.net/ncurses/">ftp://invisible-island.net/ncurses/</A> . - -<H1>Release Notes</H1> - -This release is designed to be upward compatible from ncurses 5.0 through 5.5; -very few applications will require recompilation, depending on the platform. -These are the highlights from the change-log since ncurses 5.5 release. -<p> -Interface changes: -<ul> - <li>generate linkable stubs for some macros: - <br> - getbegx, getbegy, getcurx, getcury, getmaxx, getmaxy, getparx, - getpary, getpary, - <br> - and (for libncursesw) - <br> - wgetbkgrnd - -</ul> -New features and improvements: -<ul> - <li>library - <ul> - <li>support hashed databases for the terminal descriptions. - This uses the Berkeley database, has been tested for - several versions on different platforms. - - <li>add <code>use_legacy_coding()</code> function to support - lynx's font-switching feature. - - <li>add extension <code>nofilter()</code>, to cancel a prior - <code>filter()</code> call. - - <li>add/install a package config script, e.g., - <code>ncurses5-config</code> or - <code>ncursesw5-config</code>, according to - configuration options. - - <li>provide ifdef for <code>NCURSES_NOMACROS</code> which - suppresses most macro definitions from curses.h, i.e., - where a macro is defined to override a function to improve - performance. - - <li>make ifdef's consistent in <code>curses.h</code> for the - extended colors so the header file can be used for the - normal curses library. The header file installed for - extended colors is a variation of the wide-character - configuration. - - <li>improve <code>tgetstr()</code> by making the return value - point into the user's buffer, if provided. - - <li>add ifdef's allowing ncurses to be built with - <code>tparm()</code> using either varargs (the existing - status), or using a fixed-parameter list (to match X/Open). - - <li>widen the test for xterm <code>kmous</code> a little to - <code>allow</code> for other - strings than "\E[M", e.g., for <code>xterm-sco</code> - functionality in xterm. - - <li>modify <code>wgetnstr()</code> to return - <code>KEY_RESIZE</code> if a sigwinch occurs. - - <li>move prototypes for wide-character trace functions from - curses.tail to curses.wide to avoid accidental reference to - those if <code>_XOPEN_SOURCE_EXTENDED</code> is defined - without ensuring that <wchar.h> is included. - - <li>change the way shared libraries (other than libtool) are - installed. Rather than copying the build-tree's libraries, - link the shared objects into the install directory. This - makes the <code>--with-rpath</code> option work except with - <code>$(DESTDIR)</code>. - - <li>several improvements for rendering in hpterm. These are - only available if the library is configured using - <code>--enable-xmc-glitch</code>. - - <li>Add <code>NCURSES_NO_HARD_TABS</code> and - <code>NCURSES_NO_MAGIC_COOKIE</code> environment variables - to allow runtime suppression of the related hard-tabs and - xmc-glitch features. - </ul> - - <li>programs: - <ul> - <li>add new test programs: chgat.c, demo_altkeys.c, - echochar.c, foldkeys.c, movewindow.c, redraw.c, (noting - that existing test programs also were modified to test - additional features). - - <li>modify tack to test extended capability function-key - strings. - - <li>modify toe to access termcap data, e.g., via <code>cgetent()</code> - functions, or as a text file if those are not available. - - <li>improve infocmp/tic <code>-f</code> option formatting. - - <li>add <code>toe -a</code> option, to show all databases. - This uses new private interfaces in the ncurses library for - iterating through the list of databases. - - <li>modify <code>MKfallback.sh</code> to use - <code>tic -x</code> when constructing fallback tables to - allow extended capabilities to be retrieved from a fallback entry. - </ul> - - <li>terminal database - <ul> - <li>add terminfo entries for xfce terminal (xfce) and multi gnome terminal (mgt) - <li>add nsterm-16color entry - <li>updated mlterm terminfo entry - <li>add kon, kon2 and jfbterm terminfo entry - <li>remove invis capability from klone+sgr, mainly used by linux entry, since it does not really do this - <li>add ka2, kb1, kb3, kc2 to vt220-keypad as an extension - <li>add shifted up/down arrow codes to xterm-new as kind/kri strings - <li>add hpterm-color terminfo entry - <li>add 256color variants of terminfo entries for programs which are reported to implement this feature - <li>correct order of use-clauses in rxvt-basic entry which made codes for f1-f4 vt100-style rather than vt220-style. - </ul> -</ul> -Major bug fixes: -<ul> - <li>correct a typo in configure <code>--with-bool</code> option for the - case where <code>--without-cxx</code> is used. - - <li>move assignment from environment variable <code>ESCDELAY</code> - from <code>initscr()</code> down to <code>newterm()</code> so the - environment variable affects timeouts for terminals opened with - newterm() as well. - - <li>modify <code>werase</code> to clear multicolumn characters that - extend into a derived window. - - <li>modify <code>wchgat()</code> to mark updated cells as changed so a - refresh will repaint those cells. - - <li>correct logic in <code>wadd_wch()</code> and - <code>wecho_wch()</code>, which did not guard against passing the - multi-column attribute into a call on <code>waddch()</code>, e.g., - using data returned by <code>win_wch()</code> - - <li>fix redrawing of windows other than <code>stdscr</code> using - <code>wredrawln()</code> by touching the corresponding rows in - <code>curscr</code>. - - <li>reduce memory leaks in repeated calls to <code>tgetent()</code> by - remembering the last <code>TERMINAL*</code> value allocated to hold - the corresponding data and freeing that if the - <code>tgetent()</code> result buffer is the same as the previous - call. - - <li>modify <code>read_termtype()</code> so the <code>term_names</code> - data is always allocated as part of the <code>str_table</code>, a - better fix for a memory leak. - - <li>fix <code>wins_nwstr(),</code> which did not handle single-column - non-8bit codes. - - <li>modify <code>wbkgrnd()</code> to avoid clearing the - <code>A_CHARTEXT</code> attribute bits since those record the state - of multicolumn characters. - - <li>improve <code>SIGWINCH</code> handling by postponing its effect - during <code>newterm()</code>, etc., when allocating screens. - - <li>remove 970913 feature for copying subwindows as they are moved in - <code>mvwin()</code>. - - <li>add checks in <code>waddchnstr()</code> and - <code>wadd_wchnstr()</code> to stop copying when a null character - is found. - - <li>add some checks to ensure current position is within scrolling - region before scrolling on a new line. - - <li>add a workaround to ACS mapping to allow applications such as - test/blue.c to use the "PC ROM" characters by masking them with - A_ALTCHARSET. This worked up til 5.5, but was lost in the revision - of legacy coding. -</ul> - -Portability: -<ul> - <li>configure script: - <ul> - <li>new options: - <dl> - - <dt>--with-hashed-db - <dd>Use Berkeley hashed database for storing terminfo data rather than storing - each compiled entry in a separate binary file within a directory - tree. - - <dt>--without-dlsym - <dd>Do not use <code>dlsym()</code> to load GPM dynamically. - - <dt>--with-valgrind - <dd>Simplify building for testing with valgrind. - - <dt>--enable-wgetch-events - <dd>Compile with experimental wgetch-events code. - - <dt>--enable-signed-char - <dd>Store booleans in "signed char" rather than "char". - - </dl> - - <li>improved options: - <dl> - - <dt>--disable-largefile - <dd>make the option work both ways. - - <dt>--with-gpm - <dd>The option now accepts a parameter, - i.e., the name of the dynamic GPM library to load via - <code>dlopen()</code> - - <dt>--disable-symlinks - <dd>The option now allows one to - disable <code>symlink()</code> in <code>tic</code> even when - <code>link()</code> does not work. - - </dl> - - </ul> - - <li>other configure/build issues: <ul> <li>remove special case for - Darwin in <code>CF_XOPEN_SOURCE</code> configure macro. - - <li>add configure check to ensure that <code>SIGWINCH</code> is - defined on platforms such as OS X which exclude that when - <code>_XOPEN_SOURCE,</code> etc., are defined - - <li>use ld's <code>-search_paths_first</code> option on Darwin - to work around odd search rules on that platform. - - <li>improve ifdef's for <code>_POSIX_VDISABLE</code> in tset to - work with Mac OS X. - - <li>modify configure script to ensure that if the C compiler is - used rather than the loader in making shared libraries, the - <code>$(CFLAGS)</code> variable is also used. - - <li>use <code>${CC}</code> rather than <code>${LD}</code> in - shared library rules for IRIX64, Solaris to help ensure - that initialization sections are provided for extra linkage - requirements, e.g., of C++ applications. - - <li>improve some shared-library configure scripting for Linux, - FreeBSD and NetBSD to make - <code>--with-shlib-version</code> work. - - <li>split up dependency of <code>names.c</code> and - <code>codes.c</code> in <code>ncurses/Makefile</code> to - work with parallel make. - - <li>modify <code>MKlib_gen.sh</code> to change - preprocessor-expanded <code>_Bool</code> back to <code>bool</code>. - - <li>modify <code>progs/Makefile.in</code> to make - <code>tput init</code> work properly with cygwin, - i.e., do not pass a <code>.exe</code> in the reference - string used in check_aliases. - </ul> - - <li>library: - <ul> - <li>ignore wide-acs line-drawing characters that - <code>wcwidth()</code> claims are not one-column. This is - a workaround for Solaris' broken locale support. - - <li>reduce name-pollution in <code>term.h</code> by removing - <code>#define</code>'s for HAVE_xxx symbols. - - <li>fix <code>#ifdef</code> in <code>c++/internal.h</code> for - QNX 6.1 - </ul> - - <li>test programs: <ul> <li>modify <code>test/configure</code> script - to allow building test programs with PDCurses/X11. - - <li>modified test programs to allow some to work with NetBSD - curses. Several do not because NetBSD curses implements a - subset of X/Open curses, and also lacks much of SVr4 - additions. But it is enough for comparison. - - <li>improved <code>test/configure</code> to build test/ncurses - on HPUX 11 using the vendor curses. - - <li>change configure script to produce - <code>test/Makefile</code> from data file. - </ul> -</ul> - -<H1>Features of Ncurses</H1> - -The ncurses package is fully compatible with SVr4 (System V Release 4) curses: - -<UL> -<LI>All 257 of the SVr4 calls have been implemented (and are documented). -<LI>Full support for SVr4 curses features including keyboard mapping, color, -forms-drawing with ACS characters, and automatic recognition of keypad -and function keys. -<LI>An emulation of the SVr4 panels library, supporting -a stack of windows with backing store, is included. -<LI>An emulation of the SVr4 menus library, supporting -a uniform but flexible interface for menu programming, is included. -<LI>An emulation of the SVr4 form library, supporting -data collection through on-screen forms, is included. -<LI>Binary terminfo entries generated by the ncurses tic(1) implementation -are bit-for-bit-compatible with the entry format SVr4 curses uses. -<LI>The utilities have options to allow you to filter terminfo -entries for use with less capable <STRONG>curses</STRONG>/<STRONG>terminfo</STRONG> -versions such as the HP/UX and AIX ports.</UL> - -The ncurses package also has many useful extensions over SVr4: - -<UL> -<LI>The API is 8-bit clean and base-level conformant with the X/OPEN curses -specification, XSI curses (that is, it implements all BASE level features, -and most EXTENDED features). -It includes many function calls not supported under SVr4 curses -(but portability of all -calls is documented so you can use the SVr4 subset only). -<LI>Unlike SVr3 curses, ncurses can write to the rightmost-bottommost corner -of the screen if your terminal has an insert-character capability. -<LI>Ada95 and C++ bindings. -<LI>Support for mouse event reporting with X Window xterm -and FreeBSD and OS/2 console windows. -<LI>Extended mouse support via Alessandro Rubini's gpm package. -<LI>The function <CODE>wresize()</CODE> allows you to resize windows, preserving -their data. -<LI>The function <CODE>use_default_colors()</CODE> allows you to -use the terminal's default colors for the default color pair, -achieving the effect of transparent colors. -<LI>The functions <CODE>keyok()</CODE> -and <CODE>define_key()</CODE> allow -you to better control the use of function keys, -e.g., disabling the ncurses KEY_MOUSE, -or by defining more than one control sequence to map to a given key code. -<LI>Support for 16-color terminals, such as aixterm and modern xterm. -<LI>Better cursor-movement optimization. The package now features a -cursor-local-movement computation more efficient than either BSD's -or System V's. -<LI>Super hardware scrolling support. The screen-update code incorporates -a novel, simple, and cheap algorithm that enables it to make optimal -use of hardware scrolling, line-insertion, and line-deletion -for screen-line movements. This algorithm is more powerful than -the 4.4BSD curses quickch() routine. -<LI>Real support for terminals with the magic-cookie glitch. The -screen-update code will refrain from drawing a highlight if the magic- -cookie unattributed spaces required just before the beginning and -after the end would step on a non-space character. It will -automatically shift highlight boundaries when doing so would make it -possible to draw the highlight without changing the visual appearance -of the screen. -<LI>It is possible to generate the library with a list of pre-loaded -fallback entries linked to it so that it can serve those terminal types even -when no terminfo tree or termcap file is accessible (this may be useful -for support of screen-oriented programs that must run in single-user mode). -<LI>The tic(1)/captoinfo utility provided with ncurses has the -ability to translate many termcaps from the XENIX, IBM and -AT&T extension sets. -<LI>A BSD-like tset(1) utility is provided. -<LI>The ncurses library and utilities will automatically read terminfo -entries from $HOME/.terminfo if it exists, and compile to that directory -if it exists and the user has no write access to the system directory. -This feature makes it easier for users to have personal terminfo entries -without giving up access to the system terminfo directory. -<LI>You may specify a path of directories to search for compiled -descriptions with the environment variable TERMINFO_DIRS (this -generalizes the feature provided by TERMINFO under stock System V.) -<LI>In terminfo source files, use capabilities may refer not just to -other entries in the same source file (as in System V) but also to -compiled entries in either the system terminfo directory or the user's -$HOME/.terminfo directory. -<LI>A script (<STRONG>capconvert</STRONG>) is provided to help BSD users -transition from termcap to terminfo. It gathers the information in a -TERMCAP environment variable and/or a ~/.termcap local entries file -and converts it to an equivalent local terminfo tree under $HOME/.terminfo. -<LI>Automatic fallback to the /etc/termcap file can be compiled in -when it is not possible to build a terminfo tree. This feature is neither -fast nor cheap, you don't want to use it unless you have to, -but it's there. -<LI>The table-of-entries utility <STRONG>toe</STRONG> makes it easy for users to -see exactly what terminal types are available on the system. -<LI>The library meets the XSI requirement that every macro entry -point have a corresponding function which may be linked (and will be -prototype-checked) if the macro definition is disabled with -<CODE>#undef</CODE>. -<LI>An HTML "Introduction to Programming with NCURSES" document provides -a narrative introduction to the curses programming interface. -</UL> - -<H1>State of the Package</H1> - -Numerous bugs present in earlier versions have been fixed; the -library is far more reliable than it used to be. Bounds checking in many -`dangerous' entry points has been improved. The code is now type-safe -according to gcc -Wall. The library has been checked for malloc leaks and -arena corruption by the Purify memory-allocation tester.<P> - -The ncurses code has been tested with a wide variety of applications -including (versions starting with those noted): -<DL> -<DT> cdk -<DD> Curses Development Kit -<br> -<A HREF="http://invisible-island.net/cdk/">http://invisible-island.net/cdk/</A> -<br> -<A HREF="http://www.vexus.ca/products/CDK/">http://www.vexus.ca/products/CDK/</a> -<DT> ded -<DD> directory-editor -<br> -<A HREF="http://invisible-island.net/ded/">http://invisible-island.net/ded/</A> -<DT> dialog -<DD> the underlying application used in Slackware's setup, and the basis -for similar applications on GNU/Linux. -<br> -<A HREF="http://invisible-island.net/dialog/">http://invisible-island.net/dialog/</A> -<DT> lynx -<DD> the character-screen WWW browser -<br> -<A HREF="http://lynx.isc.org/release/">http://lynx.isc.org/release/</A> -<DT> Midnight Commander -<DD> file manager -<br> -<A HREF="http://www.ibiblio.org/mc/">http://www.ibiblio.org/mc/</A> -<DT> mutt -<DD> mail utility -<br> -<A HREF="http://www.mutt.org/">http://www.mutt.org/</A> -<DT> ncftp -<DD> file-transfer utility -<br> -<A HREF="http://www.ncftp.com/">http://www.ncftp.com/</A> -<DT> nvi -<DD> New vi versions 1.50 are able to use ncurses versions 1.9.7 and later. -<br> -<A HREF="http://www.bostic.com/vi/">http://www.bostic.com/vi/</A> -<br> -<DT> pinfo -<DD> Lynx-like info browser. -<A HREF="http://dione.ids.pl/~pborys/software/pinfo/">http://dione.ids.pl/~pborys/software/pinfo/</A> -<DT> tin -<DD> newsreader, supporting color, MIME -<A HREF="http://www.tin.org/">http://www.tin.org/</A> -<DT> vh-1.6 -<DD> Volks-Hypertext browser for the Jargon File -<br> -<A HREF="http://www.debian.org/Packages/unstable/text/vh.html">http://www.debian.org/Packages/unstable/text/vh.html</A> -</DL> -as well as some that use ncurses for the terminfo support alone: -<DL> -<DT> minicom -<DD> terminal emulator -<br> -<A HREF="http://alioth.debian.org/projects/minicom/"> -http://alioth.debian.org/projects/minicom/</A> -<DT> vile -<DD> vi-like-emacs -<br> -<A HREF="http://invisible-island.net/vile/">http://invisible-island.net/vile/</A> -</DL> -<P> - -The ncurses distribution includes a selection of test programs (including -a few games). - -<H2>Who's Who and What's What</H2> - -Zeyd Ben-Halim -started it from a previous package pcurses, written by Pavel Curtis. -Eric S. Raymond -continued development. -Jürgen Pfeifer wrote most of the form and menu libraries. -Ongoing work is being done by -<A HREF="mailto:dickey@invisible-island.net">Thomas Dickey</A>. -Thomas Dickey -acts as the maintainer for the Free Software Foundation, -which holds the copyright on ncurses. -Contact the current maintainers at -<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>. -<P> - -To join the ncurses mailing list, please write email to -<CODE>bug-ncurses-request@gnu.org</CODE> containing the line: -<PRE> - subscribe <name>@<host.domain> -</PRE> - -This list is open to anyone interested in helping with the development and -testing of this package.<P> - -Beta versions of ncurses and patches to the current release are made available at -<A HREF="ftp://invisible-island.net/ncurses/">ftp://invisible-island.net/ncurses/</A> . - -<H2>Future Plans</H2> -<UL> -<LI>Extended-level XPG4 conformance, with internationalization support. -<LI>Ports to more systems, including DOS and Windows. -</UL> -We need people to help with these projects. If you are interested in working -on them, please join the ncurses list. - -<H2>Other Related Resources</H2> - -The distribution provides a newer version of the terminfo-format -terminal description file once maintained by -<A HREF="http://www.catb.org/~esr/terminfo/">Eric Raymond</A> . -Unlike the older version, the termcap and terminfo data are provided -in the same file, and provides several user-definable extensions -beyond the X/Open specification.<P> - -You can find lots of information on terminal-related topics -not covered in the terminfo file at -<A HREF="http://www.cs.utk.edu/~shuford/terminal_index.html">Richard Shuford's -archive</A> . -</BODY> -</HTML> -<!-- -# The following sets edit modes for GNU EMACS -# Local Variables: -# mode:html -# case-fold-search:nil -# fill-column:70 -# End: ---> diff --git a/contrib/ncurses/doc/html/hackguide.html b/contrib/ncurses/doc/html/hackguide.html deleted file mode 100644 index 97d1369..0000000 --- a/contrib/ncurses/doc/html/hackguide.html +++ /dev/null @@ -1,914 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN"> -<!-- - $Id: hackguide.html,v 1.27 2005/12/24 15:37:13 tom Exp $ - **************************************************************************** - * Copyright (c) 1998-2003,2005 Free Software Foundation, Inc. * - * * - * Permission is hereby granted, free of charge, to any person obtaining a * - * copy of this software and associated documentation files (the * - * "Software"), to deal in the Software without restriction, including * - * without limitation the rights to use, copy, modify, merge, publish, * - * distribute, distribute with modifications, sublicense, and/or sell * - * copies of the Software, and to permit persons to whom the Software is * - * furnished to do so, subject to the following conditions: * - * * - * The above copyright notice and this permission notice shall be included * - * in all copies or substantial portions of the Software. * - * * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * - * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * - * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * - * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * - * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * - * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * - * * - * Except as contained in this notice, the name(s) of the above copyright * - * holders shall not be used in advertising or otherwise to promote the * - * sale, use or other dealings in this Software without prior written * - * authorization. * - **************************************************************************** ---> -<HTML> -<HEAD> -<TITLE>A Hacker's Guide to Ncurses Internals</TITLE> -<link rev="made" href="mailto:bugs-ncurses@gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<!-- -This document is self-contained, *except* that there is one relative link to -the ncurses-intro.html document, expected to be in the same directory with -this one. ---> -</HEAD> -<BODY> - -<H1>A Hacker's Guide to NCURSES</H1> - -<H1>Contents</H1> -<UL> -<LI><A HREF="#abstract">Abstract</A> -<LI><A HREF="#objective">Objective of the Package</A> -<UL> -<LI><A HREF="#whysvr4">Why System V Curses?</A> -<LI><A HREF="#extensions">How to Design Extensions</A> -</UL> -<LI><A HREF="#portability">Portability and Configuration</A> -<LI><A HREF="#documentation">Documentation Conventions</A> -<LI><A HREF="#bugtrack">How to Report Bugs</A> -<LI><A HREF="#ncurslib">A Tour of the Ncurses Library</A> -<UL> -<LI><A HREF="#loverview">Library Overview</A> -<LI><A HREF="#engine">The Engine Room</A> -<LI><A HREF="#input">Keyboard Input</A> -<LI><A HREF="#mouse">Mouse Events</A> -<LI><A HREF="#output">Output and Screen Updating</A> -</UL> -<LI><A HREF="#fmnote">The Forms and Menu Libraries</A> -<LI><A HREF="#tic">A Tour of the Terminfo Compiler</A> -<UL> -<LI><A HREF="#nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A> -<LI><A HREF="#uses">Use Capability Resolution</A> -<LI><A HREF="#translation">Source-Form Translation</A> -</UL> -<LI><A HREF="#utils">Other Utilities</A> -<LI><A HREF="#style">Style Tips for Developers</A> -<LI><A HREF="#port">Porting Hints</A> -</UL> - -<H1><A NAME="abstract">Abstract</A></H1> - -This document is a hacker's tour of the <STRONG>ncurses</STRONG> library and utilities. -It discusses design philosophy, implementation methods, and the -conventions used for coding and documentation. It is recommended -reading for anyone who is interested in porting, extending or improving the -package. - -<H1><A NAME="objective">Objective of the Package</A></H1> - -The objective of the <STRONG>ncurses</STRONG> package is to provide a free software API for -character-cell terminals and terminal emulators with the following -characteristics: - -<UL> -<LI>Source-compatible with historical curses implementations (including - the original BSD curses and System V curses. -<LI>Conformant with the XSI Curses standard issued as part of XPG4 by - X/Open. -<LI>High-quality -- stable and reliable code, wide portability, good - packaging, superior documentation. -<LI>Featureful -- should eliminate as much of the drudgery of C interface - programming as possible, freeing programmers to think at a higher - level of design. -</UL> - -These objectives are in priority order. So, for example, source -compatibility with older version must trump featurefulness -- we cannot -add features if it means breaking the portion of the API corresponding -to historical curses versions. - -<H2><A NAME="whysvr4">Why System V Curses?</A></H2> - -We used System V curses as a model, reverse-engineering their API, in -order to fulfill the first two objectives. <P> - -System V curses implementations can support BSD curses programs with -just a recompilation, so by capturing the System V API we also -capture BSD's. <P> - -More importantly for the future, the XSI Curses standard issued by X/Open -is explicitly and closely modeled on System V. So conformance with -System V took us most of the way to base-level XSI conformance. - -<H2><A NAME="extensions">How to Design Extensions</A></H2> - -The third objective (standards conformance) requires that it be easy to -condition source code using <STRONG>ncurses</STRONG> so that the absence of nonstandard -extensions does not break the code. <P> - -Accordingly, we have a policy of associating with each nonstandard extension -a feature macro, so that ncurses client code can use this macro to condition -in or out the code that requires the <STRONG>ncurses</STRONG> extension. <P> - -For example, there is a macro <CODE>NCURSES_MOUSE_VERSION</CODE> which XSI Curses -does not define, but which is defined in the <STRONG>ncurses</STRONG> library header. -You can use this to condition the calls to the mouse API calls. - -<H1><A NAME="portability">Portability and Configuration</A></H1> - -Code written for <STRONG>ncurses</STRONG> may assume an ANSI-standard C compiler and -POSIX-compatible OS interface. It may also assume the presence of a -System-V-compatible <EM>select(2)</EM> call. <P> - -We encourage (but do not require) developers to make the code friendly -to less-capable UNIX environments wherever possible. <P> - -We encourage developers to support OS-specific optimizations and methods -not available under POSIX/ANSI, provided only that: - -<UL> -<LI>All such code is properly conditioned so the build process does not - attempt to compile it under a plain ANSI/POSIX environment. -<LI>Adding such implementation methods does not introduce incompatibilities - in the <STRONG>ncurses</STRONG> API between platforms. -</UL> - -We use GNU <CODE>autoconf(1)</CODE> as a tool to deal with portability issues. -The right way to leverage an OS-specific feature is to modify the autoconf -specification files (configure.in and aclocal.m4) to set up a new feature -macro, which you then use to condition your code. - -<H1><A NAME="documentation">Documentation Conventions</A></H1> - -There are three kinds of documentation associated with this package. Each -has a different preferred format: - -<UL> -<LI>Package-internal files (README, INSTALL, TO-DO etc.) -<LI>Manual pages. -<LI>Everything else (i.e., narrative documentation). -</UL> - -Our conventions are simple: -<OL> -<LI><STRONG>Maintain package-internal files in plain text.</STRONG> - The expected viewer for them <EM>more(1)</EM> or an editor window; there's - no point in elaborate mark-up. - -<LI><STRONG>Mark up manual pages in the man macros.</STRONG> These have to be viewable - through traditional <EM>man(1)</EM> programs. - -<LI><STRONG>Write everything else in HTML.</STRONG> -</OL> - -When in doubt, HTMLize a master and use <EM>lynx(1)</EM> to generate -plain ASCII (as we do for the announcement document). <P> - -The reason for choosing HTML is that it's (a) well-adapted for on-line -browsing through viewers that are everywhere; (b) more easily readable -as plain text than most other mark-ups, if you don't have a viewer; and (c) -carries enough information that you can generate a nice-looking printed -version from it. Also, of course, it make exporting things like the -announcement document to WWW pretty trivial. - -<H1><A NAME="bugtrack">How to Report Bugs</A></H1> - -The <A NAME="bugreport">reporting address for bugs</A> is -<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>. -This is a majordomo list; to join, write -to <CODE>bug-ncurses-request@gnu.org</CODE> with a message containing the line: -<PRE> - subscribe <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. - -<OL> -<LI>Develop a recipe to reproduce the bug. -<p> -Bugs we can reproduce are likely to be fixed very quickly, often -within days. The most effective single thing you can do to get a -quick fix is develop a way we can duplicate the bad behavior -- -ideally, by giving us source for a small, portable test program that -breaks the library. (Even better is a keystroke recipe using one of -the test programs provided with the distribution.) - -<LI>Try to reproduce the bug on a different terminal type. <P> - -In our experience, most of the behaviors people report as library bugs -are actually due to subtle problems in terminal descriptions. This is -especially likely to be true if you're using a traditional -asynchronous terminal or PC-based terminal emulator, rather than xterm -or a UNIX console entry. <P> - -It's therefore extremely helpful if you can tell us whether or not your -problem reproduces on other terminal types. Usually you'll have both -a console type and xterm available; please tell us whether or not your -bug reproduces on both. <P> - -If you have xterm available, it is also good to collect xterm reports for -different window sizes. This is especially true if you normally use an -unusual xterm window size -- a surprising number of the bugs we've seen -are either triggered or masked by these. - -<LI>Generate and examine a trace file for the broken behavior. <P> - -Recompile your program with the debugging versions of the libraries. -Insert a <CODE>trace()</CODE> call with the argument set to <CODE>TRACE_UPDATE</CODE>. -(See <A HREF="ncurses-intro.html#debugging">"Writing Programs with -NCURSES"</A> for details on trace levels.) -Reproduce your bug, then look at the trace file to see what the library -was actually doing. <P> - -Another frequent cause of apparent bugs is application coding errors -that cause the wrong things to be put on the virtual screen. Looking -at the virtual-screen dumps in the trace file will tell you immediately if -this is happening, and save you from the possible embarrassment of being -told that the bug is in your code and is your problem rather than ours. <P> - -If the virtual-screen dumps look correct but the bug persists, it's -possible to crank up the trace level to give more and more information -about the library's update actions and the control sequences it issues -to perform them. The test directory of the distribution contains a -tool for digesting these logs to make them less tedious to wade -through. <P> - -Often you'll find terminfo problems at this stage by noticing that the -escape sequences put out for various capabilities are wrong. If not, -you're likely to learn enough to be able to characterize any bug in -the screen-update logic quite exactly. - -<LI>Report details and symptoms, not just interpretations. <P> - -If you do the preceding two steps, it is very likely that you'll discover -the nature of the problem yourself and be able to send us a fix. This -will create happy feelings all around and earn you good karma for the first -time you run into a bug you really can't characterize and fix yourself. <P> - -If you're still stuck, at least you'll know what to tell us. Remember, we -need details. If you guess about what is safe to leave out, you are too -likely to be wrong. <P> - -If your bug produces a bad update, include a trace file. Try to make -the trace at the <EM>least</EM> voluminous level that pins down the -bug. Logs that have been through tracemunch are OK, it doesn't throw -away any information (actually they're better than un-munched ones because -they're easier to read). <P> - -If your bug produces a core-dump, please include a symbolic stack trace -generated by gdb(1) or your local equivalent. <P> - -Tell us about every terminal on which you've reproduced the bug -- and -every terminal on which you can't. Ideally, sent us terminfo sources -for all of these (yours might differ from ours). <P> - -Include your ncurses version and your OS/machine type, of course! You can -find your ncurses version in the <CODE>curses.h</CODE> file. -</OL> - -If your problem smells like a logic error or in cursor movement or -scrolling or a bad capability, there are a couple of tiny test frames -for the library algorithms in the progs directory that may help you -isolate it. These are not part of the normal build, but do have their -own make productions. <P> - -The most important of these is <CODE>mvcur</CODE>, a test frame for the -cursor-movement optimization code. With this program, you can see -directly what control sequences will be emitted for any given cursor -movement or scroll/insert/delete operations. If you think you've got -a bad capability identified, you can disable it and test again. The -program is command-driven and has on-line help. <P> - -If you think the vertical-scroll optimization is broken, or just want to -understand how it works better, build <CODE>hashmap</CODE> and read the -header comments of <CODE>hardscroll.c</CODE> and <CODE>hashmap.c</CODE>; then try -it out. You can also test the hardware-scrolling optimization separately -with <CODE>hardscroll</CODE>. <P> - -<H1><A NAME="ncurslib">A Tour of the Ncurses Library</A></H1> - -<H2><A NAME="loverview">Library Overview</A></H2> - -Most of the library is superstructure -- fairly trivial convenience -interfaces to a small set of basic functions and data structures used -to manipulate the virtual screen (in particular, none of this code -does any I/O except through calls to more fundamental modules -described below). The files -<blockquote> -<CODE> -lib_addch.c -lib_bkgd.c -lib_box.c -lib_chgat.c -lib_clear.c -lib_clearok.c -lib_clrbot.c -lib_clreol.c -lib_colorset.c -lib_data.c -lib_delch.c -lib_delwin.c -lib_echo.c -lib_erase.c -lib_gen.c -lib_getstr.c -lib_hline.c -lib_immedok.c -lib_inchstr.c -lib_insch.c -lib_insdel.c -lib_insstr.c -lib_instr.c -lib_isendwin.c -lib_keyname.c -lib_leaveok.c -lib_move.c -lib_mvwin.c -lib_overlay.c -lib_pad.c -lib_printw.c -lib_redrawln.c -lib_scanw.c -lib_screen.c -lib_scroll.c -lib_scrollok.c -lib_scrreg.c -lib_set_term.c -lib_slk.c -lib_slkatr_set.c -lib_slkatrof.c -lib_slkatron.c -lib_slkatrset.c -lib_slkattr.c -lib_slkclear.c -lib_slkcolor.c -lib_slkinit.c -lib_slklab.c -lib_slkrefr.c -lib_slkset.c -lib_slktouch.c -lib_touch.c -lib_unctrl.c -lib_vline.c -lib_wattroff.c -lib_wattron.c -lib_window.c -</CODE> -</blockquote> -are all in this category. They are very -unlikely to need change, barring bugs or some fundamental -reorganization in the underlying data structures. <P> - -These files are used only for debugging support: -<blockquote> -<code> -lib_trace.c -lib_traceatr.c -lib_tracebits.c -lib_tracechr.c -lib_tracedmp.c -lib_tracemse.c -trace_buf.c -</code> -</blockquote> -It is rather unlikely you will ever need to change these, unless -you want to introduce a new debug trace level for some reason.<P> - -There is another group of files that do direct I/O via <EM>tputs()</EM>, -computations on the terminal capabilities, or queries to the OS -environment, but nevertheless have only fairly low complexity. These -include: -<blockquote> -<code> -lib_acs.c -lib_beep.c -lib_color.c -lib_endwin.c -lib_initscr.c -lib_longname.c -lib_newterm.c -lib_options.c -lib_termcap.c -lib_ti.c -lib_tparm.c -lib_tputs.c -lib_vidattr.c -read_entry.c. -</code> -</blockquote> -They are likely to need revision only if -ncurses is being ported to an environment without an underlying -terminfo capability representation. <P> - -These files -have serious hooks into -the tty driver and signal facilities: -<blockquote> -<code> -lib_kernel.c -lib_baudrate.c -lib_raw.c -lib_tstp.c -lib_twait.c -</code> -</blockquote> -If you run into porting snafus -moving the package to another UNIX, the problem is likely to be in one -of these files. -The file <CODE>lib_print.c</CODE> uses sleep(2) and also -falls in this category.<P> - -Almost all of the real work is done in the files -<blockquote> -<code> -hardscroll.c -hashmap.c -lib_addch.c -lib_doupdate.c -lib_getch.c -lib_mouse.c -lib_mvcur.c -lib_refresh.c -lib_setup.c -lib_vidattr.c -</code> -</blockquote> -Most of the algorithmic complexity in the -library lives in these files. -If there is a real bug in <STRONG>ncurses</STRONG> itself, it's probably here. -We'll tour some of these files in detail -below (see <A HREF="#engine">The Engine Room</A>). <P> - -Finally, there is a group of files that is actually most of the -terminfo compiler. The reason this code lives in the <STRONG>ncurses</STRONG> -library is to support fallback to /etc/termcap. These files include -<blockquote> -<code> -alloc_entry.c -captoinfo.c -comp_captab.c -comp_error.c -comp_hash.c -comp_parse.c -comp_scan.c -parse_entry.c -read_termcap.c -write_entry.c -</code> -</blockquote> -We'll discuss these in the compiler tour. - -<H2><A NAME="engine">The Engine Room</A></H2> - -<H3><A NAME="input">Keyboard Input</A></H3> - -All <CODE>ncurses</CODE> input funnels through the function -<CODE>wgetch()</CODE>, defined in <CODE>lib_getch.c</CODE>. This function is -tricky; it has to poll for keyboard and mouse events and do a running -match of incoming input against the set of defined special keys. <P> - -The central data structure in this module is a FIFO queue, used to -match multiple-character input sequences against special-key -capabilities; also to implement pushback via <CODE>ungetch()</CODE>. <P> - -The <CODE>wgetch()</CODE> code distinguishes between function key -sequences and the same sequences typed manually by doing a timed wait -after each input character that could lead a function key sequence. -If the entire sequence takes less than 1 second, it is assumed to have -been generated by a function key press. <P> - -Hackers bruised by previous encounters with variant <CODE>select(2)</CODE> -calls may find the code in <CODE>lib_twait.c</CODE> interesting. It deals -with the problem that some BSD selects don't return a reliable -time-left value. The function <CODE>timed_wait()</CODE> effectively -simulates a System V select. - -<H3><A NAME="mouse">Mouse Events</A></H3> - -If the mouse interface is active, <CODE>wgetch()</CODE> polls for mouse -events each call, before it goes to the keyboard for input. It is -up to <CODE>lib_mouse.c</CODE> how the polling is accomplished; it may vary -for different devices. <P> - -Under xterm, however, mouse event notifications come in via the keyboard -input stream. They are recognized by having the <STRONG>kmous</STRONG> capability -as a prefix. This is kind of klugey, but trying to wire in recognition of -a mouse key prefix without going through the function-key machinery would -be just too painful, and this turns out to imply having the prefix somewhere -in the function-key capabilities at terminal-type initialization. <P> - -This kluge only works because <STRONG>kmous</STRONG> isn't actually used by any -historic terminal type or curses implementation we know of. Best -guess is it's a relic of some forgotten experiment in-house at Bell -Labs that didn't leave any traces in the publicly-distributed System V -terminfo files. If System V or XPG4 ever gets serious about using it -again, this kluge may have to change. <P> - -Here are some more details about mouse event handling: <P> - -The <CODE>lib_mouse()</CODE>code is logically split into a lower level that -accepts event reports in a device-dependent format and an upper level that -parses mouse gestures and filters events. The mediating data structure is a -circular queue of event structures. <P> - -Functionally, the lower level's job is to pick up primitive events and -put them on the circular queue. This can happen in one of two ways: -either (a) <CODE>_nc_mouse_event()</CODE> detects a series of incoming -mouse reports and queues them, or (b) code in <CODE>lib_getch.c</CODE> detects the -<STRONG>kmous</STRONG> prefix in the keyboard input stream and calls _nc_mouse_inline -to queue up a series of adjacent mouse reports. <P> - -In either case, <CODE>_nc_mouse_parse()</CODE> should be called after the -series is accepted to parse the digested mouse reports (low-level -events) into a gesture (a high-level or composite event). - -<H3><A NAME="output">Output and Screen Updating</A></H3> - -With the single exception of character echoes during a <CODE>wgetnstr()</CODE> -call (which simulates cooked-mode line editing in an ncurses window), -the library normally does all its output at refresh time. <P> - -The main job is to go from the current state of the screen (as represented -in the <CODE>curscr</CODE> window structure) to the desired new state (as -represented in the <CODE>newscr</CODE> window structure), while doing as -little I/O as possible. <P> - -The brains of this operation are the modules <CODE>hashmap.c</CODE>, -<CODE>hardscroll.c</CODE> and <CODE>lib_doupdate.c</CODE>; the latter two use -<CODE>lib_mvcur.c</CODE>. Essentially, what happens looks like this: <P> - -The <CODE>hashmap.c</CODE> module tries to detect vertical motion -changes between the real and virtual screens. This information -is represented by the oldindex members in the newscr structure. -These are modified by vertical-motion and clear operations, and both are -re-initialized after each update. To this change-journalling -information, the hashmap code adds deductions made using a modified Heckel -algorithm on hash values generated from the line contents. <P> - -The <CODE>hardscroll.c</CODE> module computes an optimum set of scroll, -insertion, and deletion operations to make the indices match. It calls -<CODE>_nc_mvcur_scrolln()</CODE> in <CODE>lib_mvcur.c</CODE> to do those motions. <P> - -Then <CODE>lib_doupdate.c</CODE> goes to work. Its job is to do line-by-line -transformations of <CODE>curscr</CODE> lines to <CODE>newscr</CODE> lines. Its main -tool is the routine <CODE>mvcur()</CODE> in <CODE>lib_mvcur.c</CODE>. This routine -does cursor-movement optimization, attempting to get from given screen -location A to given location B in the fewest output characters possible. <P> - -If you want to work on screen optimizations, you should use the fact -that (in the trace-enabled version of the library) enabling the -<CODE>TRACE_TIMES</CODE> trace level causes a report to be emitted after -each screen update giving the elapsed time and a count of characters -emitted during the update. You can use this to tell when an update -optimization improves efficiency. <P> - -In the trace-enabled version of the library, it is also possible to disable -and re-enable various optimizations at runtime by tweaking the variable -<CODE>_nc_optimize_enable</CODE>. See the file <CODE>include/curses.h.in</CODE> -for mask values, near the end. - -<H1><A NAME="fmnote">The Forms and Menu Libraries</A></H1> - -The forms and menu libraries should work reliably in any environment you -can port ncurses to. The only portability issue anywhere in them is what -flavor of regular expressions the built-in form field type TYPE_REGEXP -will recognize. <P> - -The configuration code prefers the POSIX regex facility, modeled on -System V's, but will settle for BSD regexps if the former isn't available. <P> - -Historical note: the panels code was written primarily to assist in -porting u386mon 2.0 (comp.sources.misc v14i001-4) to systems lacking -panels support; u386mon 2.10 and beyond use it. This version has been -slightly cleaned up for <CODE>ncurses</CODE>. - -<H1><A NAME="tic">A Tour of the Terminfo Compiler</A></H1> - -The <STRONG>ncurses</STRONG> implementation of <STRONG>tic</STRONG> is rather complex -internally; it has to do a trying combination of missions. This starts -with the fact that, in addition to its normal duty of compiling -terminfo sources into loadable terminfo binaries, it has to be able to -handle termcap syntax and compile that too into terminfo entries. <P> - -The implementation therefore starts with a table-driven, dual-mode -lexical analyzer (in <CODE>comp_scan.c</CODE>). The lexer chooses its -mode (termcap or terminfo) based on the first `,' or `:' it finds in -each entry. The lexer does all the work of recognizing capability -names and values; the grammar above it is trivial, just "parse entries -till you run out of file". - -<H2><A NAME="nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A></H2> - -Translation of most things besides <STRONG>use</STRONG> capabilities is pretty -straightforward. The lexical analyzer's tokenizer hands each capability -name to a hash function, which drives a table lookup. The table entry -yields an index which is used to look up the token type in another table, -and controls interpretation of the value. <P> - -One possibly interesting aspect of the implementation is the way the -compiler tables are initialized. All the tables are generated by various -awk/sed/sh scripts from a master table <CODE>include/Caps</CODE>; these -scripts actually write C initializers which are linked to the compiler. -Furthermore, the hash table is generated in the same way, so it doesn't -have to be generated at compiler startup time (another benefit of this -organization is that the hash table can be in shareable text space). <P> - -Thus, adding a new capability is usually pretty trivial, just a matter -of adding one line to the <CODE>include/Caps</CODE> file. We'll have more -to say about this in the section on <A HREF="#translation">Source-Form -Translation</A>. - -<H2><A NAME="uses">Use Capability Resolution</A></H2> - -The background problem that makes <STRONG>tic</STRONG> tricky isn't the capability -translation itself, it's the resolution of <STRONG>use</STRONG> capabilities. Older -versions would not handle forward <STRONG>use</STRONG> references for this reason -(that is, a using terminal always had to follow its use target in the -source file). By doing this, they got away with a simple implementation -tactic; compile everything as it blows by, then resolve uses from compiled -entries. <P> - -This won't do for <STRONG>ncurses</STRONG>. The problem is that that the whole -compilation process has to be embeddable in the <STRONG>ncurses</STRONG> library -so that it can be called by the startup code to translate termcap -entries on the fly. The embedded version can't go promiscuously writing -everything it translates out to disk -- for one thing, it will typically -be running with non-root permissions. <P> - -So our <STRONG>tic</STRONG> is designed to parse an entire terminfo file into a -doubly-linked circular list of entry structures in-core, and then do -<STRONG>use</STRONG> resolution in-memory before writing everything out. This -design has other advantages: it makes forward and back use-references -equally easy (so we get the latter for free), and it makes checking for -name collisions before they're written out easy to do. <P> - -And this is exactly how the embedded version works. But the stand-alone -user-accessible version of <STRONG>tic</STRONG> partly reverts to the historical -strategy; it writes to disk (not keeping in core) any entry with no -<STRONG>use</STRONG> references. <P> - -This is strictly a core-economy kluge, implemented because the -terminfo master file is large enough that some core-poor systems swap -like crazy when you compile it all in memory...there have been reports of -this process taking <STRONG>three hours</STRONG>, rather than the twenty seconds -or less typical on the author's development box. <P> - -So. The executable <STRONG>tic</STRONG> passes the entry-parser a hook that -<EM>immediately</EM> writes out the referenced entry if it has no use -capabilities. The compiler main loop refrains from adding the entry -to the in-core list when this hook fires. If some other entry later -needs to reference an entry that got written immediately, that's OK; -the resolution code will fetch it off disk when it can't find it in -core. <P> - -Name collisions will still be detected, just not as cleanly. The -<CODE>write_entry()</CODE> code complains before overwriting an entry that -postdates the time of <STRONG>tic</STRONG>'s first call to -<CODE>write_entry()</CODE>, Thus it will complain about overwriting -entries newly made during the <STRONG>tic</STRONG> run, but not about -overwriting ones that predate it. - -<H2><A NAME="translation">Source-Form Translation</A></H2> - -Another use of <STRONG>tic</STRONG> is to do source translation between various termcap -and terminfo formats. There are more variants out there than you might -think; the ones we know about are described in the <STRONG>captoinfo(1)</STRONG> -manual page. <P> - -The translation output code (<CODE>dump_entry()</CODE> in -<CODE>ncurses/dump_entry.c</CODE>) is shared with the <STRONG>infocmp(1)</STRONG> -utility. It takes the same internal representation used to generate -the binary form and dumps it to standard output in a specified -format. <P> - -The <CODE>include/Caps</CODE> file has a header comment describing ways you -can specify source translations for nonstandard capabilities just by -altering the master table. It's possible to set up capability aliasing -or tell the compiler to plain ignore a given capability without writing -any C code at all. <P> - -For circumstances where you need to do algorithmic translation, there -are functions in <CODE>parse_entry.c</CODE> called after the parse of each -entry that are specifically intended to encapsulate such -translations. This, for example, is where the AIX <STRONG>box1</STRONG> capability -get translated to an <STRONG>acsc</STRONG> string. - -<H1><A NAME="utils">Other Utilities</A></H1> - -The <STRONG>infocmp</STRONG> utility is just a wrapper around the same -entry-dumping code used by <STRONG>tic</STRONG> for source translation. Perhaps -the one interesting aspect of the code is the use of a predicate -function passed in to <CODE>dump_entry()</CODE> to control which -capabilities are dumped. This is necessary in order to handle both -the ordinary De-compilation case and entry difference reporting. <P> - -The <STRONG>tput</STRONG> and <STRONG>clear</STRONG> utilities just do an entry load -followed by a <CODE>tputs()</CODE> of a selected capability. - -<H1><A NAME="style">Style Tips for Developers</A></H1> - -See the TO-DO file in the top-level directory of the source distribution -for additions that would be particularly useful. <P> - -The prefix <CODE>_nc_</CODE> should be used on library public functions that are -not part of the curses API in order to prevent pollution of the -application namespace. - -If you have to add to or modify the function prototypes in curses.h.in, -read ncurses/MKlib_gen.sh first so you can avoid breaking XSI conformance. - -Please join the ncurses mailing list. See the INSTALL file in the -top level of the distribution for details on the list. <P> - -Look for the string <CODE>FIXME</CODE> in source files to tag minor bugs -and potential problems that could use fixing. <P> - -Don't try to auto-detect OS features in the main body of the C code. -That's the job of the configuration system. <P> - -To hold down complexity, do make your code data-driven. Especially, -if you can drive logic from a table filtered out of -<CODE>include/Caps</CODE>, do it. If you find you need to augment the -data in that file in order to generate the proper table, that's still -preferable to ad-hoc code -- that's why the fifth field (flags) is -there. <P> - -Have fun! - -<H1><A NAME="port">Porting Hints</A></H1> - -The following notes are intended to be a first step towards DOS and Macintosh -ports of the ncurses libraries. <P> - -The following library modules are `pure curses'; they operate only on -the curses internal structures, do all output through other curses -calls (not including <CODE>tputs()</CODE> and <CODE>putp()</CODE>) and do not -call any other UNIX routines such as signal(2) or the stdio library. -Thus, they should not need to be modified for single-terminal -ports. - -<blockquote> -<code> -lib_addch.c -lib_addstr.c -lib_bkgd.c -lib_box.c -lib_clear.c -lib_clrbot.c -lib_clreol.c -lib_delch.c -lib_delwin.c -lib_erase.c -lib_inchstr.c -lib_insch.c -lib_insdel.c -lib_insstr.c -lib_keyname.c -lib_move.c -lib_mvwin.c -lib_newwin.c -lib_overlay.c -lib_pad.c -lib_printw.c -lib_refresh.c -lib_scanw.c -lib_scroll.c -lib_scrreg.c -lib_set_term.c -lib_touch.c -lib_tparm.c -lib_tputs.c -lib_unctrl.c -lib_window.c -panel.c -</code> -</blockquote> -<P> - -This module is pure curses, but calls outstr(): - -<blockquote> -<code> -lib_getstr.c -</code> -</blockquote> -<P> - -These modules are pure curses, except that they use <CODE>tputs()</CODE> -and <CODE>putp()</CODE>: - -<blockquote> -<code> -lib_beep.c -lib_color.c -lib_endwin.c -lib_options.c -lib_slk.c -lib_vidattr.c -</code> -</blockquote> -<P> - -This modules assist in POSIX emulation on non-POSIX systems: -<DL> -<DT> sigaction.c -<DD> signal calls -</DL> - -The following source files will not be needed for a -single-terminal-type port. - -<blockquote> -<code> -alloc_entry.c -captoinfo.c -clear.c -comp_captab.c -comp_error.c -comp_hash.c -comp_main.c -comp_parse.c -comp_scan.c -dump_entry.c -infocmp.c -parse_entry.c -read_entry.c -tput.c -write_entry.c -</code> -</blockquote> -<P> - -The following modules will use open()/read()/write()/close()/lseek() on files, -but no other OS calls. - -<DL> -<DT>lib_screen.c -<DD>used to read/write screen dumps -<DT>lib_trace.c -<DD>used to write trace data to the logfile -</DL> - -Modules that would have to be modified for a port start here: <P> - -The following modules are `pure curses' but contain assumptions inappropriate -for a memory-mapped port. - -<dl> -<dt>lib_longname.c<dd>assumes there may be multiple terminals -<dt>lib_acs.c<dd>assumes acs_map as a double indirection -<dt>lib_mvcur.c<dd>assumes cursor moves have variable cost -<dt>lib_termcap.c<dd>assumes there may be multiple terminals -<dt>lib_ti.c<dd>assumes there may be multiple terminals -</dl> - -The following modules use UNIX-specific calls: - -<dl> -<dt>lib_doupdate.c<dd>input checking -<dt>lib_getch.c<dd>read() -<dt>lib_initscr.c<dd>getenv() -<dt>lib_newterm.c -<dt>lib_baudrate.c -<dt>lib_kernel.c<dd>various tty-manipulation and system calls -<dt>lib_raw.c<dd>various tty-manipulation calls -<dt>lib_setup.c<dd>various tty-manipulation calls -<dt>lib_restart.c<dd>various tty-manipulation calls -<dt>lib_tstp.c<dd>signal-manipulation calls -<dt>lib_twait.c<dd>gettimeofday(), select(). -</dl> - -<HR> -<ADDRESS>Eric S. Raymond <esr@snark.thyrsus.com></ADDRESS> -(Note: This is <EM>not</EM> the <A HREF="#bugtrack">bug address</A>!) -</BODY> -</HTML> diff --git a/contrib/ncurses/doc/html/ncurses-intro.html b/contrib/ncurses/doc/html/ncurses-intro.html deleted file mode 100644 index 451e7ab..0000000 --- a/contrib/ncurses/doc/html/ncurses-intro.html +++ /dev/null @@ -1,2722 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN"> -<!-- - $Id: ncurses-intro.html,v 1.43 2007/03/03 19:31:50 tom Exp $ - **************************************************************************** - * Copyright (c) 1998-2006,2007 Free Software Foundation, Inc. * - * * - * Permission is hereby granted, free of charge, to any person obtaining a * - * copy of this software and associated documentation files (the * - * "Software"), to deal in the Software without restriction, including * - * without limitation the rights to use, copy, modify, merge, publish, * - * distribute, distribute with modifications, sublicense, and/or sell * - * copies of the Software, and to permit persons to whom the Software is * - * furnished to do so, subject to the following conditions: * - * * - * The above copyright notice and this permission notice shall be included * - * in all copies or substantial portions of the Software. * - * * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * - * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * - * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * - * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * - * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * - * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * - * * - * Except as contained in this notice, the name(s) of the above copyright * - * holders shall not be used in advertising or otherwise to promote the * - * sale, use or other dealings in this Software without prior written * - * authorization. * - **************************************************************************** ---> -<HTML> -<HEAD> -<TITLE>Writing Programs with NCURSES</TITLE> -<link rev="made" href="mailto:bugs-ncurses@gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -</HEAD> -<BODY> - -<H1>Writing Programs with NCURSES</H1> - -<BLOCKQUOTE> -by Eric S. Raymond and Zeyd M. Ben-Halim<BR> -updates since release 1.9.9e by Thomas Dickey -</BLOCKQUOTE> - -<H1>Contents</H1> -<UL> -<LI><A HREF="#introduction">Introduction</A> -<UL> -<LI><A HREF="#history">A Brief History of Curses</A> -<LI><A HREF="#scope">Scope of This Document</A> -<LI><A HREF="#terminology">Terminology</A> -</UL> -<LI><A HREF="#curses">The Curses Library</A> -<UL> -<LI><A HREF="#overview">An Overview of Curses</A> -<UL> -<LI><A HREF="#compiling">Compiling Programs using Curses</A> -<LI><A HREF="#updating">Updating the Screen</A> -<LI><A HREF="#stdscr">Standard Windows and Function Naming Conventions</A> -<LI><A HREF="#variables">Variables</A> -</UL> -<LI><A HREF="#using">Using the Library</A> -<UL> -<LI><A HREF="#starting">Starting up</A> -<LI><A HREF="#output">Output</A> -<LI><A HREF="#input">Input</A> -<LI><A HREF="#formschars">Using Forms Characters</A> -<LI><A HREF="#attributes">Character Attributes and Color</A> -<LI><A HREF="#mouse">Mouse Interfacing</A> -<LI><A HREF="#finishing">Finishing Up</A> -</UL> -<LI><A HREF="#functions">Function Descriptions</A> -<UL> -<LI><A HREF="#init">Initialization and Wrapup</A> -<LI><A HREF="#flush">Causing Output to the Terminal</A> -<LI><A HREF="#lowlevel">Low-Level Capability Access</A> -<LI><A HREF="#debugging">Debugging</A> -</UL> -<LI><A HREF="#hints">Hints, Tips, and Tricks</A> -<UL> -<LI><A HREF="#caution">Some Notes of Caution</A> -<LI><A HREF="#leaving">Temporarily Leaving ncurses Mode</A> -<LI><A HREF="#xterm">Using <CODE>ncurses</CODE> under <CODE>xterm</CODE></A> -<LI><A HREF="#screens">Handling Multiple Terminal Screens</A> -<LI><A HREF="#testing">Testing for Terminal Capabilities</A> -<LI><A HREF="#tuning">Tuning for Speed</A> -<LI><A HREF="#special">Special Features of <CODE>ncurses</CODE></A> -</UL> -<LI><A HREF="#compat">Compatibility with Older Versions</A> -<UL> -<LI><A HREF="#refbug">Refresh of Overlapping Windows</A> -<LI><A HREF="#backbug">Background Erase</A> -</UL> -<LI><A HREF="#xsifuncs">XSI Curses Conformance</A> -</UL> -<LI><A HREF="#panels">The Panels Library</A> -<UL> -<LI><A HREF="#pcompile">Compiling With the Panels Library</A> -<LI><A HREF="#poverview">Overview of Panels</A> -<LI><A HREF="#pstdscr">Panels, Input, and the Standard Screen</A> -<LI><A HREF="#hiding">Hiding Panels</A> -<LI><A HREF="#pmisc">Miscellaneous Other Facilities</A> -</UL> -<LI><A HREF="#menu">The Menu Library</A> -<UL> -<LI><A HREF="#mcompile">Compiling with the menu Library</A> -<LI><A HREF="#moverview">Overview of Menus</A> -<LI><A HREF="#mselect">Selecting items</A> -<LI><A HREF="#mdisplay">Menu Display</A> -<LI><A HREF="#mwindows">Menu Windows</A> -<LI><A HREF="#minput">Processing Menu Input</A> -<LI><A HREF="#mmisc">Miscellaneous Other Features</A> -</UL> -<LI><A HREF="#form">The Forms Library</A> -<UL> -<LI><A HREF="#fcompile">Compiling with the forms Library</A> -<LI><A HREF="#foverview">Overview of Forms</A> -<LI><A HREF="#fcreate">Creating and Freeing Fields and Forms</A> -<LI><A HREF="#fattributes">Fetching and Changing Field Attributes</A> -<UL> -<LI><A HREF="#fsizes">Fetching Size and Location Data</A> -<LI><A HREF="#flocation">Changing the Field Location</A> -<LI><A HREF="#fjust">The Justification Attribute</A> -<LI><A HREF="#fdispatts">Field Display Attributes</A> -<LI><A HREF="#foptions">Field Option Bits</A> -<LI><A HREF="#fstatus">Field Status</A> -<LI><A HREF="#fuser">Field User Pointer</A> -</UL> -<LI><A HREF="#fdynamic">Variable-Sized Fields</A> -<LI><A HREF="#fvalidation">Field Validation</A> -<UL> -<LI><A HREF="#ftype_alpha">TYPE_ALPHA</A> -<LI><A HREF="#ftype_alnum">TYPE_ALNUM</A> -<LI><A HREF="#ftype_enum">TYPE_ENUM</A> -<LI><A HREF="#ftype_integer">TYPE_INTEGER</A> -<LI><A HREF="#ftype_numeric">TYPE_NUMERIC</A> -<LI><A HREF="#ftype_regexp">TYPE_REGEXP</A> -</UL> -<LI><A HREF="#fbuffer">Direct Field Buffer Manipulation</A> -<LI><A HREF="#formattrs">Attributes of Forms</A> -<LI><A HREF="#fdisplay">Control of Form Display</A> -<LI><A HREF="#fdriver">Input Processing in the Forms Driver</A> -<UL> -<LI><A HREF="#fpage">Page Navigation Requests</A> -<LI><A HREF="#ffield">Inter-Field Navigation Requests</A> -<LI><A HREF="#fifield">Intra-Field Navigation Requests</A> -<LI><A HREF="#fscroll">Scrolling Requests</A> -<LI><A HREF="#fedit">Field Editing Requests</A> -<LI><A HREF="#forder">Order Requests</A> -<LI><A HREF="#fappcmds">Application Commands</A> -</UL> -<LI><A HREF="#fhooks">Field Change Hooks</A> -<LI><A HREF="#ffocus">Field Change Commands</A> -<LI><A HREF="#frmoptions">Form Options</A> -<LI><A HREF="#fcustom">Custom Validation Types</A> -<UL> -<LI><A HREF="#flinktypes">Union Types</A> -<LI><A HREF="#fnewtypes">New Field Types</A> -<LI><A HREF="#fcheckargs">Validation Function Arguments</A> -<LI><A HREF="#fcustorder">Order Functions For Custom Types</A> -<LI><A HREF="#fcustprobs">Avoiding Problems</A> -</UL> -</UL> -</UL> - -<HR> -<H1><A NAME="introduction">Introduction</A></H1> - -This document is an introduction to programming with <CODE>curses</CODE>. It is -not an exhaustive reference for the curses Application Programming Interface -(API); that role is filled by the <CODE>curses</CODE> manual pages. Rather, it -is intended to help C programmers ease into using the package. <P> - -This document is aimed at C applications programmers not yet specifically -familiar with ncurses. If you are already an experienced <CODE>curses</CODE> -programmer, you should nevertheless read the sections on -<A HREF="#mouse">Mouse Interfacing</A>, <A HREF="#debugging">Debugging</A>, -<A HREF="#compat">Compatibility with Older Versions</A>, -and <A HREF="#hints">Hints, Tips, and Tricks</A>. These will bring you up -to speed on the special features and quirks of the <CODE>ncurses</CODE> -implementation. If you are not so experienced, keep reading. <P> - -The <CODE>curses</CODE> package is a subroutine library for -terminal-independent screen-painting and input-event handling which -presents a high level screen model to the programmer, hiding differences -between terminal types and doing automatic optimization of output to change -one screen full of text into another. <CODE>Curses</CODE> uses terminfo, which -is a database format that can describe the capabilities of thousands of -different terminals. <P> - -The <CODE>curses</CODE> API may seem something of an archaism on UNIX desktops -increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX still -supports tty lines and X supports <EM>xterm(1)</EM>; the <CODE>curses</CODE> -API has the advantage of (a) back-portability to character-cell terminals, -and (b) simplicity. For an application that does not require bit-mapped -graphics and multiple fonts, an interface implementation using <CODE>curses</CODE> -will typically be a great deal simpler and less expensive than one using an -X toolkit. - -<H2><A NAME="history">A Brief History of Curses</A></H2> - -Historically, the first ancestor of <CODE>curses</CODE> was the routines written to -provide screen-handling for the game <CODE>rogue</CODE>; these used the -already-existing <CODE>termcap</CODE> database facility for describing terminal -capabilities. These routines were abstracted into a documented library and -first released with the early BSD UNIX versions. <P> - -System III UNIX from Bell Labs featured a rewritten and much-improved -<CODE>curses</CODE> library. It introduced the terminfo format. Terminfo is based -on Berkeley's termcap database, but contains a number of improvements and -extensions. Parameterized capabilities strings were introduced, making it -possible to describe multiple video attributes, and colors and to handle far -more unusual terminals than possible with termcap. In the later AT&T -System V releases, <CODE>curses</CODE> evolved to use more facilities and offer -more capabilities, going far beyond BSD curses in power and flexibility. - -<H2><A NAME="scope">Scope of This Document</A></H2> - -This document describes <CODE>ncurses</CODE>, a free implementation of -the System V <CODE>curses</CODE> API with some clearly marked extensions. -It includes the following System V curses features: -<UL> -<LI>Support for multiple screen highlights (BSD curses could only -handle one `standout' highlight, usually reverse-video). -<LI>Support for line- and box-drawing using forms characters. -<LI>Recognition of function keys on input. -<LI>Color support. -<LI>Support for pads (windows of larger than screen size on which the -screen or a subwindow defines a viewport). -</UL> - -Also, this package makes use of the insert and delete line and character -features of terminals so equipped, and determines how to optimally use these -features with no help from the programmer. It allows arbitrary combinations of -video attributes to be displayed, even on terminals that leave ``magic -cookies'' on the screen to mark changes in attributes. <P> - -The <CODE>ncurses</CODE> package can also capture and use event reports from a -mouse in some environments (notably, xterm under the X window system). This -document includes tips for using the mouse. <P> - -The <CODE>ncurses</CODE> package was originated by Pavel Curtis. The original -maintainer of this package is -<A HREF="mailto:zmbenhal@netcom.com">Zeyd Ben-Halim</A> -<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. -Jürgen Pfeifer -wrote all of the menu and forms code as well as the -<A HREF="http://www.adahome.com">Ada95</A> binding. -Ongoing work is being done by -<A HREF="mailto:dickey@invisible-island.net">Thomas Dickey</A> (maintainer). -Contact the current maintainers at -<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>. -<P> - -This document also describes the <A HREF="#panels">panels</A> extension library, -similarly modeled on the SVr4 panels facility. This library allows you to -associate backing store with each of a stack or deck of overlapping windows, -and provides operations for moving windows around in the stack that change -their visibility in the natural way (handling window overlaps). <P> - -Finally, this document describes in detail the <A HREF="#menu">menus</A> and <A -HREF="#form">forms</A> extension libraries, also cloned from System V, -which support easy construction and sequences of menus and fill-in -forms. - - -<H2><A NAME="terminology">Terminology</A></H2> - -In this document, the following terminology is used with reasonable -consistency: - -<DL> -<DT> window -<DD> -A data structure describing a sub-rectangle of the screen (possibly the -entire screen). You can write to a window as though it were a miniature -screen, scrolling independently of other windows on the physical screen. -<DT> screens -<DD> -A subset of windows which are as large as the terminal screen, i.e., they start -at the upper left hand corner and encompass the lower right hand corner. One -of these, <CODE>stdscr</CODE>, is automatically provided for the programmer. -<DT> terminal screen -<DD> -The package's idea of what the terminal display currently looks like, i.e., -what the user sees now. This is a special screen. -</DL> - -<H1><A NAME="curses">The Curses Library</A></H1> - -<H2><A NAME="overview">An Overview of Curses</A></H2> - -<H3><A NAME="compiling">Compiling Programs using Curses</A></H3> - -In order to use the library, it is necessary to have certain types and -variables defined. Therefore, the programmer must have a line: - -<PRE> - #include <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. - -<H3><A NAME="stdscr">Standard Windows and Function Naming Conventions</A></H3> - -As hinted above, the routines can use several windows, but two are -automatically given: <CODE>curscr</CODE>, which knows what the terminal looks like, -and <CODE>stdscr</CODE>, which is what the programmer wants the terminal to look -like next. The user should never actually access <CODE>curscr</CODE> directly. -Changes should be made to through the API, and then the routine -<CODE>refresh()</CODE> (or <CODE>wrefresh()</CODE>) called. <P> - -Many functions are defined to use <CODE>stdscr</CODE> as a default screen. For -example, to add a character to <CODE>stdscr</CODE>, one calls <CODE>addch()</CODE> with -the desired character as argument. To write to a different window. use the -routine <CODE>waddch()</CODE> (for `w'indow-specific addch()) is provided. This -convention of prepending function names with a `w' when they are to be -applied to specific windows is consistent. The only routines which do not -follow it are those for which a window must always be specified. <P> - -In order to move the current (y, x) coordinates from one point to another, the -routines <CODE>move()</CODE> and <CODE>wmove()</CODE> are provided. However, it is -often desirable to first move and then perform some I/O operation. In order to -avoid clumsiness, most I/O routines can be preceded by the prefix 'mv' and -the desired (y, x) coordinates prepended to the arguments to the function. For -example, the calls - -<PRE> - move(y, x); - addch(ch); -</PRE> - -can be replaced by - -<PRE> - mvaddch(y, x, ch); -</PRE> - -and - -<PRE> - wmove(win, y, x); - waddch(win, ch); -</PRE> - -can be replaced by - -<PRE> - mvwaddch(win, y, x, ch); -</PRE> - -Note that the window description pointer (win) comes before the added (y, x) -coordinates. If a function requires a window pointer, it is always the first -parameter passed. - -<H3><A NAME="variables">Variables</A></H3> - -The <CODE>curses</CODE> library sets some variables describing the terminal -capabilities. - -<PRE> - type name description - ------------------------------------------------------------------ - int LINES number of lines on the terminal - int COLS number of columns on the terminal -</PRE> - -The <CODE>curses.h</CODE> also introduces some <CODE>#define</CODE> constants and types -of general usefulness: - -<DL> -<DT> <CODE>bool</CODE> -<DD> boolean type, actually a `char' (e.g., <CODE>bool doneit;</CODE>) -<DT> <CODE>TRUE</CODE> -<DD> boolean `true' flag (1). -<DT> <CODE>FALSE</CODE> -<DD> boolean `false' flag (0). -<DT> <CODE>ERR</CODE> -<DD> error flag returned by routines on a failure (-1). -<DT> <CODE>OK</CODE> -<DD> error flag returned by routines when things go right. -</DL> - -<H2><A NAME="using">Using the Library</A></H2> - -Now we describe how to actually use the screen package. In it, we assume all -updating, reading, etc. is applied to <CODE>stdscr</CODE>. These instructions will -work on any window, providing you change the function names and parameters as -mentioned above. <P> - -Here is a sample program to motivate the discussion: - -<PRE> -#include <curses.h> -#include <signal.h> - -static void finish(int sig); - -int -main(int argc, char *argv[]) -{ - int num = 0; - - /* initialize your non-curses data structures here */ - - (void) signal(SIGINT, finish); /* arrange interrupts to terminate */ - - (void) initscr(); /* initialize the curses library */ - keypad(stdscr, TRUE); /* enable keyboard mapping */ - (void) nonl(); /* tell curses not to do NL->CR/NL on output */ - (void) cbreak(); /* take input chars one at a time, no wait for \n */ - (void) echo(); /* echo input - in color */ - - if (has_colors()) - { - start_color(); - - /* - * Simple color assignment, often all we need. Color pair 0 cannot - * be redefined. This example uses the same value for the color - * pair as for the foreground color, though of course that is not - * necessary: - */ - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_YELLOW, COLOR_BLACK); - init_pair(4, COLOR_BLUE, COLOR_BLACK); - init_pair(5, COLOR_CYAN, COLOR_BLACK); - init_pair(6, COLOR_MAGENTA, COLOR_BLACK); - init_pair(7, COLOR_WHITE, COLOR_BLACK); - } - - for (;;) - { - int c = getch(); /* refresh, accept single keystroke of input */ - attrset(COLOR_PAIR(num % 8)); - num++; - - /* process the command keystroke */ - } - - finish(0); /* we're done */ -} - -static void finish(int sig) -{ - endwin(); - - /* do your non-curses wrapup here */ - - exit(0); -} -</PRE> - -<H3><A NAME="starting">Starting up</A></H3> - -In order to use the screen package, the routines must know about terminal -characteristics, and the space for <CODE>curscr</CODE> and <CODE>stdscr</CODE> must be -allocated. These function <CODE>initscr()</CODE> does both these things. Since it -must allocate space for the windows, it can overflow memory when attempting to -do so. On the rare occasions this happens, <CODE>initscr()</CODE> will terminate -the program with an error message. <CODE>initscr()</CODE> must always be called -before any of the routines which affect windows are used. If it is not, the -program will core dump as soon as either <CODE>curscr</CODE> or <CODE>stdscr</CODE> are -referenced. However, it is usually best to wait to call it until after you are -sure you will need it, like after checking for startup errors. Terminal status -changing routines like <CODE>nl()</CODE> and <CODE>cbreak()</CODE> should be called -after <CODE>initscr()</CODE>. <P> - -Once the screen windows have been allocated, you can set them up for -your program. If you want to, say, allow a screen to scroll, use -<CODE>scrollok()</CODE>. If you want the cursor to be left in place after -the last change, use <CODE>leaveok()</CODE>. If this isn't done, -<CODE>refresh()</CODE> will move the cursor to the window's current (y, x) -coordinates after updating it. <P> - -You can create new windows of your own using the functions <CODE>newwin()</CODE>, -<CODE>derwin()</CODE>, and <CODE>subwin()</CODE>. The routine <CODE>delwin()</CODE> will -allow you to get rid of old windows. All the options described above can be -applied to any window. - -<H3><A NAME="output">Output</A></H3> - -Now that we have set things up, we will want to actually update the terminal. -The basic functions used to change what will go on a window are -<CODE>addch()</CODE> and <CODE>move()</CODE>. <CODE>addch()</CODE> adds a character at the -current (y, x) coordinates. <CODE>move()</CODE> changes the current (y, x) -coordinates to whatever you want them to be. It returns <CODE>ERR</CODE> if you -try to move off the window. As mentioned above, you can combine the two into -<CODE>mvaddch()</CODE> to do both things at once. <P> - -The other output functions, such as <CODE>addstr()</CODE> and <CODE>printw()</CODE>, -all call <CODE>addch()</CODE> to add characters to the window. <P> - -After you have put on the window what you want there, when you want the portion -of the terminal covered by the window to be made to look like it, you must call -<CODE>refresh()</CODE>. In order to optimize finding changes, <CODE>refresh()</CODE> -assumes that any part of the window not changed since the last -<CODE>refresh()</CODE> of that window has not been changed on the terminal, i.e., -that you have not refreshed a portion of the terminal with an overlapping -window. If this is not the case, the routine <CODE>touchwin()</CODE> is provided -to make it look like the entire window has been changed, thus making -<CODE>refresh()</CODE> check the whole subsection of the terminal for changes. <P> - -If you call <CODE>wrefresh()</CODE> with <CODE>curscr</CODE> as its argument, it will -make the screen look like <CODE>curscr</CODE> thinks it looks like. This is useful -for implementing a command which would redraw the screen in case it get messed -up. - -<H3><A NAME="input">Input</A></H3> - -The complementary function to <CODE>addch()</CODE> is <CODE>getch()</CODE> which, if -echo is set, will call <CODE>addch()</CODE> to echo the character. Since the -screen package needs to know what is on the terminal at all times, if -characters are to be echoed, the tty must be in raw or cbreak mode. Since -initially the terminal has echoing enabled and is in ordinary ``cooked'' mode, -one or the other has to changed before calling <CODE>getch()</CODE>; otherwise, -the program's output will be unpredictable. <P> - -When you need to accept line-oriented input in a window, the functions -<CODE>wgetstr()</CODE> and friends are available. There is even a <CODE>wscanw()</CODE> -function that can do <CODE>scanf()</CODE>(3)-style multi-field parsing on window -input. These pseudo-line-oriented functions turn on echoing while they -execute. <P> - -The example code above uses the call <CODE>keypad(stdscr, TRUE)</CODE> to enable -support for function-key mapping. With this feature, the <CODE>getch()</CODE> code -watches the input stream for character sequences that correspond to arrow and -function keys. These sequences are returned as pseudo-character values. The -<CODE>#define</CODE> values returned are listed in the <CODE>curses.h</CODE> The -mapping from sequences to <CODE>#define</CODE> values is determined by -<CODE>key_</CODE> capabilities in the terminal's terminfo entry. - -<H3><A NAME="formschars">Using Forms Characters</A></H3> - -The <CODE>addch()</CODE> function (and some others, including <CODE>box()</CODE> and -<CODE>border()</CODE>) can accept some pseudo-character arguments which are specially -defined by <CODE>ncurses</CODE>. These are <CODE>#define</CODE> values set up in -the <CODE>curses.h</CODE> header; see there for a complete list (look for -the prefix <CODE>ACS_</CODE>). <P> - -The most useful of the ACS defines are the forms-drawing characters. You can -use these to draw boxes and simple graphs on the screen. If the terminal -does not have such characters, <CODE>curses.h</CODE> will map them to a -recognizable (though ugly) set of ASCII defaults. - -<H3><A NAME="attributes">Character Attributes and Color</A></H3> - -The <CODE>ncurses</CODE> package supports screen highlights including standout, -reverse-video, underline, and blink. It also supports color, which is treated -as another kind of highlight. <P> - -Highlights are encoded, internally, as high bits of the pseudo-character type -(<CODE>chtype</CODE>) that <CODE>curses.h</CODE> uses to represent the contents of a -screen cell. See the <CODE>curses.h</CODE> header file for a complete list of -highlight mask values (look for the prefix <CODE>A_</CODE>).<P> - -There are two ways to make highlights. One is to logical-or the value of the -highlights you want into the character argument of an <CODE>addch()</CODE> call, -or any other output call that takes a <CODE>chtype</CODE> argument. <P> - -The other is to set the current-highlight value. This is logical-or'ed with -any highlight you specify the first way. You do this with the functions -<CODE>attron()</CODE>, <CODE>attroff()</CODE>, and <CODE>attrset()</CODE>; see the manual -pages for details. - -Color is a special kind of highlight. The package actually thinks in terms -of color pairs, combinations of foreground and background colors. The sample -code above sets up eight color pairs, all of the guaranteed-available colors -on black. Note that each color pair is, in effect, given the name of its -foreground color. Any other range of eight non-conflicting values could -have been used as the first arguments of the <CODE>init_pair()</CODE> values. <P> - -Once you've done an <CODE>init_pair()</CODE> that creates color-pair N, you can -use <CODE>COLOR_PAIR(N)</CODE> as a highlight that invokes that particular -color combination. Note that <CODE>COLOR_PAIR(N)</CODE>, for constant N, -is itself a compile-time constant and can be used in initializers. - -<H3><A NAME="mouse">Mouse Interfacing</A></H3> - -The <CODE>ncurses</CODE> library also provides a mouse interface. -<!-- The 'note' tag is not portable enough --> -<blockquote> -<strong>NOTE:</strong> this facility is specific to <CODE>ncurses</CODE>, it is not part of either -the XSI Curses standard, nor of System V Release 4, nor BSD curses. -System V Release 4 curses contains code with similar interface definitions, -however it is not documented. Other than by disassembling the library, we -have no way to determine exactly how that mouse code works. -Thus, we recommend that you wrap mouse-related code in an #ifdef using the -feature macro NCURSES_MOUSE_VERSION so it will not be compiled and linked -on non-ncurses systems. -</blockquote> - -Presently, mouse event reporting works in the following environments: -<ul> -<li>xterm and similar programs such as rxvt. -<li>Linux console, when configured with <CODE>gpm</CODE>(1), Alessandro -Rubini's mouse server. -<li>FreeBSD sysmouse (console) -<li>OS/2 EMX -</ul> -<P> -The mouse interface is very simple. To activate it, you use the function -<CODE>mousemask()</CODE>, passing it as first argument a bit-mask that specifies -what kinds of events you want your program to be able to see. It will -return the bit-mask of events that actually become visible, which may differ -from the argument if the mouse device is not capable of reporting some of -the event types you specify. <P> - -Once the mouse is active, your application's command loop should watch -for a return value of <CODE>KEY_MOUSE</CODE> from <CODE>wgetch()</CODE>. When -you see this, a mouse event report has been queued. To pick it off -the queue, use the function <CODE>getmouse()</CODE> (you must do this before -the next <CODE>wgetch()</CODE>, otherwise another mouse event might come -in and make the first one inaccessible). <P> - -Each call to <CODE>getmouse()</CODE> fills a structure (the address of which you'll -pass it) with mouse event data. The event data includes zero-origin, -screen-relative character-cell coordinates of the mouse pointer. It also -includes an event mask. Bits in this mask will be set, corresponding -to the event type being reported. <P> - -The mouse structure contains two additional fields which may be -significant in the future as ncurses interfaces to new kinds of -pointing device. In addition to x and y coordinates, there is a slot -for a z coordinate; this might be useful with touch-screens that can -return a pressure or duration parameter. There is also a device ID -field, which could be used to distinguish between multiple pointing -devices. <P> - -The class of visible events may be changed at any time via <CODE>mousemask()</CODE>. -Events that can be reported include presses, releases, single-, double- and -triple-clicks (you can set the maximum button-down time for clicks). If -you don't make clicks visible, they will be reported as press-release -pairs. In some environments, the event mask may include bits reporting -the state of shift, alt, and ctrl keys on the keyboard during the event. <P> - -A function to check whether a mouse event fell within a given window is -also supplied. You can use this to see whether a given window should -consider a mouse event relevant to it. <P> - -Because mouse event reporting will not be available in all -environments, it would be unwise to build <CODE>ncurses</CODE> -applications that <EM>require</EM> the use of a mouse. Rather, you should -use the mouse as a shortcut for point-and-shoot commands your application -would normally accept from the keyboard. Two of the test games in the -<CODE>ncurses</CODE> distribution (<CODE>bs</CODE> and <CODE>knight</CODE>) contain -code that illustrates how this can be done. <P> - -See the manual page <CODE>curs_mouse(3X)</CODE> for full details of the -mouse-interface functions. - -<H3><A NAME="finishing">Finishing Up</A></H3> - -In order to clean up after the <CODE>ncurses</CODE> routines, the routine -<CODE>endwin()</CODE> is provided. It restores tty modes to what they were when -<CODE>initscr()</CODE> was first called, and moves the cursor down to the -lower-left corner. Thus, anytime after the call to initscr, <CODE>endwin()</CODE> -should be called before exiting. - -<H2><A NAME="functions">Function Descriptions</A></H2> - -We describe the detailed behavior of some important curses functions here, as a -supplement to the manual page descriptions. - -<H3><A NAME="init">Initialization and Wrapup</A></H3> - -<DL> -<DT> <CODE>initscr()</CODE> -<DD> The first function called should almost always be <CODE>initscr()</CODE>. -This will determine the terminal type and -initialize curses data structures. <CODE>initscr()</CODE> also arranges that -the first call to <CODE>refresh()</CODE> will clear the screen. If an error -occurs a message is written to standard error and the program -exits. Otherwise it returns a pointer to stdscr. A few functions may be -called before initscr (<CODE>slk_init()</CODE>, <CODE>filter()</CODE>, -<CODE>ripoffline()</CODE>, <CODE>use_env()</CODE>, and, if you are using multiple -terminals, <CODE>newterm()</CODE>.) -<DT> <CODE>endwin()</CODE> -<DD> Your program should always call <CODE>endwin()</CODE> before exiting or -shelling out of the program. This function will restore tty modes, -move the cursor to the lower left corner of the screen, reset the -terminal into the proper non-visual mode. Calling <CODE>refresh()</CODE> -or <CODE>doupdate()</CODE> after a temporary escape from the program will -restore the ncurses screen from before the escape. -<DT> <CODE>newterm(type, ofp, ifp)</CODE> -<DD> A program which outputs to more than one terminal should use -<CODE>newterm()</CODE> instead of <CODE>initscr()</CODE>. <CODE>newterm()</CODE> should -be called once for each terminal. It returns a variable of type -<CODE>SCREEN *</CODE> which should be saved as a reference to that -terminal. -(NOTE: a SCREEN variable is not a <em>screen</em> in the sense we -are describing in this introduction, but a collection of -parameters used to assist in optimizing the display.) -The arguments are the type of the terminal (a string) and -<CODE>FILE</CODE> pointers for the output and input of the terminal. If -type is NULL then the environment variable <CODE>$TERM</CODE> is used. -<CODE>endwin()</CODE> should called once at wrapup time for each terminal -opened using this function. -<DT> <CODE>set_term(new)</CODE> -<DD> This function is used to switch to a different terminal previously -opened by <CODE>newterm()</CODE>. The screen reference for the new terminal -is passed as the parameter. The previous terminal is returned by the -function. All other calls affect only the current terminal. -<DT> <CODE>delscreen(sp)</CODE> -<DD> The inverse of <CODE>newterm()</CODE>; deallocates the data structures -associated with a given <CODE>SCREEN</CODE> reference. -</DL> - -<H3><A NAME="flush">Causing Output to the Terminal</A></H3> - -<DL> -<DT> <CODE>refresh()</CODE> and <CODE>wrefresh(win)</CODE> -<DD> These functions must be called to actually get any output on -the terminal, as other routines merely manipulate data -structures. <CODE>wrefresh()</CODE> copies the named window to the physical -terminal screen, taking into account what is already -there in order to do optimizations. <CODE>refresh()</CODE> does a -refresh of <CODE>stdscr</CODE>. Unless <CODE>leaveok()</CODE> has been -enabled, the physical cursor of the terminal is left at the -location of the window's cursor. -<DT> <CODE>doupdate()</CODE> and <CODE>wnoutrefresh(win)</CODE> -<DD> These two functions allow multiple updates with more efficiency -than wrefresh. To use them, it is important to understand how curses -works. In addition to all the window structures, curses keeps two -data structures representing the terminal screen: a physical screen, -describing what is actually on the screen, and a virtual screen, -describing what the programmer wants to have on the screen. wrefresh -works by first copying the named window to the virtual screen -(<CODE>wnoutrefresh()</CODE>), and then calling the routine to update the -screen (<CODE>doupdate()</CODE>). If the programmer wishes to output -several windows at once, a series of calls to <CODE>wrefresh</CODE> will result -in alternating calls to <CODE>wnoutrefresh()</CODE> and <CODE>doupdate()</CODE>, -causing several bursts of output to the screen. By calling -<CODE>wnoutrefresh()</CODE> for each window, it is then possible to call -<CODE>doupdate()</CODE> once, resulting in only one burst of output, with -fewer total characters transmitted (this also avoids a visually annoying -flicker at each update). -</DL> - -<H3><A NAME="lowlevel">Low-Level Capability Access</A></H3> - -<DL> -<DT> <CODE>setupterm(term, filenum, errret)</CODE> -<DD> This routine is called to initialize a terminal's description, without setting -up the curses screen structures or changing the tty-driver mode bits. -<CODE>term</CODE> is the character string representing the name of the terminal -being used. <CODE>filenum</CODE> is the UNIX file descriptor of the terminal to -be used for output. <CODE>errret</CODE> is a pointer to an integer, in which a -success or failure indication is returned. The values returned can be 1 (all -is well), 0 (no such terminal), or -1 (some problem locating the terminfo -database). <P> - -The value of <CODE>term</CODE> can be given as NULL, which will cause the value of -<CODE>TERM</CODE> in the environment to be used. The <CODE>errret</CODE> pointer can -also be given as NULL, meaning no error code is wanted. If <CODE>errret</CODE> is -defaulted, and something goes wrong, <CODE>setupterm()</CODE> will print an -appropriate error message and exit, rather than returning. Thus, a simple -program can call setupterm(0, 1, 0) and not worry about initialization -errors. <P> - -After the call to <CODE>setupterm()</CODE>, the global variable <CODE>cur_term</CODE> is -set to point to the current structure of terminal capabilities. By calling -<CODE>setupterm()</CODE> for each terminal, and saving and restoring -<CODE>cur_term</CODE>, it is possible for a program to use two or more terminals at -once. <CODE>Setupterm()</CODE> also stores the names section of the terminal -description in the global character array <CODE>ttytype[]</CODE>. Subsequent calls -to <CODE>setupterm()</CODE> will overwrite this array, so you'll have to save it -yourself if need be. -</DL> - -<H3><A NAME="debugging">Debugging</A></H3> - -<!-- The 'note' tag is not portable enough --> -<blockquote> -<strong>NOTE:</strong> These functions are not part of the standard curses API! -</blockquote> - -<DL> -<DT> <CODE>trace()</CODE> -<DD> -This function can be used to explicitly set a trace level. If the -trace level is nonzero, execution of your program will generate a file -called `trace' in the current working directory containing a report on -the library's actions. Higher trace levels enable more detailed (and -verbose) reporting -- see comments attached to <CODE>TRACE_</CODE> defines -in the <CODE>curses.h</CODE> file for details. (It is also possible to set -a trace level by assigning a trace level value to the environment variable -<CODE>NCURSES_TRACE</CODE>). -<DT> <CODE>_tracef()</CODE> -<DD> -This function can be used to output your own debugging information. It is only -available only if you link with -lncurses_g. It can be used the same way as -<CODE>printf()</CODE>, only it outputs a newline after the end of arguments. -The output goes to a file called <CODE>trace</CODE> in the current directory. -</DL> - -Trace logs can be difficult to interpret due to the sheer volume of -data dumped in them. There is a script called <STRONG>tracemunch</STRONG> -included with the <CODE>ncurses</CODE> distribution that can alleviate -this problem somewhat; it compacts long sequences of similar operations into -more succinct single-line pseudo-operations. These pseudo-ops can be -distinguished by the fact that they are named in capital letters. - -<H2><A NAME="hints">Hints, Tips, and Tricks</A></H2> - -The <CODE>ncurses</CODE> manual pages are a complete reference for this library. -In the remainder of this document, we discuss various useful methods that -may not be obvious from the manual page descriptions. - -<H3><A NAME="caution">Some Notes of Caution</A></H3> - -If you find yourself thinking you need to use <CODE>noraw()</CODE> or -<CODE>nocbreak()</CODE>, think again and move carefully. It's probably -better design to use <CODE>getstr()</CODE> or one of its relatives to -simulate cooked mode. The <CODE>noraw()</CODE> and <CODE>nocbreak()</CODE> -functions try to restore cooked mode, but they may end up clobbering -some control bits set before you started your application. Also, they -have always been poorly documented, and are likely to hurt your -application's usability with other curses libraries. <P> - -Bear in mind that <CODE>refresh()</CODE> is a synonym for <CODE>wrefresh(stdscr)</CODE>. -Don't try to mix use of <CODE>stdscr</CODE> with use of windows declared -by <CODE>newwin()</CODE>; a <CODE>refresh()</CODE> call will blow them off the -screen. The right way to handle this is to use <CODE>subwin()</CODE>, or -not touch <CODE>stdscr</CODE> at all and tile your screen with declared -windows which you then <CODE>wnoutrefresh()</CODE> somewhere in your program -event loop, with a single <CODE>doupdate()</CODE> call to trigger actual -repainting. <P> - -You are much less likely to run into problems if you design your screen -layouts to use tiled rather than overlapping windows. Historically, -curses support for overlapping windows has been weak, fragile, and poorly -documented. The <CODE>ncurses</CODE> library is not yet an exception to this -rule. <P> - -There is a panels library included in the <CODE>ncurses</CODE> -distribution that does a pretty good job of strengthening the -overlapping-windows facilities. <P> - -Try to avoid using the global variables LINES and COLS. Use -<CODE>getmaxyx()</CODE> on the <CODE>stdscr</CODE> context instead. Reason: -your code may be ported to run in an environment with window resizes, -in which case several screens could be open with different sizes. - -<H3><A NAME="leaving">Temporarily Leaving NCURSES Mode</A></H3> - -Sometimes you will want to write a program that spends most of its time in -screen mode, but occasionally returns to ordinary `cooked' mode. A common -reason for this is to support shell-out. This behavior is simple to arrange -in <CODE>ncurses</CODE>. <P> - -To leave <CODE>ncurses</CODE> mode, call <CODE>endwin()</CODE> as you would if you -were intending to terminate the program. This will take the screen back to -cooked mode; you can do your shell-out. When you want to return to -<CODE>ncurses</CODE> mode, simply call <CODE>refresh()</CODE> or <CODE>doupdate()</CODE>. -This will repaint the screen. <P> - -There is a boolean function, <CODE>isendwin()</CODE>, which code can use to -test whether <CODE>ncurses</CODE> screen mode is active. It returns <CODE>TRUE</CODE> -in the interval between an <CODE>endwin()</CODE> call and the following -<CODE>refresh()</CODE>, <CODE>FALSE</CODE> otherwise. <P> - -Here is some sample code for shellout: - -<PRE> - addstr("Shelling out..."); - def_prog_mode(); /* save current tty modes */ - endwin(); /* restore original tty modes */ - system("sh"); /* run shell */ - addstr("returned.\n"); /* prepare return message */ - refresh(); /* restore save modes, repaint screen */ -</PRE> - -<H3><A NAME="xterm">Using NCURSES under XTERM</A></H3> - -A resize operation in X sends <CODE>SIGWINCH</CODE> to the application running -under xterm. - -The easiest way to handle <CODE>SIGWINCH</CODE> -is to do an <CODE>endwin</CODE>, -followed by an <CODE>refresh</CODE> and a screen repaint you code -yourself. -The <CODE>refresh</CODE> will pick up the new screen size from the -xterm's environment. <P> - -That is the standard way, of course (it even works with some vendor's curses -implementations). -Its drawback is that it clears the screen to reinitialize the display, and does -not resize subwindows which must be shrunk. -<CODE>Ncurses</CODE> provides an extension which works better, the -<CODE>resizeterm</CODE> function. That function ensures that all windows -are limited to the new screen dimensions, and pads <CODE>stdscr</CODE> -with blanks if the screen is larger. <P> - -The <CODE>ncurses</CODE> library provides a SIGWINCH signal handler, -which pushes a <CODE>KEY_RESIZE</CODE> via the wgetch() calls. -When <CODE>ncurses</CODE> returns that code, -it calls <code>resizeterm</CODE> -to update the size of the standard screen's window, repainting that -(filling with blanks or truncating as needed). -It also resizes other windows, -but its effect may be less satisfactory because it cannot -know how you want the screen re-painted. -You will usually have to write special-purpose code to handle -<CODE>KEY_RESIZE</CODE> yourself. - -<H3><A NAME="screens">Handling Multiple Terminal Screens</A></H3> - -The <CODE>initscr()</CODE> function actually calls a function named -<CODE>newterm()</CODE> to do most of its work. If you are writing a program that -opens multiple terminals, use <CODE>newterm()</CODE> directly. <P> - -For each call, you will have to specify a terminal type and a pair of file -pointers; each call will return a screen reference, and <CODE>stdscr</CODE> will be -set to the last one allocated. You will switch between screens with the -<CODE>set_term</CODE> call. Note that you will also have to call -<CODE>def_shell_mode</CODE> and <CODE>def_prog_mode</CODE> on each tty yourself. - -<H3><A NAME="testing">Testing for Terminal Capabilities</A></H3> - -Sometimes you may want to write programs that test for the presence of various -capabilities before deciding whether to go into <CODE>ncurses</CODE> mode. An easy -way to do this is to call <CODE>setupterm()</CODE>, then use the functions -<CODE>tigetflag()</CODE>, <CODE>tigetnum()</CODE>, and <CODE>tigetstr()</CODE> to do your -testing. <P> - -A particularly useful case of this often comes up when you want to -test whether a given terminal type should be treated as `smart' -(cursor-addressable) or `stupid'. The right way to test this is to see -if the return value of <CODE>tigetstr("cup")</CODE> is non-NULL. Alternatively, -you can include the <CODE>term.h</CODE> file and test the value of the -macro <CODE>cursor_address</CODE>. - -<H3><A NAME="tuning">Tuning for Speed</A></H3> - -Use the <CODE>addchstr()</CODE> family of functions for fast -screen-painting of text when you know the text doesn't contain any -control characters. Try to make attribute changes infrequent on your -screens. Don't use the <CODE>immedok()</CODE> option! - -<H3><A NAME="special">Special Features of NCURSES</A></H3> - -The <CODE>wresize()</CODE> function allows you to resize a window in place. -The associated <CODE>resizeterm()</CODE> function simplifies the construction -of <a HREF="#xterm">SIGWINCH</a> handlers, for resizing all windows. <P> - -The <CODE>define_key()</CODE> function allows you -to define at runtime function-key control sequences which are not in the -terminal description. -The <CODE>keyok()</CODE> function allows you to temporarily -enable or disable interpretation of any function-key control sequence. <P> - -The <CODE>use_default_colors()</CODE> function allows you to construct -applications which can use the terminal's default foreground and -background colors as an additional "default" color. -Several terminal emulators support this feature, which is based on ISO 6429. <P> - -Ncurses supports up 16 colors, unlike SVr4 curses which defines only 8. -While most terminals which provide color allow only 8 colors, about -a quarter (including XFree86 xterm) support 16 colors. - -<H2><A NAME="compat">Compatibility with Older Versions</A></H2> - -Despite our best efforts, there are some differences between <CODE>ncurses</CODE> -and the (undocumented!) behavior of older curses implementations. These arise -from ambiguities or omissions in the documentation of the API. - -<H3><A NAME="refbug">Refresh of Overlapping Windows</A></H3> - -If you define two windows A and B that overlap, and then alternately scribble -on and refresh them, the changes made to the overlapping region under historic -<CODE>curses</CODE> versions were often not documented precisely. <P> - -To understand why this is a problem, remember that screen updates are -calculated between two representations of the <EM>entire</EM> display. The -documentation says that when you refresh a window, it is first copied to the -virtual screen, and then changes are calculated to update the physical screen -(and applied to the terminal). But "copied to" is not very specific, and -subtle differences in how copying works can produce different behaviors in the -case where two overlapping windows are each being refreshed at unpredictable -intervals. <P> - -What happens to the overlapping region depends on what <CODE>wnoutrefresh()</CODE> -does with its argument -- what portions of the argument window it copies to the -virtual screen. Some implementations do "change copy", copying down only -locations in the window that have changed (or been marked changed with -<CODE>wtouchln()</CODE> and friends). Some implementations do "entire copy", -copying <EM>all</EM> window locations to the virtual screen whether or not -they have changed. <P> - -The <CODE>ncurses</CODE> library itself has not always been consistent on this -score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. Versions -1.8.6 and older, and versions 1.9.9 and newer, do change copy. <P> - -For most commercial curses implementations, it is not documented and not known -for sure (at least not to the <CODE>ncurses</CODE> maintainers) whether they do -change copy or entire copy. We know that System V release 3 curses has logic -in it that looks like an attempt to do change copy, but the surrounding logic -and data representations are sufficiently complex, and our knowledge -sufficiently indirect, that it's hard to know whether this is reliable. - -It is not clear what the SVr4 documentation and XSI standard intend. The XSI -Curses standard barely mentions wnoutrefresh(); the SVr4 documents seem to be -describing entire-copy, but it is possible with some effort and straining to -read them the other way. <P> - -It might therefore be unwise to rely on either behavior in programs that might -have to be linked with other curses implementations. Instead, you can do an -explicit <CODE>touchwin()</CODE> before the <CODE>wnoutrefresh()</CODE> call to -guarantee an entire-contents copy anywhere. <P> - -The really clean way to handle this is to use the panels library. If, -when you want a screen update, you do <CODE>update_panels()</CODE>, it will -do all the necessary <CODE>wnoutrefresh()</CODE> calls for whatever panel -stacking order you have defined. Then you can do one <CODE>doupdate()</CODE> -and there will be a <EM>single</EM> burst of physical I/O that will do -all your updates. - -<H3><A NAME="backbug">Background Erase</A></H3> - -If you have been using a very old versions of <CODE>ncurses</CODE> (1.8.7 or -older) you may be surprised by the behavior of the erase functions. In older -versions, erased areas of a window were filled with a blank modified by the -window's current attribute (as set by <STRONG>wattrset()</STRONG>, <STRONG>wattron()</STRONG>, -<STRONG>wattroff()</STRONG> and friends). <P> - -In newer versions, this is not so. Instead, the attribute of erased blanks -is normal unless and until it is modified by the functions <CODE>bkgdset()</CODE> -or <CODE>wbkgdset()</CODE>. <P> - -This change in behavior conforms <CODE>ncurses</CODE> to System V Release 4 and -the XSI Curses standard. - -<H2><A NAME="xsifuncs">XSI Curses Conformance</A></H2> - -The <CODE>ncurses</CODE> library is intended to be base-level conformant with the -XSI Curses standard from X/Open. Many extended-level features (in fact, almost -all features not directly concerned with wide characters and -internationalization) are also supported. <P> - -One effect of XSI conformance is the change in behavior described under -<A HREF="#backbug">"Background Erase -- Compatibility with Old Versions"</A>. <P> - -Also, <CODE>ncurses</CODE> meets the XSI requirement that every macro -entry point have a corresponding function which may be linked (and -will be prototype-checked) if the macro definition is disabled with -<CODE>#undef</CODE>. - -<H1><A NAME="panels">The Panels Library</A></H1> - -The <CODE>ncurses</CODE> library by itself provides good support for screen -displays in which the windows are tiled (non-overlapping). In the more -general case that windows may overlap, you have to use a series of -<CODE>wnoutrefresh()</CODE> calls followed by a <CODE>doupdate()</CODE>, and be -careful about the order you do the window refreshes in. It has to be -bottom-upwards, otherwise parts of windows that should be obscured will -show through. <P> - -When your interface design is such that windows may dive deeper into the -visibility stack or pop to the top at runtime, the resulting book-keeping -can be tedious and difficult to get right. Hence the panels library. <P> - -The <CODE>panel</CODE> library first appeared in AT&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. - -<H2><A NAME="pstdscr">Panels, Input, and the Standard Screen</A></H2> - -You shouldn't mix <CODE>wnoutrefresh()</CODE> or <CODE>wrefresh()</CODE> -operations with panels code; this will work only if the argument window -is either in the top panel or unobscured by any other panels. <P> - -The <CODE>stsdcr</CODE> window is a special case. It is considered below all -panels. Because changes to panels may obscure parts of <CODE>stdscr</CODE>, -though, you should call <CODE>update_panels()</CODE> before -<CODE>doupdate()</CODE> even when you only change <CODE>stdscr</CODE>. <P> - -Note that <CODE>wgetch</CODE> automatically calls <CODE>wrefresh</CODE>. -Therefore, before requesting input from a panel window, you need to be sure -that the panel is totally unobscured. <P> - -There is presently no way to display changes to one obscured panel without -repainting all panels. - -<H2><A NAME="hiding">Hiding Panels</A></H2> - -It's possible to remove a panel from the deck temporarily; use -<CODE>hide_panel</CODE> for this. Use <CODE>show_panel()</CODE> to render it -visible again. The predicate function <CODE>panel_hidden</CODE> -tests whether or not a panel is hidden. <P> - -The <CODE>panel_update</CODE> code ignores hidden panels. You cannot do -<CODE>top_panel()</CODE> or <CODE>bottom_panel</CODE> on a hidden panel(). -Other panels operations are applicable. - -<H2><A NAME="pmisc">Miscellaneous Other Facilities</A></H2> - -It's possible to navigate the deck using the functions -<CODE>panel_above()</CODE> and <CODE>panel_below</CODE>. Handed a panel -pointer, they return the panel above or below that panel. Handed -<CODE>NULL</CODE>, they return the bottom-most or top-most panel. <P> - -Every panel has an associated user pointer, not used by the panel code, to -which you can attach application data. See the man page documentation -of <CODE>set_panel_userptr()</CODE> and <CODE>panel_userptr</CODE> for -details. - -<H1><A NAME="menu">The Menu Library</A></H1> - -A menu is a screen display that assists the user to choose some subset -of a given set of items. The <CODE>menu</CODE> library is a curses -extension that supports easy programming of menu hierarchies with a -uniform but flexible interface. <P> - -The <CODE>menu</CODE> library first appeared in AT&T System V. The -version documented here is the <CODE>menu</CODE> code distributed -with <CODE>ncurses</CODE>. - -<H2><A NAME="mcompile">Compiling With the menu Library</A></H2> - -Your menu-using modules must import the menu library declarations with - -<PRE> - #include <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>post_menu()</CODE>. -<LI>Refresh the screen. -<LI>Process user requests via an input loop. -<LI>Unpost the menu using <CODE>unpost_menu()</CODE>. -<LI>Free the menu, using <CODE>free_menu()</CODE>. -<LI>Free the items using <CODE>free_item()</CODE>. -<LI>Terminate <CODE>curses</CODE>. -</OL> - -<H2><A NAME="mselect">Selecting items</A></H2> - -Menus may be multi-valued or (the default) single-valued (see the manual -page <CODE>menu_opts(3x)</CODE> to see how to change the default). -Both types always have a <DFN>current item</DFN>. <P> - -From a single-valued menu you can read the selected value simply by looking -at the current item. From a multi-valued menu, you get the selected set -by looping through the items applying the <CODE>item_value()</CODE> -predicate function. Your menu-processing code can use the function -<CODE>set_item_value()</CODE> to flag the items in the select set. <P> - -Menu items can be made unselectable using <CODE>set_item_opts()</CODE> -or <CODE>item_opts_off()</CODE> with the <CODE>O_SELECTABLE</CODE> -argument. This is the only option so far defined for menus, but it -is good practice to code as though other option bits might be on. - -<H2><A NAME="mdisplay">Menu Display</A></H2> - -The menu library calculates a minimum display size for your window, based -on the following variables: - -<UL> -<LI>The number and maximum length of the menu items -<LI>Whether the O_ROWMAJOR option is enabled -<LI>Whether display of descriptions is enabled -<LI>Whatever menu format may have been set by the programmer -<LI>The length of the menu mark string used for highlighting selected items -</UL> - -The function <CODE>set_menu_format()</CODE> allows you to set the -maximum size of the viewport or <DFN>menu page</DFN> that will be used -to display menu items. You can retrieve any format associated with a -menu with <CODE>menu_format()</CODE>. The default format is rows=16, -columns=1. <P> - -The actual menu page may be smaller than the format size. This depends -on the item number and size and whether O_ROWMAJOR is on. This option -(on by default) causes menu items to be displayed in a `raster-scan' -pattern, so that if more than one item will fit horizontally the first -couple of items are side-by-side in the top row. The alternative is -column-major display, which tries to put the first several items in -the first column. <P> - -As mentioned above, a menu format not large enough to allow all items to fit -on-screen will result in a menu display that is vertically scrollable. <P> -You can scroll it with requests to the menu driver, which will be described -in the section on <A HREF="#minput">menu input handling</A>. <P> - -Each menu has a <DFN>mark string</DFN> used to visually tag selected items; -see the <CODE>menu_mark(3x)</CODE> manual page for details. The mark -string length also influences the menu page size. <P> - -The function <CODE>scale_menu()</CODE> returns the minimum display size -that the menu code computes from all these factors. - -There are other menu display attributes including a select attribute, -an attribute for selectable items, an attribute for unselectable items, -and a pad character used to separate item name text from description -text. These have reasonable defaults which the library allows you to -change (see the <CODE>menu_attribs(3x)</CODE> manual page. - -<H2><A NAME="mwindows">Menu Windows</A></H2> - -Each menu has, as mentioned previously, a pair of associated windows. -Both these windows are painted when the menu is posted and erased when -the menu is unposted. <P> - -The outer or frame window is not otherwise touched by the menu -routines. It exists so the programmer can associate a title, a -border, or perhaps help text with the menu and have it properly -refreshed or erased at post/unpost time. The inner window or -<DFN>subwindow</DFN> is where the current menu page is displayed. <P> - -By default, both windows are <CODE>stdscr</CODE>. You can set them with the -functions in <CODE>menu_win(3x)</CODE>. <P> - -When you call <CODE>post_menu()</CODE>, you write the menu to its -subwindow. When you call <CODE>unpost_menu()</CODE>, you erase the -subwindow, However, neither of these actually modifies the screen. To -do that, call <CODE>wrefresh()</CODE> or some equivalent. - -<H2><A NAME="minput">Processing Menu Input</A></H2> - -The main loop of your menu-processing code should call -<CODE>menu_driver()</CODE> repeatedly. The first argument of this routine -is a menu pointer; the second is a menu command code. You should write an -input-fetching routine that maps input characters to menu command codes, and -pass its output to <CODE>menu_driver()</CODE>. The menu command codes are -fully documented in <CODE>menu_driver(3x)</CODE>. <P> - -The simplest group of command codes is <CODE>REQ_NEXT_ITEM</CODE>, -<CODE>REQ_PREV_ITEM</CODE>, <CODE>REQ_FIRST_ITEM</CODE>, -<CODE>REQ_LAST_ITEM</CODE>, <CODE>REQ_UP_ITEM</CODE>, -<CODE>REQ_DOWN_ITEM</CODE>, <CODE>REQ_LEFT_ITEM</CODE>, -<CODE>REQ_RIGHT_ITEM</CODE>. These change the currently selected -item. These requests may cause scrolling of the menu page if it only -partially displayed. <P> - -There are explicit requests for scrolling which also change the -current item (because the select location does not change, but the -item there does). These are <CODE>REQ_SCR_DLINE</CODE>, -<CODE>REQ_SCR_ULINE</CODE>, <CODE>REQ_SCR_DPAGE</CODE>, and -<CODE>REQ_SCR_UPAGE</CODE>. <P> - -The <CODE>REQ_TOGGLE_ITEM</CODE> selects or deselects the current item. -It is for use in multi-valued menus; if you use it with <CODE>O_ONEVALUE</CODE> -on, you'll get an error return (<CODE>E_REQUEST_DENIED</CODE>). <P> - -Each menu has an associated pattern buffer. The -<CODE>menu_driver()</CODE> logic tries to accumulate printable ASCII -characters passed in in that buffer; when it matches a prefix of an -item name, that item (or the next matching item) is selected. If -appending a character yields no new match, that character is deleted -from the pattern buffer, and <CODE>menu_driver()</CODE> returns -<CODE>E_NO_MATCH</CODE>. <P> - -Some requests change the pattern buffer directly: -<CODE>REQ_CLEAR_PATTERN</CODE>, <CODE>REQ_BACK_PATTERN</CODE>, -<CODE>REQ_NEXT_MATCH</CODE>, <CODE>REQ_PREV_MATCH</CODE>. The latter -two are useful when pattern buffer input matches more than one item -in a multi-valued menu. <P> - -Each successful scroll or item navigation request clears the pattern -buffer. It is also possible to set the pattern buffer explicitly -with <CODE>set_menu_pattern()</CODE>. <P> - -Finally, menu driver requests above the constant <CODE>MAX_COMMAND</CODE> -are considered application-specific commands. The <CODE>menu_driver()</CODE> -code ignores them and returns <CODE>E_UNKNOWN_COMMAND</CODE>. - -<H2><A NAME="mmisc">Miscellaneous Other Features</A></H2> - -Various menu options can affect the processing and visual appearance -and input processing of menus. See <CODE>menu_opts(3x) for -details.</CODE> <P> - -It is possible to change the current item from application code; this -is useful if you want to write your own navigation requests. It is -also possible to explicitly set the top row of the menu display. See -<CODE>mitem_current(3x)</CODE>. - -If your application needs to change the menu subwindow cursor for -any reason, <CODE>pos_menu_cursor()</CODE> will restore it to the -correct location for continuing menu driver processing. <P> - -It is possible to set hooks to be called at menu initialization and -wrapup time, and whenever the selected item changes. See -<CODE>menu_hook(3x)</CODE>. <P> - -Each item, and each menu, has an associated user pointer on which you -can hang application data. See <CODE>mitem_userptr(3x)</CODE> and -<CODE>menu_userptr(3x)</CODE>. - -<H1><A NAME="form">The Forms Library</A></H1> - -The <CODE>form</CODE> library is a curses extension that supports easy -programming of on-screen forms for data entry and program control. <P> - -The <CODE>form</CODE> library first appeared in AT&T System V. The -version documented here is the <CODE>form</CODE> code distributed -with <CODE>ncurses</CODE>. - -<H2><A NAME="fcompile">Compiling With the form Library</A></H2> - -Your form-using modules must import the form library declarations with - -<PRE> - #include <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. - -<H2><A NAME="foverview">Overview of Forms</A></H2> - -A form is a collection of fields; each field may be either a label -(explanatory text) or a data-entry location. Long forms may be -segmented into pages; each entry to a new page clears the screen. <P> -To make forms, you create groups of fields and connect them with form -frame objects; the form library makes this relatively simple. <P> - -Once defined, a form can be <DFN>posted</DFN>, that is written to an -associated window. Actually, each form has two associated windows; a -containing window in which the programmer can scribble titles or -borders, and a subwindow in which the form fields proper are displayed. <P> - -As the form user fills out the posted form, navigation and editing -keys support movement between fields, editing keys support modifying -field, and plain text adds to or changes data in a current field. The -form library allows you (the forms designer) to bind each navigation -and editing key to any keystroke accepted by <CODE>curses</CODE> - -Fields may have validation conditions on them, so that they check input -data for type and value. The form library supplies a rich set of -pre-defined field types, and makes it relatively easy to define new ones. <P> - -Once its transaction is completed (or aborted), a form may be -<DFN>unposted</DFN> (that is, undisplayed), and finally freed to make -the storage associated with it and its items available for re-use. <P> - -The general flow of control of a form program looks like this: - -<OL> -<LI>Initialize <CODE>curses</CODE>. -<LI>Create the form fields, using <CODE>new_field()</CODE>. -<LI>Create the form using <CODE>new_form()</CODE>. -<LI>Post the form using <CODE>post_form()</CODE>. -<LI>Refresh the screen. -<LI>Process user requests via an input loop. -<LI>Unpost the form using <CODE>unpost_form()</CODE>. -<LI>Free the form, using <CODE>free_form()</CODE>. -<LI>Free the fields using <CODE>free_field()</CODE>. -<LI>Terminate <CODE>curses</CODE>. -</OL> - -Note that this looks much like a menu program; the form library handles -tasks which are in many ways similar, and its interface was obviously -designed to resemble that of the <A HREF="#menu">menu library</A> -wherever possible. <P> - -In forms programs, however, the `process user requests' is somewhat more -complicated than for menus. Besides menu-like navigation operations, -the menu driver loop has to support field editing and data validation. - -<H2><A NAME="fcreate">Creating and Freeing Fields and Forms</A></H2> - -The basic function for creating fields is <CODE>new_field()</CODE>: - -<PRE> -FIELD *new_field(int height, int width, /* new field size */ - int top, int left, /* upper left corner */ - int offscreen, /* number of offscreen rows */ - int nbuf); /* number of working buffers */ -</PRE> - -Menu items always occupy a single row, but forms fields may have -multiple rows. So <CODE>new_field()</CODE> requires you to specify a -width and height (the first two arguments, which mist both be greater -than zero). <P> - -You must also specify the location of the field's upper left corner on -the screen (the third and fourth arguments, which must be zero or -greater). Note that these coordinates are relative to the form -subwindow, which will coincide with <CODE>stdscr</CODE> by default but -need not be <CODE>stdscr</CODE> if you've done an explicit -<CODE>set_form_win()</CODE> call. <P> - -The fifth argument allows you to specify a number of off-screen rows. If -this is zero, the entire field will always be displayed. If it is -nonzero, the form will be scrollable, with only one screen-full (initially -the top part) displayed at any given time. If you make a field dynamic -and grow it so it will no longer fit on the screen, the form will become -scrollable even if the <CODE>offscreen</CODE> argument was initially zero. <P> - -The forms library allocates one working buffer per field; the size of -each buffer is <CODE>((height + offscreen)*width + 1</CODE>, one character -for each position in the field plus a NUL terminator. The sixth -argument is the number of additional data buffers to allocate for the -field; your application can use them for its own purposes. - -<PRE> -FIELD *dup_field(FIELD *field, /* field to copy */ - int top, int left); /* location of new copy */ -</PRE> - -The function <CODE>dup_field()</CODE> duplicates an existing field at a -new location. Size and buffering information are copied; some -attribute flags and status bits are not (see the -<CODE>form_field_new(3X)</CODE> for details). - -<PRE> -FIELD *link_field(FIELD *field, /* field to copy */ - int top, int left); /* location of new copy */ -</PRE> - -The function <CODE>link_field()</CODE> also duplicates an existing field -at a new location. The difference from <CODE>dup_field()</CODE> is that -it arranges for the new field's buffer to be shared with the old one. <P> - -Besides the obvious use in making a field editable from two different -form pages, linked fields give you a way to hack in dynamic labels. If -you declare several fields linked to an original, and then make them -inactive, changes from the original will still be propagated to the -linked fields. <P> - -As with duplicated fields, linked fields have attribute bits separate -from the original. <P> - -As you might guess, all these field-allocations return <CODE>NULL</CODE> if -the field allocation is not possible due to an out-of-memory error or -out-of-bounds arguments. <P> - -To connect fields to a form, use - -<PRE> -FORM *new_form(FIELD **fields); -</PRE> - -This function expects to see a NULL-terminated array of field pointers. -Said fields are connected to a newly-allocated form object; its address -is returned (or else NULL if the allocation fails). <P> - -Note that <CODE>new_field()</CODE> does <EM>not</EM> copy the pointer array -into private storage; if you modify the contents of the pointer array -during forms processing, all manner of bizarre things might happen. Also -note that any given field may only be connected to one form. <P> - -The functions <CODE>free_field()</CODE> and <CODE>free_form</CODE> are available -to free field and form objects. It is an error to attempt to free a field -connected to a form, but not vice-versa; thus, you will generally free -your form objects first. - -<H2><A NAME="fattributes">Fetching and Changing Field Attributes</A></H2> - -Each form field has a number of location and size attributes -associated with it. There are other field attributes used to control -display and editing of the field. Some (for example, the <CODE>O_STATIC</CODE> bit) -involve sufficient complications to be covered in sections of their own -later on. We cover the functions used to get and set several basic -attributes here. <P> - -When a field is created, the attributes not specified by the -<CODE>new_field</CODE> function are copied from an invisible system -default field. In attribute-setting and -fetching functions, the -argument NULL is taken to mean this field. Changes to it persist -as defaults until your forms application terminates. - -<H3><A NAME="fsizes">Fetching Size and Location Data</A></H3> - -You can retrieve field sizes and locations through: - -<PRE> -int field_info(FIELD *field, /* field from which to fetch */ - int *height, *int width, /* field size */ - int *top, int *left, /* upper left corner */ - int *offscreen, /* number of offscreen rows */ - int *nbuf); /* number of working buffers */ -</PRE> - -This function is a sort of inverse of <CODE>new_field()</CODE>; instead of -setting size and location attributes of a new field, it fetches them -from an existing one. - -<H3><A NAME="flocation">Changing the Field Location</A></H3> - -It is possible to move a field's location on the screen: - -<PRE> -int move_field(FIELD *field, /* field to alter */ - int top, int left); /* new upper-left corner */ -</PRE> - -You can, of course. query the current location through <CODE>field_info()</CODE>. - -<H3><A NAME="fjust">The Justification Attribute</A></H3> - -One-line fields may be unjustified, justified right, justified left, -or centered. Here is how you manipulate this attribute: - -<PRE> -int set_field_just(FIELD *field, /* field to alter */ - int justmode); /* mode to set */ - -int field_just(FIELD *field); /* fetch mode of field */ -</PRE> - -The mode values accepted and returned by this functions are -preprocessor macros <CODE>NO_JUSTIFICATION</CODE>, <CODE>JUSTIFY_RIGHT</CODE>, -<CODE>JUSTIFY_LEFT</CODE>, or <CODE>JUSTIFY_CENTER</CODE>. - -<H3><A NAME="fdispatts">Field Display Attributes</A></H3> - -For each field, you can set a foreground attribute for entered -characters, a background attribute for the entire field, and a pad -character for the unfilled portion of the field. You can also -control pagination of the form. <P> - -This group of four field attributes controls the visual appearance -of the field on the screen, without affecting in any way the data -in the field buffer. - -<PRE> -int set_field_fore(FIELD *field, /* field to alter */ - chtype attr); /* attribute to set */ - -chtype field_fore(FIELD *field); /* field to query */ - -int set_field_back(FIELD *field, /* field to alter */ - chtype attr); /* attribute to set */ - -chtype field_back(FIELD *field); /* field to query */ - -int set_field_pad(FIELD *field, /* field to alter */ - int pad); /* pad character to set */ - -chtype field_pad(FIELD *field); - -int set_new_page(FIELD *field, /* field to alter */ - int flag); /* TRUE to force new page */ - -chtype new_page(FIELD *field); /* field to query */ -</PRE> - -The attributes set and returned by the first four functions are normal -<CODE>curses(3x)</CODE> display attribute values (<CODE>A_STANDOUT</CODE>, -<CODE>A_BOLD</CODE>, <CODE>A_REVERSE</CODE> etc). - -The page bit of a field controls whether it is displayed at the start of -a new form screen. - -<H3><A NAME="foptions">Field Option Bits</A></H3> - -There is also a large collection of field option bits you can set to control -various aspects of forms processing. You can manipulate them with these -functions: - -<PRE> -int set_field_opts(FIELD *field, /* field to alter */ - int attr); /* attribute to set */ - -int field_opts_on(FIELD *field, /* field to alter */ - int attr); /* attributes to turn on */ - -int field_opts_off(FIELD *field, /* field to alter */ - int attr); /* attributes to turn off */ - -int field_opts(FIELD *field); /* field to query */ -</PRE> - -By default, all options are on. Here are the available option bits: -<DL> -<DT> O_VISIBLE -<DD> Controls whether the field is visible on the screen. Can be used -during form processing to hide or pop up fields depending on the value -of parent fields. -<DT> O_ACTIVE -<DD> Controls whether the field is active during forms processing (i.e. -visited by form navigation keys). Can be used to make labels or derived -fields with buffer values alterable by the forms application, not the user. -<DT> O_PUBLIC -<DD> Controls whether data is displayed during field entry. If this option is -turned off on a field, the library will accept and edit data in that field, -but it will not be displayed and the visible field cursor will not move. -You can turn off the O_PUBLIC bit to define password fields. -<DT> O_EDIT -<DD> Controls whether the field's data can be modified. When this option is -off, all editing requests except <CODE>REQ_PREV_CHOICE</CODE> and -<CODE>REQ_NEXT_CHOICE</CODE> will fail. Such read-only fields may be useful for -help messages. -<DT> O_WRAP -<DD> Controls word-wrapping in multi-line fields. Normally, when any -character of a (blank-separated) word reaches the end of the current line, the -entire word is wrapped to the next line (assuming there is one). When this -option is off, the word will be split across the line break. -<DT> O_BLANK -<DD> Controls field blanking. When this option is on, entering a character at -the first field position erases the entire field (except for the just-entered -character). -<DT> O_AUTOSKIP -<DD> Controls automatic skip to next field when this one fills. Normally, -when the forms user tries to type more data into a field than will fit, -the editing location jumps to next field. When this option is off, the -user's cursor will hang at the end of the field. This option is ignored -in dynamic fields that have not reached their size limit. -<DT> O_NULLOK -<DD> Controls whether <A HREF="#fvalidation">validation</A> is applied to -blank fields. Normally, it is not; the user can leave a field blank -without invoking the usual validation check on exit. If this option is -off on a field, exit from it will invoke a validation check. -<DT> O_PASSOK -<DD> Controls whether validation occurs on every exit, or only after -the field is modified. Normally the latter is true. Setting O_PASSOK -may be useful if your field's validation function may change during -forms processing. -<DT> O_STATIC -<DD> Controls whether the field is fixed to its initial dimensions. If you -turn this off, the field becomes <A HREF="#fdynamic">dynamic</A> and will -stretch to fit entered data. -</DL> - -A field's options cannot be changed while the field is currently selected. -However, options may be changed on posted fields that are not current. <P> - -The option values are bit-masks and can be composed with logical-or in -the obvious way. - -<H2><A NAME="fstatus">Field Status</A></H2> - -Every field has a status flag, which is set to FALSE when the field is -created and TRUE when the value in field buffer 0 changes. This flag can -be queried and set directly: - -<PRE> -int set_field_status(FIELD *field, /* field to alter */ - int status); /* mode to set */ - -int field_status(FIELD *field); /* fetch mode of field */ -</PRE> - -Setting this flag under program control can be useful if you use the same -form repeatedly, looking for modified fields each time. <P> - -Calling <CODE>field_status()</CODE> on a field not currently selected -for input will return a correct value. Calling <CODE>field_status()</CODE> on a -field that is currently selected for input may not necessarily give a -correct field status value, because entered data isn't necessarily copied to -buffer zero before the exit validation check. - -To guarantee that the returned status value reflects reality, call -<CODE>field_status()</CODE> either (1) in the field's exit validation check -routine, (2) from the field's or form's initialization or termination -hooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been -processed by the forms driver. - -<H2><A NAME="fuser">Field User Pointer</A></H2> - -Each field structure contains one character pointer slot that is not used -by the forms library. It is intended to be used by applications to store -private per-field data. You can manipulate it with: - -<PRE> -int set_field_userptr(FIELD *field, /* field to alter */ - char *userptr); /* mode to set */ - -char *field_userptr(FIELD *field); /* fetch mode of field */ -</PRE> - -(Properly, this user pointer field ought to have <CODE>(void *)</CODE> type. -The <CODE>(char *)</CODE> type is retained for System V compatibility.) <P> - -It is valid to set the user pointer of the default field (with a -<CODE>set_field_userptr()</CODE> call passed a NULL field pointer.) -When a new field is created, the default-field user pointer is copied -to initialize the new field's user pointer. - -<H2><A NAME="fdynamic">Variable-Sized Fields</A></H2> - -Normally, a field is fixed at the size specified for it at creation -time. If, however, you turn off its O_STATIC bit, it becomes -<DFN>dynamic</DFN> and will automatically resize itself to accommodate -data as it is entered. If the field has extra buffers associated with it, -they will grow right along with the main input buffer. <P> - -A one-line dynamic field will have a fixed height (1) but variable -width, scrolling horizontally to display data within the field area as -originally dimensioned and located. A multi-line dynamic field will -have a fixed width, but variable height (number of rows), scrolling -vertically to display data within the field area as originally -dimensioned and located. <P> - -Normally, a dynamic field is allowed to grow without limit. But it is -possible to set an upper limit on the size of a dynamic field. You do -it with this function: - -<PRE> -int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ - int max_size); /* upper limit on field size */ -</PRE> - -If the field is one-line, <CODE>max_size</CODE> is taken to be a column size -limit; if it is multi-line, it is taken to be a line size limit. To disable -any limit, use an argument of zero. The growth limit can be changed whether -or not the O_STATIC bit is on, but has no effect until it is. <P> - -The following properties of a field change when it becomes dynamic: - -<UL> -<LI>If there is no growth limit, there is no final position of the field; -therefore <CODE>O_AUTOSKIP</CODE> and <CODE>O_NL_OVERLOAD</CODE> are ignored. -<LI>Field justification will be ignored (though whatever justification is -set up will be retained internally and can be queried). -<LI>The <CODE>dup_field()</CODE> and <CODE>link_field()</CODE> calls copy -dynamic-buffer sizes. If the <CODE>O_STATIC</CODE> option is set on one of a -collection of links, buffer resizing will occur only when the field is -edited through that link. -<LI>The call <CODE>field_info()</CODE> will retrieve the original static size of -the field; use <CODE>dynamic_field_info()</CODE> to get the actual dynamic size. -</UL> - -<H2><A NAME="fvalidation">Field Validation</A></H2> - -By default, a field will accept any data that will fit in its input buffer. -However, it is possible to attach a validation type to a field. If you do -this, any attempt to leave the field while it contains data that doesn't -match the validation type will fail. Some validation types also have a -character-validity check for each time a character is entered in the field. <P> - -A field's validation check (if any) is not called when -<CODE>set_field_buffer()</CODE> modifies the input buffer, nor when that buffer -is changed through a linked field. <P> - -The <CODE>form</CODE> library provides a rich set of pre-defined validation -types, and gives you the capability to define custom ones of your own. You -can examine and change field validation attributes with the following -functions: - -<PRE> -int set_field_type(FIELD *field, /* field to alter */ - FIELDTYPE *ftype, /* type to associate */ - ...); /* additional arguments*/ - -FIELDTYPE *field_type(FIELD *field); /* field to query */ -</PRE> - -The validation type of a field is considered an attribute of the field. As -with other field attributes, Also, doing <CODE>set_field_type()</CODE> with a -<CODE>NULL</CODE> field default will change the system default for validation of -newly-created fields. <P> - -Here are the pre-defined validation types: - -<H3><A NAME="ftype_alpha">TYPE_ALPHA</A></H3> - -This field type accepts alphabetic data; no blanks, no digits, no special -characters (this is checked at character-entry time). It is set up with: - -<PRE> -int set_field_type(FIELD *field, /* field to alter */ - TYPE_ALPHA, /* type to associate */ - int width); /* maximum width of field */ -</PRE> - -The <CODE>width</CODE> argument sets a minimum width of data. Typically -you'll want to set this to the field width; if it's greater than the -field width, the validation check will always fail. A minimum width -of zero makes field completion optional. - -<H3><A NAME="ftype_alnum">TYPE_ALNUM</A></H3> - -This field type accepts alphabetic data and digits; no blanks, no special -characters (this is checked at character-entry time). It is set up with: - -<PRE> -int set_field_type(FIELD *field, /* field to alter */ - TYPE_ALNUM, /* type to associate */ - int width); /* maximum width of field */ -</PRE> - -The <CODE>width</CODE> argument sets a minimum width of data. As with -TYPE_ALPHA, typically you'll want to set this to the field width; if it's -greater than the field width, the validation check will always fail. A -minimum width of zero makes field completion optional. - -<H3><A NAME="ftype_enum">TYPE_ENUM</A></H3> - -This type allows you to restrict a field's values to be among a specified -set of string values (for example, the two-letter postal codes for U.S. -states). It is set up with: - -<PRE> -int set_field_type(FIELD *field, /* field to alter */ - TYPE_ENUM, /* type to associate */ - char **valuelist; /* list of possible values */ - int checkcase; /* case-sensitive? */ - int checkunique); /* must specify uniquely? */ -</PRE> - -The <CODE>valuelist</CODE> parameter must point at a NULL-terminated list of -valid strings. The <CODE>checkcase</CODE> argument, if true, makes comparison -with the string case-sensitive. <P> - -When the user exits a TYPE_ENUM field, the validation procedure tries to -complete the data in the buffer to a valid entry. If a complete choice string -has been entered, it is of course valid. But it is also possible to enter a -prefix of a valid string and have it completed for you. <P> - -By default, if you enter such a prefix and it matches more than one value -in the string list, the prefix will be completed to the first matching -value. But the <CODE>checkunique</CODE> argument, if true, requires prefix -matches to be unique in order to be valid. <P> - -The <CODE>REQ_NEXT_CHOICE</CODE> and <CODE>REQ_PREV_CHOICE</CODE> input requests -can be particularly useful with these fields. - -<H3><A NAME="ftype_integer">TYPE_INTEGER</A></H3> - -This field type accepts an integer. It is set up as follows: - -<PRE> -int set_field_type(FIELD *field, /* field to alter */ - TYPE_INTEGER, /* type to associate */ - int padding, /* # places to zero-pad to */ - int vmin, int vmax); /* valid range */ -</PRE> - -Valid characters consist of an optional leading minus and digits. -The range check is performed on exit. If the range maximum is less -than or equal to the minimum, the range is ignored. <P> - -If the value passes its range check, it is padded with as many leading -zero digits as necessary to meet the padding argument. <P> - -A <CODE>TYPE_INTEGER</CODE> value buffer can conveniently be interpreted -with the C library function <CODE>atoi(3)</CODE>. - -<H3><A NAME="ftype_numeric">TYPE_NUMERIC</A></H3> - -This field type accepts a decimal number. It is set up as follows: - -<PRE> -int set_field_type(FIELD *field, /* field to alter */ - TYPE_NUMERIC, /* type to associate */ - int padding, /* # places of precision */ - double vmin, double vmax); /* valid range */ -</PRE> - -Valid characters consist of an optional leading minus and digits. possibly -including a decimal point. If your system supports locale's, the decimal point -character used must be the one defined by your locale. The range check is -performed on exit. If the range maximum is less than or equal to the minimum, -the range is ignored. <P> - -If the value passes its range check, it is padded with as many trailing -zero digits as necessary to meet the padding argument. <P> - -A <CODE>TYPE_NUMERIC</CODE> value buffer can conveniently be interpreted -with the C library function <CODE>atof(3)</CODE>. - -<H3><A NAME="ftype_regexp">TYPE_REGEXP</A></H3> - -This field type accepts data matching a regular expression. It is set up -as follows: - -<PRE> -int set_field_type(FIELD *field, /* field to alter */ - TYPE_REGEXP, /* type to associate */ - char *regexp); /* expression to match */ -</PRE> - -The syntax for regular expressions is that of <CODE>regcomp(3)</CODE>. -The check for regular-expression match is performed on exit. - -<H2><A NAME="fbuffer">Direct Field Buffer Manipulation</A></H2> - -The chief attribute of a field is its buffer contents. When a form has -been completed, your application usually needs to know the state of each -field buffer. You can find this out with: - -<PRE> -char *field_buffer(FIELD *field, /* field to query */ - int bufindex); /* number of buffer to query */ -</PRE> - -Normally, the state of the zero-numbered buffer for each field is set by -the user's editing actions on that field. It's sometimes useful to be able -to set the value of the zero-numbered (or some other) buffer from your -application: - -<PRE> -int set_field_buffer(FIELD *field, /* field to alter */ - int bufindex, /* number of buffer to alter */ - char *value); /* string value to set */ -</PRE> - -If the field is not large enough and cannot be resized to a sufficiently -large size to contain the specified value, the value will be truncated -to fit. <P> - -Calling <CODE>field_buffer()</CODE> with a null field pointer will raise an -error. Calling <CODE>field_buffer()</CODE> on a field not currently selected -for input will return a correct value. Calling <CODE>field_buffer()</CODE> on a -field that is currently selected for input may not necessarily give a -correct field buffer value, because entered data isn't necessarily copied to -buffer zero before the exit validation check. - -To guarantee that the returned buffer value reflects on-screen reality, -call <CODE>field_buffer()</CODE> either (1) in the field's exit validation -check routine, (2) from the field's or form's initialization or termination -hooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been processed -by the forms driver. - -<H2><A NAME="formattrs">Attributes of Forms</A></H2> - -As with field attributes, form attributes inherit a default from a -system default form structure. These defaults can be queried or set by -of these functions using a form-pointer argument of <CODE>NULL</CODE>. <P> - -The principal attribute of a form is its field list. You can query -and change this list with: - -<PRE> -int set_form_fields(FORM *form, /* form to alter */ - FIELD **fields); /* fields to connect */ - -char *form_fields(FORM *form); /* fetch fields of form */ - -int field_count(FORM *form); /* count connect fields */ -</PRE> - -The second argument of <CODE>set_form_fields()</CODE> may be a -NULL-terminated field pointer array like the one required by -<CODE>new_form()</CODE>. In that case, the old fields of the form are -disconnected but not freed (and eligible to be connected to other -forms), then the new fields are connected. <P> - -It may also be null, in which case the old fields are disconnected -(and not freed) but no new ones are connected. <P> - -The <CODE>field_count()</CODE> function simply counts the number of fields -connected to a given from. It returns -1 if the form-pointer argument -is NULL. - -<H2><A NAME="fdisplay">Control of Form Display</A></H2> - -In the overview section, you saw that to display a form you normally -start by defining its size (and fields), posting it, and refreshing -the screen. There is an hidden step before posting, which is the -association of the form with a frame window (actually, a pair of -windows) within which it will be displayed. By default, the forms -library associates every form with the full-screen window -<CODE>stdscr</CODE>. <P> - -By making this step explicit, you can associate a form with a declared -frame window on your screen display. This can be useful if you want to -adapt the form display to different screen sizes, dynamically tile -forms on the screen, or use a form as part of an interface layout -managed by <A HREF="#panels">panels</A>. <P> - -The two windows associated with each form have the same functions as -their analogues in the <A HREF="#menu">menu library</A>. Both these -windows are painted when the form is posted and erased when the form -is unposted. <P> - -The outer or frame window is not otherwise touched by the form -routines. It exists so the programmer can associate a title, a -border, or perhaps help text with the form and have it properly -refreshed or erased at post/unpost time. The inner window or subwindow -is where the current form page is actually displayed. <P> - -In order to declare your own frame window for a form, you'll need to -know the size of the form's bounding rectangle. You can get this -information with: - -<PRE> -int scale_form(FORM *form, /* form to query */ - int *rows, /* form rows */ - int *cols); /* form cols */ -</PRE> - -The form dimensions are passed back in the locations pointed to by -the arguments. Once you have this information, you can use it to -declare of windows, then use one of these functions: - -<PRE> -int set_form_win(FORM *form, /* form to alter */ - WINDOW *win); /* frame window to connect */ - -WINDOW *form_win(FORM *form); /* fetch frame window of form */ - -int set_form_sub(FORM *form, /* form to alter */ - WINDOW *win); /* form subwindow to connect */ - -WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ -</PRE> - -Note that curses operations, including <CODE>refresh()</CODE>, on the form, -should be done on the frame window, not the form subwindow. <P> - -It is possible to check from your application whether all of a -scrollable field is actually displayed within the menu subwindow. Use -these functions: - -<PRE> -int data_ahead(FORM *form); /* form to be queried */ - -int data_behind(FORM *form); /* form to be queried */ -</PRE> - -The function <CODE>data_ahead()</CODE> returns TRUE if (a) the current -field is one-line and has undisplayed data off to the right, (b) the current -field is multi-line and there is data off-screen below it. <P> - -The function <CODE>data_behind()</CODE> returns TRUE if the first (upper -left hand) character position is off-screen (not being displayed). <P> - -Finally, there is a function to restore the form window's cursor to the -value expected by the forms driver: - -<PRE> -int pos_form_cursor(FORM *) /* form to be queried */ -</PRE> - -If your application changes the form window cursor, call this function before -handing control back to the forms driver in order to re-synchronize it. - -<H2><A NAME="fdriver">Input Processing in the Forms Driver</A></H2> - -The function <CODE>form_driver()</CODE> handles virtualized input requests -for form navigation, editing, and validation requests, just as -<CODE>menu_driver</CODE> does for menus (see the section on <A -HREF="#minput">menu input handling</A>). - -<PRE> -int form_driver(FORM *form, /* form to pass input to */ - int request); /* form request code */ -</PRE> - -Your input virtualization function needs to take input and then convert it -to either an alphanumeric character (which is treated as data to be -entered in the currently-selected field), or a forms processing request. <P> - -The forms driver provides hooks (through input-validation and -field-termination functions) with which your application code can check -that the input taken by the driver matched what was expected. - -<H3><A NAME="fpage">Page Navigation Requests</A></H3> - -These requests cause page-level moves through the form, -triggering display of a new form screen. - -<DL> -<DT> <CODE>REQ_NEXT_PAGE</CODE> -<DD> Move to the next form page. -<DT> <CODE>REQ_PREV_PAGE</CODE> -<DD> Move to the previous form page. -<DT> <CODE>REQ_FIRST_PAGE</CODE> -<DD> Move to the first form page. -<DT> <CODE>REQ_LAST_PAGE</CODE> -<DD> Move to the last form page. -</DL> - -These requests treat the list as cyclic; that is, <CODE>REQ_NEXT_PAGE</CODE> -from the last page goes to the first, and <CODE>REQ_PREV_PAGE</CODE> from -the first page goes to the last. - -<H3><A NAME="ffield">Inter-Field Navigation Requests</A></H3> - -These requests handle navigation between fields on the same page. - -<DL> -<DT> <CODE>REQ_NEXT_FIELD</CODE> -<DD> Move to next field. -<DT> <CODE>REQ_PREV_FIELD</CODE> -<DD> Move to previous field. -<DT> <CODE>REQ_FIRST_FIELD</CODE> -<DD> Move to the first field. -<DT> <CODE>REQ_LAST_FIELD</CODE> -<DD> Move to the last field. -<DT> <CODE>REQ_SNEXT_FIELD</CODE> -<DD> Move to sorted next field. -<DT> <CODE>REQ_SPREV_FIELD</CODE> -<DD> Move to sorted previous field. -<DT> <CODE>REQ_SFIRST_FIELD</CODE> -<DD> Move to the sorted first field. -<DT> <CODE>REQ_SLAST_FIELD</CODE> -<DD> Move to the sorted last field. -<DT> <CODE>REQ_LEFT_FIELD</CODE> -<DD> Move left to field. -<DT> <CODE>REQ_RIGHT_FIELD</CODE> -<DD> Move right to field. -<DT> <CODE>REQ_UP_FIELD</CODE> -<DD> Move up to field. -<DT> <CODE>REQ_DOWN_FIELD</CODE> -<DD> Move down to field. -</DL> - -These requests treat the list of fields on a page as cyclic; that is, -<CODE>REQ_NEXT_FIELD</CODE> from the last field goes to the first, and -<CODE>REQ_PREV_FIELD</CODE> from the first field goes to the last. The -order of the fields for these (and the <CODE>REQ_FIRST_FIELD</CODE> and -<CODE>REQ_LAST_FIELD</CODE> requests) is simply the order of the field -pointers in the form array (as set up by <CODE>new_form()</CODE> or -<CODE>set_form_fields()</CODE> <P> - -It is also possible to traverse the fields as if they had been sorted in -screen-position order, so the sequence goes left-to-right and top-to-bottom. -To do this, use the second group of four sorted-movement requests. <P> - -Finally, it is possible to move between fields using visual directions up, -down, right, and left. To accomplish this, use the third group of four -requests. Note, however, that the position of a form for purposes of these -requests is its upper-left corner. <P> - -For example, suppose you have a multi-line field B, and two -single-line fields A and C on the same line with B, with A to the left -of B and C to the right of B. A <CODE>REQ_MOVE_RIGHT</CODE> from A will -go to B only if A, B, and C <EM>all</EM> share the same first line; -otherwise it will skip over B to C. - -<H3><A NAME="fifield">Intra-Field Navigation Requests</A></H3> - -These requests drive movement of the edit cursor within the currently -selected field. - -<DL> -<DT> <CODE>REQ_NEXT_CHAR</CODE> -<DD> Move to next character. -<DT> <CODE>REQ_PREV_CHAR</CODE> -<DD> Move to previous character. -<DT> <CODE>REQ_NEXT_LINE</CODE> -<DD> Move to next line. -<DT> <CODE>REQ_PREV_LINE</CODE> -<DD> Move to previous line. -<DT> <CODE>REQ_NEXT_WORD</CODE> -<DD> Move to next word. -<DT> <CODE>REQ_PREV_WORD</CODE> -<DD> Move to previous word. -<DT> <CODE>REQ_BEG_FIELD</CODE> -<DD> Move to beginning of field. -<DT> <CODE>REQ_END_FIELD</CODE> -<DD> Move to end of field. -<DT> <CODE>REQ_BEG_LINE</CODE> -<DD> Move to beginning of line. -<DT> <CODE>REQ_END_LINE</CODE> -<DD> Move to end of line. -<DT> <CODE>REQ_LEFT_CHAR</CODE> -<DD> Move left in field. -<DT> <CODE>REQ_RIGHT_CHAR</CODE> -<DD> Move right in field. -<DT> <CODE>REQ_UP_CHAR</CODE> -<DD> Move up in field. -<DT> <CODE>REQ_DOWN_CHAR</CODE> -<DD> Move down in field. -</DL> - -Each <EM>word</EM> is separated from the previous and next characters -by whitespace. The commands to move to beginning and end of line or field -look for the first or last non-pad character in their ranges. - -<H3><A NAME="fscroll">Scrolling Requests</A></H3> - -Fields that are dynamic and have grown and fields explicitly created -with offscreen rows are scrollable. One-line fields scroll horizontally; -multi-line fields scroll vertically. Most scrolling is triggered by -editing and intra-field movement (the library scrolls the field to keep the -cursor visible). It is possible to explicitly request scrolling with the -following requests: - -<DL> -<DT> <CODE>REQ_SCR_FLINE</CODE> -<DD> Scroll vertically forward a line. -<DT> <CODE>REQ_SCR_BLINE</CODE> -<DD> Scroll vertically backward a line. -<DT> <CODE>REQ_SCR_FPAGE</CODE> -<DD> Scroll vertically forward a page. -<DT> <CODE>REQ_SCR_BPAGE</CODE> -<DD> Scroll vertically backward a page. -<DT> <CODE>REQ_SCR_FHPAGE</CODE> -<DD> Scroll vertically forward half a page. -<DT> <CODE>REQ_SCR_BHPAGE</CODE> -<DD> Scroll vertically backward half a page. -<DT> <CODE>REQ_SCR_FCHAR</CODE> -<DD> Scroll horizontally forward a character. -<DT> <CODE>REQ_SCR_BCHAR</CODE> -<DD> Scroll horizontally backward a character. -<DT> <CODE>REQ_SCR_HFLINE</CODE> -<DD> Scroll horizontally one field width forward. -<DT> <CODE>REQ_SCR_HBLINE</CODE> -<DD> Scroll horizontally one field width backward. -<DT> <CODE>REQ_SCR_HFHALF</CODE> -<DD> Scroll horizontally one half field width forward. -<DT> <CODE>REQ_SCR_HBHALF</CODE> -<DD> Scroll horizontally one half field width backward. -</DL> - -For scrolling purposes, a <EM>page</EM> of a field is the height -of its visible part. - -<H3><A NAME="fedit">Editing Requests</A></H3> - -When you pass the forms driver an ASCII character, it is treated as a -request to add the character to the field's data buffer. Whether this -is an insertion or a replacement depends on the field's edit mode -(insertion is the default. <P> - -The following requests support editing the field and changing the edit -mode: - -<DL> -<DT> <CODE>REQ_INS_MODE</CODE> -<DD> Set insertion mode. -<DT> <CODE>REQ_OVL_MODE</CODE> -<DD> Set overlay mode. -<DT> <CODE>REQ_NEW_LINE</CODE> -<DD> New line request (see below for explanation). -<DT> <CODE>REQ_INS_CHAR</CODE> -<DD> Insert space at character location. -<DT> <CODE>REQ_INS_LINE</CODE> -<DD> Insert blank line at character location. -<DT> <CODE>REQ_DEL_CHAR</CODE> -<DD> Delete character at cursor. -<DT> <CODE>REQ_DEL_PREV</CODE> -<DD> Delete previous word at cursor. -<DT> <CODE>REQ_DEL_LINE</CODE> -<DD> Delete line at cursor. -<DT> <CODE>REQ_DEL_WORD</CODE> -<DD> Delete word at cursor. -<DT> <CODE>REQ_CLR_EOL</CODE> -<DD> Clear to end of line. -<DT> <CODE>REQ_CLR_EOF</CODE> -<DD> Clear to end of field. -<DT> <CODE>REQ_CLEAR_FIELD</CODE> -<DD> Clear entire field. -</DL> - -The behavior of the <CODE>REQ_NEW_LINE</CODE> and <CODE>REQ_DEL_PREV</CODE> requests -is complicated and partly controlled by a pair of forms options. -The special cases are triggered when the cursor is at the beginning of -a field, or on the last line of the field. <P> - -First, we consider <CODE>REQ_NEW_LINE</CODE>: <P> - -The normal behavior of <CODE>REQ_NEW_LINE</CODE> in insert mode is to break the -current line at the position of the edit cursor, inserting the portion of -the current line after the cursor as a new line following the current -and moving the cursor to the beginning of that new line (you may think -of this as inserting a newline in the field buffer). <P> - -The normal behavior of <CODE>REQ_NEW_LINE</CODE> in overlay mode is to clear the -current line from the position of the edit cursor to end of line. -The cursor is then moved to the beginning of the next line. <P> - -However, <CODE>REQ_NEW_LINE</CODE> at the beginning of a field, or on the -last line of a field, instead does a <CODE>REQ_NEXT_FIELD</CODE>. -<CODE>O_NL_OVERLOAD</CODE> option is off, this special action is -disabled. <P> - -Now, let us consider <CODE>REQ_DEL_PREV</CODE>: <P> - -The normal behavior of <CODE>REQ_DEL_PREV</CODE> is to delete the previous -character. If insert mode is on, and the cursor is at the start of a -line, and the text on that line will fit on the previous one, it -instead appends the contents of the current line to the previous one -and deletes the current line (you may think of this as deleting a -newline from the field buffer). <P> - -However, <CODE>REQ_DEL_PREV</CODE> at the beginning of a field is instead -treated as a <CODE>REQ_PREV_FIELD</CODE>. <P> If the -<CODE>O_BS_OVERLOAD</CODE> option is off, this special action is -disabled and the forms driver just returns <CODE>E_REQUEST_DENIED</CODE>. <P> - -See <A HREF="#frmoptions">Form Options</A> for discussion of how to set -and clear the overload options. - -<H3><A NAME="forder">Order Requests</A></H3> - -If the type of your field is ordered, and has associated functions -for getting the next and previous values of the type from a given value, -there are requests that can fetch that value into the field buffer: - -<DL> -<DT> <CODE>REQ_NEXT_CHOICE</CODE> -<DD> Place the successor value of the current value in the buffer. -<DT> <CODE>REQ_PREV_CHOICE</CODE> -<DD> Place the predecessor value of the current value in the buffer. -</DL> - -Of the built-in field types, only <CODE>TYPE_ENUM</CODE> has built-in successor -and predecessor functions. When you define a field type of your own -(see <A HREF="#fcustom">Custom Validation Types</A>), you can associate -our own ordering functions. - -<H3><A NAME="fappcmds">Application Commands</A></H3> - -Form requests are represented as integers above the <CODE>curses</CODE> value -greater than <CODE>KEY_MAX</CODE> and less than or equal to the constant -<CODE>MAX_COMMAND</CODE>. If your input-virtualization routine returns a -value above <CODE>MAX_COMMAND</CODE>, the forms driver will ignore it. - -<H2><A NAME="fhooks">Field Change Hooks</A></H2> - -It is possible to set function hooks to be executed whenever the -current field or form changes. Here are the functions that support this: - -<PRE> -typedef void (*HOOK)(); /* pointer to function returning void */ - -int set_form_init(FORM *form, /* form to alter */ - HOOK hook); /* initialization hook */ - -HOOK form_init(FORM *form); /* form to query */ - -int set_form_term(FORM *form, /* form to alter */ - HOOK hook); /* termination hook */ - -HOOK form_term(FORM *form); /* form to query */ - -int set_field_init(FORM *form, /* form to alter */ - HOOK hook); /* initialization hook */ - -HOOK field_init(FORM *form); /* form to query */ - -int set_field_term(FORM *form, /* form to alter */ - HOOK hook); /* termination hook */ - -HOOK field_term(FORM *form); /* form to query */ -</PRE> - -These functions allow you to either set or query four different hooks. -In each of the set functions, the second argument should be the -address of a hook function. These functions differ only in the timing -of the hook call. - -<DL> -<DT> form_init -<DD> This hook is called when the form is posted; also, just after -each page change operation. -<DT> field_init -<DD> This hook is called when the form is posted; also, just after -each field change -<DT> field_term -<DD> This hook is called just after field validation; that is, just before -the field is altered. It is also called when the form is unposted. -<DT> form_term -<DD> This hook is called when the form is unposted; also, just before -each page change operation. -</DL> - -Calls to these hooks may be triggered -<OL> -<LI>When user editing requests are processed by the forms driver -<LI>When the current page is changed by <CODE>set_current_field()</CODE> call -<LI>When the current field is changed by a <CODE>set_form_page()</CODE> call -</OL> - -See <A NAME="ffocus">Field Change Commands</A> for discussion of the latter -two cases. <P> - -You can set a default hook for all fields by passing one of the set functions -a NULL first argument. <P> - -You can disable any of these hooks by (re)setting them to NULL, the default -value. - -<H2><A HREF="#ffocus">Field Change Commands</A></H2> - -Normally, navigation through the form will be driven by the user's -input requests. But sometimes it is useful to be able to move the -focus for editing and viewing under control of your application, or -ask which field it currently is in. The following functions help you -accomplish this: - -<PRE> -int set_current_field(FORM *form, /* form to alter */ - FIELD *field); /* field to shift to */ - -FIELD *current_field(FORM *form); /* form to query */ - -int field_index(FORM *form, /* form to query */ - FIELD *field); /* field to get index of */ -</PRE> - -The function <CODE>field_index()</CODE> returns the index of the given field -in the given form's field array (the array passed to <CODE>new_form()</CODE> or -<CODE>set_form_fields()</CODE>). <P> - -The initial current field of a form is the first active field on the -first page. The function <CODE>set_form_fields()</CODE> resets this.<P> - -It is also possible to move around by pages. - -<PRE> -int set_form_page(FORM *form, /* form to alter */ - int page); /* page to go to (0-origin) */ - -int form_page(FORM *form); /* return form's current page */ -</PRE> - -The initial page of a newly-created form is 0. The function -<CODE>set_form_fields()</CODE> resets this. - -<H2><A NAME="frmoptions">Form Options</A></H2> - -Like fields, forms may have control option bits. They can be changed -or queried with these functions: - -<PRE> -int set_form_opts(FORM *form, /* form to alter */ - int attr); /* attribute to set */ - -int form_opts_on(FORM *form, /* form to alter */ - int attr); /* attributes to turn on */ - -int form_opts_off(FORM *form, /* form to alter */ - int attr); /* attributes to turn off */ - -int form_opts(FORM *form); /* form to query */ -</PRE> - -By default, all options are on. Here are the available option bits: - -<DL> -<DT> O_NL_OVERLOAD -<DD> Enable overloading of <CODE>REQ_NEW_LINE</CODE> as described in <A -href="#fedit">Editing Requests</A>. The value of this option is -ignored on dynamic fields that have not reached their size limit; -these have no last line, so the circumstances for triggering a -<CODE>REQ_NEXT_FIELD</CODE> never arise. -<DT> O_BS_OVERLOAD -<DD> Enable overloading of <CODE>REQ_DEL_PREV</CODE> as described in -<A href="#fedit">Editing Requests</A>. -</DL> - -The option values are bit-masks and can be composed with logical-or in -the obvious way. - -<H2><A NAME="fcustom">Custom Validation Types</A></H2> - -The <CODE>form</CODE> library gives you the capability to define custom -validation types of your own. Further, the optional additional arguments -of <CODE>set_field_type</CODE> effectively allow you to parameterize validation -types. Most of the complications in the validation-type interface have to -do with the handling of the additional arguments within custom validation -functions. - -<H3><A NAME="flinktypes">Union Types</A></H3> - -The simplest way to create a custom data type is to compose it from two -preexisting ones: - -<PRE> -FIELD *link_fieldtype(FIELDTYPE *type1, - FIELDTYPE *type2); -</PRE> - -This function creates a field type that will accept any of the values -legal for either of its argument field types (which may be either -predefined or programmer-defined). - -If a <CODE>set_field_type()</CODE> call later requires arguments, the new -composite type expects all arguments for the first type, than all arguments -for the second. Order functions (see <A HREF="#forder">Order Requests</A>) -associated with the component types will work on the composite; what it does -is check the validation function for the first type, then for the second, to -figure what type the buffer contents should be treated as. - -<H3><A NAME="fnewtypes">New Field Types</A></H3> - -To create a field type from scratch, you need to specify one or both of the -following things: - -<UL> -<LI>A character-validation function, to check each character as it is entered. -<LI>A field-validation function to be applied on exit from the field. -</UL> - -Here's how you do that: -<PRE> -typedef int (*HOOK)(); /* pointer to function returning int */ - -FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ - HOOK c_validate) /* character validator */ - - -int free_fieldtype(FIELDTYPE *ftype); /* type to free */ -</PRE> - -At least one of the arguments of <CODE>new_fieldtype()</CODE> must be -non-NULL. The forms driver will automatically call the new type's -validation functions at appropriate points in processing a field of -the new type. <P> - -The function <CODE>free_fieldtype()</CODE> deallocates the argument -fieldtype, freeing all storage associated with it. <P> - -Normally, a field validator is called when the user attempts to -leave the field. Its first argument is a field pointer, from which it -can get to field buffer 0 and test it. If the function returns TRUE, -the operation succeeds; if it returns FALSE, the edit cursor stays in -the field. <P> - -A character validator gets the character passed in as a first argument. -It too should return TRUE if the character is valid, FALSE otherwise. - -<H3><A NAME="fcheckargs">Validation Function Arguments</A></H3> - -Your field- and character- validation functions will be passed a -second argument as well. This second argument is the address of a -structure (which we'll call a <EM>pile</EM>) built from any of the -field-type-specific arguments passed to <CODE>set_field_type()</CODE>. If -no such arguments are defined for the field type, this pile pointer -argument will be NULL. <P> - -In order to arrange for such arguments to be passed to your validation -functions, you must associate a small set of storage-management functions -with the type. The forms driver will use these to synthesize a pile -from the trailing arguments of each <CODE>set_field_type()</CODE> argument, and -a pointer to the pile will be passed to the validation functions. <P> - -Here is how you make the association: - -<PRE> -typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ -typedef void (*VOIDHOOK)(); /* pointer to function returning void */ - -int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ - PTRHOOK make_str, /* make structure from args */ - PTRHOOK copy_str, /* make copy of structure */ - VOIDHOOK free_str); /* free structure storage */ -</PRE> - -Here is how the storage-management hooks are used: - -<DL> -<DT> <CODE>make_str</CODE> -<DD> This function is called by <CODE>set_field_type()</CODE>. It gets one -argument, a <CODE>va_list</CODE> of the type-specific arguments passed to -<CODE>set_field_type()</CODE>. It is expected to return a pile pointer to a data -structure that encapsulates those arguments. -<DT> <CODE>copy_str</CODE> -<DD> This function is called by form library functions that allocate new -field instances. It is expected to take a pile pointer, copy the pile -to allocated storage, and return the address of the pile copy. -<DT> <CODE>free_str</CODE> -<DD> This function is called by field- and type-deallocation routines in the -library. It takes a pile pointer argument, and is expected to free the -storage of that pile. -</DL> - -The <CODE>make_str</CODE> and <CODE>copy_str</CODE> functions may return NULL to -signal allocation failure. The library routines will that call them will -return error indication when this happens. Thus, your validation functions -should never see a NULL file pointer and need not check specially for it. - -<H3><A NAME="fcustorder">Order Functions For Custom Types</A></H3> - -Some custom field types are simply ordered in the same well-defined way -that <CODE>TYPE_ENUM</CODE> is. For such types, it is possible to define -successor and predecessor functions to support the <CODE>REQ_NEXT_CHOICE</CODE> -and <CODE>REQ_PREV_CHOICE</CODE> requests. Here's how: - -<PRE> -typedef int (*INTHOOK)(); /* pointer to function returning int */ - -int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ - INTHOOK succ, /* get successor value */ - INTHOOK pred); /* get predecessor value */ -</PRE> - -The successor and predecessor arguments will each be passed two arguments; -a field pointer, and a pile pointer (as for the validation functions). They -are expected to use the function <CODE>field_buffer()</CODE> to read the -current value, and <CODE>set_field_buffer()</CODE> on buffer 0 to set the next -or previous value. Either hook may return TRUE to indicate success (a -legal next or previous value was set) or FALSE to indicate failure. - -<H3><A NAME="fcustprobs">Avoiding Problems</A></H3> - -The interface for defining custom types is complicated and tricky. -Rather than attempting to create a custom type entirely from scratch, -you should start by studying the library source code for whichever of -the pre-defined types seems to be closest to what you want. <P> - -Use that code as a model, and evolve it towards what you really want. -You will avoid many problems and annoyances that way. The code -in the <CODE>ncurses</CODE> library has been specifically exempted from -the package copyright to support this. <P> - -If your custom type defines order functions, have do something intuitive -with a blank field. A useful convention is to make the successor of a -blank field the types minimum value, and its predecessor the maximum. -</BODY> -</HTML> diff --git a/contrib/ncurses/doc/ncurses-intro.doc b/contrib/ncurses/doc/ncurses-intro.doc deleted file mode 100644 index 85179d1..0000000 --- a/contrib/ncurses/doc/ncurses-intro.doc +++ /dev/null @@ -1,2501 +0,0 @@ - Writing Programs with NCURSES - - by Eric S. Raymond and Zeyd M. Ben-Halim - updates since release 1.9.9e by Thomas Dickey - - Contents - - * Introduction - + A Brief History of Curses - + Scope of This Document - + Terminology - * The Curses Library - + An Overview of Curses - o Compiling Programs using Curses - o Updating the Screen - o Standard Windows and Function Naming Conventions - o Variables - + Using the Library - o Starting up - o Output - o Input - o Using Forms Characters - o Character Attributes and Color - o Mouse Interfacing - o Finishing Up - + Function Descriptions - o Initialization and Wrapup - o Causing Output to the Terminal - o Low-Level Capability Access - o Debugging - + Hints, Tips, and Tricks - o Some Notes of Caution - o Temporarily Leaving ncurses Mode - o Using ncurses under xterm - o Handling Multiple Terminal Screens - o Testing for Terminal Capabilities - o Tuning for Speed - o Special Features of ncurses - + Compatibility with Older Versions - o Refresh of Overlapping Windows - o Background Erase - + XSI Curses Conformance - * The Panels Library - + Compiling With the Panels Library - + Overview of Panels - + Panels, Input, and the Standard Screen - + Hiding Panels - + Miscellaneous Other Facilities - * The Menu Library - + Compiling with the menu Library - + Overview of Menus - + Selecting items - + Menu Display - + Menu Windows - + Processing Menu Input - + Miscellaneous Other Features - * The Forms Library - + Compiling with the forms Library - + Overview of Forms - + Creating and Freeing Fields and Forms - + Fetching and Changing Field Attributes - o Fetching Size and Location Data - o Changing the Field Location - o The Justification Attribute - o Field Display Attributes - o Field Option Bits - o Field Status - o Field User Pointer - + Variable-Sized Fields - + Field Validation - o TYPE_ALPHA - o TYPE_ALNUM - o TYPE_ENUM - o TYPE_INTEGER - o TYPE_NUMERIC - o TYPE_REGEXP - + Direct Field Buffer Manipulation - + Attributes of Forms - + Control of Form Display - + Input Processing in the Forms Driver - o Page Navigation Requests - o Inter-Field Navigation Requests - o Intra-Field Navigation Requests - o Scrolling Requests - o Field Editing Requests - o Order Requests - o Application Commands - + Field Change Hooks - + Field Change Commands - + Form Options - + Custom Validation Types - o Union Types - o New Field Types - o Validation Function Arguments - o Order Functions For Custom Types - o Avoiding Problems - _________________________________________________________________ - - Introduction - - This document is an introduction to programming with curses. It is not - an exhaustive reference for the curses Application Programming - Interface (API); that role is filled by the curses manual pages. - Rather, it is intended to help C programmers ease into using the - package. - - This document is aimed at C applications programmers not yet - specifically familiar with ncurses. If you are already an experienced - curses programmer, you should nevertheless read the sections on Mouse - Interfacing, Debugging, Compatibility with Older Versions, and Hints, - Tips, and Tricks. These will bring you up to speed on the special - features and quirks of the ncurses implementation. If you are not so - experienced, keep reading. - - The curses package is a subroutine library for terminal-independent - screen-painting and input-event handling which presents a high level - screen model to the programmer, hiding differences between terminal - types and doing automatic optimization of output to change one screen - full of text into another. Curses uses terminfo, which is a database - format that can describe the capabilities of thousands of different - terminals. - - The curses API may seem something of an archaism on UNIX desktops - increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX - still supports tty lines and X supports xterm(1); the curses API has - the advantage of (a) back-portability to character-cell terminals, and - (b) simplicity. For an application that does not require bit-mapped - graphics and multiple fonts, an interface implementation using curses - will typically be a great deal simpler and less expensive than one - using an X toolkit. - -A Brief History of Curses - - Historically, the first ancestor of curses was the routines written to - provide screen-handling for the game rogue; these used the - already-existing termcap database facility for describing terminal - capabilities. These routines were abstracted into a documented library - and first released with the early BSD UNIX versions. - - System III UNIX from Bell Labs featured a rewritten and much-improved - curses library. It introduced the terminfo format. Terminfo is based - on Berkeley's termcap database, but contains a number of improvements - and extensions. Parameterized capabilities strings were introduced, - making it possible to describe multiple video attributes, and colors - and to handle far more unusual terminals than possible with termcap. - In the later AT&T System V releases, curses evolved to use more - facilities and offer more capabilities, going far beyond BSD curses in - power and flexibility. - -Scope of This Document - - This document describes ncurses, a free implementation of the System V - curses API with some clearly marked extensions. It includes the - following System V curses features: - * Support for multiple screen highlights (BSD curses could only - handle one `standout' highlight, usually reverse-video). - * Support for line- and box-drawing using forms characters. - * Recognition of function keys on input. - * Color support. - * Support for pads (windows of larger than screen size on which the - screen or a subwindow defines a viewport). - - Also, this package makes use of the insert and delete line and - character features of terminals so equipped, and determines how to - optimally use these features with no help from the programmer. It - allows arbitrary combinations of video attributes to be displayed, - even on terminals that leave ``magic cookies'' on the screen to mark - changes in attributes. - - The ncurses package can also capture and use event reports from a - mouse in some environments (notably, xterm under the X window system). - This document includes tips for using the mouse. - - The ncurses package was originated by Pavel Curtis. The original - maintainer of this package is Zeyd Ben-Halim <zmbenhal@netcom.com>. - Eric S. Raymond <esr@snark.thyrsus.com> wrote many of the new features - in versions after 1.8.1 and wrote most of this introduction. Juergen - Pfeifer wrote all of the menu and forms code as well as the Ada95 - binding. Ongoing work is being done by Thomas Dickey (maintainer). - Contact the current maintainers at bug-ncurses@gnu.org. - - This document also describes the panels extension library, similarly - modeled on the SVr4 panels facility. This library allows you to - associate backing store with each of a stack or deck of overlapping - windows, and provides operations for moving windows around in the - stack that change their visibility in the natural way (handling window - overlaps). - - Finally, this document describes in detail the menus and forms - extension libraries, also cloned from System V, which support easy - construction and sequences of menus and fill-in forms. - -Terminology - - In this document, the following terminology is used with reasonable - consistency: - - window - A data structure describing a sub-rectangle of the screen - (possibly the entire screen). You can write to a window as - though it were a miniature screen, scrolling independently of - other windows on the physical screen. - - screens - A subset of windows which are as large as the terminal screen, - i.e., they start at the upper left hand corner and encompass - the lower right hand corner. One of these, stdscr, is - automatically provided for the programmer. - - terminal screen - The package's idea of what the terminal display currently looks - like, i.e., what the user sees now. This is a special screen. - - The Curses Library - -An Overview of Curses - - Compiling Programs using Curses - - In order to use the library, it is necessary to have certain types and - variables defined. Therefore, the programmer must have a line: - #include <curses.h> - - at the top of the program source. The screen package uses the Standard - I/O library, so <curses.h> includes <stdio.h>. <curses.h> also - includes <termios.h>, <termio.h>, or <sgtty.h> depending on your - system. It is redundant (but harmless) for the programmer to do these - includes, too. In linking with curses you need to have -lncurses in - your LDFLAGS or on the command line. There is no need for any other - libraries. - - Updating the Screen - - In order to update the screen optimally, it is necessary for the - routines to know what the screen currently looks like and what the - programmer wants it to look like next. For this purpose, a data type - (structure) named WINDOW is defined which describes a window image to - the routines, including its starting position on the screen (the (y, - x) coordinates of the upper left hand corner) and its size. One of - these (called curscr, for current screen) is a screen image of what - the terminal currently looks like. Another screen (called stdscr, for - standard screen) is provided by default to make changes on. - - A window is a purely internal representation. It is used to build and - store a potential image of a portion of the terminal. It doesn't bear - any necessary relation to what is really on the terminal screen; it's - more like a scratchpad or write buffer. - - To make the section of physical screen corresponding to a window - reflect the contents of the window structure, the routine refresh() - (or wrefresh() if the window is not stdscr) is called. - - A given physical screen section may be within the scope of any number - of overlapping windows. Also, changes can be made to windows in any - order, without regard to motion efficiency. Then, at will, the - programmer can effectively say ``make it look like this,'' and let the - package implementation determine the most efficient way to repaint the - screen. - - Standard Windows and Function Naming Conventions - - As hinted above, the routines can use several windows, but two are - automatically given: curscr, which knows what the terminal looks like, - and stdscr, which is what the programmer wants the terminal to look - like next. The user should never actually access curscr directly. - Changes should be made to through the API, and then the routine - refresh() (or wrefresh()) called. - - Many functions are defined to use stdscr as a default screen. For - example, to add a character to stdscr, one calls addch() with the - desired character as argument. To write to a different window. use the - routine waddch() (for `w'indow-specific addch()) is provided. This - convention of prepending function names with a `w' when they are to be - applied to specific windows is consistent. The only routines which do - not follow it are those for which a window must always be specified. - - In order to move the current (y, x) coordinates from one point to - another, the routines move() and wmove() are provided. However, it is - often desirable to first move and then perform some I/O operation. In - order to avoid clumsiness, most I/O routines can be preceded by the - prefix 'mv' and the desired (y, x) coordinates prepended to the - arguments to the function. For example, the calls - move(y, x); - addch(ch); - - can be replaced by - mvaddch(y, x, ch); - - and - wmove(win, y, x); - waddch(win, ch); - - can be replaced by - mvwaddch(win, y, x, ch); - - Note that the window description pointer (win) comes before the added - (y, x) coordinates. If a function requires a window pointer, it is - always the first parameter passed. - - Variables - - The curses library sets some variables describing the terminal - capabilities. - type name description - ------------------------------------------------------------------ - int LINES number of lines on the terminal - int COLS number of columns on the terminal - - The curses.h also introduces some #define constants and types of - general usefulness: - - bool - boolean type, actually a `char' (e.g., bool doneit;) - - TRUE - boolean `true' flag (1). - - FALSE - boolean `false' flag (0). - - ERR - error flag returned by routines on a failure (-1). - - OK - error flag returned by routines when things go right. - -Using the Library - - Now we describe how to actually use the screen package. In it, we - assume all updating, reading, etc. is applied to stdscr. These - instructions will work on any window, providing you change the - function names and parameters as mentioned above. - - Here is a sample program to motivate the discussion: -#include <curses.h> -#include <signal.h> - -static void finish(int sig); - -int -main(int argc, char *argv[]) -{ - int num = 0; - - /* initialize your non-curses data structures here */ - - (void) signal(SIGINT, finish); /* arrange interrupts to terminate */ - - (void) initscr(); /* initialize the curses library */ - keypad(stdscr, TRUE); /* enable keyboard mapping */ - (void) nonl(); /* tell curses not to do NL->CR/NL on output */ - (void) cbreak(); /* take input chars one at a time, no wait for \n */ - (void) echo(); /* echo input - in color */ - - if (has_colors()) - { - start_color(); - - /* - * Simple color assignment, often all we need. Color pair 0 cannot - * be redefined. This example uses the same value for the color - * pair as for the foreground color, though of course that is not - * necessary: - */ - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_YELLOW, COLOR_BLACK); - init_pair(4, COLOR_BLUE, COLOR_BLACK); - init_pair(5, COLOR_CYAN, COLOR_BLACK); - init_pair(6, COLOR_MAGENTA, COLOR_BLACK); - init_pair(7, COLOR_WHITE, COLOR_BLACK); - } - - for (;;) - { - int c = getch(); /* refresh, accept single keystroke of input */ - attrset(COLOR_PAIR(num % 8)); - num++; - - /* process the command keystroke */ - } - - finish(0); /* we're done */ -} - -static void finish(int sig) -{ - endwin(); - - /* do your non-curses wrapup here */ - - exit(0); -} - - Starting up - - In order to use the screen package, the routines must know about - terminal characteristics, and the space for curscr and stdscr must be - allocated. These function initscr() does both these things. Since it - must allocate space for the windows, it can overflow memory when - attempting to do so. On the rare occasions this happens, initscr() - will terminate the program with an error message. initscr() must - always be called before any of the routines which affect windows are - used. If it is not, the program will core dump as soon as either - curscr or stdscr are referenced. However, it is usually best to wait - to call it until after you are sure you will need it, like after - checking for startup errors. Terminal status changing routines like - nl() and cbreak() should be called after initscr(). - - Once the screen windows have been allocated, you can set them up for - your program. If you want to, say, allow a screen to scroll, use - scrollok(). If you want the cursor to be left in place after the last - change, use leaveok(). If this isn't done, refresh() will move the - cursor to the window's current (y, x) coordinates after updating it. - - You can create new windows of your own using the functions newwin(), - derwin(), and subwin(). The routine delwin() will allow you to get rid - of old windows. All the options described above can be applied to any - window. - - Output - - Now that we have set things up, we will want to actually update the - terminal. The basic functions used to change what will go on a window - are addch() and move(). addch() adds a character at the current (y, x) - coordinates. move() changes the current (y, x) coordinates to whatever - you want them to be. It returns ERR if you try to move off the window. - As mentioned above, you can combine the two into mvaddch() to do both - things at once. - - The other output functions, such as addstr() and printw(), all call - addch() to add characters to the window. - - After you have put on the window what you want there, when you want - the portion of the terminal covered by the window to be made to look - like it, you must call refresh(). In order to optimize finding - changes, refresh() assumes that any part of the window not changed - since the last refresh() of that window has not been changed on the - terminal, i.e., that you have not refreshed a portion of the terminal - with an overlapping window. If this is not the case, the routine - touchwin() is provided to make it look like the entire window has been - changed, thus making refresh() check the whole subsection of the - terminal for changes. - - If you call wrefresh() with curscr as its argument, it will make the - screen look like curscr thinks it looks like. This is useful for - implementing a command which would redraw the screen in case it get - messed up. - - Input - - The complementary function to addch() is getch() which, if echo is - set, will call addch() to echo the character. Since the screen package - needs to know what is on the terminal at all times, if characters are - to be echoed, the tty must be in raw or cbreak mode. Since initially - the terminal has echoing enabled and is in ordinary ``cooked'' mode, - one or the other has to changed before calling getch(); otherwise, the - program's output will be unpredictable. - - When you need to accept line-oriented input in a window, the functions - wgetstr() and friends are available. There is even a wscanw() function - that can do scanf()(3)-style multi-field parsing on window input. - These pseudo-line-oriented functions turn on echoing while they - execute. - - The example code above uses the call keypad(stdscr, TRUE) to enable - support for function-key mapping. With this feature, the getch() code - watches the input stream for character sequences that correspond to - arrow and function keys. These sequences are returned as - pseudo-character values. The #define values returned are listed in the - curses.h The mapping from sequences to #define values is determined by - key_ capabilities in the terminal's terminfo entry. - - Using Forms Characters - - The addch() function (and some others, including box() and border()) - can accept some pseudo-character arguments which are specially defined - by ncurses. These are #define values set up in the curses.h header; - see there for a complete list (look for the prefix ACS_). - - The most useful of the ACS defines are the forms-drawing characters. - You can use these to draw boxes and simple graphs on the screen. If - the terminal does not have such characters, curses.h will map them to - a recognizable (though ugly) set of ASCII defaults. - - Character Attributes and Color - - The ncurses package supports screen highlights including standout, - reverse-video, underline, and blink. It also supports color, which is - treated as another kind of highlight. - - Highlights are encoded, internally, as high bits of the - pseudo-character type (chtype) that curses.h uses to represent the - contents of a screen cell. See the curses.h header file for a complete - list of highlight mask values (look for the prefix A_). - - There are two ways to make highlights. One is to logical-or the value - of the highlights you want into the character argument of an addch() - call, or any other output call that takes a chtype argument. - - The other is to set the current-highlight value. This is logical-or'ed - with any highlight you specify the first way. You do this with the - functions attron(), attroff(), and attrset(); see the manual pages for - details. Color is a special kind of highlight. The package actually - thinks in terms of color pairs, combinations of foreground and - background colors. The sample code above sets up eight color pairs, - all of the guaranteed-available colors on black. Note that each color - pair is, in effect, given the name of its foreground color. Any other - range of eight non-conflicting values could have been used as the - first arguments of the init_pair() values. - - Once you've done an init_pair() that creates color-pair N, you can use - COLOR_PAIR(N) as a highlight that invokes that particular color - combination. Note that COLOR_PAIR(N), for constant N, is itself a - compile-time constant and can be used in initializers. - - Mouse Interfacing - - The ncurses library also provides a mouse interface. - - NOTE: this facility is specific to ncurses, it is not part of - either the XSI Curses standard, nor of System V Release 4, nor BSD - curses. System V Release 4 curses contains code with similar - interface definitions, however it is not documented. Other than by - disassembling the library, we have no way to determine exactly how - that mouse code works. Thus, we recommend that you wrap - mouse-related code in an #ifdef using the feature macro - NCURSES_MOUSE_VERSION so it will not be compiled and linked on - non-ncurses systems. - - Presently, mouse event reporting works in the following environments: - * xterm and similar programs such as rxvt. - * Linux console, when configured with gpm(1), Alessandro Rubini's - mouse server. - * FreeBSD sysmouse (console) - * OS/2 EMX - - The mouse interface is very simple. To activate it, you use the - function mousemask(), passing it as first argument a bit-mask that - specifies what kinds of events you want your program to be able to - see. It will return the bit-mask of events that actually become - visible, which may differ from the argument if the mouse device is not - capable of reporting some of the event types you specify. - - Once the mouse is active, your application's command loop should watch - for a return value of KEY_MOUSE from wgetch(). When you see this, a - mouse event report has been queued. To pick it off the queue, use the - function getmouse() (you must do this before the next wgetch(), - otherwise another mouse event might come in and make the first one - inaccessible). - - Each call to getmouse() fills a structure (the address of which you'll - pass it) with mouse event data. The event data includes zero-origin, - screen-relative character-cell coordinates of the mouse pointer. It - also includes an event mask. Bits in this mask will be set, - corresponding to the event type being reported. - - The mouse structure contains two additional fields which may be - significant in the future as ncurses interfaces to new kinds of - pointing device. In addition to x and y coordinates, there is a slot - for a z coordinate; this might be useful with touch-screens that can - return a pressure or duration parameter. There is also a device ID - field, which could be used to distinguish between multiple pointing - devices. - - The class of visible events may be changed at any time via - mousemask(). Events that can be reported include presses, releases, - single-, double- and triple-clicks (you can set the maximum - button-down time for clicks). If you don't make clicks visible, they - will be reported as press-release pairs. In some environments, the - event mask may include bits reporting the state of shift, alt, and - ctrl keys on the keyboard during the event. - - A function to check whether a mouse event fell within a given window - is also supplied. You can use this to see whether a given window - should consider a mouse event relevant to it. - - Because mouse event reporting will not be available in all - environments, it would be unwise to build ncurses applications that - require the use of a mouse. Rather, you should use the mouse as a - shortcut for point-and-shoot commands your application would normally - accept from the keyboard. Two of the test games in the ncurses - distribution (bs and knight) contain code that illustrates how this - can be done. - - See the manual page curs_mouse(3X) for full details of the - mouse-interface functions. - - Finishing Up - - In order to clean up after the ncurses routines, the routine endwin() - is provided. It restores tty modes to what they were when initscr() - was first called, and moves the cursor down to the lower-left corner. - Thus, anytime after the call to initscr, endwin() should be called - before exiting. - -Function Descriptions - - We describe the detailed behavior of some important curses functions - here, as a supplement to the manual page descriptions. - - Initialization and Wrapup - - initscr() - The first function called should almost always be initscr(). - This will determine the terminal type and initialize curses - data structures. initscr() also arranges that the first call to - refresh() will clear the screen. If an error occurs a message - is written to standard error and the program exits. Otherwise - it returns a pointer to stdscr. A few functions may be called - before initscr (slk_init(), filter(), ripoffline(), use_env(), - and, if you are using multiple terminals, newterm().) - - endwin() - Your program should always call endwin() before exiting or - shelling out of the program. This function will restore tty - modes, move the cursor to the lower left corner of the screen, - reset the terminal into the proper non-visual mode. Calling - refresh() or doupdate() after a temporary escape from the - program will restore the ncurses screen from before the escape. - - newterm(type, ofp, ifp) - A program which outputs to more than one terminal should use - newterm() instead of initscr(). newterm() should be called once - for each terminal. It returns a variable of type SCREEN * which - should be saved as a reference to that terminal. (NOTE: a - SCREEN variable is not a screen in the sense we are describing - in this introduction, but a collection of parameters used to - assist in optimizing the display.) The arguments are the type - of the terminal (a string) and FILE pointers for the output and - input of the terminal. If type is NULL then the environment - variable $TERM is used. endwin() should called once at wrapup - time for each terminal opened using this function. - - set_term(new) - This function is used to switch to a different terminal - previously opened by newterm(). The screen reference for the - new terminal is passed as the parameter. The previous terminal - is returned by the function. All other calls affect only the - current terminal. - - delscreen(sp) - The inverse of newterm(); deallocates the data structures - associated with a given SCREEN reference. - - Causing Output to the Terminal - - refresh() and wrefresh(win) - These functions must be called to actually get any output on - the terminal, as other routines merely manipulate data - structures. wrefresh() copies the named window to the physical - terminal screen, taking into account what is already there in - order to do optimizations. refresh() does a refresh of stdscr. - Unless leaveok() has been enabled, the physical cursor of the - terminal is left at the location of the window's cursor. - - doupdate() and wnoutrefresh(win) - These two functions allow multiple updates with more efficiency - than wrefresh. To use them, it is important to understand how - curses works. In addition to all the window structures, curses - keeps two data structures representing the terminal screen: a - physical screen, describing what is actually on the screen, and - a virtual screen, describing what the programmer wants to have - on the screen. wrefresh works by first copying the named window - to the virtual screen (wnoutrefresh()), and then calling the - routine to update the screen (doupdate()). If the programmer - wishes to output several windows at once, a series of calls to - wrefresh will result in alternating calls to wnoutrefresh() and - doupdate(), causing several bursts of output to the screen. By - calling wnoutrefresh() for each window, it is then possible to - call doupdate() once, resulting in only one burst of output, - with fewer total characters transmitted (this also avoids a - visually annoying flicker at each update). - - Low-Level Capability Access - - setupterm(term, filenum, errret) - This routine is called to initialize a terminal's description, - without setting up the curses screen structures or changing the - tty-driver mode bits. term is the character string representing - the name of the terminal being used. filenum is the UNIX file - descriptor of the terminal to be used for output. errret is a - pointer to an integer, in which a success or failure indication - is returned. The values returned can be 1 (all is well), 0 (no - such terminal), or -1 (some problem locating the terminfo - database). - - The value of term can be given as NULL, which will cause the - value of TERM in the environment to be used. The errret pointer - can also be given as NULL, meaning no error code is wanted. If - errret is defaulted, and something goes wrong, setupterm() will - print an appropriate error message and exit, rather than - returning. Thus, a simple program can call setupterm(0, 1, 0) - and not worry about initialization errors. - - After the call to setupterm(), the global variable cur_term is - set to point to the current structure of terminal capabilities. - By calling setupterm() for each terminal, and saving and - restoring cur_term, it is possible for a program to use two or - more terminals at once. Setupterm() also stores the names - section of the terminal description in the global character - array ttytype[]. Subsequent calls to setupterm() will overwrite - this array, so you'll have to save it yourself if need be. - - Debugging - - NOTE: These functions are not part of the standard curses API! - - trace() - This function can be used to explicitly set a trace level. If - the trace level is nonzero, execution of your program will - generate a file called `trace' in the current working directory - containing a report on the library's actions. Higher trace - levels enable more detailed (and verbose) reporting -- see - comments attached to TRACE_ defines in the curses.h file for - details. (It is also possible to set a trace level by assigning - a trace level value to the environment variable NCURSES_TRACE). - - _tracef() - This function can be used to output your own debugging - information. It is only available only if you link with - -lncurses_g. It can be used the same way as printf(), only it - outputs a newline after the end of arguments. The output goes - to a file called trace in the current directory. - - Trace logs can be difficult to interpret due to the sheer volume of - data dumped in them. There is a script called tracemunch included with - the ncurses distribution that can alleviate this problem somewhat; it - compacts long sequences of similar operations into more succinct - single-line pseudo-operations. These pseudo-ops can be distinguished - by the fact that they are named in capital letters. - -Hints, Tips, and Tricks - - The ncurses manual pages are a complete reference for this library. In - the remainder of this document, we discuss various useful methods that - may not be obvious from the manual page descriptions. - - Some Notes of Caution - - If you find yourself thinking you need to use noraw() or nocbreak(), - think again and move carefully. It's probably better design to use - getstr() or one of its relatives to simulate cooked mode. The noraw() - and nocbreak() functions try to restore cooked mode, but they may end - up clobbering some control bits set before you started your - application. Also, they have always been poorly documented, and are - likely to hurt your application's usability with other curses - libraries. - - Bear in mind that refresh() is a synonym for wrefresh(stdscr). Don't - try to mix use of stdscr with use of windows declared by newwin(); a - refresh() call will blow them off the screen. The right way to handle - this is to use subwin(), or not touch stdscr at all and tile your - screen with declared windows which you then wnoutrefresh() somewhere - in your program event loop, with a single doupdate() call to trigger - actual repainting. - - You are much less likely to run into problems if you design your - screen layouts to use tiled rather than overlapping windows. - Historically, curses support for overlapping windows has been weak, - fragile, and poorly documented. The ncurses library is not yet an - exception to this rule. - - There is a panels library included in the ncurses distribution that - does a pretty good job of strengthening the overlapping-windows - facilities. - - Try to avoid using the global variables LINES and COLS. Use getmaxyx() - on the stdscr context instead. Reason: your code may be ported to run - in an environment with window resizes, in which case several screens - could be open with different sizes. - - Temporarily Leaving NCURSES Mode - - Sometimes you will want to write a program that spends most of its - time in screen mode, but occasionally returns to ordinary `cooked' - mode. A common reason for this is to support shell-out. This behavior - is simple to arrange in ncurses. - - To leave ncurses mode, call endwin() as you would if you were - intending to terminate the program. This will take the screen back to - cooked mode; you can do your shell-out. When you want to return to - ncurses mode, simply call refresh() or doupdate(). This will repaint - the screen. - - There is a boolean function, isendwin(), which code can use to test - whether ncurses screen mode is active. It returns TRUE in the interval - between an endwin() call and the following refresh(), FALSE otherwise. - - Here is some sample code for shellout: - addstr("Shelling out..."); - def_prog_mode(); /* save current tty modes */ - endwin(); /* restore original tty modes */ - system("sh"); /* run shell */ - addstr("returned.\n"); /* prepare return message */ - refresh(); /* restore save modes, repaint screen */ - - Using NCURSES under XTERM - - A resize operation in X sends SIGWINCH to the application running - under xterm. The easiest way to handle SIGWINCH is to do an endwin, - followed by an refresh and a screen repaint you code yourself. The - refresh will pick up the new screen size from the xterm's environment. - - That is the standard way, of course (it even works with some vendor's - curses implementations). Its drawback is that it clears the screen to - reinitialize the display, and does not resize subwindows which must be - shrunk. Ncurses provides an extension which works better, the - resizeterm function. That function ensures that all windows are - limited to the new screen dimensions, and pads stdscr with blanks if - the screen is larger. - - The ncurses library provides a SIGWINCH signal handler, which pushes a - KEY_RESIZE via the wgetch() calls. When ncurses returns that code, it - calls resizeterm to update the size of the standard screen's window, - repainting that (filling with blanks or truncating as needed). It also - resizes other windows, but its effect may be less satisfactory because - it cannot know how you want the screen re-painted. You will usually - have to write special-purpose code to handle KEY_RESIZE yourself. - - Handling Multiple Terminal Screens - - The initscr() function actually calls a function named newterm() to do - most of its work. If you are writing a program that opens multiple - terminals, use newterm() directly. - - For each call, you will have to specify a terminal type and a pair of - file pointers; each call will return a screen reference, and stdscr - will be set to the last one allocated. You will switch between screens - with the set_term call. Note that you will also have to call - def_shell_mode and def_prog_mode on each tty yourself. - - Testing for Terminal Capabilities - - Sometimes you may want to write programs that test for the presence of - various capabilities before deciding whether to go into ncurses mode. - An easy way to do this is to call setupterm(), then use the functions - tigetflag(), tigetnum(), and tigetstr() to do your testing. - - A particularly useful case of this often comes up when you want to - test whether a given terminal type should be treated as `smart' - (cursor-addressable) or `stupid'. The right way to test this is to see - if the return value of tigetstr("cup") is non-NULL. Alternatively, you - can include the term.h file and test the value of the macro - cursor_address. - - Tuning for Speed - - Use the addchstr() family of functions for fast screen-painting of - text when you know the text doesn't contain any control characters. - Try to make attribute changes infrequent on your screens. Don't use - the immedok() option! - - Special Features of NCURSES - - The wresize() function allows you to resize a window in place. The - associated resizeterm() function simplifies the construction of - SIGWINCH handlers, for resizing all windows. - - The define_key() function allows you to define at runtime function-key - control sequences which are not in the terminal description. The - keyok() function allows you to temporarily enable or disable - interpretation of any function-key control sequence. - - The use_default_colors() function allows you to construct applications - which can use the terminal's default foreground and background colors - as an additional "default" color. Several terminal emulators support - this feature, which is based on ISO 6429. - - Ncurses supports up 16 colors, unlike SVr4 curses which defines only - 8. While most terminals which provide color allow only 8 colors, about - a quarter (including XFree86 xterm) support 16 colors. - -Compatibility with Older Versions - - Despite our best efforts, there are some differences between ncurses - and the (undocumented!) behavior of older curses implementations. - These arise from ambiguities or omissions in the documentation of the - API. - - Refresh of Overlapping Windows - - If you define two windows A and B that overlap, and then alternately - scribble on and refresh them, the changes made to the overlapping - region under historic curses versions were often not documented - precisely. - - To understand why this is a problem, remember that screen updates are - calculated between two representations of the entire display. The - documentation says that when you refresh a window, it is first copied - to the virtual screen, and then changes are calculated to update the - physical screen (and applied to the terminal). But "copied to" is not - very specific, and subtle differences in how copying works can produce - different behaviors in the case where two overlapping windows are each - being refreshed at unpredictable intervals. - - What happens to the overlapping region depends on what wnoutrefresh() - does with its argument -- what portions of the argument window it - copies to the virtual screen. Some implementations do "change copy", - copying down only locations in the window that have changed (or been - marked changed with wtouchln() and friends). Some implementations do - "entire copy", copying all window locations to the virtual screen - whether or not they have changed. - - The ncurses library itself has not always been consistent on this - score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. - Versions 1.8.6 and older, and versions 1.9.9 and newer, do change - copy. - - For most commercial curses implementations, it is not documented and - not known for sure (at least not to the ncurses maintainers) whether - they do change copy or entire copy. We know that System V release 3 - curses has logic in it that looks like an attempt to do change copy, - but the surrounding logic and data representations are sufficiently - complex, and our knowledge sufficiently indirect, that it's hard to - know whether this is reliable. It is not clear what the SVr4 - documentation and XSI standard intend. The XSI Curses standard barely - mentions wnoutrefresh(); the SVr4 documents seem to be describing - entire-copy, but it is possible with some effort and straining to read - them the other way. - - It might therefore be unwise to rely on either behavior in programs - that might have to be linked with other curses implementations. - Instead, you can do an explicit touchwin() before the wnoutrefresh() - call to guarantee an entire-contents copy anywhere. - - The really clean way to handle this is to use the panels library. If, - when you want a screen update, you do update_panels(), it will do all - the necessary wnoutrefresh() calls for whatever panel stacking order - you have defined. Then you can do one doupdate() and there will be a - single burst of physical I/O that will do all your updates. - - Background Erase - - If you have been using a very old versions of ncurses (1.8.7 or older) - you may be surprised by the behavior of the erase functions. In older - versions, erased areas of a window were filled with a blank modified - by the window's current attribute (as set by wattrset(), wattron(), - wattroff() and friends). - - In newer versions, this is not so. Instead, the attribute of erased - blanks is normal unless and until it is modified by the functions - bkgdset() or wbkgdset(). - - This change in behavior conforms ncurses to System V Release 4 and the - XSI Curses standard. - -XSI Curses Conformance - - The ncurses library is intended to be base-level conformant with the - XSI Curses standard from X/Open. Many extended-level features (in - fact, almost all features not directly concerned with wide characters - and internationalization) are also supported. - - One effect of XSI conformance is the change in behavior described - under "Background Erase -- Compatibility with Old Versions". - - Also, ncurses meets the XSI requirement that every macro entry point - have a corresponding function which may be linked (and will be - prototype-checked) if the macro definition is disabled with #undef. - - The Panels Library - - The ncurses library by itself provides good support for screen - displays in which the windows are tiled (non-overlapping). In the more - general case that windows may overlap, you have to use a series of - wnoutrefresh() calls followed by a doupdate(), and be careful about - the order you do the window refreshes in. It has to be bottom-upwards, - otherwise parts of windows that should be obscured will show through. - - When your interface design is such that windows may dive deeper into - the visibility stack or pop to the top at runtime, the resulting - book-keeping can be tedious and difficult to get right. Hence the - panels library. - - The panel library first appeared in AT&T System V. The version - documented here is the panel code distributed with ncurses. - -Compiling With the Panels Library - - Your panels-using modules must import the panels library declarations - with - #include <panel.h> - - and must be linked explicitly with the panels library using an -lpanel - argument. Note that they must also link the ncurses library with - -lncurses. Many linkers are two-pass and will accept either order, but - it is still good practice to put -lpanel first and -lncurses second. - -Overview of Panels - - A panel object is a window that is implicitly treated as part of a - deck including all other panel objects. The deck has an implicit - bottom-to-top visibility order. The panels library includes an update - function (analogous to refresh()) that displays all panels in the deck - in the proper order to resolve overlaps. The standard window, stdscr, - is considered below all panels. - - Details on the panels functions are available in the man pages. We'll - just hit the highlights here. - - You create a panel from a window by calling new_panel() on a window - pointer. It then becomes the top of the deck. The panel's window is - available as the value of panel_window() called with the panel pointer - as argument. - - You can delete a panel (removing it from the deck) with del_panel. - This will not deallocate the associated window; you have to do that - yourself. You can replace a panel's window with a different window by - calling replace_window. The new window may be of different size; the - panel code will re-compute all overlaps. This operation doesn't change - the panel's position in the deck. - - To move a panel's window, use move_panel(). The mvwin() function on - the panel's window isn't sufficient because it doesn't update the - panels library's representation of where the windows are. This - operation leaves the panel's depth, contents, and size unchanged. - - Two functions (top_panel(), bottom_panel()) are provided for - rearranging the deck. The first pops its argument window to the top of - the deck; the second sends it to the bottom. Either operation leaves - the panel's screen location, contents, and size unchanged. - - The function update_panels() does all the wnoutrefresh() calls needed - to prepare for doupdate() (which you must call yourself, afterwards). - - Typically, you will want to call update_panels() and doupdate() just - before accepting command input, once in each cycle of interaction with - the user. If you call update_panels() after each and every panel - write, you'll generate a lot of unnecessary refresh activity and - screen flicker. - -Panels, Input, and the Standard Screen - - You shouldn't mix wnoutrefresh() or wrefresh() operations with panels - code; this will work only if the argument window is either in the top - panel or unobscured by any other panels. - - The stsdcr window is a special case. It is considered below all - panels. Because changes to panels may obscure parts of stdscr, though, - you should call update_panels() before doupdate() even when you only - change stdscr. - - Note that wgetch automatically calls wrefresh. Therefore, before - requesting input from a panel window, you need to be sure that the - panel is totally unobscured. - - There is presently no way to display changes to one obscured panel - without repainting all panels. - -Hiding Panels - - It's possible to remove a panel from the deck temporarily; use - hide_panel for this. Use show_panel() to render it visible again. The - predicate function panel_hidden tests whether or not a panel is - hidden. - - The panel_update code ignores hidden panels. You cannot do top_panel() - or bottom_panel on a hidden panel(). Other panels operations are - applicable. - -Miscellaneous Other Facilities - - It's possible to navigate the deck using the functions panel_above() - and panel_below. Handed a panel pointer, they return the panel above - or below that panel. Handed NULL, they return the bottom-most or - top-most panel. - - Every panel has an associated user pointer, not used by the panel - code, to which you can attach application data. See the man page - documentation of set_panel_userptr() and panel_userptr for details. - - The Menu Library - - A menu is a screen display that assists the user to choose some subset - of a given set of items. The menu library is a curses extension that - supports easy programming of menu hierarchies with a uniform but - flexible interface. - - The menu library first appeared in AT&T System V. The version - documented here is the menu code distributed with ncurses. - -Compiling With the menu Library - - Your menu-using modules must import the menu library declarations with - #include <menu.h> - - and must be linked explicitly with the menus library using an -lmenu - argument. Note that they must also link the ncurses library with - -lncurses. Many linkers are two-pass and will accept either order, but - it is still good practice to put -lmenu first and -lncurses second. - -Overview of Menus - - The menus created by this library consist of collections of items - including a name string part and a description string part. To make - menus, you create groups of these items and connect them with menu - frame objects. - - The menu can then by posted, that is written to an associated window. - Actually, each menu has two associated windows; a containing window in - which the programmer can scribble titles or borders, and a subwindow - in which the menu items proper are displayed. If this subwindow is too - small to display all the items, it will be a scrollable viewport on - the collection of items. - - A menu may also be unposted (that is, undisplayed), and finally freed - to make the storage associated with it and its items available for - re-use. - - The general flow of control of a menu program looks like this: - 1. Initialize curses. - 2. Create the menu items, using new_item(). - 3. Create the menu using new_menu(). - 4. Post the menu using post_menu(). - 5. Refresh the screen. - 6. Process user requests via an input loop. - 7. Unpost the menu using unpost_menu(). - 8. Free the menu, using free_menu(). - 9. Free the items using free_item(). - 10. Terminate curses. - -Selecting items - - Menus may be multi-valued or (the default) single-valued (see the - manual page menu_opts(3x) to see how to change the default). Both - types always have a current item. - - From a single-valued menu you can read the selected value simply by - looking at the current item. From a multi-valued menu, you get the - selected set by looping through the items applying the item_value() - predicate function. Your menu-processing code can use the function - set_item_value() to flag the items in the select set. - - Menu items can be made unselectable using set_item_opts() or - item_opts_off() with the O_SELECTABLE argument. This is the only - option so far defined for menus, but it is good practice to code as - though other option bits might be on. - -Menu Display - - The menu library calculates a minimum display size for your window, - based on the following variables: - * The number and maximum length of the menu items - * Whether the O_ROWMAJOR option is enabled - * Whether display of descriptions is enabled - * Whatever menu format may have been set by the programmer - * The length of the menu mark string used for highlighting selected - items - - The function set_menu_format() allows you to set the maximum size of - the viewport or menu page that will be used to display menu items. You - can retrieve any format associated with a menu with menu_format(). The - default format is rows=16, columns=1. - - The actual menu page may be smaller than the format size. This depends - on the item number and size and whether O_ROWMAJOR is on. This option - (on by default) causes menu items to be displayed in a `raster-scan' - pattern, so that if more than one item will fit horizontally the first - couple of items are side-by-side in the top row. The alternative is - column-major display, which tries to put the first several items in - the first column. - - As mentioned above, a menu format not large enough to allow all items - to fit on-screen will result in a menu display that is vertically - scrollable. - - You can scroll it with requests to the menu driver, which will be - described in the section on menu input handling. - - Each menu has a mark string used to visually tag selected items; see - the menu_mark(3x) manual page for details. The mark string length also - influences the menu page size. - - The function scale_menu() returns the minimum display size that the - menu code computes from all these factors. There are other menu - display attributes including a select attribute, an attribute for - selectable items, an attribute for unselectable items, and a pad - character used to separate item name text from description text. These - have reasonable defaults which the library allows you to change (see - the menu_attribs(3x) manual page. - -Menu Windows - - Each menu has, as mentioned previously, a pair of associated windows. - Both these windows are painted when the menu is posted and erased when - the menu is unposted. - - The outer or frame window is not otherwise touched by the menu - routines. It exists so the programmer can associate a title, a border, - or perhaps help text with the menu and have it properly refreshed or - erased at post/unpost time. The inner window or subwindow is where the - current menu page is displayed. - - By default, both windows are stdscr. You can set them with the - functions in menu_win(3x). - - When you call post_menu(), you write the menu to its subwindow. When - you call unpost_menu(), you erase the subwindow, However, neither of - these actually modifies the screen. To do that, call wrefresh() or - some equivalent. - -Processing Menu Input - - The main loop of your menu-processing code should call menu_driver() - repeatedly. The first argument of this routine is a menu pointer; the - second is a menu command code. You should write an input-fetching - routine that maps input characters to menu command codes, and pass its - output to menu_driver(). The menu command codes are fully documented - in menu_driver(3x). - - The simplest group of command codes is REQ_NEXT_ITEM, REQ_PREV_ITEM, - REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_UP_ITEM, REQ_DOWN_ITEM, - REQ_LEFT_ITEM, REQ_RIGHT_ITEM. These change the currently selected - item. These requests may cause scrolling of the menu page if it only - partially displayed. - - There are explicit requests for scrolling which also change the - current item (because the select location does not change, but the - item there does). These are REQ_SCR_DLINE, REQ_SCR_ULINE, - REQ_SCR_DPAGE, and REQ_SCR_UPAGE. - - The REQ_TOGGLE_ITEM selects or deselects the current item. It is for - use in multi-valued menus; if you use it with O_ONEVALUE on, you'll - get an error return (E_REQUEST_DENIED). - - Each menu has an associated pattern buffer. The menu_driver() logic - tries to accumulate printable ASCII characters passed in in that - buffer; when it matches a prefix of an item name, that item (or the - next matching item) is selected. If appending a character yields no - new match, that character is deleted from the pattern buffer, and - menu_driver() returns E_NO_MATCH. - - Some requests change the pattern buffer directly: REQ_CLEAR_PATTERN, - REQ_BACK_PATTERN, REQ_NEXT_MATCH, REQ_PREV_MATCH. The latter two are - useful when pattern buffer input matches more than one item in a - multi-valued menu. - - Each successful scroll or item navigation request clears the pattern - buffer. It is also possible to set the pattern buffer explicitly with - set_menu_pattern(). - - Finally, menu driver requests above the constant MAX_COMMAND are - considered application-specific commands. The menu_driver() code - ignores them and returns E_UNKNOWN_COMMAND. - -Miscellaneous Other Features - - Various menu options can affect the processing and visual appearance - and input processing of menus. See menu_opts(3x) for details. - - It is possible to change the current item from application code; this - is useful if you want to write your own navigation requests. It is - also possible to explicitly set the top row of the menu display. See - mitem_current(3x). If your application needs to change the menu - subwindow cursor for any reason, pos_menu_cursor() will restore it to - the correct location for continuing menu driver processing. - - It is possible to set hooks to be called at menu initialization and - wrapup time, and whenever the selected item changes. See - menu_hook(3x). - - Each item, and each menu, has an associated user pointer on which you - can hang application data. See mitem_userptr(3x) and menu_userptr(3x). - - The Forms Library - - The form library is a curses extension that supports easy programming - of on-screen forms for data entry and program control. - - The form library first appeared in AT&T System V. The version - documented here is the form code distributed with ncurses. - -Compiling With the form Library - - Your form-using modules must import the form library declarations with - #include <form.h> - - and must be linked explicitly with the forms library using an -lform - argument. Note that they must also link the ncurses library with - -lncurses. Many linkers are two-pass and will accept either order, but - it is still good practice to put -lform first and -lncurses second. - -Overview of Forms - - A form is a collection of fields; each field may be either a label - (explanatory text) or a data-entry location. Long forms may be - segmented into pages; each entry to a new page clears the screen. - - To make forms, you create groups of fields and connect them with form - frame objects; the form library makes this relatively simple. - - Once defined, a form can be posted, that is written to an associated - window. Actually, each form has two associated windows; a containing - window in which the programmer can scribble titles or borders, and a - subwindow in which the form fields proper are displayed. - - As the form user fills out the posted form, navigation and editing - keys support movement between fields, editing keys support modifying - field, and plain text adds to or changes data in a current field. The - form library allows you (the forms designer) to bind each navigation - and editing key to any keystroke accepted by curses Fields may have - validation conditions on them, so that they check input data for type - and value. The form library supplies a rich set of pre-defined field - types, and makes it relatively easy to define new ones. - - Once its transaction is completed (or aborted), a form may be unposted - (that is, undisplayed), and finally freed to make the storage - associated with it and its items available for re-use. - - The general flow of control of a form program looks like this: - 1. Initialize curses. - 2. Create the form fields, using new_field(). - 3. Create the form using new_form(). - 4. Post the form using post_form(). - 5. Refresh the screen. - 6. Process user requests via an input loop. - 7. Unpost the form using unpost_form(). - 8. Free the form, using free_form(). - 9. Free the fields using free_field(). - 10. Terminate curses. - - Note that this looks much like a menu program; the form library - handles tasks which are in many ways similar, and its interface was - obviously designed to resemble that of the menu library wherever - possible. - - In forms programs, however, the `process user requests' is somewhat - more complicated than for menus. Besides menu-like navigation - operations, the menu driver loop has to support field editing and data - validation. - -Creating and Freeing Fields and Forms - - The basic function for creating fields is new_field(): -FIELD *new_field(int height, int width, /* new field size */ - int top, int left, /* upper left corner */ - int offscreen, /* number of offscreen rows */ - int nbuf); /* number of working buffers */ - - Menu items always occupy a single row, but forms fields may have - multiple rows. So new_field() requires you to specify a width and - height (the first two arguments, which mist both be greater than - zero). - - You must also specify the location of the field's upper left corner on - the screen (the third and fourth arguments, which must be zero or - greater). Note that these coordinates are relative to the form - subwindow, which will coincide with stdscr by default but need not be - stdscr if you've done an explicit set_form_win() call. - - The fifth argument allows you to specify a number of off-screen rows. - If this is zero, the entire field will always be displayed. If it is - nonzero, the form will be scrollable, with only one screen-full - (initially the top part) displayed at any given time. If you make a - field dynamic and grow it so it will no longer fit on the screen, the - form will become scrollable even if the offscreen argument was - initially zero. - - The forms library allocates one working buffer per field; the size of - each buffer is ((height + offscreen)*width + 1, one character for each - position in the field plus a NUL terminator. The sixth argument is the - number of additional data buffers to allocate for the field; your - application can use them for its own purposes. -FIELD *dup_field(FIELD *field, /* field to copy */ - int top, int left); /* location of new copy */ - - The function dup_field() duplicates an existing field at a new - location. Size and buffering information are copied; some attribute - flags and status bits are not (see the form_field_new(3X) for - details). -FIELD *link_field(FIELD *field, /* field to copy */ - int top, int left); /* location of new copy */ - - The function link_field() also duplicates an existing field at a new - location. The difference from dup_field() is that it arranges for the - new field's buffer to be shared with the old one. - - Besides the obvious use in making a field editable from two different - form pages, linked fields give you a way to hack in dynamic labels. If - you declare several fields linked to an original, and then make them - inactive, changes from the original will still be propagated to the - linked fields. - - As with duplicated fields, linked fields have attribute bits separate - from the original. - - As you might guess, all these field-allocations return NULL if the - field allocation is not possible due to an out-of-memory error or - out-of-bounds arguments. - - To connect fields to a form, use -FORM *new_form(FIELD **fields); - - This function expects to see a NULL-terminated array of field - pointers. Said fields are connected to a newly-allocated form object; - its address is returned (or else NULL if the allocation fails). - - Note that new_field() does not copy the pointer array into private - storage; if you modify the contents of the pointer array during forms - processing, all manner of bizarre things might happen. Also note that - any given field may only be connected to one form. - - The functions free_field() and free_form are available to free field - and form objects. It is an error to attempt to free a field connected - to a form, but not vice-versa; thus, you will generally free your form - objects first. - -Fetching and Changing Field Attributes - - Each form field has a number of location and size attributes - associated with it. There are other field attributes used to control - display and editing of the field. Some (for example, the O_STATIC bit) - involve sufficient complications to be covered in sections of their - own later on. We cover the functions used to get and set several basic - attributes here. - - When a field is created, the attributes not specified by the new_field - function are copied from an invisible system default field. In - attribute-setting and -fetching functions, the argument NULL is taken - to mean this field. Changes to it persist as defaults until your forms - application terminates. - - Fetching Size and Location Data - - You can retrieve field sizes and locations through: -int field_info(FIELD *field, /* field from which to fetch */ - int *height, *int width, /* field size */ - int *top, int *left, /* upper left corner */ - int *offscreen, /* number of offscreen rows */ - int *nbuf); /* number of working buffers */ - - This function is a sort of inverse of new_field(); instead of setting - size and location attributes of a new field, it fetches them from an - existing one. - - Changing the Field Location - - It is possible to move a field's location on the screen: -int move_field(FIELD *field, /* field to alter */ - int top, int left); /* new upper-left corner */ - - You can, of course. query the current location through field_info(). - - The Justification Attribute - - One-line fields may be unjustified, justified right, justified left, - or centered. Here is how you manipulate this attribute: -int set_field_just(FIELD *field, /* field to alter */ - int justmode); /* mode to set */ - -int field_just(FIELD *field); /* fetch mode of field */ - - The mode values accepted and returned by this functions are - preprocessor macros NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or - JUSTIFY_CENTER. - - Field Display Attributes - - For each field, you can set a foreground attribute for entered - characters, a background attribute for the entire field, and a pad - character for the unfilled portion of the field. You can also control - pagination of the form. - - This group of four field attributes controls the visual appearance of - the field on the screen, without affecting in any way the data in the - field buffer. -int set_field_fore(FIELD *field, /* field to alter */ - chtype attr); /* attribute to set */ - -chtype field_fore(FIELD *field); /* field to query */ - -int set_field_back(FIELD *field, /* field to alter */ - chtype attr); /* attribute to set */ - -chtype field_back(FIELD *field); /* field to query */ - -int set_field_pad(FIELD *field, /* field to alter */ - int pad); /* pad character to set */ - -chtype field_pad(FIELD *field); - -int set_new_page(FIELD *field, /* field to alter */ - int flag); /* TRUE to force new page */ - -chtype new_page(FIELD *field); /* field to query */ - - The attributes set and returned by the first four functions are normal - curses(3x) display attribute values (A_STANDOUT, A_BOLD, A_REVERSE - etc). The page bit of a field controls whether it is displayed at the - start of a new form screen. - - Field Option Bits - - There is also a large collection of field option bits you can set to - control various aspects of forms processing. You can manipulate them - with these functions: -int set_field_opts(FIELD *field, /* field to alter */ - int attr); /* attribute to set */ - -int field_opts_on(FIELD *field, /* field to alter */ - int attr); /* attributes to turn on */ - -int field_opts_off(FIELD *field, /* field to alter */ - int attr); /* attributes to turn off */ - -int field_opts(FIELD *field); /* field to query */ - - By default, all options are on. Here are the available option bits: - - O_VISIBLE - Controls whether the field is visible on the screen. Can be - used during form processing to hide or pop up fields depending - on the value of parent fields. - - O_ACTIVE - Controls whether the field is active during forms processing - (i.e. visited by form navigation keys). Can be used to make - labels or derived fields with buffer values alterable by the - forms application, not the user. - - O_PUBLIC - Controls whether data is displayed during field entry. If this - option is turned off on a field, the library will accept and - edit data in that field, but it will not be displayed and the - visible field cursor will not move. You can turn off the - O_PUBLIC bit to define password fields. - - O_EDIT - Controls whether the field's data can be modified. When this - option is off, all editing requests except REQ_PREV_CHOICE and - REQ_NEXT_CHOICE will fail. Such read-only fields may be useful - for help messages. - - O_WRAP - Controls word-wrapping in multi-line fields. Normally, when any - character of a (blank-separated) word reaches the end of the - current line, the entire word is wrapped to the next line - (assuming there is one). When this option is off, the word will - be split across the line break. - - O_BLANK - Controls field blanking. When this option is on, entering a - character at the first field position erases the entire field - (except for the just-entered character). - - O_AUTOSKIP - Controls automatic skip to next field when this one fills. - Normally, when the forms user tries to type more data into a - field than will fit, the editing location jumps to next field. - When this option is off, the user's cursor will hang at the end - of the field. This option is ignored in dynamic fields that - have not reached their size limit. - - O_NULLOK - Controls whether validation is applied to blank fields. - Normally, it is not; the user can leave a field blank without - invoking the usual validation check on exit. If this option is - off on a field, exit from it will invoke a validation check. - - O_PASSOK - Controls whether validation occurs on every exit, or only after - the field is modified. Normally the latter is true. Setting - O_PASSOK may be useful if your field's validation function may - change during forms processing. - - O_STATIC - Controls whether the field is fixed to its initial dimensions. - If you turn this off, the field becomes dynamic and will - stretch to fit entered data. - - A field's options cannot be changed while the field is currently - selected. However, options may be changed on posted fields that are - not current. - - The option values are bit-masks and can be composed with logical-or in - the obvious way. - -Field Status - - Every field has a status flag, which is set to FALSE when the field is - created and TRUE when the value in field buffer 0 changes. This flag - can be queried and set directly: -int set_field_status(FIELD *field, /* field to alter */ - int status); /* mode to set */ - -int field_status(FIELD *field); /* fetch mode of field */ - - Setting this flag under program control can be useful if you use the - same form repeatedly, looking for modified fields each time. - - Calling field_status() on a field not currently selected for input - will return a correct value. Calling field_status() on a field that is - currently selected for input may not necessarily give a correct field - status value, because entered data isn't necessarily copied to buffer - zero before the exit validation check. To guarantee that the returned - status value reflects reality, call field_status() either (1) in the - field's exit validation check routine, (2) from the field's or form's - initialization or termination hooks, or (3) just after a - REQ_VALIDATION request has been processed by the forms driver. - -Field User Pointer - - Each field structure contains one character pointer slot that is not - used by the forms library. It is intended to be used by applications - to store private per-field data. You can manipulate it with: -int set_field_userptr(FIELD *field, /* field to alter */ - char *userptr); /* mode to set */ - -char *field_userptr(FIELD *field); /* fetch mode of field */ - - (Properly, this user pointer field ought to have (void *) type. The - (char *) type is retained for System V compatibility.) - - It is valid to set the user pointer of the default field (with a - set_field_userptr() call passed a NULL field pointer.) When a new - field is created, the default-field user pointer is copied to - initialize the new field's user pointer. - -Variable-Sized Fields - - Normally, a field is fixed at the size specified for it at creation - time. If, however, you turn off its O_STATIC bit, it becomes dynamic - and will automatically resize itself to accommodate data as it is - entered. If the field has extra buffers associated with it, they will - grow right along with the main input buffer. - - A one-line dynamic field will have a fixed height (1) but variable - width, scrolling horizontally to display data within the field area as - originally dimensioned and located. A multi-line dynamic field will - have a fixed width, but variable height (number of rows), scrolling - vertically to display data within the field area as originally - dimensioned and located. - - Normally, a dynamic field is allowed to grow without limit. But it is - possible to set an upper limit on the size of a dynamic field. You do - it with this function: -int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ - int max_size); /* upper limit on field size */ - - If the field is one-line, max_size is taken to be a column size limit; - if it is multi-line, it is taken to be a line size limit. To disable - any limit, use an argument of zero. The growth limit can be changed - whether or not the O_STATIC bit is on, but has no effect until it is. - - The following properties of a field change when it becomes dynamic: - * If there is no growth limit, there is no final position of the - field; therefore O_AUTOSKIP and O_NL_OVERLOAD are ignored. - * Field justification will be ignored (though whatever justification - is set up will be retained internally and can be queried). - * The dup_field() and link_field() calls copy dynamic-buffer sizes. - If the O_STATIC option is set on one of a collection of links, - buffer resizing will occur only when the field is edited through - that link. - * The call field_info() will retrieve the original static size of - the field; use dynamic_field_info() to get the actual dynamic - size. - -Field Validation - - By default, a field will accept any data that will fit in its input - buffer. However, it is possible to attach a validation type to a - field. If you do this, any attempt to leave the field while it - contains data that doesn't match the validation type will fail. Some - validation types also have a character-validity check for each time a - character is entered in the field. - - A field's validation check (if any) is not called when - set_field_buffer() modifies the input buffer, nor when that buffer is - changed through a linked field. - - The form library provides a rich set of pre-defined validation types, - and gives you the capability to define custom ones of your own. You - can examine and change field validation attributes with the following - functions: -int set_field_type(FIELD *field, /* field to alter */ - FIELDTYPE *ftype, /* type to associate */ - ...); /* additional arguments*/ - -FIELDTYPE *field_type(FIELD *field); /* field to query */ - - The validation type of a field is considered an attribute of the - field. As with other field attributes, Also, doing set_field_type() - with a NULL field default will change the system default for - validation of newly-created fields. - - Here are the pre-defined validation types: - - TYPE_ALPHA - - This field type accepts alphabetic data; no blanks, no digits, no - special characters (this is checked at character-entry time). It is - set up with: -int set_field_type(FIELD *field, /* field to alter */ - TYPE_ALPHA, /* type to associate */ - int width); /* maximum width of field */ - - The width argument sets a minimum width of data. Typically you'll want - to set this to the field width; if it's greater than the field width, - the validation check will always fail. A minimum width of zero makes - field completion optional. - - TYPE_ALNUM - - This field type accepts alphabetic data and digits; no blanks, no - special characters (this is checked at character-entry time). It is - set up with: -int set_field_type(FIELD *field, /* field to alter */ - TYPE_ALNUM, /* type to associate */ - int width); /* maximum width of field */ - - The width argument sets a minimum width of data. As with TYPE_ALPHA, - typically you'll want to set this to the field width; if it's greater - than the field width, the validation check will always fail. A minimum - width of zero makes field completion optional. - - TYPE_ENUM - - This type allows you to restrict a field's values to be among a - specified set of string values (for example, the two-letter postal - codes for U.S. states). It is set up with: -int set_field_type(FIELD *field, /* field to alter */ - TYPE_ENUM, /* type to associate */ - char **valuelist; /* list of possible values */ - int checkcase; /* case-sensitive? */ - int checkunique); /* must specify uniquely? */ - - The valuelist parameter must point at a NULL-terminated list of valid - strings. The checkcase argument, if true, makes comparison with the - string case-sensitive. - - When the user exits a TYPE_ENUM field, the validation procedure tries - to complete the data in the buffer to a valid entry. If a complete - choice string has been entered, it is of course valid. But it is also - possible to enter a prefix of a valid string and have it completed for - you. - - By default, if you enter such a prefix and it matches more than one - value in the string list, the prefix will be completed to the first - matching value. But the checkunique argument, if true, requires prefix - matches to be unique in order to be valid. - - The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be - particularly useful with these fields. - - TYPE_INTEGER - - This field type accepts an integer. It is set up as follows: -int set_field_type(FIELD *field, /* field to alter */ - TYPE_INTEGER, /* type to associate */ - int padding, /* # places to zero-pad to */ - int vmin, int vmax); /* valid range */ - - Valid characters consist of an optional leading minus and digits. The - range check is performed on exit. If the range maximum is less than or - equal to the minimum, the range is ignored. - - If the value passes its range check, it is padded with as many leading - zero digits as necessary to meet the padding argument. - - A TYPE_INTEGER value buffer can conveniently be interpreted with the C - library function atoi(3). - - TYPE_NUMERIC - - This field type accepts a decimal number. It is set up as follows: -int set_field_type(FIELD *field, /* field to alter */ - TYPE_NUMERIC, /* type to associate */ - int padding, /* # places of precision */ - double vmin, double vmax); /* valid range */ - - Valid characters consist of an optional leading minus and digits. - possibly including a decimal point. If your system supports locale's, - the decimal point character used must be the one defined by your - locale. The range check is performed on exit. If the range maximum is - less than or equal to the minimum, the range is ignored. - - If the value passes its range check, it is padded with as many - trailing zero digits as necessary to meet the padding argument. - - A TYPE_NUMERIC value buffer can conveniently be interpreted with the C - library function atof(3). - - TYPE_REGEXP - - This field type accepts data matching a regular expression. It is set - up as follows: -int set_field_type(FIELD *field, /* field to alter */ - TYPE_REGEXP, /* type to associate */ - char *regexp); /* expression to match */ - - The syntax for regular expressions is that of regcomp(3). The check - for regular-expression match is performed on exit. - -Direct Field Buffer Manipulation - - The chief attribute of a field is its buffer contents. When a form has - been completed, your application usually needs to know the state of - each field buffer. You can find this out with: -char *field_buffer(FIELD *field, /* field to query */ - int bufindex); /* number of buffer to query */ - - Normally, the state of the zero-numbered buffer for each field is set - by the user's editing actions on that field. It's sometimes useful to - be able to set the value of the zero-numbered (or some other) buffer - from your application: -int set_field_buffer(FIELD *field, /* field to alter */ - int bufindex, /* number of buffer to alter */ - char *value); /* string value to set */ - - If the field is not large enough and cannot be resized to a - sufficiently large size to contain the specified value, the value will - be truncated to fit. - - Calling field_buffer() with a null field pointer will raise an error. - Calling field_buffer() on a field not currently selected for input - will return a correct value. Calling field_buffer() on a field that is - currently selected for input may not necessarily give a correct field - buffer value, because entered data isn't necessarily copied to buffer - zero before the exit validation check. To guarantee that the returned - buffer value reflects on-screen reality, call field_buffer() either - (1) in the field's exit validation check routine, (2) from the field's - or form's initialization or termination hooks, or (3) just after a - REQ_VALIDATION request has been processed by the forms driver. - -Attributes of Forms - - As with field attributes, form attributes inherit a default from a - system default form structure. These defaults can be queried or set by - of these functions using a form-pointer argument of NULL. - - The principal attribute of a form is its field list. You can query and - change this list with: -int set_form_fields(FORM *form, /* form to alter */ - FIELD **fields); /* fields to connect */ - -char *form_fields(FORM *form); /* fetch fields of form */ - -int field_count(FORM *form); /* count connect fields */ - - The second argument of set_form_fields() may be a NULL-terminated - field pointer array like the one required by new_form(). In that case, - the old fields of the form are disconnected but not freed (and - eligible to be connected to other forms), then the new fields are - connected. - - It may also be null, in which case the old fields are disconnected - (and not freed) but no new ones are connected. - - The field_count() function simply counts the number of fields - connected to a given from. It returns -1 if the form-pointer argument - is NULL. - -Control of Form Display - - In the overview section, you saw that to display a form you normally - start by defining its size (and fields), posting it, and refreshing - the screen. There is an hidden step before posting, which is the - association of the form with a frame window (actually, a pair of - windows) within which it will be displayed. By default, the forms - library associates every form with the full-screen window stdscr. - - By making this step explicit, you can associate a form with a declared - frame window on your screen display. This can be useful if you want to - adapt the form display to different screen sizes, dynamically tile - forms on the screen, or use a form as part of an interface layout - managed by panels. - - The two windows associated with each form have the same functions as - their analogues in the menu library. Both these windows are painted - when the form is posted and erased when the form is unposted. - - The outer or frame window is not otherwise touched by the form - routines. It exists so the programmer can associate a title, a border, - or perhaps help text with the form and have it properly refreshed or - erased at post/unpost time. The inner window or subwindow is where the - current form page is actually displayed. - - In order to declare your own frame window for a form, you'll need to - know the size of the form's bounding rectangle. You can get this - information with: -int scale_form(FORM *form, /* form to query */ - int *rows, /* form rows */ - int *cols); /* form cols */ - - The form dimensions are passed back in the locations pointed to by the - arguments. Once you have this information, you can use it to declare - of windows, then use one of these functions: -int set_form_win(FORM *form, /* form to alter */ - WINDOW *win); /* frame window to connect */ - -WINDOW *form_win(FORM *form); /* fetch frame window of form */ - -int set_form_sub(FORM *form, /* form to alter */ - WINDOW *win); /* form subwindow to connect */ - -WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ - - Note that curses operations, including refresh(), on the form, should - be done on the frame window, not the form subwindow. - - It is possible to check from your application whether all of a - scrollable field is actually displayed within the menu subwindow. Use - these functions: -int data_ahead(FORM *form); /* form to be queried */ - -int data_behind(FORM *form); /* form to be queried */ - - The function data_ahead() returns TRUE if (a) the current field is - one-line and has undisplayed data off to the right, (b) the current - field is multi-line and there is data off-screen below it. - - The function data_behind() returns TRUE if the first (upper left hand) - character position is off-screen (not being displayed). - - Finally, there is a function to restore the form window's cursor to - the value expected by the forms driver: -int pos_form_cursor(FORM *) /* form to be queried */ - - If your application changes the form window cursor, call this function - before handing control back to the forms driver in order to - re-synchronize it. - -Input Processing in the Forms Driver - - The function form_driver() handles virtualized input requests for form - navigation, editing, and validation requests, just as menu_driver does - for menus (see the section on menu input handling). -int form_driver(FORM *form, /* form to pass input to */ - int request); /* form request code */ - - Your input virtualization function needs to take input and then - convert it to either an alphanumeric character (which is treated as - data to be entered in the currently-selected field), or a forms - processing request. - - The forms driver provides hooks (through input-validation and - field-termination functions) with which your application code can - check that the input taken by the driver matched what was expected. - - Page Navigation Requests - - These requests cause page-level moves through the form, triggering - display of a new form screen. - - REQ_NEXT_PAGE - Move to the next form page. - - REQ_PREV_PAGE - Move to the previous form page. - - REQ_FIRST_PAGE - Move to the first form page. - - REQ_LAST_PAGE - Move to the last form page. - - These requests treat the list as cyclic; that is, REQ_NEXT_PAGE from - the last page goes to the first, and REQ_PREV_PAGE from the first page - goes to the last. - - Inter-Field Navigation Requests - - These requests handle navigation between fields on the same page. - - REQ_NEXT_FIELD - Move to next field. - - REQ_PREV_FIELD - Move to previous field. - - REQ_FIRST_FIELD - Move to the first field. - - REQ_LAST_FIELD - Move to the last field. - - REQ_SNEXT_FIELD - Move to sorted next field. - - REQ_SPREV_FIELD - Move to sorted previous field. - - REQ_SFIRST_FIELD - Move to the sorted first field. - - REQ_SLAST_FIELD - Move to the sorted last field. - - REQ_LEFT_FIELD - Move left to field. - - REQ_RIGHT_FIELD - Move right to field. - - REQ_UP_FIELD - Move up to field. - - REQ_DOWN_FIELD - Move down to field. - - These requests treat the list of fields on a page as cyclic; that is, - REQ_NEXT_FIELD from the last field goes to the first, and - REQ_PREV_FIELD from the first field goes to the last. The order of the - fields for these (and the REQ_FIRST_FIELD and REQ_LAST_FIELD requests) - is simply the order of the field pointers in the form array (as set up - by new_form() or set_form_fields() - - It is also possible to traverse the fields as if they had been sorted - in screen-position order, so the sequence goes left-to-right and - top-to-bottom. To do this, use the second group of four - sorted-movement requests. - - Finally, it is possible to move between fields using visual directions - up, down, right, and left. To accomplish this, use the third group of - four requests. Note, however, that the position of a form for purposes - of these requests is its upper-left corner. - - For example, suppose you have a multi-line field B, and two - single-line fields A and C on the same line with B, with A to the left - of B and C to the right of B. A REQ_MOVE_RIGHT from A will go to B - only if A, B, and C all share the same first line; otherwise it will - skip over B to C. - - Intra-Field Navigation Requests - - These requests drive movement of the edit cursor within the currently - selected field. - - REQ_NEXT_CHAR - Move to next character. - - REQ_PREV_CHAR - Move to previous character. - - REQ_NEXT_LINE - Move to next line. - - REQ_PREV_LINE - Move to previous line. - - REQ_NEXT_WORD - Move to next word. - - REQ_PREV_WORD - Move to previous word. - - REQ_BEG_FIELD - Move to beginning of field. - - REQ_END_FIELD - Move to end of field. - - REQ_BEG_LINE - Move to beginning of line. - - REQ_END_LINE - Move to end of line. - - REQ_LEFT_CHAR - Move left in field. - - REQ_RIGHT_CHAR - Move right in field. - - REQ_UP_CHAR - Move up in field. - - REQ_DOWN_CHAR - Move down in field. - - Each word is separated from the previous and next characters by - whitespace. The commands to move to beginning and end of line or field - look for the first or last non-pad character in their ranges. - - Scrolling Requests - - Fields that are dynamic and have grown and fields explicitly created - with offscreen rows are scrollable. One-line fields scroll - horizontally; multi-line fields scroll vertically. Most scrolling is - triggered by editing and intra-field movement (the library scrolls the - field to keep the cursor visible). It is possible to explicitly - request scrolling with the following requests: - - REQ_SCR_FLINE - Scroll vertically forward a line. - - REQ_SCR_BLINE - Scroll vertically backward a line. - - REQ_SCR_FPAGE - Scroll vertically forward a page. - - REQ_SCR_BPAGE - Scroll vertically backward a page. - - REQ_SCR_FHPAGE - Scroll vertically forward half a page. - - REQ_SCR_BHPAGE - Scroll vertically backward half a page. - - REQ_SCR_FCHAR - Scroll horizontally forward a character. - - REQ_SCR_BCHAR - Scroll horizontally backward a character. - - REQ_SCR_HFLINE - Scroll horizontally one field width forward. - - REQ_SCR_HBLINE - Scroll horizontally one field width backward. - - REQ_SCR_HFHALF - Scroll horizontally one half field width forward. - - REQ_SCR_HBHALF - Scroll horizontally one half field width backward. - - For scrolling purposes, a page of a field is the height of its visible - part. - - Editing Requests - - When you pass the forms driver an ASCII character, it is treated as a - request to add the character to the field's data buffer. Whether this - is an insertion or a replacement depends on the field's edit mode - (insertion is the default. - - The following requests support editing the field and changing the edit - mode: - - REQ_INS_MODE - Set insertion mode. - - REQ_OVL_MODE - Set overlay mode. - - REQ_NEW_LINE - New line request (see below for explanation). - - REQ_INS_CHAR - Insert space at character location. - - REQ_INS_LINE - Insert blank line at character location. - - REQ_DEL_CHAR - Delete character at cursor. - - REQ_DEL_PREV - Delete previous word at cursor. - - REQ_DEL_LINE - Delete line at cursor. - - REQ_DEL_WORD - Delete word at cursor. - - REQ_CLR_EOL - Clear to end of line. - - REQ_CLR_EOF - Clear to end of field. - - REQ_CLEAR_FIELD - Clear entire field. - - The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is - complicated and partly controlled by a pair of forms options. The - special cases are triggered when the cursor is at the beginning of a - field, or on the last line of the field. - - First, we consider REQ_NEW_LINE: - - The normal behavior of REQ_NEW_LINE in insert mode is to break the - current line at the position of the edit cursor, inserting the portion - of the current line after the cursor as a new line following the - current and moving the cursor to the beginning of that new line (you - may think of this as inserting a newline in the field buffer). - - The normal behavior of REQ_NEW_LINE in overlay mode is to clear the - current line from the position of the edit cursor to end of line. The - cursor is then moved to the beginning of the next line. - - However, REQ_NEW_LINE at the beginning of a field, or on the last line - of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD option is - off, this special action is disabled. - - Now, let us consider REQ_DEL_PREV: - - The normal behavior of REQ_DEL_PREV is to delete the previous - character. If insert mode is on, and the cursor is at the start of a - line, and the text on that line will fit on the previous one, it - instead appends the contents of the current line to the previous one - and deletes the current line (you may think of this as deleting a - newline from the field buffer). - - However, REQ_DEL_PREV at the beginning of a field is instead treated - as a REQ_PREV_FIELD. - - If the O_BS_OVERLOAD option is off, this special action is disabled - and the forms driver just returns E_REQUEST_DENIED. - - See Form Options for discussion of how to set and clear the overload - options. - - Order Requests - - If the type of your field is ordered, and has associated functions for - getting the next and previous values of the type from a given value, - there are requests that can fetch that value into the field buffer: - - REQ_NEXT_CHOICE - Place the successor value of the current value in the buffer. - - REQ_PREV_CHOICE - Place the predecessor value of the current value in the buffer. - - Of the built-in field types, only TYPE_ENUM has built-in successor and - predecessor functions. When you define a field type of your own (see - Custom Validation Types), you can associate our own ordering - functions. - - Application Commands - - Form requests are represented as integers above the curses value - greater than KEY_MAX and less than or equal to the constant - MAX_COMMAND. If your input-virtualization routine returns a value - above MAX_COMMAND, the forms driver will ignore it. - -Field Change Hooks - - It is possible to set function hooks to be executed whenever the - current field or form changes. Here are the functions that support - this: -typedef void (*HOOK)(); /* pointer to function returning void */ - -int set_form_init(FORM *form, /* form to alter */ - HOOK hook); /* initialization hook */ - -HOOK form_init(FORM *form); /* form to query */ - -int set_form_term(FORM *form, /* form to alter */ - HOOK hook); /* termination hook */ - -HOOK form_term(FORM *form); /* form to query */ - -int set_field_init(FORM *form, /* form to alter */ - HOOK hook); /* initialization hook */ - -HOOK field_init(FORM *form); /* form to query */ - -int set_field_term(FORM *form, /* form to alter */ - HOOK hook); /* termination hook */ - -HOOK field_term(FORM *form); /* form to query */ - - These functions allow you to either set or query four different hooks. - In each of the set functions, the second argument should be the - address of a hook function. These functions differ only in the timing - of the hook call. - - form_init - This hook is called when the form is posted; also, just after - each page change operation. - - field_init - This hook is called when the form is posted; also, just after - each field change - - field_term - This hook is called just after field validation; that is, just - before the field is altered. It is also called when the form is - unposted. - - form_term - This hook is called when the form is unposted; also, just - before each page change operation. - - Calls to these hooks may be triggered - 1. When user editing requests are processed by the forms driver - 2. When the current page is changed by set_current_field() call - 3. When the current field is changed by a set_form_page() call - - See Field Change Commands for discussion of the latter two cases. - - You can set a default hook for all fields by passing one of the set - functions a NULL first argument. - - You can disable any of these hooks by (re)setting them to NULL, the - default value. - -Field Change Commands - - Normally, navigation through the form will be driven by the user's - input requests. But sometimes it is useful to be able to move the - focus for editing and viewing under control of your application, or - ask which field it currently is in. The following functions help you - accomplish this: -int set_current_field(FORM *form, /* form to alter */ - FIELD *field); /* field to shift to */ - -FIELD *current_field(FORM *form); /* form to query */ - -int field_index(FORM *form, /* form to query */ - FIELD *field); /* field to get index of */ - - The function field_index() returns the index of the given field in the - given form's field array (the array passed to new_form() or - set_form_fields()). - - The initial current field of a form is the first active field on the - first page. The function set_form_fields() resets this. - - It is also possible to move around by pages. -int set_form_page(FORM *form, /* form to alter */ - int page); /* page to go to (0-origin) */ - -int form_page(FORM *form); /* return form's current page */ - - The initial page of a newly-created form is 0. The function - set_form_fields() resets this. - -Form Options - - Like fields, forms may have control option bits. They can be changed - or queried with these functions: -int set_form_opts(FORM *form, /* form to alter */ - int attr); /* attribute to set */ - -int form_opts_on(FORM *form, /* form to alter */ - int attr); /* attributes to turn on */ - -int form_opts_off(FORM *form, /* form to alter */ - int attr); /* attributes to turn off */ - -int form_opts(FORM *form); /* form to query */ - - By default, all options are on. Here are the available option bits: - - O_NL_OVERLOAD - Enable overloading of REQ_NEW_LINE as described in Editing - Requests. The value of this option is ignored on dynamic fields - that have not reached their size limit; these have no last - line, so the circumstances for triggering a REQ_NEXT_FIELD - never arise. - - O_BS_OVERLOAD - Enable overloading of REQ_DEL_PREV as described in Editing - Requests. - - The option values are bit-masks and can be composed with logical-or in - the obvious way. - -Custom Validation Types - - The form library gives you the capability to define custom validation - types of your own. Further, the optional additional arguments of - set_field_type effectively allow you to parameterize validation types. - Most of the complications in the validation-type interface have to do - with the handling of the additional arguments within custom validation - functions. - - Union Types - - The simplest way to create a custom data type is to compose it from - two preexisting ones: -FIELD *link_fieldtype(FIELDTYPE *type1, - FIELDTYPE *type2); - - This function creates a field type that will accept any of the values - legal for either of its argument field types (which may be either - predefined or programmer-defined). If a set_field_type() call later - requires arguments, the new composite type expects all arguments for - the first type, than all arguments for the second. Order functions - (see Order Requests) associated with the component types will work on - the composite; what it does is check the validation function for the - first type, then for the second, to figure what type the buffer - contents should be treated as. - - New Field Types - - To create a field type from scratch, you need to specify one or both - of the following things: - * A character-validation function, to check each character as it is - entered. - * A field-validation function to be applied on exit from the field. - - Here's how you do that: -typedef int (*HOOK)(); /* pointer to function returning int */ - -FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ - HOOK c_validate) /* character validator */ - - -int free_fieldtype(FIELDTYPE *ftype); /* type to free */ - - At least one of the arguments of new_fieldtype() must be non-NULL. The - forms driver will automatically call the new type's validation - functions at appropriate points in processing a field of the new type. - - The function free_fieldtype() deallocates the argument fieldtype, - freeing all storage associated with it. - - Normally, a field validator is called when the user attempts to leave - the field. Its first argument is a field pointer, from which it can - get to field buffer 0 and test it. If the function returns TRUE, the - operation succeeds; if it returns FALSE, the edit cursor stays in the - field. - - A character validator gets the character passed in as a first - argument. It too should return TRUE if the character is valid, FALSE - otherwise. - - Validation Function Arguments - - Your field- and character- validation functions will be passed a - second argument as well. This second argument is the address of a - structure (which we'll call a pile) built from any of the - field-type-specific arguments passed to set_field_type(). If no such - arguments are defined for the field type, this pile pointer argument - will be NULL. - - In order to arrange for such arguments to be passed to your validation - functions, you must associate a small set of storage-management - functions with the type. The forms driver will use these to synthesize - a pile from the trailing arguments of each set_field_type() argument, - and a pointer to the pile will be passed to the validation functions. - - Here is how you make the association: -typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ -typedef void (*VOIDHOOK)(); /* pointer to function returning void */ - -int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ - PTRHOOK make_str, /* make structure from args */ - PTRHOOK copy_str, /* make copy of structure */ - VOIDHOOK free_str); /* free structure storage */ - - Here is how the storage-management hooks are used: - - make_str - This function is called by set_field_type(). It gets one - argument, a va_list of the type-specific arguments passed to - set_field_type(). It is expected to return a pile pointer to a - data structure that encapsulates those arguments. - - copy_str - This function is called by form library functions that allocate - new field instances. It is expected to take a pile pointer, - copy the pile to allocated storage, and return the address of - the pile copy. - - free_str - This function is called by field- and type-deallocation - routines in the library. It takes a pile pointer argument, and - is expected to free the storage of that pile. - - The make_str and copy_str functions may return NULL to signal - allocation failure. The library routines will that call them will - return error indication when this happens. Thus, your validation - functions should never see a NULL file pointer and need not check - specially for it. - - Order Functions For Custom Types - - Some custom field types are simply ordered in the same well-defined - way that TYPE_ENUM is. For such types, it is possible to define - successor and predecessor functions to support the REQ_NEXT_CHOICE and - REQ_PREV_CHOICE requests. Here's how: -typedef int (*INTHOOK)(); /* pointer to function returning int */ - -int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ - INTHOOK succ, /* get successor value */ - INTHOOK pred); /* get predecessor value */ - - The successor and predecessor arguments will each be passed two - arguments; a field pointer, and a pile pointer (as for the validation - functions). They are expected to use the function field_buffer() to - read the current value, and set_field_buffer() on buffer 0 to set the - next or previous value. Either hook may return TRUE to indicate - success (a legal next or previous value was set) or FALSE to indicate - failure. - - Avoiding Problems - - The interface for defining custom types is complicated and tricky. - Rather than attempting to create a custom type entirely from scratch, - you should start by studying the library source code for whichever of - the pre-defined types seems to be closest to what you want. - - Use that code as a model, and evolve it towards what you really want. - You will avoid many problems and annoyances that way. The code in the - ncurses library has been specifically exempted from the package - copyright to support this. - - If your custom type defines order functions, have do something - intuitive with a blank field. A useful convention is to make the - successor of a blank field the types minimum value, and its - predecessor the maximum. |
