17a69bbfbSPeter Wemm Writing Programs with NCURSES 27a69bbfbSPeter Wemm 37a69bbfbSPeter Wemm by Eric S. Raymond and Zeyd M. Ben-Halim 47a69bbfbSPeter Wemm updates since release 1.9.9e by Thomas Dickey 57a69bbfbSPeter Wemm 67a69bbfbSPeter Wemm Contents 77a69bbfbSPeter Wemm 87a69bbfbSPeter Wemm * Introduction 97a69bbfbSPeter Wemm + A Brief History of Curses 107a69bbfbSPeter Wemm + Scope of This Document 117a69bbfbSPeter Wemm + Terminology 127a69bbfbSPeter Wemm * The Curses Library 137a69bbfbSPeter Wemm + An Overview of Curses 147a69bbfbSPeter Wemm o Compiling Programs using Curses 157a69bbfbSPeter Wemm o Updating the Screen 167a69bbfbSPeter Wemm o Standard Windows and Function Naming Conventions 177a69bbfbSPeter Wemm o Variables 187a69bbfbSPeter Wemm + Using the Library 197a69bbfbSPeter Wemm o Starting up 207a69bbfbSPeter Wemm o Output 217a69bbfbSPeter Wemm o Input 227a69bbfbSPeter Wemm o Using Forms Characters 237a69bbfbSPeter Wemm o Character Attributes and Color 247a69bbfbSPeter Wemm o Mouse Interfacing 257a69bbfbSPeter Wemm o Finishing Up 267a69bbfbSPeter Wemm + Function Descriptions 277a69bbfbSPeter Wemm o Initialization and Wrapup 287a69bbfbSPeter Wemm o Causing Output to the Terminal 297a69bbfbSPeter Wemm o Low-Level Capability Access 307a69bbfbSPeter Wemm o Debugging 317a69bbfbSPeter Wemm + Hints, Tips, and Tricks 327a69bbfbSPeter Wemm o Some Notes of Caution 337a69bbfbSPeter Wemm o Temporarily Leaving ncurses Mode 347a69bbfbSPeter Wemm o Using ncurses under xterm 357a69bbfbSPeter Wemm o Handling Multiple Terminal Screens 367a69bbfbSPeter Wemm o Testing for Terminal Capabilities 377a69bbfbSPeter Wemm o Tuning for Speed 387a69bbfbSPeter Wemm o Special Features of ncurses 397a69bbfbSPeter Wemm + Compatibility with Older Versions 407a69bbfbSPeter Wemm o Refresh of Overlapping Windows 417a69bbfbSPeter Wemm o Background Erase 427a69bbfbSPeter Wemm + XSI Curses Conformance 437a69bbfbSPeter Wemm * The Panels Library 447a69bbfbSPeter Wemm + Compiling With the Panels Library 457a69bbfbSPeter Wemm + Overview of Panels 467a69bbfbSPeter Wemm + Panels, Input, and the Standard Screen 477a69bbfbSPeter Wemm + Hiding Panels 487a69bbfbSPeter Wemm + Miscellaneous Other Facilities 497a69bbfbSPeter Wemm * The Menu Library 507a69bbfbSPeter Wemm + Compiling with the menu Library 517a69bbfbSPeter Wemm + Overview of Menus 527a69bbfbSPeter Wemm + Selecting items 537a69bbfbSPeter Wemm + Menu Display 547a69bbfbSPeter Wemm + Menu Windows 557a69bbfbSPeter Wemm + Processing Menu Input 567a69bbfbSPeter Wemm + Miscellaneous Other Features 577a69bbfbSPeter Wemm * The Forms Library 587a69bbfbSPeter Wemm + Compiling with the forms Library 597a69bbfbSPeter Wemm + Overview of Forms 607a69bbfbSPeter Wemm + Creating and Freeing Fields and Forms 617a69bbfbSPeter Wemm + Fetching and Changing Field Attributes 627a69bbfbSPeter Wemm o Fetching Size and Location Data 637a69bbfbSPeter Wemm o Changing the Field Location 647a69bbfbSPeter Wemm o The Justification Attribute 657a69bbfbSPeter Wemm o Field Display Attributes 667a69bbfbSPeter Wemm o Field Option Bits 677a69bbfbSPeter Wemm o Field Status 687a69bbfbSPeter Wemm o Field User Pointer 697a69bbfbSPeter Wemm + Variable-Sized Fields 707a69bbfbSPeter Wemm + Field Validation 717a69bbfbSPeter Wemm o TYPE_ALPHA 727a69bbfbSPeter Wemm o TYPE_ALNUM 737a69bbfbSPeter Wemm o TYPE_ENUM 747a69bbfbSPeter Wemm o TYPE_INTEGER 757a69bbfbSPeter Wemm o TYPE_NUMERIC 767a69bbfbSPeter Wemm o TYPE_REGEXP 777a69bbfbSPeter Wemm + Direct Field Buffer Manipulation 787a69bbfbSPeter Wemm + Attributes of Forms 797a69bbfbSPeter Wemm + Control of Form Display 807a69bbfbSPeter Wemm + Input Processing in the Forms Driver 817a69bbfbSPeter Wemm o Page Navigation Requests 827a69bbfbSPeter Wemm o Inter-Field Navigation Requests 837a69bbfbSPeter Wemm o Intra-Field Navigation Requests 847a69bbfbSPeter Wemm o Scrolling Requests 857a69bbfbSPeter Wemm o Field Editing Requests 867a69bbfbSPeter Wemm o Order Requests 877a69bbfbSPeter Wemm o Application Commands 887a69bbfbSPeter Wemm + Field Change Hooks 897a69bbfbSPeter Wemm + Field Change Commands 907a69bbfbSPeter Wemm + Form Options 917a69bbfbSPeter Wemm + Custom Validation Types 927a69bbfbSPeter Wemm o Union Types 937a69bbfbSPeter Wemm o New Field Types 947a69bbfbSPeter Wemm o Validation Function Arguments 957a69bbfbSPeter Wemm o Order Functions For Custom Types 967a69bbfbSPeter Wemm o Avoiding Problems 977a69bbfbSPeter Wemm _________________________________________________________________ 987a69bbfbSPeter Wemm 997a69bbfbSPeter Wemm Introduction 1007a69bbfbSPeter Wemm 1017a69bbfbSPeter Wemm This document is an introduction to programming with curses. It is not 1027a69bbfbSPeter Wemm an exhaustive reference for the curses Application Programming 1037a69bbfbSPeter Wemm Interface (API); that role is filled by the curses manual pages. 1047a69bbfbSPeter Wemm Rather, it is intended to help C programmers ease into using the 1057a69bbfbSPeter Wemm package. 1067a69bbfbSPeter Wemm 1077a69bbfbSPeter Wemm This document is aimed at C applications programmers not yet 1087a69bbfbSPeter Wemm specifically familiar with ncurses. If you are already an experienced 1097a69bbfbSPeter Wemm curses programmer, you should nevertheless read the sections on Mouse 1107a69bbfbSPeter Wemm Interfacing, Debugging, Compatibility with Older Versions, and Hints, 1117a69bbfbSPeter Wemm Tips, and Tricks. These will bring you up to speed on the special 1127a69bbfbSPeter Wemm features and quirks of the ncurses implementation. If you are not so 1137a69bbfbSPeter Wemm experienced, keep reading. 1147a69bbfbSPeter Wemm 1157a69bbfbSPeter Wemm The curses package is a subroutine library for terminal-independent 1167a69bbfbSPeter Wemm screen-painting and input-event handling which presents a high level 1177a69bbfbSPeter Wemm screen model to the programmer, hiding differences between terminal 1187a69bbfbSPeter Wemm types and doing automatic optimization of output to change one screen 1197a69bbfbSPeter Wemm full of text into another. Curses uses terminfo, which is a database 1207a69bbfbSPeter Wemm format that can describe the capabilities of thousands of different 1217a69bbfbSPeter Wemm terminals. 1227a69bbfbSPeter Wemm 1237a69bbfbSPeter Wemm The curses API may seem something of an archaism on UNIX desktops 1247a69bbfbSPeter Wemm increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX 1257a69bbfbSPeter Wemm still supports tty lines and X supports xterm(1); the curses API has 1267a69bbfbSPeter Wemm the advantage of (a) back-portability to character-cell terminals, and 1277a69bbfbSPeter Wemm (b) simplicity. For an application that does not require bit-mapped 1287a69bbfbSPeter Wemm graphics and multiple fonts, an interface implementation using curses 1297a69bbfbSPeter Wemm will typically be a great deal simpler and less expensive than one 1307a69bbfbSPeter Wemm using an X toolkit. 1317a69bbfbSPeter Wemm 1327a69bbfbSPeter WemmA Brief History of Curses 1337a69bbfbSPeter Wemm 1347a69bbfbSPeter Wemm Historically, the first ancestor of curses was the routines written to 1357a69bbfbSPeter Wemm provide screen-handling for the vi editor; these used the termcap 1367a69bbfbSPeter Wemm database facility (both released in 3BSD) for describing terminal 1377a69bbfbSPeter Wemm capabilities. These routines were abstracted into a documented library 1387a69bbfbSPeter Wemm and first released with the early BSD UNIX versions. All of this work 1397a69bbfbSPeter Wemm was done by students at the University of California (Berkeley 1407a69bbfbSPeter Wemm campus). The curses library was first published in 4.0BSD, a year 1417a69bbfbSPeter Wemm after 3BSD (i.e., late 1980). 1427a69bbfbSPeter Wemm 1437a69bbfbSPeter Wemm After graduation, one of those students went to work at AT&T Bell 1447a69bbfbSPeter Wemm Labs, and made an improved termcap library called terminfo (i.e., 1457a69bbfbSPeter Wemm "libterm"), and adapted the curses library to use this. That was 1467a69bbfbSPeter Wemm subsequently released in System V Release 2 (early 1984). Thereafter, 1477a69bbfbSPeter Wemm other developers added to the curses and terminfo libraries. For 1487a69bbfbSPeter Wemm instance, a student at Cornell University wrote an improved terminfo 1497a69bbfbSPeter Wemm library as well as a tool (tic) to compile the terminal descriptions. 1507a69bbfbSPeter Wemm As a general rule, AT&T did not identify the developers in the 1517a69bbfbSPeter Wemm source-code or documentation; the tic and infocmp programs are the 1527a69bbfbSPeter Wemm exceptions. 1537a69bbfbSPeter Wemm 1547a69bbfbSPeter Wemm System V Release 3 (System III UNIX) from Bell Labs featured a 1557a69bbfbSPeter Wemm rewritten and much-improved curses library, along with the tic program 1567a69bbfbSPeter Wemm (late 1986). 1577a69bbfbSPeter Wemm 1587a69bbfbSPeter Wemm To recap, terminfo is based on Berkeley's termcap database, but 1597a69bbfbSPeter Wemm contains a number of improvements and extensions. Parameterized 1607a69bbfbSPeter Wemm capabilities strings were introduced, making it possible to describe 1617a69bbfbSPeter Wemm multiple video attributes, and colors and to handle far more unusual 1627a69bbfbSPeter Wemm terminals than possible with termcap. In the later AT&T System V 1637a69bbfbSPeter Wemm releases, curses evolved to use more facilities and offer more 1647a69bbfbSPeter Wemm capabilities, going far beyond BSD curses in power and flexibility. 1657a69bbfbSPeter Wemm 1667a69bbfbSPeter WemmScope of This Document 1677a69bbfbSPeter Wemm 1687a69bbfbSPeter Wemm This document describes ncurses, a free implementation of the System V 1697a69bbfbSPeter Wemm curses API with some clearly marked extensions. It includes the 1707a69bbfbSPeter Wemm following System V curses features: 1717a69bbfbSPeter Wemm * Support for multiple screen highlights (BSD curses could only 1727a69bbfbSPeter Wemm handle one "standout" highlight, usually reverse-video). 1737a69bbfbSPeter Wemm * Support for line- and box-drawing using forms characters. 1747a69bbfbSPeter Wemm * Recognition of function keys on input. 1757a69bbfbSPeter Wemm * Color support. 1767a69bbfbSPeter Wemm * Support for pads (windows of larger than screen size on which the 1775ca44d1cSRong-En Fan screen or a subwindow defines a viewport). 1787a69bbfbSPeter Wemm 1794a1a9510SRong-En Fan Also, this package makes use of the insert and delete line and 1804a1a9510SRong-En Fan character features of terminals so equipped, and determines how to 1817a69bbfbSPeter Wemm optimally use these features with no help from the programmer. It 1827a69bbfbSPeter Wemm allows arbitrary combinations of video attributes to be displayed, 1837a69bbfbSPeter Wemm even on terminals that leave "magic cookies" on the screen to mark 1847a69bbfbSPeter Wemm changes in attributes. 1857a69bbfbSPeter Wemm 1867a69bbfbSPeter Wemm The ncurses package can also capture and use event reports from a 1877a69bbfbSPeter Wemm mouse in some environments (notably, xterm under the X window system). 1887a69bbfbSPeter Wemm This document includes tips for using the mouse. 1897a69bbfbSPeter Wemm 1907a69bbfbSPeter Wemm The ncurses package was originated by Pavel Curtis. The original 1917a69bbfbSPeter Wemm maintainer of this package is Zeyd Ben-Halim <zmbenhal@netcom.com>. 1927a69bbfbSPeter Wemm Eric S. Raymond <esr@snark.thyrsus.com> wrote many of the new features 1937a69bbfbSPeter Wemm in versions after 1.8.1 and wrote most of this introduction. Juergen 1947a69bbfbSPeter Wemm Pfeifer wrote all of the menu and forms code as well as the Ada95 1957a69bbfbSPeter Wemm binding. Ongoing work is being done by Thomas Dickey (maintainer). 1967a69bbfbSPeter Wemm Contact the current maintainers at bug-ncurses@gnu.org. 1977a69bbfbSPeter Wemm 1987a69bbfbSPeter Wemm This document also describes the panels extension library, similarly 1997a69bbfbSPeter Wemm modeled on the SVr4 panels facility. This library allows you to 2007a69bbfbSPeter Wemm associate backing store with each of a stack or deck of overlapping 2017a69bbfbSPeter Wemm windows, and provides operations for moving windows around in the 2027a69bbfbSPeter Wemm stack that change their visibility in the natural way (handling window 2037a69bbfbSPeter Wemm overlaps). 2047a69bbfbSPeter Wemm 2057a69bbfbSPeter Wemm Finally, this document describes in detail the menus and forms 2067a69bbfbSPeter Wemm extension libraries, also cloned from System V, which support easy 2077a69bbfbSPeter Wemm construction and sequences of menus and fill-in forms. 2087a69bbfbSPeter Wemm 2097a69bbfbSPeter WemmTerminology 2107a69bbfbSPeter Wemm 2117a69bbfbSPeter Wemm In this document, the following terminology is used with reasonable 2127a69bbfbSPeter Wemm consistency: 2137a69bbfbSPeter Wemm 2147a69bbfbSPeter Wemm window 2157a69bbfbSPeter Wemm A data structure describing a sub-rectangle of the screen 2167a69bbfbSPeter Wemm (possibly the entire screen). You can write to a window as 2177a69bbfbSPeter Wemm though it were a miniature screen, scrolling independently of 2187a69bbfbSPeter Wemm other windows on the physical screen. 2197a69bbfbSPeter Wemm 2207a69bbfbSPeter Wemm screens 2217a69bbfbSPeter Wemm A subset of windows which are as large as the terminal screen, 2227a69bbfbSPeter Wemm i.e., they start at the upper left hand corner and encompass 2237a69bbfbSPeter Wemm the lower right hand corner. One of these, stdscr, is 2247a69bbfbSPeter Wemm automatically provided for the programmer. 2257a69bbfbSPeter Wemm 2267a69bbfbSPeter Wemm terminal screen 2277a69bbfbSPeter Wemm The package's idea of what the terminal display currently looks 2287a69bbfbSPeter Wemm like, i.e., what the user sees now. This is a special screen. 2297a69bbfbSPeter Wemm 2307a69bbfbSPeter Wemm The Curses Library 2317a69bbfbSPeter Wemm 2327a69bbfbSPeter WemmAn Overview of Curses 2337a69bbfbSPeter Wemm 2347a69bbfbSPeter Wemm Compiling Programs using Curses 2357a69bbfbSPeter Wemm 2367a69bbfbSPeter Wemm In order to use the library, it is necessary to have certain types and 2377a69bbfbSPeter Wemm variables defined. Therefore, the programmer must have a line: 2387a69bbfbSPeter Wemm #include <curses.h> 2397a69bbfbSPeter Wemm 2407a69bbfbSPeter Wemm at the top of the program source. The screen package uses the Standard 2417a69bbfbSPeter Wemm I/O library, so <curses.h> includes <stdio.h>. <curses.h> also 2427a69bbfbSPeter Wemm includes <termios.h>, <termio.h>, or <sgtty.h> depending on your 2437a69bbfbSPeter Wemm system. It is redundant (but harmless) for the programmer to do these 2447a69bbfbSPeter Wemm includes, too. In linking with curses you need to have -lncurses in 2457a69bbfbSPeter Wemm your LDFLAGS or on the command line. There is no need for any other 2467a69bbfbSPeter Wemm libraries. 2477a69bbfbSPeter Wemm 2487a69bbfbSPeter Wemm Updating the Screen 2497a69bbfbSPeter Wemm 2507a69bbfbSPeter Wemm In order to update the screen optimally, it is necessary for the 2517a69bbfbSPeter Wemm routines to know what the screen currently looks like and what the 2527a69bbfbSPeter Wemm programmer wants it to look like next. For this purpose, a data type 2537a69bbfbSPeter Wemm (structure) named WINDOW is defined which describes a window image to 2547a69bbfbSPeter Wemm the routines, including its starting position on the screen (the (y, 2557a69bbfbSPeter Wemm x) coordinates of the upper left hand corner) and its size. One of 2567a69bbfbSPeter Wemm these (called curscr, for current screen) is a screen image of what 2577a69bbfbSPeter Wemm the terminal currently looks like. Another screen (called stdscr, for 2587a69bbfbSPeter Wemm standard screen) is provided by default to make changes on. 2597a69bbfbSPeter Wemm 2607a69bbfbSPeter Wemm A window is a purely internal representation. It is used to build and 2617a69bbfbSPeter Wemm store a potential image of a portion of the terminal. It does not bear 2627a69bbfbSPeter Wemm any necessary relation to what is really on the terminal screen; it is 2637a69bbfbSPeter Wemm more like a scratchpad or write buffer. 2647a69bbfbSPeter Wemm 2657a69bbfbSPeter Wemm To make the section of physical screen corresponding to a window 2667a69bbfbSPeter Wemm reflect the contents of the window structure, the routine refresh() 2677a69bbfbSPeter Wemm (or wrefresh() if the window is not stdscr) is called. 2687a69bbfbSPeter Wemm 2697a69bbfbSPeter Wemm A given physical screen section may be within the scope of any number 2707a69bbfbSPeter Wemm of overlapping windows. Also, changes can be made to windows in any 2717a69bbfbSPeter Wemm order, without regard to motion efficiency. Then, at will, the 2727a69bbfbSPeter Wemm programmer can effectively say "make it look like this," and let the 2737a69bbfbSPeter Wemm package implementation determine the most efficient way to repaint the 2747a69bbfbSPeter Wemm screen. 2757a69bbfbSPeter Wemm 2767a69bbfbSPeter Wemm Standard Windows and Function Naming Conventions 2777a69bbfbSPeter Wemm 2787a69bbfbSPeter Wemm As hinted above, the routines can use several windows, but two are 2797a69bbfbSPeter Wemm automatically given: curscr, which knows what the terminal looks like, 2807a69bbfbSPeter Wemm and stdscr, which is what the programmer wants the terminal to look 2817a69bbfbSPeter Wemm like next. The user should never actually access curscr directly. 2827a69bbfbSPeter Wemm Changes should be made to through the API, and then the routine 2837a69bbfbSPeter Wemm refresh() (or wrefresh()) called. 2847a69bbfbSPeter Wemm 2857a69bbfbSPeter Wemm Many functions are defined to use stdscr as a default screen. For 2867a69bbfbSPeter Wemm example, to add a character to stdscr, one calls addch() with the 2877a69bbfbSPeter Wemm desired character as argument. To write to a different window. use the 2887a69bbfbSPeter Wemm routine waddch() (for window-specific addch()) is provided. This 2897a69bbfbSPeter Wemm convention of prepending function names with a "w" when they are to be 2907a69bbfbSPeter Wemm applied to specific windows is consistent. The only routines which do 2917a69bbfbSPeter Wemm not follow it are those for which a window must always be specified. 2927a69bbfbSPeter Wemm 2937a69bbfbSPeter Wemm In order to move the current (y, x) coordinates from one point to 2947a69bbfbSPeter Wemm another, the routines move() and wmove() are provided. However, it is 2957a69bbfbSPeter Wemm often desirable to first move and then perform some I/O operation. In 2967a69bbfbSPeter Wemm order to avoid clumsiness, most I/O routines can be preceded by the 2977a69bbfbSPeter Wemm prefix "mv" and the desired (y, x) coordinates prepended to the 2987a69bbfbSPeter Wemm arguments to the function. For example, the calls 2997a69bbfbSPeter Wemm move(y, x); 3007a69bbfbSPeter Wemm addch(ch); 3017a69bbfbSPeter Wemm 3027a69bbfbSPeter Wemm can be replaced by 3037a69bbfbSPeter Wemm mvaddch(y, x, ch); 3047a69bbfbSPeter Wemm 3057a69bbfbSPeter Wemm and 3067a69bbfbSPeter Wemm wmove(win, y, x); 3077a69bbfbSPeter Wemm waddch(win, ch); 3087a69bbfbSPeter Wemm 3097a69bbfbSPeter Wemm can be replaced by 3107a69bbfbSPeter Wemm mvwaddch(win, y, x, ch); 3117a69bbfbSPeter Wemm 3127a69bbfbSPeter Wemm Note that the window description pointer (win) comes before the added 3137a69bbfbSPeter Wemm (y, x) coordinates. If a function requires a window pointer, it is 3147a69bbfbSPeter Wemm always the first parameter passed. 3157a69bbfbSPeter Wemm 3167a69bbfbSPeter Wemm Variables 3177a69bbfbSPeter Wemm 3187a69bbfbSPeter Wemm The curses library sets some variables describing the terminal 3197a69bbfbSPeter Wemm capabilities. 3207a69bbfbSPeter Wemm type name description 3217a69bbfbSPeter Wemm ------------------------------------------------------------------ 3227a69bbfbSPeter Wemm int LINES number of lines on the terminal 3237a69bbfbSPeter Wemm int COLS number of columns on the terminal 3247a69bbfbSPeter Wemm 3257a69bbfbSPeter Wemm The curses.h also introduces some #define constants and types of 3267a69bbfbSPeter Wemm general usefulness: 3277a69bbfbSPeter Wemm 3287a69bbfbSPeter Wemm bool 3297a69bbfbSPeter Wemm boolean type, actually a "char" (e.g., bool doneit;) 3307a69bbfbSPeter Wemm 3317a69bbfbSPeter Wemm TRUE 3327a69bbfbSPeter Wemm boolean "true" flag (1). 3337a69bbfbSPeter Wemm 3347a69bbfbSPeter Wemm FALSE 3357a69bbfbSPeter Wemm boolean "false" flag (0). 3367a69bbfbSPeter Wemm 3377a69bbfbSPeter Wemm ERR 3387a69bbfbSPeter Wemm error flag returned by routines on a failure (-1). 3397a69bbfbSPeter Wemm 3407a69bbfbSPeter Wemm OK 3417a69bbfbSPeter Wemm error flag returned by routines when things go right. 3427a69bbfbSPeter Wemm 3437a69bbfbSPeter WemmUsing the Library 3447a69bbfbSPeter Wemm 3457a69bbfbSPeter Wemm Now we describe how to actually use the screen package. In it, we 3467a69bbfbSPeter Wemm assume all updating, reading, etc. is applied to stdscr. These 3477a69bbfbSPeter Wemm instructions will work on any window, providing you change the 3487a69bbfbSPeter Wemm function names and parameters as mentioned above. 3497a69bbfbSPeter Wemm 3507a69bbfbSPeter Wemm Here is a sample program to motivate the discussion: 3517a69bbfbSPeter Wemm#include <stdlib.h> 3527a69bbfbSPeter Wemm#include <curses.h> 3537a69bbfbSPeter Wemm#include <signal.h> 3547a69bbfbSPeter Wemm 3557a69bbfbSPeter Wemmstatic void finish(int sig); 3567a69bbfbSPeter Wemm 3577a69bbfbSPeter Wemmint 3587a69bbfbSPeter Wemmmain(int argc, char *argv[]) 3597a69bbfbSPeter Wemm{ 3607a69bbfbSPeter Wemm int num = 0; 3617a69bbfbSPeter Wemm 3627a69bbfbSPeter Wemm /* initialize your non-curses data structures here */ 3637a69bbfbSPeter Wemm 3647a69bbfbSPeter Wemm (void) signal(SIGINT, finish); /* arrange interrupts to terminate */ 3657a69bbfbSPeter Wemm 3667a69bbfbSPeter Wemm (void) initscr(); /* initialize the curses library */ 3677a69bbfbSPeter Wemm keypad(stdscr, TRUE); /* enable keyboard mapping */ 3687a69bbfbSPeter Wemm (void) nonl(); /* tell curses not to do NL->CR/NL on output */ 3697a69bbfbSPeter Wemm (void) cbreak(); /* take input chars one at a time, no wait for \n */ 3707a69bbfbSPeter Wemm (void) echo(); /* echo input - in color */ 3717a69bbfbSPeter Wemm 3727a69bbfbSPeter Wemm if (has_colors()) 3737a69bbfbSPeter Wemm { 3747a69bbfbSPeter Wemm start_color(); 3757a69bbfbSPeter Wemm 3767a69bbfbSPeter Wemm /* 3777a69bbfbSPeter Wemm * Simple color assignment, often all we need. Color pair 0 cannot 3787a69bbfbSPeter Wemm * be redefined. This example uses the same value for the color 3797a69bbfbSPeter Wemm * pair as for the foreground color, though of course that is not 3807a69bbfbSPeter Wemm * necessary: 3817a69bbfbSPeter Wemm */ 3827a69bbfbSPeter Wemm init_pair(1, COLOR_RED, COLOR_BLACK); 3837a69bbfbSPeter Wemm init_pair(2, COLOR_GREEN, COLOR_BLACK); 3847a69bbfbSPeter Wemm init_pair(3, COLOR_YELLOW, COLOR_BLACK); 3857a69bbfbSPeter Wemm init_pair(4, COLOR_BLUE, COLOR_BLACK); 3867a69bbfbSPeter Wemm init_pair(5, COLOR_CYAN, COLOR_BLACK); 3877a69bbfbSPeter Wemm init_pair(6, COLOR_MAGENTA, COLOR_BLACK); 3887a69bbfbSPeter Wemm init_pair(7, COLOR_WHITE, COLOR_BLACK); 3897a69bbfbSPeter Wemm } 3907a69bbfbSPeter Wemm 3917a69bbfbSPeter Wemm for (;;) 3927a69bbfbSPeter Wemm { 3937a69bbfbSPeter Wemm int c = getch(); /* refresh, accept single keystroke of input */ 3947a69bbfbSPeter Wemm attrset(COLOR_PAIR(num % 8)); 3957a69bbfbSPeter Wemm num++; 3967a69bbfbSPeter Wemm 3977a69bbfbSPeter Wemm /* process the command keystroke */ 3987a69bbfbSPeter Wemm } 3997a69bbfbSPeter Wemm 4007a69bbfbSPeter Wemm finish(0); /* we are done */ 4017a69bbfbSPeter Wemm} 4027a69bbfbSPeter Wemm 4037a69bbfbSPeter Wemmstatic void finish(int sig) 4047a69bbfbSPeter Wemm{ 4057a69bbfbSPeter Wemm endwin(); 4067a69bbfbSPeter Wemm 4077a69bbfbSPeter Wemm /* do your non-curses wrapup here */ 4087a69bbfbSPeter Wemm 4097a69bbfbSPeter Wemm exit(0); 4107a69bbfbSPeter Wemm} 4117a69bbfbSPeter Wemm 4127a69bbfbSPeter Wemm Starting up 4137a69bbfbSPeter Wemm 4147a69bbfbSPeter Wemm In order to use the screen package, the routines must know about 4157a69bbfbSPeter Wemm terminal characteristics, and the space for curscr and stdscr must be 4167a69bbfbSPeter Wemm allocated. These function initscr() does both these things. Since it 4177a69bbfbSPeter Wemm must allocate space for the windows, it can overflow memory when 4187a69bbfbSPeter Wemm attempting to do so. On the rare occasions this happens, initscr() 4197a69bbfbSPeter Wemm will terminate the program with an error message. initscr() must 4207a69bbfbSPeter Wemm always be called before any of the routines which affect windows are 4217a69bbfbSPeter Wemm used. If it is not, the program will core dump as soon as either 4227a69bbfbSPeter Wemm curscr or stdscr are referenced. However, it is usually best to wait 4237a69bbfbSPeter Wemm to call it until after you are sure you will need it, like after 4247a69bbfbSPeter Wemm checking for startup errors. Terminal status changing routines like 4257a69bbfbSPeter Wemm nl() and cbreak() should be called after initscr(). 4267a69bbfbSPeter Wemm 4277a69bbfbSPeter Wemm Once the screen windows have been allocated, you can set them up for 4287a69bbfbSPeter Wemm your program. If you want to, say, allow a screen to scroll, use 4297a69bbfbSPeter Wemm scrollok(). If you want the cursor to be left in place after the last 4307a69bbfbSPeter Wemm change, use leaveok(). If this is not done, refresh() will move the 4317a69bbfbSPeter Wemm cursor to the window's current (y, x) coordinates after updating it. 4327a69bbfbSPeter Wemm 4337a69bbfbSPeter Wemm You can create new windows of your own using the functions newwin(), 4347a69bbfbSPeter Wemm derwin(), and subwin(). The routine delwin() will allow you to get rid 4357a69bbfbSPeter Wemm of old windows. All the options described above can be applied to any 4367a69bbfbSPeter Wemm window. 4377a69bbfbSPeter Wemm 4387a69bbfbSPeter Wemm Output 4397a69bbfbSPeter Wemm 4407a69bbfbSPeter Wemm Now that we have set things up, we will want to actually update the 4417a69bbfbSPeter Wemm terminal. The basic functions used to change what will go on a window 4427a69bbfbSPeter Wemm are addch() and move(). addch() adds a character at the current (y, x) 4437a69bbfbSPeter Wemm coordinates. move() changes the current (y, x) coordinates to whatever 4447a69bbfbSPeter Wemm you want them to be. It returns ERR if you try to move off the window. 4457a69bbfbSPeter Wemm As mentioned above, you can combine the two into mvaddch() to do both 4467a69bbfbSPeter Wemm things at once. 4477a69bbfbSPeter Wemm 4487a69bbfbSPeter Wemm The other output functions, such as addstr() and printw(), all call 4497a69bbfbSPeter Wemm addch() to add characters to the window. 4507a69bbfbSPeter Wemm 4517a69bbfbSPeter Wemm After you have put on the window what you want there, when you want 4527a69bbfbSPeter Wemm the portion of the terminal covered by the window to be made to look 4537a69bbfbSPeter Wemm like it, you must call refresh(). In order to optimize finding 4547a69bbfbSPeter Wemm changes, refresh() assumes that any part of the window not changed 4557a69bbfbSPeter Wemm since the last refresh() of that window has not been changed on the 4567a69bbfbSPeter Wemm terminal, i.e., that you have not refreshed a portion of the terminal 4577a69bbfbSPeter Wemm with an overlapping window. If this is not the case, the routine 4587a69bbfbSPeter Wemm touchwin() is provided to make it look like the entire window has been 4597a69bbfbSPeter Wemm changed, thus making refresh() check the whole subsection of the 4607a69bbfbSPeter Wemm terminal for changes. 4617a69bbfbSPeter Wemm 4627a69bbfbSPeter Wemm If you call wrefresh() with curscr as its argument, it will make the 4637a69bbfbSPeter Wemm screen look like curscr thinks it looks like. This is useful for 4647a69bbfbSPeter Wemm implementing a command which would redraw the screen in case it get 4657a69bbfbSPeter Wemm messed up. 4667a69bbfbSPeter Wemm 4677a69bbfbSPeter Wemm Input 4687a69bbfbSPeter Wemm 4697a69bbfbSPeter Wemm The complementary function to addch() is getch() which, if echo is 4707a69bbfbSPeter Wemm set, will call addch() to echo the character. Since the screen package 4717a69bbfbSPeter Wemm needs to know what is on the terminal at all times, if characters are 4727a69bbfbSPeter Wemm to be echoed, the tty must be in raw or cbreak mode. Since initially 4737a69bbfbSPeter Wemm the terminal has echoing enabled and is in ordinary "cooked" mode, one 4747a69bbfbSPeter Wemm or the other has to changed before calling getch(); otherwise, the 4757a69bbfbSPeter Wemm program's output will be unpredictable. 4767a69bbfbSPeter Wemm 4777a69bbfbSPeter Wemm When you need to accept line-oriented input in a window, the functions 4787a69bbfbSPeter Wemm wgetstr() and friends are available. There is even a wscanw() function 4797a69bbfbSPeter Wemm that can do scanf()(3)-style multi-field parsing on window input. 4807a69bbfbSPeter Wemm These pseudo-line-oriented functions turn on echoing while they 4817a69bbfbSPeter Wemm execute. 4827a69bbfbSPeter Wemm 4837a69bbfbSPeter Wemm The example code above uses the call keypad(stdscr, TRUE) to enable 4847a69bbfbSPeter Wemm support for function-key mapping. With this feature, the getch() code 4857a69bbfbSPeter Wemm watches the input stream for character sequences that correspond to 4867a69bbfbSPeter Wemm arrow and function keys. These sequences are returned as 4877a69bbfbSPeter Wemm pseudo-character values. The #define values returned are listed in the 4887a69bbfbSPeter Wemm curses.h The mapping from sequences to #define values is determined by 4897a69bbfbSPeter Wemm key_ capabilities in the terminal's terminfo entry. 4907a69bbfbSPeter Wemm 4917a69bbfbSPeter Wemm Using Forms Characters 4927a69bbfbSPeter Wemm 4937a69bbfbSPeter Wemm The addch() function (and some others, including box() and border()) 4947a69bbfbSPeter Wemm can accept some pseudo-character arguments which are specially defined 4957a69bbfbSPeter Wemm by ncurses. These are #define values set up in the curses.h header; 4967a69bbfbSPeter Wemm see there for a complete list (look for the prefix ACS_). 4977a69bbfbSPeter Wemm 4987a69bbfbSPeter Wemm The most useful of the ACS defines are the forms-drawing characters. 4997a69bbfbSPeter Wemm You can use these to draw boxes and simple graphs on the screen. If 5007a69bbfbSPeter Wemm the terminal does not have such characters, curses.h will map them to 5017a69bbfbSPeter Wemm a recognizable (though ugly) set of ASCII defaults. 5027a69bbfbSPeter Wemm 5037a69bbfbSPeter Wemm Character Attributes and Color 5047a69bbfbSPeter Wemm 5057a69bbfbSPeter Wemm The ncurses package supports screen highlights including standout, 5067a69bbfbSPeter Wemm reverse-video, underline, and blink. It also supports color, which is 5077a69bbfbSPeter Wemm treated as another kind of highlight. 5087a69bbfbSPeter Wemm 5097a69bbfbSPeter Wemm Highlights are encoded, internally, as high bits of the 5107a69bbfbSPeter Wemm pseudo-character type (chtype) that curses.h uses to represent the 5117a69bbfbSPeter Wemm contents of a screen cell. See the curses.h header file for a complete 5127a69bbfbSPeter Wemm list of highlight mask values (look for the prefix A_). 5137a69bbfbSPeter Wemm 5147a69bbfbSPeter Wemm There are two ways to make highlights. One is to logical-or the value 5157a69bbfbSPeter Wemm of the highlights you want into the character argument of an addch() 5167a69bbfbSPeter Wemm call, or any other output call that takes a chtype argument. 5177a69bbfbSPeter Wemm 5187a69bbfbSPeter Wemm The other is to set the current-highlight value. This is logical-ORed 5197a69bbfbSPeter Wemm with any highlight you specify the first way. You do this with the 5207a69bbfbSPeter Wemm functions attron(), attroff(), and attrset(); see the manual pages for 5217a69bbfbSPeter Wemm details. Color is a special kind of highlight. The package actually 5227a69bbfbSPeter Wemm thinks in terms of color pairs, combinations of foreground and 5237a69bbfbSPeter Wemm background colors. The sample code above sets up eight color pairs, 5247a69bbfbSPeter Wemm all of the guaranteed-available colors on black. Note that each color 5257a69bbfbSPeter Wemm pair is, in effect, given the name of its foreground color. Any other 5267a69bbfbSPeter Wemm range of eight non-conflicting values could have been used as the 5277a69bbfbSPeter Wemm first arguments of the init_pair() values. 5287a69bbfbSPeter Wemm 5297a69bbfbSPeter Wemm Once you have done an init_pair() that creates color-pair N, you can 5307a69bbfbSPeter Wemm use COLOR_PAIR(N) as a highlight that invokes that particular color 5317a69bbfbSPeter Wemm combination. Note that COLOR_PAIR(N), for constant N, is itself a 5327a69bbfbSPeter Wemm compile-time constant and can be used in initializers. 5337a69bbfbSPeter Wemm 5347a69bbfbSPeter Wemm Mouse Interfacing 5354a1a9510SRong-En Fan 5367a69bbfbSPeter Wemm The ncurses library also provides a mouse interface. 5377a69bbfbSPeter Wemm 5387a69bbfbSPeter Wemm NOTE: this facility is specific to ncurses, it is not part of 5397a69bbfbSPeter Wemm either the XSI Curses standard, nor of System V Release 4, nor BSD 5407a69bbfbSPeter Wemm curses. System V Release 4 curses contains code with similar 5417a69bbfbSPeter Wemm interface definitions, however it is not documented. Other than by 5427a69bbfbSPeter Wemm disassembling the library, we have no way to determine exactly how 5437a69bbfbSPeter Wemm that mouse code works. Thus, we recommend that you wrap 5447a69bbfbSPeter Wemm mouse-related code in an #ifdef using the feature macro 5457a69bbfbSPeter Wemm NCURSES_MOUSE_VERSION so it will not be compiled and linked on 5467a69bbfbSPeter Wemm non-ncurses systems. 5477a69bbfbSPeter Wemm 5487a69bbfbSPeter Wemm Presently, mouse event reporting works in the following environments: 5497a69bbfbSPeter Wemm * xterm and similar programs such as rxvt. 5507a69bbfbSPeter Wemm * Linux console, when configured with gpm(1), Alessandro Rubini's 5517a69bbfbSPeter Wemm mouse server. 5527a69bbfbSPeter Wemm * FreeBSD sysmouse (console) 5537a69bbfbSPeter Wemm * OS/2 EMX 5547a69bbfbSPeter Wemm 5557a69bbfbSPeter Wemm The mouse interface is very simple. To activate it, you use the 5567a69bbfbSPeter Wemm function mousemask(), passing it as first argument a bit-mask that 5577a69bbfbSPeter Wemm specifies what kinds of events you want your program to be able to 5587a69bbfbSPeter Wemm see. It will return the bit-mask of events that actually become 5597a69bbfbSPeter Wemm visible, which may differ from the argument if the mouse device is not 5607a69bbfbSPeter Wemm capable of reporting some of the event types you specify. 5617a69bbfbSPeter Wemm 5627a69bbfbSPeter Wemm Once the mouse is active, your application's command loop should watch 5637a69bbfbSPeter Wemm for a return value of KEY_MOUSE from wgetch(). When you see this, a 5647a69bbfbSPeter Wemm mouse event report has been queued. To pick it off the queue, use the 5657a69bbfbSPeter Wemm function getmouse() (you must do this before the next wgetch(), 5667a69bbfbSPeter Wemm otherwise another mouse event might come in and make the first one 5677a69bbfbSPeter Wemm inaccessible). 5687a69bbfbSPeter Wemm 5697a69bbfbSPeter Wemm Each call to getmouse() fills a structure (the address of which you 5707a69bbfbSPeter Wemm will pass it) with mouse event data. The event data includes 5717a69bbfbSPeter Wemm zero-origin, screen-relative character-cell coordinates of the mouse 5727a69bbfbSPeter Wemm pointer. It also includes an event mask. Bits in this mask will be 5737a69bbfbSPeter Wemm set, corresponding to the event type being reported. 5747a69bbfbSPeter Wemm 5757a69bbfbSPeter Wemm The mouse structure contains two additional fields which may be 5767a69bbfbSPeter Wemm significant in the future as ncurses interfaces to new kinds of 5777a69bbfbSPeter Wemm pointing device. In addition to x and y coordinates, there is a slot 5787a69bbfbSPeter Wemm for a z coordinate; this might be useful with touch-screens that can 5797a69bbfbSPeter Wemm return a pressure or duration parameter. There is also a device ID 5807a69bbfbSPeter Wemm field, which could be used to distinguish between multiple pointing 5817a69bbfbSPeter Wemm devices. 5827a69bbfbSPeter Wemm 5837a69bbfbSPeter Wemm The class of visible events may be changed at any time via 5847a69bbfbSPeter Wemm mousemask(). Events that can be reported include presses, releases, 5857a69bbfbSPeter Wemm single-, double- and triple-clicks (you can set the maximum 5867a69bbfbSPeter Wemm button-down time for clicks). If you do not make clicks visible, they 5877a69bbfbSPeter Wemm will be reported as press-release pairs. In some environments, the 5887a69bbfbSPeter Wemm event mask may include bits reporting the state of shift, alt, and 5897a69bbfbSPeter Wemm ctrl keys on the keyboard during the event. 5907a69bbfbSPeter Wemm 5917a69bbfbSPeter Wemm A function to check whether a mouse event fell within a given window 5927a69bbfbSPeter Wemm is also supplied. You can use this to see whether a given window 5937a69bbfbSPeter Wemm should consider a mouse event relevant to it. 5947a69bbfbSPeter Wemm 5957a69bbfbSPeter Wemm Because mouse event reporting will not be available in all 5967a69bbfbSPeter Wemm environments, it would be unwise to build ncurses applications that 5977a69bbfbSPeter Wemm require the use of a mouse. Rather, you should use the mouse as a 5987a69bbfbSPeter Wemm shortcut for point-and-shoot commands your application would normally 5997a69bbfbSPeter Wemm accept from the keyboard. Two of the test games in the ncurses 6007a69bbfbSPeter Wemm distribution (bs and knight) contain code that illustrates how this 6017a69bbfbSPeter Wemm can be done. 6027a69bbfbSPeter Wemm 6037a69bbfbSPeter Wemm See the manual page curs_mouse(3X) for full details of the 6047a69bbfbSPeter Wemm mouse-interface functions. 6057a69bbfbSPeter Wemm 6067a69bbfbSPeter Wemm Finishing Up 6077a69bbfbSPeter Wemm 6087a69bbfbSPeter Wemm In order to clean up after the ncurses routines, the routine endwin() 6097a69bbfbSPeter Wemm is provided. It restores tty modes to what they were when initscr() 6107a69bbfbSPeter Wemm was first called, and moves the cursor down to the lower-left corner. 6114a1a9510SRong-En Fan Thus, anytime after the call to initscr, endwin() should be called 6127a69bbfbSPeter Wemm before exiting. 6137a69bbfbSPeter Wemm 6147a69bbfbSPeter WemmFunction Descriptions 6157a69bbfbSPeter Wemm 6167a69bbfbSPeter Wemm We describe the detailed behavior of some important curses functions 6177a69bbfbSPeter Wemm here, as a supplement to the manual page descriptions. 6187a69bbfbSPeter Wemm 6197a69bbfbSPeter Wemm Initialization and Wrapup 6207a69bbfbSPeter Wemm 6217a69bbfbSPeter Wemm initscr() 6227a69bbfbSPeter Wemm The first function called should almost always be initscr(). 6237a69bbfbSPeter Wemm This will determine the terminal type and initialize curses 6247a69bbfbSPeter Wemm data structures. initscr() also arranges that the first call to 6257a69bbfbSPeter Wemm refresh() will clear the screen. If an error occurs a message 6264a1a9510SRong-En Fan is written to standard error and the program exits. Otherwise 6274a1a9510SRong-En Fan it returns a pointer to stdscr. A few functions may be called 6284a1a9510SRong-En Fan before initscr (slk_init(), filter(), ripoffline(), use_env(), 6294a1a9510SRong-En Fan and, if you are using multiple terminals, newterm().) 6304a1a9510SRong-En Fan 6314a1a9510SRong-En Fan endwin() 6324a1a9510SRong-En Fan Your program should always call endwin() before exiting or 6334a1a9510SRong-En Fan shelling out of the program. This function will restore tty 6347a69bbfbSPeter Wemm modes, move the cursor to the lower left corner of the screen, 6357a69bbfbSPeter Wemm reset the terminal into the proper non-visual mode. Calling 6367a69bbfbSPeter Wemm refresh() or doupdate() after a temporary escape from the 6377a69bbfbSPeter Wemm program will restore the ncurses screen from before the escape. 6387a69bbfbSPeter Wemm 6397a69bbfbSPeter Wemm newterm(type, ofp, ifp) 6407a69bbfbSPeter Wemm A program which outputs to more than one terminal should use 6417a69bbfbSPeter Wemm newterm() instead of initscr(). newterm() should be called once 6427a69bbfbSPeter Wemm for each terminal. It returns a variable of type SCREEN * which 6437a69bbfbSPeter Wemm should be saved as a reference to that terminal. (NOTE: a 6447a69bbfbSPeter Wemm SCREEN variable is not a screen in the sense we are describing 6457a69bbfbSPeter Wemm in this introduction, but a collection of parameters used to 6467a69bbfbSPeter Wemm assist in optimizing the display.) The arguments are the type 6477a69bbfbSPeter Wemm of the terminal (a string) and FILE pointers for the output and 6487a69bbfbSPeter Wemm input of the terminal. If type is NULL then the environment 6497a69bbfbSPeter Wemm variable $TERM is used. endwin() should called once at wrapup 6507a69bbfbSPeter Wemm time for each terminal opened using this function. 6517a69bbfbSPeter Wemm 6527a69bbfbSPeter Wemm set_term(new) 6534a1a9510SRong-En Fan This function is used to switch to a different terminal 6544a1a9510SRong-En Fan previously opened by newterm(). The screen reference for the 6554a1a9510SRong-En Fan new terminal is passed as the parameter. The previous terminal 6567a69bbfbSPeter Wemm is returned by the function. All other calls affect only the 6577a69bbfbSPeter Wemm current terminal. 6587a69bbfbSPeter Wemm 6597a69bbfbSPeter Wemm delscreen(sp) 6607a69bbfbSPeter Wemm The inverse of newterm(); deallocates the data structures 6617a69bbfbSPeter Wemm associated with a given SCREEN reference. 6627a69bbfbSPeter Wemm 6637a69bbfbSPeter Wemm Causing Output to the Terminal 6647a69bbfbSPeter Wemm 6657a69bbfbSPeter Wemm refresh() and wrefresh(win) 6667a69bbfbSPeter Wemm These functions must be called to actually get any output on 6677a69bbfbSPeter Wemm the terminal, as other routines merely manipulate data 6687a69bbfbSPeter Wemm structures. wrefresh() copies the named window to the physical 6697a69bbfbSPeter Wemm terminal screen, taking into account what is already there in 6707a69bbfbSPeter Wemm order to do optimizations. refresh() does a refresh of stdscr. 6717a69bbfbSPeter Wemm Unless leaveok() has been enabled, the physical cursor of the 6727a69bbfbSPeter Wemm terminal is left at the location of the window's cursor. 6737a69bbfbSPeter Wemm 6747a69bbfbSPeter Wemm doupdate() and wnoutrefresh(win) 6757a69bbfbSPeter Wemm These two functions allow multiple updates with more efficiency 6767a69bbfbSPeter Wemm than wrefresh. To use them, it is important to understand how 6777a69bbfbSPeter Wemm curses works. In addition to all the window structures, curses 6787a69bbfbSPeter Wemm keeps two data structures representing the terminal screen: a 6797a69bbfbSPeter Wemm physical screen, describing what is actually on the screen, and 6807a69bbfbSPeter Wemm a virtual screen, describing what the programmer wants to have 6817a69bbfbSPeter Wemm on the screen. wrefresh works by first copying the named window 6827a69bbfbSPeter Wemm to the virtual screen (wnoutrefresh()), and then calling the 6837a69bbfbSPeter Wemm routine to update the screen (doupdate()). If the programmer 6847a69bbfbSPeter Wemm wishes to output several windows at once, a series of calls to 6857a69bbfbSPeter Wemm wrefresh will result in alternating calls to wnoutrefresh() and 6867a69bbfbSPeter Wemm doupdate(), causing several bursts of output to the screen. By 6877a69bbfbSPeter Wemm calling wnoutrefresh() for each window, it is then possible to 6887a69bbfbSPeter Wemm call doupdate() once, resulting in only one burst of output, 6897a69bbfbSPeter Wemm with fewer total characters transmitted (this also avoids a 6907a69bbfbSPeter Wemm visually annoying flicker at each update). 6917a69bbfbSPeter Wemm 6927a69bbfbSPeter Wemm Low-Level Capability Access 6937a69bbfbSPeter Wemm 6947a69bbfbSPeter Wemm setupterm(term, filenum, errret) 6957a69bbfbSPeter Wemm This routine is called to initialize a terminal's description, 6967a69bbfbSPeter Wemm without setting up the curses screen structures or changing the 6977a69bbfbSPeter Wemm tty-driver mode bits. term is the character string representing 6987a69bbfbSPeter Wemm the name of the terminal being used. filenum is the UNIX file 6997a69bbfbSPeter Wemm descriptor of the terminal to be used for output. errret is a 7007a69bbfbSPeter Wemm pointer to an integer, in which a success or failure indication 7017a69bbfbSPeter Wemm is returned. The values returned can be 1 (all is well), 0 (no 7027a69bbfbSPeter Wemm such terminal), or -1 (some problem locating the terminfo 7037a69bbfbSPeter Wemm database). 7047a69bbfbSPeter Wemm 7057a69bbfbSPeter Wemm The value of term can be given as NULL, which will cause the 7067a69bbfbSPeter Wemm value of TERM in the environment to be used. The errret pointer 7077a69bbfbSPeter Wemm can also be given as NULL, meaning no error code is wanted. If 7087a69bbfbSPeter Wemm errret is defaulted, and something goes wrong, setupterm() will 7097a69bbfbSPeter Wemm print an appropriate error message and exit, rather than 7107a69bbfbSPeter Wemm returning. Thus, a simple program can call setupterm(0, 1, 0) 7117a69bbfbSPeter Wemm and not worry about initialization errors. 7127a69bbfbSPeter Wemm 7137a69bbfbSPeter Wemm After the call to setupterm(), the global variable cur_term is 7147a69bbfbSPeter Wemm set to point to the current structure of terminal capabilities. 7157a69bbfbSPeter Wemm By calling setupterm() for each terminal, and saving and 7167a69bbfbSPeter Wemm restoring cur_term, it is possible for a program to use two or 7177a69bbfbSPeter Wemm more terminals at once. Setupterm() also stores the names 7187a69bbfbSPeter Wemm section of the terminal description in the global character 7197a69bbfbSPeter Wemm array ttytype[]. Subsequent calls to setupterm() will overwrite 7207a69bbfbSPeter Wemm this array, so you will have to save it yourself if need be. 7217a69bbfbSPeter Wemm 7227a69bbfbSPeter Wemm Debugging 7237a69bbfbSPeter Wemm 7247a69bbfbSPeter Wemm NOTE: These functions are not part of the standard curses API! 7257a69bbfbSPeter Wemm 7267a69bbfbSPeter Wemm trace() 7277a69bbfbSPeter Wemm This function can be used to explicitly set a trace level. If 7287a69bbfbSPeter Wemm the trace level is nonzero, execution of your program will 7297a69bbfbSPeter Wemm generate a file called "trace" in the current working directory 7307a69bbfbSPeter Wemm containing a report on the library's actions. Higher trace 7317a69bbfbSPeter Wemm levels enable more detailed (and verbose) reporting -- see 7327a69bbfbSPeter Wemm comments attached to TRACE_ defines in the curses.h file for 7337a69bbfbSPeter Wemm details. (It is also possible to set a trace level by assigning 7347a69bbfbSPeter Wemm a trace level value to the environment variable NCURSES_TRACE). 7357a69bbfbSPeter Wemm 7367a69bbfbSPeter Wemm _tracef() 7377a69bbfbSPeter Wemm This function can be used to output your own debugging 7387a69bbfbSPeter Wemm information. It is only available only if you link with 7397a69bbfbSPeter Wemm -lncurses_g. It can be used the same way as printf(), only it 7407a69bbfbSPeter Wemm outputs a newline after the end of arguments. The output goes 7417a69bbfbSPeter Wemm to a file called trace in the current directory. 7427a69bbfbSPeter Wemm 7437a69bbfbSPeter Wemm Trace logs can be difficult to interpret due to the sheer volume of 7447a69bbfbSPeter Wemm data dumped in them. There is a script called tracemunch included with 7457a69bbfbSPeter Wemm the ncurses distribution that can alleviate this problem somewhat; it 7467a69bbfbSPeter Wemm compacts long sequences of similar operations into more succinct 7477a69bbfbSPeter Wemm single-line pseudo-operations. These pseudo-ops can be distinguished 7487a69bbfbSPeter Wemm by the fact that they are named in capital letters. 7497a69bbfbSPeter Wemm 7507a69bbfbSPeter WemmHints, Tips, and Tricks 7517a69bbfbSPeter Wemm 7527a69bbfbSPeter Wemm The ncurses manual pages are a complete reference for this library. In 7537a69bbfbSPeter Wemm the remainder of this document, we discuss various useful methods that 7547a69bbfbSPeter Wemm may not be obvious from the manual page descriptions. 7557a69bbfbSPeter Wemm 7567a69bbfbSPeter Wemm Some Notes of Caution 7577a69bbfbSPeter Wemm 7587a69bbfbSPeter Wemm If you find yourself thinking you need to use noraw() or nocbreak(), 7597a69bbfbSPeter Wemm think again and move carefully. It is probably better design to use 7607a69bbfbSPeter Wemm getstr() or one of its relatives to simulate cooked mode. The noraw() 7617a69bbfbSPeter Wemm and nocbreak() functions try to restore cooked mode, but they may end 7627a69bbfbSPeter Wemm up clobbering some control bits set before you started your 7637a69bbfbSPeter Wemm application. Also, they have always been poorly documented, and are 7647a69bbfbSPeter Wemm likely to hurt your application's usability with other curses 7657a69bbfbSPeter Wemm libraries. 7667a69bbfbSPeter Wemm 7677a69bbfbSPeter Wemm Bear in mind that refresh() is a synonym for wrefresh(stdscr). Do not 7687a69bbfbSPeter Wemm try to mix use of stdscr with use of windows declared by newwin(); a 7697a69bbfbSPeter Wemm refresh() call will blow them off the screen. The right way to handle 7707a69bbfbSPeter Wemm this is to use subwin(), or not touch stdscr at all and tile your 7717a69bbfbSPeter Wemm screen with declared windows which you then wnoutrefresh() somewhere 7727a69bbfbSPeter Wemm in your program event loop, with a single doupdate() call to trigger 7737a69bbfbSPeter Wemm actual repainting. 7747a69bbfbSPeter Wemm 7757a69bbfbSPeter Wemm You are much less likely to run into problems if you design your 7767a69bbfbSPeter Wemm screen layouts to use tiled rather than overlapping windows. 7777a69bbfbSPeter Wemm Historically, curses support for overlapping windows has been weak, 7787a69bbfbSPeter Wemm fragile, and poorly documented. The ncurses library is not yet an 7797a69bbfbSPeter Wemm exception to this rule. 7807a69bbfbSPeter Wemm 7817a69bbfbSPeter Wemm There is a panels library included in the ncurses distribution that 7827a69bbfbSPeter Wemm does a pretty good job of strengthening the overlapping-windows 7837a69bbfbSPeter Wemm facilities. 7847a69bbfbSPeter Wemm 7857a69bbfbSPeter Wemm Try to avoid using the global variables LINES and COLS. Use getmaxyx() 7867a69bbfbSPeter Wemm on the stdscr context instead. Reason: your code may be ported to run 7877a69bbfbSPeter Wemm in an environment with window resizes, in which case several screens 7887a69bbfbSPeter Wemm could be open with different sizes. 7897a69bbfbSPeter Wemm 7907a69bbfbSPeter Wemm Temporarily Leaving NCURSES Mode 7917a69bbfbSPeter Wemm 7927a69bbfbSPeter Wemm Sometimes you will want to write a program that spends most of its 7937a69bbfbSPeter Wemm time in screen mode, but occasionally returns to ordinary "cooked" 7947a69bbfbSPeter Wemm mode. A common reason for this is to support shell-out. This behavior 7957a69bbfbSPeter Wemm is simple to arrange in ncurses. 7967a69bbfbSPeter Wemm 7977a69bbfbSPeter Wemm To leave ncurses mode, call endwin() as you would if you were 7987a69bbfbSPeter Wemm intending to terminate the program. This will take the screen back to 7997a69bbfbSPeter Wemm cooked mode; you can do your shell-out. When you want to return to 8007a69bbfbSPeter Wemm ncurses mode, simply call refresh() or doupdate(). This will repaint 8015ca44d1cSRong-En Fan the screen. 8025ca44d1cSRong-En Fan 8035ca44d1cSRong-En Fan There is a boolean function, isendwin(), which code can use to test 8047a69bbfbSPeter Wemm whether ncurses screen mode is active. It returns TRUE in the interval 8057a69bbfbSPeter Wemm between an endwin() call and the following refresh(), FALSE otherwise. 8067a69bbfbSPeter Wemm 8077a69bbfbSPeter Wemm Here is some sample code for shellout: 8087a69bbfbSPeter Wemm addstr("Shelling out..."); 8097a69bbfbSPeter Wemm def_prog_mode(); /* save current tty modes */ 8107a69bbfbSPeter Wemm endwin(); /* restore original tty modes */ 8117a69bbfbSPeter Wemm system("sh"); /* run shell */ 8127a69bbfbSPeter Wemm addstr("returned.\n"); /* prepare return message */ 8135ca44d1cSRong-En Fan refresh(); /* restore save modes, repaint screen */ 8145ca44d1cSRong-En Fan 8155ca44d1cSRong-En Fan Using NCURSES under XTERM 8165ca44d1cSRong-En Fan 8175ca44d1cSRong-En Fan A resize operation in X sends SIGWINCH to the application running 8185ca44d1cSRong-En Fan under xterm. The easiest way to handle SIGWINCH is to do an endwin, 8195ca44d1cSRong-En Fan followed by an refresh and a screen repaint you code yourself. The 8207a69bbfbSPeter Wemm refresh will pick up the new screen size from the xterm's environment. 8217a69bbfbSPeter Wemm 8227a69bbfbSPeter Wemm That is the standard way, of course (it even works with some vendor's 8237a69bbfbSPeter Wemm curses implementations). Its drawback is that it clears the screen to 8247a69bbfbSPeter Wemm reinitialize the display, and does not resize subwindows which must be 8257a69bbfbSPeter Wemm shrunk. Ncurses provides an extension which works better, the 8267a69bbfbSPeter Wemm resizeterm function. That function ensures that all windows are 8277a69bbfbSPeter Wemm limited to the new screen dimensions, and pads stdscr with blanks if 8287a69bbfbSPeter Wemm the screen is larger. 8297a69bbfbSPeter Wemm 8307a69bbfbSPeter Wemm The ncurses library provides a SIGWINCH signal handler, which pushes a 8317a69bbfbSPeter Wemm KEY_RESIZE via the wgetch() calls. When ncurses returns that code, it 8327a69bbfbSPeter Wemm calls resizeterm to update the size of the standard screen's window, 8337a69bbfbSPeter Wemm repainting that (filling with blanks or truncating as needed). It also 8347a69bbfbSPeter Wemm resizes other windows, but its effect may be less satisfactory because 8357a69bbfbSPeter Wemm it cannot know how you want the screen re-painted. You will usually 8367a69bbfbSPeter Wemm have to write special-purpose code to handle KEY_RESIZE yourself. 8377a69bbfbSPeter Wemm 8387a69bbfbSPeter Wemm Handling Multiple Terminal Screens 8397a69bbfbSPeter Wemm 8407a69bbfbSPeter Wemm The initscr() function actually calls a function named newterm() to do 8417a69bbfbSPeter Wemm most of its work. If you are writing a program that opens multiple 8427a69bbfbSPeter Wemm terminals, use newterm() directly. 8437a69bbfbSPeter Wemm 8447a69bbfbSPeter Wemm For each call, you will have to specify a terminal type and a pair of 8457a69bbfbSPeter Wemm file pointers; each call will return a screen reference, and stdscr 8467a69bbfbSPeter Wemm will be set to the last one allocated. You will switch between screens 8477a69bbfbSPeter Wemm with the set_term call. Note that you will also have to call 8487a69bbfbSPeter Wemm def_shell_mode and def_prog_mode on each tty yourself. 8497a69bbfbSPeter Wemm 8507a69bbfbSPeter Wemm Testing for Terminal Capabilities 8517a69bbfbSPeter Wemm 8527a69bbfbSPeter Wemm Sometimes you may want to write programs that test for the presence of 8537a69bbfbSPeter Wemm various capabilities before deciding whether to go into ncurses mode. 8547a69bbfbSPeter Wemm An easy way to do this is to call setupterm(), then use the functions 8557a69bbfbSPeter Wemm tigetflag(), tigetnum(), and tigetstr() to do your testing. 8567a69bbfbSPeter Wemm 8577a69bbfbSPeter Wemm A particularly useful case of this often comes up when you want to 8587a69bbfbSPeter Wemm test whether a given terminal type should be treated as "smart" 8597a69bbfbSPeter Wemm (cursor-addressable) or "stupid". The right way to test this is to see 8607a69bbfbSPeter Wemm if the return value of tigetstr("cup") is non-NULL. Alternatively, you 8617a69bbfbSPeter Wemm can include the term.h file and test the value of the macro 8627a69bbfbSPeter Wemm cursor_address. 8637a69bbfbSPeter Wemm 8647a69bbfbSPeter Wemm Tuning for Speed 8657a69bbfbSPeter Wemm 8667a69bbfbSPeter Wemm Use the addchstr() family of functions for fast screen-painting of 8677a69bbfbSPeter Wemm text when you know the text does not contain any control characters. 8687a69bbfbSPeter Wemm Try to make attribute changes infrequent on your screens. Do not use 8697a69bbfbSPeter Wemm the immedok() option! 8707a69bbfbSPeter Wemm 8717a69bbfbSPeter Wemm Special Features of NCURSES 8727a69bbfbSPeter Wemm 8737a69bbfbSPeter Wemm The wresize() function allows you to resize a window in place. The 8747a69bbfbSPeter Wemm associated resizeterm() function simplifies the construction of 8757a69bbfbSPeter Wemm SIGWINCH handlers, for resizing all windows. 8767a69bbfbSPeter Wemm 8777a69bbfbSPeter Wemm The define_key() function allows you to define at runtime function-key 8787a69bbfbSPeter Wemm control sequences which are not in the terminal description. The 8797a69bbfbSPeter Wemm keyok() function allows you to temporarily enable or disable 8807a69bbfbSPeter Wemm interpretation of any function-key control sequence. 8817a69bbfbSPeter Wemm 8827a69bbfbSPeter Wemm The use_default_colors() function allows you to construct applications 8837a69bbfbSPeter Wemm which can use the terminal's default foreground and background colors 8847a69bbfbSPeter Wemm as an additional "default" color. Several terminal emulators support 8857a69bbfbSPeter Wemm this feature, which is based on ISO 6429. 8867a69bbfbSPeter Wemm 8877a69bbfbSPeter Wemm Ncurses supports up 16 colors, unlike SVr4 curses which defines only 8887a69bbfbSPeter Wemm 8. While most terminals which provide color allow only 8 colors, about 8897a69bbfbSPeter Wemm a quarter (including XFree86 xterm) support 16 colors. 8907a69bbfbSPeter Wemm 8915ca44d1cSRong-En FanCompatibility with Older Versions 8925ca44d1cSRong-En Fan 8935ca44d1cSRong-En Fan Despite our best efforts, there are some differences between ncurses 8945ca44d1cSRong-En Fan and the (undocumented!) behavior of older curses implementations. 8955ca44d1cSRong-En Fan These arise from ambiguities or omissions in the documentation of the 8967a69bbfbSPeter Wemm API. 8977a69bbfbSPeter Wemm 8987a69bbfbSPeter Wemm Refresh of Overlapping Windows 8997a69bbfbSPeter Wemm 9007a69bbfbSPeter Wemm If you define two windows A and B that overlap, and then alternately 9017a69bbfbSPeter Wemm scribble on and refresh them, the changes made to the overlapping 9027a69bbfbSPeter Wemm region under historic curses versions were often not documented 9037a69bbfbSPeter Wemm precisely. 9047a69bbfbSPeter Wemm 9057a69bbfbSPeter Wemm To understand why this is a problem, remember that screen updates are 9067a69bbfbSPeter Wemm calculated between two representations of the entire display. The 9077a69bbfbSPeter Wemm documentation says that when you refresh a window, it is first copied 9087a69bbfbSPeter Wemm to the virtual screen, and then changes are calculated to update the 9097a69bbfbSPeter Wemm physical screen (and applied to the terminal). But "copied to" is not 9107a69bbfbSPeter Wemm very specific, and subtle differences in how copying works can produce 9117a69bbfbSPeter Wemm different behaviors in the case where two overlapping windows are each 9127a69bbfbSPeter Wemm being refreshed at unpredictable intervals. 9137a69bbfbSPeter Wemm 9147a69bbfbSPeter Wemm What happens to the overlapping region depends on what wnoutrefresh() 9157a69bbfbSPeter Wemm does with its argument -- what portions of the argument window it 9167a69bbfbSPeter Wemm copies to the virtual screen. Some implementations do "change copy", 9177a69bbfbSPeter Wemm copying down only locations in the window that have changed (or been 9187a69bbfbSPeter Wemm marked changed with wtouchln() and friends). Some implementations do 9197a69bbfbSPeter Wemm "entire copy", copying all window locations to the virtual screen 9207a69bbfbSPeter Wemm whether or not they have changed. 9217a69bbfbSPeter Wemm 9227a69bbfbSPeter Wemm The ncurses library itself has not always been consistent on this 9237a69bbfbSPeter Wemm score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. 9247a69bbfbSPeter Wemm Versions 1.8.6 and older, and versions 1.9.9 and newer, do change 9257a69bbfbSPeter Wemm copy. 9267a69bbfbSPeter Wemm 9277a69bbfbSPeter Wemm For most commercial curses implementations, it is not documented and 9287a69bbfbSPeter Wemm not known for sure (at least not to the ncurses maintainers) whether 9294a1a9510SRong-En Fan they do change copy or entire copy. We know that System V release 3 9307a69bbfbSPeter Wemm curses has logic in it that looks like an attempt to do change copy, 9317a69bbfbSPeter Wemm but the surrounding logic and data representations are sufficiently 9327a69bbfbSPeter Wemm complex, and our knowledge sufficiently indirect, that it is hard to 9337a69bbfbSPeter Wemm know whether this is reliable. It is not clear what the SVr4 9347a69bbfbSPeter Wemm documentation and XSI standard intend. The XSI Curses standard barely 9357a69bbfbSPeter Wemm mentions wnoutrefresh(); the SVr4 documents seem to be describing 9367a69bbfbSPeter Wemm entire-copy, but it is possible with some effort and straining to read 9377a69bbfbSPeter Wemm them the other way. 9387a69bbfbSPeter Wemm 9397a69bbfbSPeter Wemm It might therefore be unwise to rely on either behavior in programs 9407a69bbfbSPeter Wemm that might have to be linked with other curses implementations. 9417a69bbfbSPeter Wemm Instead, you can do an explicit touchwin() before the wnoutrefresh() 9427a69bbfbSPeter Wemm call to guarantee an entire-contents copy anywhere. 9437a69bbfbSPeter Wemm 9447a69bbfbSPeter Wemm The really clean way to handle this is to use the panels library. If, 9457a69bbfbSPeter Wemm when you want a screen update, you do update_panels(), it will do all 9467a69bbfbSPeter Wemm the necessary wnoutrefresh() calls for whatever panel stacking order 9477a69bbfbSPeter Wemm you have defined. Then you can do one doupdate() and there will be a 9487a69bbfbSPeter Wemm single burst of physical I/O that will do all your updates. 9497a69bbfbSPeter Wemm 9507a69bbfbSPeter Wemm Background Erase 9517a69bbfbSPeter Wemm 9527a69bbfbSPeter Wemm If you have been using a very old versions of ncurses (1.8.7 or older) 9537a69bbfbSPeter Wemm you may be surprised by the behavior of the erase functions. In older 9547a69bbfbSPeter Wemm versions, erased areas of a window were filled with a blank modified 9557a69bbfbSPeter Wemm by the window's current attribute (as set by wattrset(), wattron(), 9567a69bbfbSPeter Wemm wattroff() and friends). 9577a69bbfbSPeter Wemm 9587a69bbfbSPeter Wemm In newer versions, this is not so. Instead, the attribute of erased 9597a69bbfbSPeter Wemm blanks is normal unless and until it is modified by the functions 9607a69bbfbSPeter Wemm bkgdset() or wbkgdset(). 9617a69bbfbSPeter Wemm 9627a69bbfbSPeter Wemm This change in behavior conforms ncurses to System V Release 4 and the 9637a69bbfbSPeter Wemm XSI Curses standard. 9647a69bbfbSPeter Wemm 9657a69bbfbSPeter WemmXSI Curses Conformance 9667a69bbfbSPeter Wemm 9677a69bbfbSPeter Wemm The ncurses library is intended to be base-level conformant with the 9687a69bbfbSPeter Wemm XSI Curses standard from X/Open. Many extended-level features (in 9697a69bbfbSPeter Wemm fact, almost all features not directly concerned with wide characters 9707a69bbfbSPeter Wemm and internationalization) are also supported. 9717a69bbfbSPeter Wemm 9727a69bbfbSPeter Wemm One effect of XSI conformance is the change in behavior described 9737a69bbfbSPeter Wemm under "Background Erase -- Compatibility with Old Versions". 9747a69bbfbSPeter Wemm 9757a69bbfbSPeter Wemm Also, ncurses meets the XSI requirement that every macro entry point 9767a69bbfbSPeter Wemm have a corresponding function which may be linked (and will be 9777a69bbfbSPeter Wemm prototype-checked) if the macro definition is disabled with #undef. 9787a69bbfbSPeter Wemm 9797a69bbfbSPeter Wemm The Panels Library 9807a69bbfbSPeter Wemm 9817a69bbfbSPeter Wemm The ncurses library by itself provides good support for screen 9827a69bbfbSPeter Wemm displays in which the windows are tiled (non-overlapping). In the more 9837a69bbfbSPeter Wemm general case that windows may overlap, you have to use a series of 9847a69bbfbSPeter Wemm wnoutrefresh() calls followed by a doupdate(), and be careful about 9857a69bbfbSPeter Wemm the order you do the window refreshes in. It has to be bottom-upwards, 9867a69bbfbSPeter Wemm otherwise parts of windows that should be obscured will show through. 9877a69bbfbSPeter Wemm 9887a69bbfbSPeter Wemm When your interface design is such that windows may dive deeper into 9897a69bbfbSPeter Wemm the visibility stack or pop to the top at runtime, the resulting 9907a69bbfbSPeter Wemm book-keeping can be tedious and difficult to get right. Hence the 9917a69bbfbSPeter Wemm panels library. 9927a69bbfbSPeter Wemm 9937a69bbfbSPeter Wemm The panel library first appeared in AT&T System V. The version 9947a69bbfbSPeter Wemm documented here is the panel code distributed with ncurses. 9957a69bbfbSPeter Wemm 9967a69bbfbSPeter WemmCompiling With the Panels Library 9977a69bbfbSPeter Wemm 9987a69bbfbSPeter Wemm Your panels-using modules must import the panels library declarations 9997a69bbfbSPeter Wemm with 10007a69bbfbSPeter Wemm #include <panel.h> 10017a69bbfbSPeter Wemm 10027a69bbfbSPeter Wemm and must be linked explicitly with the panels library using an -lpanel 10037a69bbfbSPeter Wemm argument. Note that they must also link the ncurses library with 10047a69bbfbSPeter Wemm -lncurses. Many linkers are two-pass and will accept either order, but 10057a69bbfbSPeter Wemm it is still good practice to put -lpanel first and -lncurses second. 10067a69bbfbSPeter Wemm 10077a69bbfbSPeter WemmOverview of Panels 10087a69bbfbSPeter Wemm 10097a69bbfbSPeter Wemm A panel object is a window that is implicitly treated as part of a 10107a69bbfbSPeter Wemm deck including all other panel objects. The deck has an implicit 10117a69bbfbSPeter Wemm bottom-to-top visibility order. The panels library includes an update 10127a69bbfbSPeter Wemm function (analogous to refresh()) that displays all panels in the deck 10137a69bbfbSPeter Wemm in the proper order to resolve overlaps. The standard window, stdscr, 10147a69bbfbSPeter Wemm is considered below all panels. 10157a69bbfbSPeter Wemm 10167a69bbfbSPeter Wemm Details on the panels functions are available in the man pages. We 10177a69bbfbSPeter Wemm will just hit the highlights here. 10187a69bbfbSPeter Wemm 10197a69bbfbSPeter Wemm You create a panel from a window by calling new_panel() on a window 10207a69bbfbSPeter Wemm pointer. It then becomes the top of the deck. The panel's window is 10217a69bbfbSPeter Wemm available as the value of panel_window() called with the panel pointer 10227a69bbfbSPeter Wemm as argument. 10237a69bbfbSPeter Wemm 10247a69bbfbSPeter Wemm You can delete a panel (removing it from the deck) with del_panel. 10257a69bbfbSPeter Wemm This will not deallocate the associated window; you have to do that 10267a69bbfbSPeter Wemm yourself. You can replace a panel's window with a different window by 10277a69bbfbSPeter Wemm calling replace_window. The new window may be of different size; the 10287a69bbfbSPeter Wemm panel code will re-compute all overlaps. This operation does not 10297a69bbfbSPeter Wemm change the panel's position in the deck. 10307a69bbfbSPeter Wemm 10317a69bbfbSPeter Wemm To move a panel's window, use move_panel(). The mvwin() function on 10327a69bbfbSPeter Wemm the panel's window is not sufficient because it does not update the 10337a69bbfbSPeter Wemm panels library's representation of where the windows are. This 10347a69bbfbSPeter Wemm operation leaves the panel's depth, contents, and size unchanged. 10357a69bbfbSPeter Wemm 10367a69bbfbSPeter Wemm Two functions (top_panel(), bottom_panel()) are provided for 10377a69bbfbSPeter Wemm rearranging the deck. The first pops its argument window to the top of 10387a69bbfbSPeter Wemm the deck; the second sends it to the bottom. Either operation leaves 10397a69bbfbSPeter Wemm the panel's screen location, contents, and size unchanged. 10407a69bbfbSPeter Wemm 10417a69bbfbSPeter Wemm The function update_panels() does all the wnoutrefresh() calls needed 10427a69bbfbSPeter Wemm to prepare for doupdate() (which you must call yourself, afterwards). 10437a69bbfbSPeter Wemm 10447a69bbfbSPeter Wemm Typically, you will want to call update_panels() and doupdate() just 10457a69bbfbSPeter Wemm before accepting command input, once in each cycle of interaction with 10467a69bbfbSPeter Wemm the user. If you call update_panels() after each and every panel 10477a69bbfbSPeter Wemm write, you will generate a lot of unnecessary refresh activity and 10487a69bbfbSPeter Wemm screen flicker. 10497a69bbfbSPeter Wemm 10507a69bbfbSPeter WemmPanels, Input, and the Standard Screen 10517a69bbfbSPeter Wemm 10527a69bbfbSPeter Wemm You should not mix wnoutrefresh() or wrefresh() operations with panels 10537a69bbfbSPeter Wemm code; this will work only if the argument window is either in the top 10547a69bbfbSPeter Wemm panel or unobscured by any other panels. 10557a69bbfbSPeter Wemm 10567a69bbfbSPeter Wemm The stsdcr window is a special case. It is considered below all 10577a69bbfbSPeter Wemm panels. Because changes to panels may obscure parts of stdscr, though, 10587a69bbfbSPeter Wemm you should call update_panels() before doupdate() even when you only 10597a69bbfbSPeter Wemm change stdscr. 10607a69bbfbSPeter Wemm 10617a69bbfbSPeter Wemm Note that wgetch automatically calls wrefresh. Therefore, before 10627a69bbfbSPeter Wemm requesting input from a panel window, you need to be sure that the 10637a69bbfbSPeter Wemm panel is totally unobscured. 10647a69bbfbSPeter Wemm 10657a69bbfbSPeter Wemm There is presently no way to display changes to one obscured panel 10667a69bbfbSPeter Wemm without repainting all panels. 10677a69bbfbSPeter Wemm 10687a69bbfbSPeter WemmHiding Panels 10697a69bbfbSPeter Wemm 10707a69bbfbSPeter Wemm It is possible to remove a panel from the deck temporarily; use 10717a69bbfbSPeter Wemm hide_panel for this. Use show_panel() to render it visible again. The 10727a69bbfbSPeter Wemm predicate function panel_hidden tests whether or not a panel is 10737a69bbfbSPeter Wemm hidden. 10747a69bbfbSPeter Wemm 10757a69bbfbSPeter Wemm The panel_update code ignores hidden panels. You cannot do top_panel() 10767a69bbfbSPeter Wemm or bottom_panel on a hidden panel(). Other panels operations are 10777a69bbfbSPeter Wemm applicable. 10787a69bbfbSPeter Wemm 10797a69bbfbSPeter WemmMiscellaneous Other Facilities 10807a69bbfbSPeter Wemm 10817a69bbfbSPeter Wemm It is possible to navigate the deck using the functions panel_above() 10827a69bbfbSPeter Wemm and panel_below. Handed a panel pointer, they return the panel above 10837a69bbfbSPeter Wemm or below that panel. Handed NULL, they return the bottom-most or 10847a69bbfbSPeter Wemm top-most panel. 10857a69bbfbSPeter Wemm 10867a69bbfbSPeter Wemm Every panel has an associated user pointer, not used by the panel 10877a69bbfbSPeter Wemm code, to which you can attach application data. See the man page 10887a69bbfbSPeter Wemm documentation of set_panel_userptr() and panel_userptr for details. 10897a69bbfbSPeter Wemm 10907a69bbfbSPeter Wemm The Menu Library 10917a69bbfbSPeter Wemm 10927a69bbfbSPeter Wemm A menu is a screen display that assists the user to choose some subset 10937a69bbfbSPeter Wemm of a given set of items. The menu library is a curses extension that 10947a69bbfbSPeter Wemm supports easy programming of menu hierarchies with a uniform but 10957a69bbfbSPeter Wemm flexible interface. 10967a69bbfbSPeter Wemm 10977a69bbfbSPeter Wemm The menu library first appeared in AT&T System V. The version 10987a69bbfbSPeter Wemm documented here is the menu code distributed with ncurses. 10997a69bbfbSPeter Wemm 11007a69bbfbSPeter WemmCompiling With the menu Library 11017a69bbfbSPeter Wemm 11027a69bbfbSPeter Wemm Your menu-using modules must import the menu library declarations with 11037a69bbfbSPeter Wemm #include <menu.h> 11047a69bbfbSPeter Wemm 11057a69bbfbSPeter Wemm and must be linked explicitly with the menus library using an -lmenu 11067a69bbfbSPeter Wemm argument. Note that they must also link the ncurses library with 11077a69bbfbSPeter Wemm -lncurses. Many linkers are two-pass and will accept either order, but 11087a69bbfbSPeter Wemm it is still good practice to put -lmenu first and -lncurses second. 11097a69bbfbSPeter Wemm 11107a69bbfbSPeter WemmOverview of Menus 11117a69bbfbSPeter Wemm 11127a69bbfbSPeter Wemm The menus created by this library consist of collections of items 11137a69bbfbSPeter Wemm including a name string part and a description string part. To make 11147a69bbfbSPeter Wemm menus, you create groups of these items and connect them with menu 11154a1a9510SRong-En Fan frame objects. 11167a69bbfbSPeter Wemm 11177a69bbfbSPeter Wemm The menu can then by posted, that is written to an associated window. 11184a1a9510SRong-En Fan Actually, each menu has two associated windows; a containing window in 11197a69bbfbSPeter Wemm which the programmer can scribble titles or borders, and a subwindow 11207a69bbfbSPeter Wemm in which the menu items proper are displayed. If this subwindow is too 11217a69bbfbSPeter Wemm small to display all the items, it will be a scrollable viewport on 11227a69bbfbSPeter Wemm the collection of items. 11237a69bbfbSPeter Wemm 11247a69bbfbSPeter Wemm A menu may also be unposted (that is, undisplayed), and finally freed 11257a69bbfbSPeter Wemm to make the storage associated with it and its items available for 11267a69bbfbSPeter Wemm re-use. 11277a69bbfbSPeter Wemm 11287a69bbfbSPeter Wemm The general flow of control of a menu program looks like this: 11297a69bbfbSPeter Wemm 1. Initialize curses. 11307a69bbfbSPeter Wemm 2. Create the menu items, using new_item(). 11317a69bbfbSPeter Wemm 3. Create the menu using new_menu(). 11327a69bbfbSPeter Wemm 4. Post the menu using post_menu(). 11337a69bbfbSPeter Wemm 5. Refresh the screen. 11347a69bbfbSPeter Wemm 6. Process user requests via an input loop. 11357a69bbfbSPeter Wemm 7. Unpost the menu using unpost_menu(). 11367a69bbfbSPeter Wemm 8. Free the menu, using free_menu(). 11377a69bbfbSPeter Wemm 9. Free the items using free_item(). 11387a69bbfbSPeter Wemm 10. Terminate curses. 11397a69bbfbSPeter Wemm 11407a69bbfbSPeter WemmSelecting items 11417a69bbfbSPeter Wemm 11427a69bbfbSPeter Wemm Menus may be multi-valued or (the default) single-valued (see the 11437a69bbfbSPeter Wemm manual page menu_opts(3x) to see how to change the default). Both 11447a69bbfbSPeter Wemm types always have a current item. 11457a69bbfbSPeter Wemm 11467a69bbfbSPeter Wemm From a single-valued menu you can read the selected value simply by 11477a69bbfbSPeter Wemm looking at the current item. From a multi-valued menu, you get the 11487a69bbfbSPeter Wemm selected set by looping through the items applying the item_value() 11497a69bbfbSPeter Wemm predicate function. Your menu-processing code can use the function 11507a69bbfbSPeter Wemm set_item_value() to flag the items in the select set. 11517a69bbfbSPeter Wemm 11527a69bbfbSPeter Wemm Menu items can be made unselectable using set_item_opts() or 11537a69bbfbSPeter Wemm item_opts_off() with the O_SELECTABLE argument. This is the only 11547a69bbfbSPeter Wemm option so far defined for menus, but it is good practice to code as 11557a69bbfbSPeter Wemm though other option bits might be on. 11567a69bbfbSPeter Wemm 11577a69bbfbSPeter WemmMenu Display 11587a69bbfbSPeter Wemm 11597a69bbfbSPeter Wemm The menu library calculates a minimum display size for your window, 11607a69bbfbSPeter Wemm based on the following variables: 11617a69bbfbSPeter Wemm * The number and maximum length of the menu items 11627a69bbfbSPeter Wemm * Whether the O_ROWMAJOR option is enabled 11637a69bbfbSPeter Wemm * Whether display of descriptions is enabled 11647a69bbfbSPeter Wemm * Whatever menu format may have been set by the programmer 11657a69bbfbSPeter Wemm * The length of the menu mark string used for highlighting selected 11667a69bbfbSPeter Wemm items 11677a69bbfbSPeter Wemm 11687a69bbfbSPeter Wemm The function set_menu_format() allows you to set the maximum size of 11697a69bbfbSPeter Wemm the viewport or menu page that will be used to display menu items. You 11707a69bbfbSPeter Wemm can retrieve any format associated with a menu with menu_format(). The 11717a69bbfbSPeter Wemm default format is rows=16, columns=1. 11727a69bbfbSPeter Wemm 11737a69bbfbSPeter Wemm The actual menu page may be smaller than the format size. This depends 11747a69bbfbSPeter Wemm on the item number and size and whether O_ROWMAJOR is on. This option 11757a69bbfbSPeter Wemm (on by default) causes menu items to be displayed in a "raster-scan" 11767a69bbfbSPeter Wemm pattern, so that if more than one item will fit horizontally the first 11777a69bbfbSPeter Wemm couple of items are side-by-side in the top row. The alternative is 11787a69bbfbSPeter Wemm column-major display, which tries to put the first several items in 11797a69bbfbSPeter Wemm the first column. 11807a69bbfbSPeter Wemm 11817a69bbfbSPeter Wemm As mentioned above, a menu format not large enough to allow all items 11827a69bbfbSPeter Wemm to fit on-screen will result in a menu display that is vertically 11837a69bbfbSPeter Wemm scrollable. 11847a69bbfbSPeter Wemm 11857a69bbfbSPeter Wemm You can scroll it with requests to the menu driver, which will be 11867a69bbfbSPeter Wemm described in the section on menu input handling. 11877a69bbfbSPeter Wemm 11887a69bbfbSPeter Wemm Each menu has a mark string used to visually tag selected items; see 11897a69bbfbSPeter Wemm the menu_mark(3x) manual page for details. The mark string length also 11907a69bbfbSPeter Wemm influences the menu page size. 11917a69bbfbSPeter Wemm 11927a69bbfbSPeter Wemm The function scale_menu() returns the minimum display size that the 11937a69bbfbSPeter Wemm menu code computes from all these factors. There are other menu 11947a69bbfbSPeter Wemm display attributes including a select attribute, an attribute for 11957a69bbfbSPeter Wemm selectable items, an attribute for unselectable items, and a pad 11967a69bbfbSPeter Wemm character used to separate item name text from description text. These 11977a69bbfbSPeter Wemm have reasonable defaults which the library allows you to change (see 11984a1a9510SRong-En Fan the menu_attribs(3x) manual page. 11994a1a9510SRong-En Fan 12007a69bbfbSPeter WemmMenu Windows 12017a69bbfbSPeter Wemm 12027a69bbfbSPeter Wemm Each menu has, as mentioned previously, a pair of associated windows. 12037a69bbfbSPeter Wemm Both these windows are painted when the menu is posted and erased when 12047a69bbfbSPeter Wemm the menu is unposted. 12057a69bbfbSPeter Wemm 12067a69bbfbSPeter Wemm The outer or frame window is not otherwise touched by the menu 12077a69bbfbSPeter Wemm routines. It exists so the programmer can associate a title, a border, 12087a69bbfbSPeter Wemm or perhaps help text with the menu and have it properly refreshed or 12097a69bbfbSPeter Wemm erased at post/unpost time. The inner window or subwindow is where the 12107a69bbfbSPeter Wemm current menu page is displayed. 12117a69bbfbSPeter Wemm 12127a69bbfbSPeter Wemm By default, both windows are stdscr. You can set them with the 12137a69bbfbSPeter Wemm functions in menu_win(3x). 12147a69bbfbSPeter Wemm 12157a69bbfbSPeter Wemm When you call post_menu(), you write the menu to its subwindow. When 12167a69bbfbSPeter Wemm you call unpost_menu(), you erase the subwindow, However, neither of 12177a69bbfbSPeter Wemm these actually modifies the screen. To do that, call wrefresh() or 12187a69bbfbSPeter Wemm some equivalent. 12197a69bbfbSPeter Wemm 12207a69bbfbSPeter WemmProcessing Menu Input 12217a69bbfbSPeter Wemm 12227a69bbfbSPeter Wemm The main loop of your menu-processing code should call menu_driver() 12237a69bbfbSPeter Wemm repeatedly. The first argument of this routine is a menu pointer; the 12247a69bbfbSPeter Wemm second is a menu command code. You should write an input-fetching 12257a69bbfbSPeter Wemm routine that maps input characters to menu command codes, and pass its 12267a69bbfbSPeter Wemm output to menu_driver(). The menu command codes are fully documented 12277a69bbfbSPeter Wemm in menu_driver(3x). 12287a69bbfbSPeter Wemm 12297a69bbfbSPeter Wemm The simplest group of command codes is REQ_NEXT_ITEM, REQ_PREV_ITEM, 12307a69bbfbSPeter Wemm REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_UP_ITEM, REQ_DOWN_ITEM, 12317a69bbfbSPeter Wemm REQ_LEFT_ITEM, REQ_RIGHT_ITEM. These change the currently selected 12327a69bbfbSPeter Wemm item. These requests may cause scrolling of the menu page if it only 12337a69bbfbSPeter Wemm partially displayed. 12347a69bbfbSPeter Wemm 12357a69bbfbSPeter Wemm There are explicit requests for scrolling which also change the 12367a69bbfbSPeter Wemm current item (because the select location does not change, but the 12377a69bbfbSPeter Wemm item there does). These are REQ_SCR_DLINE, REQ_SCR_ULINE, 12387a69bbfbSPeter Wemm REQ_SCR_DPAGE, and REQ_SCR_UPAGE. 12397a69bbfbSPeter Wemm 12407a69bbfbSPeter Wemm The REQ_TOGGLE_ITEM selects or deselects the current item. It is for 12417a69bbfbSPeter Wemm use in multi-valued menus; if you use it with O_ONEVALUE on, you will 12427a69bbfbSPeter Wemm get an error return (E_REQUEST_DENIED). 12437a69bbfbSPeter Wemm 12447a69bbfbSPeter Wemm Each menu has an associated pattern buffer. The menu_driver() logic 12457a69bbfbSPeter Wemm tries to accumulate printable ASCII characters passed in in that 12467a69bbfbSPeter Wemm buffer; when it matches a prefix of an item name, that item (or the 12477a69bbfbSPeter Wemm next matching item) is selected. If appending a character yields no 12487a69bbfbSPeter Wemm new match, that character is deleted from the pattern buffer, and 12497a69bbfbSPeter Wemm menu_driver() returns E_NO_MATCH. 12507a69bbfbSPeter Wemm 12517a69bbfbSPeter Wemm Some requests change the pattern buffer directly: REQ_CLEAR_PATTERN, 12527a69bbfbSPeter Wemm REQ_BACK_PATTERN, REQ_NEXT_MATCH, REQ_PREV_MATCH. The latter two are 12537a69bbfbSPeter Wemm useful when pattern buffer input matches more than one item in a 12547a69bbfbSPeter Wemm multi-valued menu. 12557a69bbfbSPeter Wemm 12567a69bbfbSPeter Wemm Each successful scroll or item navigation request clears the pattern 12577a69bbfbSPeter Wemm buffer. It is also possible to set the pattern buffer explicitly with 12587a69bbfbSPeter Wemm set_menu_pattern(). 12597a69bbfbSPeter Wemm 12607a69bbfbSPeter Wemm Finally, menu driver requests above the constant MAX_COMMAND are 12617a69bbfbSPeter Wemm considered application-specific commands. The menu_driver() code 12627a69bbfbSPeter Wemm ignores them and returns E_UNKNOWN_COMMAND. 12637a69bbfbSPeter Wemm 12647a69bbfbSPeter WemmMiscellaneous Other Features 12657a69bbfbSPeter Wemm 12667a69bbfbSPeter Wemm Various menu options can affect the processing and visual appearance 12677a69bbfbSPeter Wemm and input processing of menus. See menu_opts(3x) for details. 12687a69bbfbSPeter Wemm 12697a69bbfbSPeter Wemm It is possible to change the current item from application code; this 12707a69bbfbSPeter Wemm is useful if you want to write your own navigation requests. It is 12717a69bbfbSPeter Wemm also possible to explicitly set the top row of the menu display. See 12727a69bbfbSPeter Wemm mitem_current(3x). If your application needs to change the menu 12737a69bbfbSPeter Wemm subwindow cursor for any reason, pos_menu_cursor() will restore it to 12747a69bbfbSPeter Wemm the correct location for continuing menu driver processing. 12757a69bbfbSPeter Wemm 12767a69bbfbSPeter Wemm It is possible to set hooks to be called at menu initialization and 12777a69bbfbSPeter Wemm wrapup time, and whenever the selected item changes. See 12787a69bbfbSPeter Wemm menu_hook(3x). 12797a69bbfbSPeter Wemm 12807a69bbfbSPeter Wemm Each item, and each menu, has an associated user pointer on which you 12817a69bbfbSPeter Wemm can hang application data. See mitem_userptr(3x) and menu_userptr(3x). 12827a69bbfbSPeter Wemm 12837a69bbfbSPeter Wemm The Forms Library 12847a69bbfbSPeter Wemm 12857a69bbfbSPeter Wemm The form library is a curses extension that supports easy programming 12867a69bbfbSPeter Wemm of on-screen forms for data entry and program control. 12877a69bbfbSPeter Wemm 12887a69bbfbSPeter Wemm The form library first appeared in AT&T System V. The version 12897a69bbfbSPeter Wemm documented here is the form code distributed with ncurses. 12907a69bbfbSPeter Wemm 12917a69bbfbSPeter WemmCompiling With the form Library 12927a69bbfbSPeter Wemm 12937a69bbfbSPeter Wemm Your form-using modules must import the form library declarations with 12947a69bbfbSPeter Wemm #include <form.h> 12957a69bbfbSPeter Wemm 12967a69bbfbSPeter Wemm and must be linked explicitly with the forms library using an -lform 12977a69bbfbSPeter Wemm argument. Note that they must also link the ncurses library with 12987a69bbfbSPeter Wemm -lncurses. Many linkers are two-pass and will accept either order, but 12997a69bbfbSPeter Wemm it is still good practice to put -lform first and -lncurses second. 13007a69bbfbSPeter Wemm 13017a69bbfbSPeter WemmOverview of Forms 13027a69bbfbSPeter Wemm 13037a69bbfbSPeter Wemm A form is a collection of fields; each field may be either a label 13047a69bbfbSPeter Wemm (explanatory text) or a data-entry location. Long forms may be 13057a69bbfbSPeter Wemm segmented into pages; each entry to a new page clears the screen. 13067a69bbfbSPeter Wemm 13077a69bbfbSPeter Wemm To make forms, you create groups of fields and connect them with form 13087a69bbfbSPeter Wemm frame objects; the form library makes this relatively simple. 13097a69bbfbSPeter Wemm 13107a69bbfbSPeter Wemm Once defined, a form can be posted, that is written to an associated 13117a69bbfbSPeter Wemm window. Actually, each form has two associated windows; a containing 13127a69bbfbSPeter Wemm window in which the programmer can scribble titles or borders, and a 13137a69bbfbSPeter Wemm subwindow in which the form fields proper are displayed. 13147a69bbfbSPeter Wemm 13154a1a9510SRong-En Fan As the form user fills out the posted form, navigation and editing 13167a69bbfbSPeter Wemm keys support movement between fields, editing keys support modifying 13177a69bbfbSPeter Wemm field, and plain text adds to or changes data in a current field. The 13184a1a9510SRong-En Fan form library allows you (the forms designer) to bind each navigation 13197a69bbfbSPeter Wemm and editing key to any keystroke accepted by curses Fields may have 13207a69bbfbSPeter Wemm validation conditions on them, so that they check input data for type 13217a69bbfbSPeter Wemm and value. The form library supplies a rich set of pre-defined field 13227a69bbfbSPeter Wemm types, and makes it relatively easy to define new ones. 13237a69bbfbSPeter Wemm 13247a69bbfbSPeter Wemm Once its transaction is completed (or aborted), a form may be unposted 13257a69bbfbSPeter Wemm (that is, undisplayed), and finally freed to make the storage 13267a69bbfbSPeter Wemm associated with it and its items available for re-use. 13277a69bbfbSPeter Wemm 13287a69bbfbSPeter Wemm The general flow of control of a form program looks like this: 13297a69bbfbSPeter Wemm 1. Initialize curses. 13307a69bbfbSPeter Wemm 2. Create the form fields, using new_field(). 13317a69bbfbSPeter Wemm 3. Create the form using new_form(). 13327a69bbfbSPeter Wemm 4. Post the form using post_form(). 13337a69bbfbSPeter Wemm 5. Refresh the screen. 13347a69bbfbSPeter Wemm 6. Process user requests via an input loop. 13357a69bbfbSPeter Wemm 7. Unpost the form using unpost_form(). 13367a69bbfbSPeter Wemm 8. Free the form, using free_form(). 13377a69bbfbSPeter Wemm 9. Free the fields using free_field(). 13387a69bbfbSPeter Wemm 10. Terminate curses. 13397a69bbfbSPeter Wemm 13407a69bbfbSPeter Wemm Note that this looks much like a menu program; the form library 13417a69bbfbSPeter Wemm handles tasks which are in many ways similar, and its interface was 13427a69bbfbSPeter Wemm obviously designed to resemble that of the menu library wherever 13437a69bbfbSPeter Wemm possible. 13447a69bbfbSPeter Wemm 13457a69bbfbSPeter Wemm In forms programs, however, the "process user requests" is somewhat 13467a69bbfbSPeter Wemm more complicated than for menus. Besides menu-like navigation 13477a69bbfbSPeter Wemm operations, the menu driver loop has to support field editing and data 13487a69bbfbSPeter Wemm validation. 13497a69bbfbSPeter Wemm 13504a1a9510SRong-En FanCreating and Freeing Fields and Forms 13517a69bbfbSPeter Wemm 13527a69bbfbSPeter Wemm The basic function for creating fields is new_field(): 13537a69bbfbSPeter WemmFIELD *new_field(int height, int width, /* new field size */ 13547a69bbfbSPeter Wemm int top, int left, /* upper left corner */ 13557a69bbfbSPeter Wemm int offscreen, /* number of offscreen rows */ 13567a69bbfbSPeter Wemm int nbuf); /* number of working buffers */ 13577a69bbfbSPeter Wemm 13587a69bbfbSPeter Wemm Menu items always occupy a single row, but forms fields may have 13597a69bbfbSPeter Wemm multiple rows. So new_field() requires you to specify a width and 13607a69bbfbSPeter Wemm height (the first two arguments, which mist both be greater than 13617a69bbfbSPeter Wemm zero). 13627a69bbfbSPeter Wemm 13637a69bbfbSPeter Wemm You must also specify the location of the field's upper left corner on 13647a69bbfbSPeter Wemm the screen (the third and fourth arguments, which must be zero or 13657a69bbfbSPeter Wemm greater). Note that these coordinates are relative to the form 13667a69bbfbSPeter Wemm subwindow, which will coincide with stdscr by default but need not be 13677a69bbfbSPeter Wemm stdscr if you have done an explicit set_form_win() call. 13687a69bbfbSPeter Wemm 13697a69bbfbSPeter Wemm The fifth argument allows you to specify a number of off-screen rows. 13707a69bbfbSPeter Wemm If this is zero, the entire field will always be displayed. If it is 13717a69bbfbSPeter Wemm nonzero, the form will be scrollable, with only one screen-full 13727a69bbfbSPeter Wemm (initially the top part) displayed at any given time. If you make a 13737a69bbfbSPeter Wemm field dynamic and grow it so it will no longer fit on the screen, the 13747a69bbfbSPeter Wemm form will become scrollable even if the offscreen argument was 13757a69bbfbSPeter Wemm initially zero. 13767a69bbfbSPeter Wemm 13777a69bbfbSPeter Wemm The forms library allocates one working buffer per field; the size of 13787a69bbfbSPeter Wemm each buffer is ((height + offscreen)*width + 1, one character for each 13797a69bbfbSPeter Wemm position in the field plus a NUL terminator. The sixth argument is the 13807a69bbfbSPeter Wemm number of additional data buffers to allocate for the field; your 13817a69bbfbSPeter Wemm application can use them for its own purposes. 13827a69bbfbSPeter WemmFIELD *dup_field(FIELD *field, /* field to copy */ 13837a69bbfbSPeter Wemm int top, int left); /* location of new copy */ 13847a69bbfbSPeter Wemm 13857a69bbfbSPeter Wemm The function dup_field() duplicates an existing field at a new 13867a69bbfbSPeter Wemm location. Size and buffering information are copied; some attribute 13877a69bbfbSPeter Wemm flags and status bits are not (see the form_field_new(3X) for 13887a69bbfbSPeter Wemm details). 13897a69bbfbSPeter WemmFIELD *link_field(FIELD *field, /* field to copy */ 13907a69bbfbSPeter Wemm int top, int left); /* location of new copy */ 13917a69bbfbSPeter Wemm 13927a69bbfbSPeter Wemm The function link_field() also duplicates an existing field at a new 13937a69bbfbSPeter Wemm location. The difference from dup_field() is that it arranges for the 13947a69bbfbSPeter Wemm new field's buffer to be shared with the old one. 13957a69bbfbSPeter Wemm 13967a69bbfbSPeter Wemm Besides the obvious use in making a field editable from two different 13977a69bbfbSPeter Wemm form pages, linked fields give you a way to hack in dynamic labels. If 13987a69bbfbSPeter Wemm you declare several fields linked to an original, and then make them 13997a69bbfbSPeter Wemm inactive, changes from the original will still be propagated to the 14007a69bbfbSPeter Wemm linked fields. 14017a69bbfbSPeter Wemm 14027a69bbfbSPeter Wemm As with duplicated fields, linked fields have attribute bits separate 14037a69bbfbSPeter Wemm from the original. 14047a69bbfbSPeter Wemm 14057a69bbfbSPeter Wemm As you might guess, all these field-allocations return NULL if the 14067a69bbfbSPeter Wemm field allocation is not possible due to an out-of-memory error or 14077a69bbfbSPeter Wemm out-of-bounds arguments. 14087a69bbfbSPeter Wemm 14097a69bbfbSPeter Wemm To connect fields to a form, use 14107a69bbfbSPeter WemmFORM *new_form(FIELD **fields); 14117a69bbfbSPeter Wemm 14127a69bbfbSPeter Wemm This function expects to see a NULL-terminated array of field 14137a69bbfbSPeter Wemm pointers. Said fields are connected to a newly-allocated form object; 14147a69bbfbSPeter Wemm its address is returned (or else NULL if the allocation fails). 14157a69bbfbSPeter Wemm 14167a69bbfbSPeter Wemm Note that new_field() does not copy the pointer array into private 14177a69bbfbSPeter Wemm storage; if you modify the contents of the pointer array during forms 14187a69bbfbSPeter Wemm processing, all manner of bizarre things might happen. Also note that 14197a69bbfbSPeter Wemm any given field may only be connected to one form. 14207a69bbfbSPeter Wemm 14217a69bbfbSPeter Wemm The functions free_field() and free_form are available to free field 14227a69bbfbSPeter Wemm and form objects. It is an error to attempt to free a field connected 14237a69bbfbSPeter Wemm to a form, but not vice-versa; thus, you will generally free your form 14247a69bbfbSPeter Wemm objects first. 14257a69bbfbSPeter Wemm 14267a69bbfbSPeter WemmFetching and Changing Field Attributes 14277a69bbfbSPeter Wemm 14287a69bbfbSPeter Wemm Each form field has a number of location and size attributes 14297a69bbfbSPeter Wemm associated with it. There are other field attributes used to control 14307a69bbfbSPeter Wemm display and editing of the field. Some (for example, the O_STATIC bit) 14317a69bbfbSPeter Wemm involve sufficient complications to be covered in sections of their 14327a69bbfbSPeter Wemm own later on. We cover the functions used to get and set several basic 14337a69bbfbSPeter Wemm attributes here. 14347a69bbfbSPeter Wemm 14357a69bbfbSPeter Wemm When a field is created, the attributes not specified by the new_field 14367a69bbfbSPeter Wemm function are copied from an invisible system default field. In 14377a69bbfbSPeter Wemm attribute-setting and -fetching functions, the argument NULL is taken 14387a69bbfbSPeter Wemm to mean this field. Changes to it persist as defaults until your forms 14397a69bbfbSPeter Wemm application terminates. 14407a69bbfbSPeter Wemm 14417a69bbfbSPeter Wemm Fetching Size and Location Data 14427a69bbfbSPeter Wemm 14437a69bbfbSPeter Wemm You can retrieve field sizes and locations through: 14447a69bbfbSPeter Wemmint field_info(FIELD *field, /* field from which to fetch */ 14457a69bbfbSPeter Wemm int *height, *int width, /* field size */ 14467a69bbfbSPeter Wemm int *top, int *left, /* upper left corner */ 14477a69bbfbSPeter Wemm int *offscreen, /* number of offscreen rows */ 14487a69bbfbSPeter Wemm int *nbuf); /* number of working buffers */ 14497a69bbfbSPeter Wemm 14507a69bbfbSPeter Wemm This function is a sort of inverse of new_field(); instead of setting 14517a69bbfbSPeter Wemm size and location attributes of a new field, it fetches them from an 14527a69bbfbSPeter Wemm existing one. 14537a69bbfbSPeter Wemm 14547a69bbfbSPeter Wemm Changing the Field Location 14557a69bbfbSPeter Wemm 14567a69bbfbSPeter Wemm It is possible to move a field's location on the screen: 14577a69bbfbSPeter Wemmint move_field(FIELD *field, /* field to alter */ 14587a69bbfbSPeter Wemm int top, int left); /* new upper-left corner */ 14597a69bbfbSPeter Wemm 14607a69bbfbSPeter Wemm You can, of course. query the current location through field_info(). 14617a69bbfbSPeter Wemm 14627a69bbfbSPeter Wemm The Justification Attribute 14637a69bbfbSPeter Wemm 14647a69bbfbSPeter Wemm One-line fields may be unjustified, justified right, justified left, 14657a69bbfbSPeter Wemm or centered. Here is how you manipulate this attribute: 14667a69bbfbSPeter Wemmint set_field_just(FIELD *field, /* field to alter */ 14677a69bbfbSPeter Wemm int justmode); /* mode to set */ 14687a69bbfbSPeter Wemm 14697a69bbfbSPeter Wemmint field_just(FIELD *field); /* fetch mode of field */ 14707a69bbfbSPeter Wemm 14717a69bbfbSPeter Wemm The mode values accepted and returned by this functions are 14727a69bbfbSPeter Wemm preprocessor macros NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or 14737a69bbfbSPeter Wemm JUSTIFY_CENTER. 14747a69bbfbSPeter Wemm 14757a69bbfbSPeter Wemm Field Display Attributes 14767a69bbfbSPeter Wemm 14777a69bbfbSPeter Wemm For each field, you can set a foreground attribute for entered 14787a69bbfbSPeter Wemm characters, a background attribute for the entire field, and a pad 14797a69bbfbSPeter Wemm character for the unfilled portion of the field. You can also control 14807a69bbfbSPeter Wemm pagination of the form. 14817a69bbfbSPeter Wemm 14827a69bbfbSPeter Wemm This group of four field attributes controls the visual appearance of 14837a69bbfbSPeter Wemm the field on the screen, without affecting in any way the data in the 14847a69bbfbSPeter Wemm field buffer. 14857a69bbfbSPeter Wemmint set_field_fore(FIELD *field, /* field to alter */ 14867a69bbfbSPeter Wemm chtype attr); /* attribute to set */ 14877a69bbfbSPeter Wemm 14887a69bbfbSPeter Wemmchtype field_fore(FIELD *field); /* field to query */ 14897a69bbfbSPeter Wemm 14907a69bbfbSPeter Wemmint set_field_back(FIELD *field, /* field to alter */ 14917a69bbfbSPeter Wemm chtype attr); /* attribute to set */ 14927a69bbfbSPeter Wemm 14937a69bbfbSPeter Wemmchtype field_back(FIELD *field); /* field to query */ 14947a69bbfbSPeter Wemm 14957a69bbfbSPeter Wemmint set_field_pad(FIELD *field, /* field to alter */ 14967a69bbfbSPeter Wemm int pad); /* pad character to set */ 14977a69bbfbSPeter Wemm 14987a69bbfbSPeter Wemmchtype field_pad(FIELD *field); 14997a69bbfbSPeter Wemm 15007a69bbfbSPeter Wemmint set_new_page(FIELD *field, /* field to alter */ 15017a69bbfbSPeter Wemm int flag); /* TRUE to force new page */ 15027a69bbfbSPeter Wemm 15037a69bbfbSPeter Wemmchtype new_page(FIELD *field); /* field to query */ 15047a69bbfbSPeter Wemm 15057a69bbfbSPeter Wemm The attributes set and returned by the first four functions are normal 15067a69bbfbSPeter Wemm curses(3x) display attribute values (A_STANDOUT, A_BOLD, A_REVERSE 15077a69bbfbSPeter Wemm etc). The page bit of a field controls whether it is displayed at the 15087a69bbfbSPeter Wemm start of a new form screen. 15097a69bbfbSPeter Wemm 15107a69bbfbSPeter Wemm Field Option Bits 15117a69bbfbSPeter Wemm 15127a69bbfbSPeter Wemm There is also a large collection of field option bits you can set to 15137a69bbfbSPeter Wemm control various aspects of forms processing. You can manipulate them 15147a69bbfbSPeter Wemm with these functions: 15157a69bbfbSPeter Wemmint set_field_opts(FIELD *field, /* field to alter */ 15167a69bbfbSPeter Wemm int attr); /* attribute to set */ 15177a69bbfbSPeter Wemm 15187a69bbfbSPeter Wemmint field_opts_on(FIELD *field, /* field to alter */ 15197a69bbfbSPeter Wemm int attr); /* attributes to turn on */ 15207a69bbfbSPeter Wemm 15217a69bbfbSPeter Wemmint field_opts_off(FIELD *field, /* field to alter */ 15227a69bbfbSPeter Wemm int attr); /* attributes to turn off */ 15237a69bbfbSPeter Wemm 15247a69bbfbSPeter Wemmint field_opts(FIELD *field); /* field to query */ 15257a69bbfbSPeter Wemm 15267a69bbfbSPeter Wemm By default, all options are on. Here are the available option bits: 15277a69bbfbSPeter Wemm 15287a69bbfbSPeter Wemm O_VISIBLE 15297a69bbfbSPeter Wemm Controls whether the field is visible on the screen. Can be 15307a69bbfbSPeter Wemm used during form processing to hide or pop up fields depending 15317a69bbfbSPeter Wemm on the value of parent fields. 15327a69bbfbSPeter Wemm 15337a69bbfbSPeter Wemm O_ACTIVE 15347a69bbfbSPeter Wemm Controls whether the field is active during forms processing 15357a69bbfbSPeter Wemm (i.e. visited by form navigation keys). Can be used to make 15367a69bbfbSPeter Wemm labels or derived fields with buffer values alterable by the 15377a69bbfbSPeter Wemm forms application, not the user. 15387a69bbfbSPeter Wemm 15397a69bbfbSPeter Wemm O_PUBLIC 15407a69bbfbSPeter Wemm Controls whether data is displayed during field entry. If this 15417a69bbfbSPeter Wemm option is turned off on a field, the library will accept and 15427a69bbfbSPeter Wemm edit data in that field, but it will not be displayed and the 15437a69bbfbSPeter Wemm visible field cursor will not move. You can turn off the 15447a69bbfbSPeter Wemm O_PUBLIC bit to define password fields. 15457a69bbfbSPeter Wemm 15467a69bbfbSPeter Wemm O_EDIT 15477a69bbfbSPeter Wemm Controls whether the field's data can be modified. When this 15487a69bbfbSPeter Wemm option is off, all editing requests except REQ_PREV_CHOICE and 15497a69bbfbSPeter Wemm REQ_NEXT_CHOICE will fail. Such read-only fields may be useful 15507a69bbfbSPeter Wemm for help messages. 15517a69bbfbSPeter Wemm 15527a69bbfbSPeter Wemm O_WRAP 15537a69bbfbSPeter Wemm Controls word-wrapping in multi-line fields. Normally, when any 15547a69bbfbSPeter Wemm character of a (blank-separated) word reaches the end of the 15557a69bbfbSPeter Wemm current line, the entire word is wrapped to the next line 15567a69bbfbSPeter Wemm (assuming there is one). When this option is off, the word will 15577a69bbfbSPeter Wemm be split across the line break. 15587a69bbfbSPeter Wemm 15597a69bbfbSPeter Wemm O_BLANK 15607a69bbfbSPeter Wemm Controls field blanking. When this option is on, entering a 15617a69bbfbSPeter Wemm character at the first field position erases the entire field 15627a69bbfbSPeter Wemm (except for the just-entered character). 15637a69bbfbSPeter Wemm 15647a69bbfbSPeter Wemm O_AUTOSKIP 15657a69bbfbSPeter Wemm Controls automatic skip to next field when this one fills. 15667a69bbfbSPeter Wemm Normally, when the forms user tries to type more data into a 15677a69bbfbSPeter Wemm field than will fit, the editing location jumps to next field. 15687a69bbfbSPeter Wemm When this option is off, the user's cursor will hang at the end 15697a69bbfbSPeter Wemm of the field. This option is ignored in dynamic fields that 15707a69bbfbSPeter Wemm have not reached their size limit. 15717a69bbfbSPeter Wemm 15727a69bbfbSPeter Wemm O_NULLOK 15737a69bbfbSPeter Wemm Controls whether validation is applied to blank fields. 15747a69bbfbSPeter Wemm Normally, it is not; the user can leave a field blank without 15757a69bbfbSPeter Wemm invoking the usual validation check on exit. If this option is 15767a69bbfbSPeter Wemm off on a field, exit from it will invoke a validation check. 15777a69bbfbSPeter Wemm 15787a69bbfbSPeter Wemm O_PASSOK 15797a69bbfbSPeter Wemm Controls whether validation occurs on every exit, or only after 15807a69bbfbSPeter Wemm the field is modified. Normally the latter is true. Setting 15817a69bbfbSPeter Wemm O_PASSOK may be useful if your field's validation function may 15827a69bbfbSPeter Wemm change during forms processing. 15837a69bbfbSPeter Wemm 15847a69bbfbSPeter Wemm O_STATIC 15857a69bbfbSPeter Wemm Controls whether the field is fixed to its initial dimensions. 15867a69bbfbSPeter Wemm If you turn this off, the field becomes dynamic and will 15877a69bbfbSPeter Wemm stretch to fit entered data. 15887a69bbfbSPeter Wemm 15897a69bbfbSPeter Wemm A field's options cannot be changed while the field is currently 15907a69bbfbSPeter Wemm selected. However, options may be changed on posted fields that are 15917a69bbfbSPeter Wemm not current. 15927a69bbfbSPeter Wemm 15937a69bbfbSPeter Wemm The option values are bit-masks and can be composed with logical-or in 15947a69bbfbSPeter Wemm the obvious way. 15957a69bbfbSPeter Wemm 15967a69bbfbSPeter WemmField Status 15977a69bbfbSPeter Wemm 15987a69bbfbSPeter Wemm Every field has a status flag, which is set to FALSE when the field is 15997a69bbfbSPeter Wemm created and TRUE when the value in field buffer 0 changes. This flag 16007a69bbfbSPeter Wemm can be queried and set directly: 16017a69bbfbSPeter Wemmint set_field_status(FIELD *field, /* field to alter */ 16027a69bbfbSPeter Wemm int status); /* mode to set */ 16037a69bbfbSPeter Wemm 16047a69bbfbSPeter Wemmint field_status(FIELD *field); /* fetch mode of field */ 16057a69bbfbSPeter Wemm 16067a69bbfbSPeter Wemm Setting this flag under program control can be useful if you use the 16077a69bbfbSPeter Wemm same form repeatedly, looking for modified fields each time. 16087a69bbfbSPeter Wemm 16097a69bbfbSPeter Wemm Calling field_status() on a field not currently selected for input 16107a69bbfbSPeter Wemm will return a correct value. Calling field_status() on a field that is 16117a69bbfbSPeter Wemm currently selected for input may not necessarily give a correct field 16127a69bbfbSPeter Wemm status value, because entered data is not necessarily copied to buffer 16137a69bbfbSPeter Wemm zero before the exit validation check. To guarantee that the returned 16147a69bbfbSPeter Wemm status value reflects reality, call field_status() either (1) in the 16157a69bbfbSPeter Wemm field's exit validation check routine, (2) from the field's or form's 16167a69bbfbSPeter Wemm initialization or termination hooks, or (3) just after a 16177a69bbfbSPeter Wemm REQ_VALIDATION request has been processed by the forms driver. 16187a69bbfbSPeter Wemm 16197a69bbfbSPeter WemmField User Pointer 16207a69bbfbSPeter Wemm 16217a69bbfbSPeter Wemm Each field structure contains one character pointer slot that is not 16227a69bbfbSPeter Wemm used by the forms library. It is intended to be used by applications 16237a69bbfbSPeter Wemm to store private per-field data. You can manipulate it with: 16247a69bbfbSPeter Wemmint set_field_userptr(FIELD *field, /* field to alter */ 16257a69bbfbSPeter Wemm char *userptr); /* mode to set */ 16267a69bbfbSPeter Wemm 16277a69bbfbSPeter Wemmchar *field_userptr(FIELD *field); /* fetch mode of field */ 16287a69bbfbSPeter Wemm 16297a69bbfbSPeter Wemm (Properly, this user pointer field ought to have (void *) type. The 16307a69bbfbSPeter Wemm (char *) type is retained for System V compatibility.) 16317a69bbfbSPeter Wemm 16327a69bbfbSPeter Wemm It is valid to set the user pointer of the default field (with a 16337a69bbfbSPeter Wemm set_field_userptr() call passed a NULL field pointer.) When a new 16347a69bbfbSPeter Wemm field is created, the default-field user pointer is copied to 16357a69bbfbSPeter Wemm initialize the new field's user pointer. 16367a69bbfbSPeter Wemm 16377a69bbfbSPeter WemmVariable-Sized Fields 16387a69bbfbSPeter Wemm 16397a69bbfbSPeter Wemm Normally, a field is fixed at the size specified for it at creation 16407a69bbfbSPeter Wemm time. If, however, you turn off its O_STATIC bit, it becomes dynamic 16417a69bbfbSPeter Wemm and will automatically resize itself to accommodate data as it is 16427a69bbfbSPeter Wemm entered. If the field has extra buffers associated with it, they will 16437a69bbfbSPeter Wemm grow right along with the main input buffer. 16447a69bbfbSPeter Wemm 16457a69bbfbSPeter Wemm A one-line dynamic field will have a fixed height (1) but variable 16467a69bbfbSPeter Wemm width, scrolling horizontally to display data within the field area as 16477a69bbfbSPeter Wemm originally dimensioned and located. A multi-line dynamic field will 16487a69bbfbSPeter Wemm have a fixed width, but variable height (number of rows), scrolling 16497a69bbfbSPeter Wemm vertically to display data within the field area as originally 16507a69bbfbSPeter Wemm dimensioned and located. 16517a69bbfbSPeter Wemm 16527a69bbfbSPeter Wemm Normally, a dynamic field is allowed to grow without limit. But it is 16537a69bbfbSPeter Wemm possible to set an upper limit on the size of a dynamic field. You do 16547a69bbfbSPeter Wemm it with this function: 16557a69bbfbSPeter Wemmint set_max_field(FIELD *field, /* field to alter (may not be NULL) */ 16567a69bbfbSPeter Wemm int max_size); /* upper limit on field size */ 16577a69bbfbSPeter Wemm 16587a69bbfbSPeter Wemm If the field is one-line, max_size is taken to be a column size limit; 16597a69bbfbSPeter Wemm if it is multi-line, it is taken to be a line size limit. To disable 16607a69bbfbSPeter Wemm any limit, use an argument of zero. The growth limit can be changed 16617a69bbfbSPeter Wemm whether or not the O_STATIC bit is on, but has no effect until it is. 16627a69bbfbSPeter Wemm 16637a69bbfbSPeter Wemm The following properties of a field change when it becomes dynamic: 16647a69bbfbSPeter Wemm * If there is no growth limit, there is no final position of the 16657a69bbfbSPeter Wemm field; therefore O_AUTOSKIP and O_NL_OVERLOAD are ignored. 16667a69bbfbSPeter Wemm * Field justification will be ignored (though whatever justification 16677a69bbfbSPeter Wemm is set up will be retained internally and can be queried). 16687a69bbfbSPeter Wemm * The dup_field() and link_field() calls copy dynamic-buffer sizes. 16697a69bbfbSPeter Wemm If the O_STATIC option is set on one of a collection of links, 16707a69bbfbSPeter Wemm buffer resizing will occur only when the field is edited through 16717a69bbfbSPeter Wemm that link. 16727a69bbfbSPeter Wemm * The call field_info() will retrieve the original static size of 16737a69bbfbSPeter Wemm the field; use dynamic_field_info() to get the actual dynamic 16747a69bbfbSPeter Wemm size. 16757a69bbfbSPeter Wemm 16767a69bbfbSPeter WemmField Validation 16777a69bbfbSPeter Wemm 16787a69bbfbSPeter Wemm By default, a field will accept any data that will fit in its input 16797a69bbfbSPeter Wemm buffer. However, it is possible to attach a validation type to a 16807a69bbfbSPeter Wemm field. If you do this, any attempt to leave the field while it 16817a69bbfbSPeter Wemm contains data that does not match the validation type will fail. Some 16827a69bbfbSPeter Wemm validation types also have a character-validity check for each time a 16837a69bbfbSPeter Wemm character is entered in the field. 16847a69bbfbSPeter Wemm 16857a69bbfbSPeter Wemm A field's validation check (if any) is not called when 16867a69bbfbSPeter Wemm set_field_buffer() modifies the input buffer, nor when that buffer is 16877a69bbfbSPeter Wemm changed through a linked field. 16887a69bbfbSPeter Wemm 16897a69bbfbSPeter Wemm The form library provides a rich set of pre-defined validation types, 16907a69bbfbSPeter Wemm and gives you the capability to define custom ones of your own. You 16917a69bbfbSPeter Wemm can examine and change field validation attributes with the following 16927a69bbfbSPeter Wemm functions: 16937a69bbfbSPeter Wemmint set_field_type(FIELD *field, /* field to alter */ 16947a69bbfbSPeter Wemm FIELDTYPE *ftype, /* type to associate */ 16957a69bbfbSPeter Wemm ...); /* additional arguments*/ 16967a69bbfbSPeter Wemm 16977a69bbfbSPeter WemmFIELDTYPE *field_type(FIELD *field); /* field to query */ 16987a69bbfbSPeter Wemm 16997a69bbfbSPeter Wemm The validation type of a field is considered an attribute of the 17007a69bbfbSPeter Wemm field. As with other field attributes, Also, doing set_field_type() 17017a69bbfbSPeter Wemm with a NULL field default will change the system default for 17027a69bbfbSPeter Wemm validation of newly-created fields. 17037a69bbfbSPeter Wemm 17047a69bbfbSPeter Wemm Here are the pre-defined validation types: 17057a69bbfbSPeter Wemm 17067a69bbfbSPeter Wemm TYPE_ALPHA 17077a69bbfbSPeter Wemm 17087a69bbfbSPeter Wemm This field type accepts alphabetic data; no blanks, no digits, no 17097a69bbfbSPeter Wemm special characters (this is checked at character-entry time). It is 17107a69bbfbSPeter Wemm set up with: 17117a69bbfbSPeter Wemmint set_field_type(FIELD *field, /* field to alter */ 17127a69bbfbSPeter Wemm TYPE_ALPHA, /* type to associate */ 17137a69bbfbSPeter Wemm int width); /* maximum width of field */ 17147a69bbfbSPeter Wemm 17157a69bbfbSPeter Wemm The width argument sets a minimum width of data. Typically you will 17167a69bbfbSPeter Wemm want to set this to the field width; if it is greater than the field 17177a69bbfbSPeter Wemm width, the validation check will always fail. A minimum width of zero 17187a69bbfbSPeter Wemm makes field completion optional. 17197a69bbfbSPeter Wemm 17207a69bbfbSPeter Wemm TYPE_ALNUM 17217a69bbfbSPeter Wemm 17227a69bbfbSPeter Wemm This field type accepts alphabetic data and digits; no blanks, no 17237a69bbfbSPeter Wemm special characters (this is checked at character-entry time). It is 17247a69bbfbSPeter Wemm set up with: 17257a69bbfbSPeter Wemmint set_field_type(FIELD *field, /* field to alter */ 17267a69bbfbSPeter Wemm TYPE_ALNUM, /* type to associate */ 17277a69bbfbSPeter Wemm int width); /* maximum width of field */ 17287a69bbfbSPeter Wemm 17297a69bbfbSPeter Wemm The width argument sets a minimum width of data. As with TYPE_ALPHA, 17307a69bbfbSPeter Wemm typically you will want to set this to the field width; if it is 17317a69bbfbSPeter Wemm greater than the field width, the validation check will always fail. A 17327a69bbfbSPeter Wemm minimum width of zero makes field completion optional. 17337a69bbfbSPeter Wemm 17347a69bbfbSPeter Wemm TYPE_ENUM 17357a69bbfbSPeter Wemm 17367a69bbfbSPeter Wemm This type allows you to restrict a field's values to be among a 17377a69bbfbSPeter Wemm specified set of string values (for example, the two-letter postal 17387a69bbfbSPeter Wemm codes for U.S. states). It is set up with: 17397a69bbfbSPeter Wemmint set_field_type(FIELD *field, /* field to alter */ 17407a69bbfbSPeter Wemm TYPE_ENUM, /* type to associate */ 17417a69bbfbSPeter Wemm char **valuelist; /* list of possible values */ 17427a69bbfbSPeter Wemm int checkcase; /* case-sensitive? */ 17437a69bbfbSPeter Wemm int checkunique); /* must specify uniquely? */ 17447a69bbfbSPeter Wemm 17457a69bbfbSPeter Wemm The valuelist parameter must point at a NULL-terminated list of valid 17467a69bbfbSPeter Wemm strings. The checkcase argument, if true, makes comparison with the 17477a69bbfbSPeter Wemm string case-sensitive. 17487a69bbfbSPeter Wemm 17497a69bbfbSPeter Wemm When the user exits a TYPE_ENUM field, the validation procedure tries 17507a69bbfbSPeter Wemm to complete the data in the buffer to a valid entry. If a complete 17517a69bbfbSPeter Wemm choice string has been entered, it is of course valid. But it is also 17527a69bbfbSPeter Wemm possible to enter a prefix of a valid string and have it completed for 17537a69bbfbSPeter Wemm you. 17547a69bbfbSPeter Wemm 17557a69bbfbSPeter Wemm By default, if you enter such a prefix and it matches more than one 17567a69bbfbSPeter Wemm value in the string list, the prefix will be completed to the first 17577a69bbfbSPeter Wemm matching value. But the checkunique argument, if true, requires prefix 17587a69bbfbSPeter Wemm matches to be unique in order to be valid. 17597a69bbfbSPeter Wemm 17607a69bbfbSPeter Wemm The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be 17617a69bbfbSPeter Wemm particularly useful with these fields. 17627a69bbfbSPeter Wemm 17637a69bbfbSPeter Wemm TYPE_INTEGER 17647a69bbfbSPeter Wemm 17657a69bbfbSPeter Wemm This field type accepts an integer. It is set up as follows: 17667a69bbfbSPeter Wemmint set_field_type(FIELD *field, /* field to alter */ 17677a69bbfbSPeter Wemm TYPE_INTEGER, /* type to associate */ 17687a69bbfbSPeter Wemm int padding, /* # places to zero-pad to */ 17697a69bbfbSPeter Wemm int vmin, int vmax); /* valid range */ 17707a69bbfbSPeter Wemm 17717a69bbfbSPeter Wemm Valid characters consist of an optional leading minus and digits. The 17727a69bbfbSPeter Wemm range check is performed on exit. If the range maximum is less than or 17737a69bbfbSPeter Wemm equal to the minimum, the range is ignored. 17747a69bbfbSPeter Wemm 17757a69bbfbSPeter Wemm If the value passes its range check, it is padded with as many leading 17767a69bbfbSPeter Wemm zero digits as necessary to meet the padding argument. 17777a69bbfbSPeter Wemm 17787a69bbfbSPeter Wemm A TYPE_INTEGER value buffer can conveniently be interpreted with the C 17797a69bbfbSPeter Wemm library function atoi(3). 17807a69bbfbSPeter Wemm 17817a69bbfbSPeter Wemm TYPE_NUMERIC 17827a69bbfbSPeter Wemm 17837a69bbfbSPeter Wemm This field type accepts a decimal number. It is set up as follows: 17847a69bbfbSPeter Wemmint set_field_type(FIELD *field, /* field to alter */ 17857a69bbfbSPeter Wemm TYPE_NUMERIC, /* type to associate */ 17867a69bbfbSPeter Wemm int padding, /* # places of precision */ 17877a69bbfbSPeter Wemm double vmin, double vmax); /* valid range */ 17887a69bbfbSPeter Wemm 17897a69bbfbSPeter Wemm Valid characters consist of an optional leading minus and digits. 17907a69bbfbSPeter Wemm possibly including a decimal point. If your system supports locale's, 17917a69bbfbSPeter Wemm the decimal point character used must be the one defined by your 17927a69bbfbSPeter Wemm locale. The range check is performed on exit. If the range maximum is 17937a69bbfbSPeter Wemm less than or equal to the minimum, the range is ignored. 17947a69bbfbSPeter Wemm 17957a69bbfbSPeter Wemm If the value passes its range check, it is padded with as many 17967a69bbfbSPeter Wemm trailing zero digits as necessary to meet the padding argument. 17977a69bbfbSPeter Wemm 17987a69bbfbSPeter Wemm A TYPE_NUMERIC value buffer can conveniently be interpreted with the C 17997a69bbfbSPeter Wemm library function atof(3). 18007a69bbfbSPeter Wemm 18017a69bbfbSPeter Wemm TYPE_REGEXP 18027a69bbfbSPeter Wemm 18037a69bbfbSPeter Wemm This field type accepts data matching a regular expression. It is set 18047a69bbfbSPeter Wemm up as follows: 18057a69bbfbSPeter Wemmint set_field_type(FIELD *field, /* field to alter */ 18067a69bbfbSPeter Wemm TYPE_REGEXP, /* type to associate */ 18077a69bbfbSPeter Wemm char *regexp); /* expression to match */ 18087a69bbfbSPeter Wemm 18097a69bbfbSPeter Wemm The syntax for regular expressions is that of regcomp(3). The check 18107a69bbfbSPeter Wemm for regular-expression match is performed on exit. 18117a69bbfbSPeter Wemm 18127a69bbfbSPeter WemmDirect Field Buffer Manipulation 18137a69bbfbSPeter Wemm 18147a69bbfbSPeter Wemm The chief attribute of a field is its buffer contents. When a form has 18157a69bbfbSPeter Wemm been completed, your application usually needs to know the state of 18167a69bbfbSPeter Wemm each field buffer. You can find this out with: 18177a69bbfbSPeter Wemmchar *field_buffer(FIELD *field, /* field to query */ 18187a69bbfbSPeter Wemm int bufindex); /* number of buffer to query */ 18197a69bbfbSPeter Wemm 18207a69bbfbSPeter Wemm Normally, the state of the zero-numbered buffer for each field is set 18217a69bbfbSPeter Wemm by the user's editing actions on that field. It is sometimes useful to 18227a69bbfbSPeter Wemm be able to set the value of the zero-numbered (or some other) buffer 18237a69bbfbSPeter Wemm from your application: 18247a69bbfbSPeter Wemmint set_field_buffer(FIELD *field, /* field to alter */ 18257a69bbfbSPeter Wemm int bufindex, /* number of buffer to alter */ 18267a69bbfbSPeter Wemm char *value); /* string value to set */ 18277a69bbfbSPeter Wemm 18287a69bbfbSPeter Wemm If the field is not large enough and cannot be resized to a 18297a69bbfbSPeter Wemm sufficiently large size to contain the specified value, the value will 18307a69bbfbSPeter Wemm be truncated to fit. 18317a69bbfbSPeter Wemm 18327a69bbfbSPeter Wemm Calling field_buffer() with a null field pointer will raise an error. 18337a69bbfbSPeter Wemm Calling field_buffer() on a field not currently selected for input 18347a69bbfbSPeter Wemm will return a correct value. Calling field_buffer() on a field that is 18357a69bbfbSPeter Wemm currently selected for input may not necessarily give a correct field 18367a69bbfbSPeter Wemm buffer value, because entered data is not necessarily copied to buffer 18377a69bbfbSPeter Wemm zero before the exit validation check. To guarantee that the returned 18387a69bbfbSPeter Wemm buffer value reflects on-screen reality, call field_buffer() either 18397a69bbfbSPeter Wemm (1) in the field's exit validation check routine, (2) from the field's 18407a69bbfbSPeter Wemm or form's initialization or termination hooks, or (3) just after a 18417a69bbfbSPeter Wemm REQ_VALIDATION request has been processed by the forms driver. 18427a69bbfbSPeter Wemm 18437a69bbfbSPeter WemmAttributes of Forms 18447a69bbfbSPeter Wemm 18457a69bbfbSPeter Wemm As with field attributes, form attributes inherit a default from a 18467a69bbfbSPeter Wemm system default form structure. These defaults can be queried or set by 18477a69bbfbSPeter Wemm of these functions using a form-pointer argument of NULL. 18487a69bbfbSPeter Wemm 18497a69bbfbSPeter Wemm The principal attribute of a form is its field list. You can query and 18507a69bbfbSPeter Wemm change this list with: 18517a69bbfbSPeter Wemmint set_form_fields(FORM *form, /* form to alter */ 18527a69bbfbSPeter Wemm FIELD **fields); /* fields to connect */ 18537a69bbfbSPeter Wemm 18547a69bbfbSPeter Wemmchar *form_fields(FORM *form); /* fetch fields of form */ 18557a69bbfbSPeter Wemm 18567a69bbfbSPeter Wemmint field_count(FORM *form); /* count connect fields */ 18577a69bbfbSPeter Wemm 18587a69bbfbSPeter Wemm The second argument of set_form_fields() may be a NULL-terminated 18597a69bbfbSPeter Wemm field pointer array like the one required by new_form(). In that case, 18607a69bbfbSPeter Wemm the old fields of the form are disconnected but not freed (and 18617a69bbfbSPeter Wemm eligible to be connected to other forms), then the new fields are 18627a69bbfbSPeter Wemm connected. 18637a69bbfbSPeter Wemm 18647a69bbfbSPeter Wemm It may also be null, in which case the old fields are disconnected 18657a69bbfbSPeter Wemm (and not freed) but no new ones are connected. 18667a69bbfbSPeter Wemm 18677a69bbfbSPeter Wemm The field_count() function simply counts the number of fields 18687a69bbfbSPeter Wemm connected to a given from. It returns -1 if the form-pointer argument 18697a69bbfbSPeter Wemm is NULL. 18707a69bbfbSPeter Wemm 18717a69bbfbSPeter WemmControl of Form Display 18727a69bbfbSPeter Wemm 18737a69bbfbSPeter Wemm In the overview section, you saw that to display a form you normally 18747a69bbfbSPeter Wemm start by defining its size (and fields), posting it, and refreshing 18757a69bbfbSPeter Wemm the screen. There is an hidden step before posting, which is the 18767a69bbfbSPeter Wemm association of the form with a frame window (actually, a pair of 18777a69bbfbSPeter Wemm windows) within which it will be displayed. By default, the forms 18787a69bbfbSPeter Wemm library associates every form with the full-screen window stdscr. 18797a69bbfbSPeter Wemm 18807a69bbfbSPeter Wemm By making this step explicit, you can associate a form with a declared 18817a69bbfbSPeter Wemm frame window on your screen display. This can be useful if you want to 18827a69bbfbSPeter Wemm adapt the form display to different screen sizes, dynamically tile 18837a69bbfbSPeter Wemm forms on the screen, or use a form as part of an interface layout 18847a69bbfbSPeter Wemm managed by panels. 18857a69bbfbSPeter Wemm 18867a69bbfbSPeter Wemm The two windows associated with each form have the same functions as 18877a69bbfbSPeter Wemm their analogues in the menu library. Both these windows are painted 18887a69bbfbSPeter Wemm when the form is posted and erased when the form is unposted. 18897a69bbfbSPeter Wemm 18907a69bbfbSPeter Wemm The outer or frame window is not otherwise touched by the form 18917a69bbfbSPeter Wemm routines. It exists so the programmer can associate a title, a border, 18927a69bbfbSPeter Wemm or perhaps help text with the form and have it properly refreshed or 18937a69bbfbSPeter Wemm erased at post/unpost time. The inner window or subwindow is where the 18947a69bbfbSPeter Wemm current form page is actually displayed. 18957a69bbfbSPeter Wemm 18967a69bbfbSPeter Wemm In order to declare your own frame window for a form, you will need to 18977a69bbfbSPeter Wemm know the size of the form's bounding rectangle. You can get this 18987a69bbfbSPeter Wemm information with: 18997a69bbfbSPeter Wemmint scale_form(FORM *form, /* form to query */ 19007a69bbfbSPeter Wemm int *rows, /* form rows */ 19017a69bbfbSPeter Wemm int *cols); /* form cols */ 19027a69bbfbSPeter Wemm 19037a69bbfbSPeter Wemm The form dimensions are passed back in the locations pointed to by the 19047a69bbfbSPeter Wemm arguments. Once you have this information, you can use it to declare 19057a69bbfbSPeter Wemm of windows, then use one of these functions: 19067a69bbfbSPeter Wemmint set_form_win(FORM *form, /* form to alter */ 19077a69bbfbSPeter Wemm WINDOW *win); /* frame window to connect */ 19087a69bbfbSPeter Wemm 19097a69bbfbSPeter WemmWINDOW *form_win(FORM *form); /* fetch frame window of form */ 19107a69bbfbSPeter Wemm 19117a69bbfbSPeter Wemmint set_form_sub(FORM *form, /* form to alter */ 19127a69bbfbSPeter Wemm WINDOW *win); /* form subwindow to connect */ 19137a69bbfbSPeter Wemm 19147a69bbfbSPeter WemmWINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ 19157a69bbfbSPeter Wemm 19167a69bbfbSPeter Wemm Note that curses operations, including refresh(), on the form, should 19177a69bbfbSPeter Wemm be done on the frame window, not the form subwindow. 19187a69bbfbSPeter Wemm 19197a69bbfbSPeter Wemm It is possible to check from your application whether all of a 19207a69bbfbSPeter Wemm scrollable field is actually displayed within the menu subwindow. Use 19217a69bbfbSPeter Wemm these functions: 19227a69bbfbSPeter Wemmint data_ahead(FORM *form); /* form to be queried */ 19237a69bbfbSPeter Wemm 19247a69bbfbSPeter Wemmint data_behind(FORM *form); /* form to be queried */ 19257a69bbfbSPeter Wemm 19267a69bbfbSPeter Wemm The function data_ahead() returns TRUE if (a) the current field is 19277a69bbfbSPeter Wemm one-line and has undisplayed data off to the right, (b) the current 19287a69bbfbSPeter Wemm field is multi-line and there is data off-screen below it. 19297a69bbfbSPeter Wemm 19307a69bbfbSPeter Wemm The function data_behind() returns TRUE if the first (upper left hand) 19317a69bbfbSPeter Wemm character position is off-screen (not being displayed). 19327a69bbfbSPeter Wemm 19337a69bbfbSPeter Wemm Finally, there is a function to restore the form window's cursor to 19347a69bbfbSPeter Wemm the value expected by the forms driver: 19357a69bbfbSPeter Wemmint pos_form_cursor(FORM *) /* form to be queried */ 19367a69bbfbSPeter Wemm 19377a69bbfbSPeter Wemm If your application changes the form window cursor, call this function 19387a69bbfbSPeter Wemm before handing control back to the forms driver in order to 19397a69bbfbSPeter Wemm re-synchronize it. 19407a69bbfbSPeter Wemm 19417a69bbfbSPeter WemmInput Processing in the Forms Driver 19427a69bbfbSPeter Wemm 19437a69bbfbSPeter Wemm The function form_driver() handles virtualized input requests for form 19447a69bbfbSPeter Wemm navigation, editing, and validation requests, just as menu_driver does 19457a69bbfbSPeter Wemm for menus (see the section on menu input handling). 19467a69bbfbSPeter Wemmint form_driver(FORM *form, /* form to pass input to */ 19477a69bbfbSPeter Wemm int request); /* form request code */ 19487a69bbfbSPeter Wemm 19497a69bbfbSPeter Wemm Your input virtualization function needs to take input and then 19507a69bbfbSPeter Wemm convert it to either an alphanumeric character (which is treated as 19517a69bbfbSPeter Wemm data to be entered in the currently-selected field), or a forms 19527a69bbfbSPeter Wemm processing request. 19537a69bbfbSPeter Wemm 19547a69bbfbSPeter Wemm The forms driver provides hooks (through input-validation and 19557a69bbfbSPeter Wemm field-termination functions) with which your application code can 19567a69bbfbSPeter Wemm check that the input taken by the driver matched what was expected. 19577a69bbfbSPeter Wemm 19587a69bbfbSPeter Wemm Page Navigation Requests 19597a69bbfbSPeter Wemm 19607a69bbfbSPeter Wemm These requests cause page-level moves through the form, triggering 19617a69bbfbSPeter Wemm display of a new form screen. 19627a69bbfbSPeter Wemm 19637a69bbfbSPeter Wemm REQ_NEXT_PAGE 19647a69bbfbSPeter Wemm Move to the next form page. 19657a69bbfbSPeter Wemm 19667a69bbfbSPeter Wemm REQ_PREV_PAGE 19677a69bbfbSPeter Wemm Move to the previous form page. 19687a69bbfbSPeter Wemm 19697a69bbfbSPeter Wemm REQ_FIRST_PAGE 19707a69bbfbSPeter Wemm Move to the first form page. 19717a69bbfbSPeter Wemm 19727a69bbfbSPeter Wemm REQ_LAST_PAGE 19737a69bbfbSPeter Wemm Move to the last form page. 19747a69bbfbSPeter Wemm 19757a69bbfbSPeter Wemm These requests treat the list as cyclic; that is, REQ_NEXT_PAGE from 19767a69bbfbSPeter Wemm the last page goes to the first, and REQ_PREV_PAGE from the first page 19777a69bbfbSPeter Wemm goes to the last. 19787a69bbfbSPeter Wemm 19797a69bbfbSPeter Wemm Inter-Field Navigation Requests 19807a69bbfbSPeter Wemm 19817a69bbfbSPeter Wemm These requests handle navigation between fields on the same page. 19827a69bbfbSPeter Wemm 19837a69bbfbSPeter Wemm REQ_NEXT_FIELD 19847a69bbfbSPeter Wemm Move to next field. 19857a69bbfbSPeter Wemm 19867a69bbfbSPeter Wemm REQ_PREV_FIELD 19877a69bbfbSPeter Wemm Move to previous field. 19887a69bbfbSPeter Wemm 19897a69bbfbSPeter Wemm REQ_FIRST_FIELD 19907a69bbfbSPeter Wemm Move to the first field. 19917a69bbfbSPeter Wemm 19927a69bbfbSPeter Wemm REQ_LAST_FIELD 19937a69bbfbSPeter Wemm Move to the last field. 19947a69bbfbSPeter Wemm 19957a69bbfbSPeter Wemm REQ_SNEXT_FIELD 19967a69bbfbSPeter Wemm Move to sorted next field. 19977a69bbfbSPeter Wemm 19987a69bbfbSPeter Wemm REQ_SPREV_FIELD 19997a69bbfbSPeter Wemm Move to sorted previous field. 20007a69bbfbSPeter Wemm 20017a69bbfbSPeter Wemm REQ_SFIRST_FIELD 20027a69bbfbSPeter Wemm Move to the sorted first field. 20037a69bbfbSPeter Wemm 20047a69bbfbSPeter Wemm REQ_SLAST_FIELD 20057a69bbfbSPeter Wemm Move to the sorted last field. 20067a69bbfbSPeter Wemm 20077a69bbfbSPeter Wemm REQ_LEFT_FIELD 20087a69bbfbSPeter Wemm Move left to field. 20097a69bbfbSPeter Wemm 20107a69bbfbSPeter Wemm REQ_RIGHT_FIELD 20117a69bbfbSPeter Wemm Move right to field. 20127a69bbfbSPeter Wemm 20137a69bbfbSPeter Wemm REQ_UP_FIELD 20147a69bbfbSPeter Wemm Move up to field. 20157a69bbfbSPeter Wemm 20167a69bbfbSPeter Wemm REQ_DOWN_FIELD 20177a69bbfbSPeter Wemm Move down to field. 20187a69bbfbSPeter Wemm 20197a69bbfbSPeter Wemm These requests treat the list of fields on a page as cyclic; that is, 20207a69bbfbSPeter Wemm REQ_NEXT_FIELD from the last field goes to the first, and 20217a69bbfbSPeter Wemm REQ_PREV_FIELD from the first field goes to the last. The order of the 20227a69bbfbSPeter Wemm fields for these (and the REQ_FIRST_FIELD and REQ_LAST_FIELD requests) 20237a69bbfbSPeter Wemm is simply the order of the field pointers in the form array (as set up 20247a69bbfbSPeter Wemm by new_form() or set_form_fields() 20257a69bbfbSPeter Wemm 20267a69bbfbSPeter Wemm It is also possible to traverse the fields as if they had been sorted 20277a69bbfbSPeter Wemm in screen-position order, so the sequence goes left-to-right and 20287a69bbfbSPeter Wemm top-to-bottom. To do this, use the second group of four 20297a69bbfbSPeter Wemm sorted-movement requests. 20307a69bbfbSPeter Wemm 20317a69bbfbSPeter Wemm Finally, it is possible to move between fields using visual directions 20327a69bbfbSPeter Wemm up, down, right, and left. To accomplish this, use the third group of 20337a69bbfbSPeter Wemm four requests. Note, however, that the position of a form for purposes 20347a69bbfbSPeter Wemm of these requests is its upper-left corner. 20357a69bbfbSPeter Wemm 20367a69bbfbSPeter Wemm For example, suppose you have a multi-line field B, and two 20377a69bbfbSPeter Wemm single-line fields A and C on the same line with B, with A to the left 20387a69bbfbSPeter Wemm of B and C to the right of B. A REQ_MOVE_RIGHT from A will go to B 20397a69bbfbSPeter Wemm only if A, B, and C all share the same first line; otherwise it will 20407a69bbfbSPeter Wemm skip over B to C. 20417a69bbfbSPeter Wemm 20427a69bbfbSPeter Wemm Intra-Field Navigation Requests 20437a69bbfbSPeter Wemm 20447a69bbfbSPeter Wemm These requests drive movement of the edit cursor within the currently 20457a69bbfbSPeter Wemm selected field. 20467a69bbfbSPeter Wemm 20477a69bbfbSPeter Wemm REQ_NEXT_CHAR 20487a69bbfbSPeter Wemm Move to next character. 20497a69bbfbSPeter Wemm 20507a69bbfbSPeter Wemm REQ_PREV_CHAR 20517a69bbfbSPeter Wemm Move to previous character. 20527a69bbfbSPeter Wemm 20537a69bbfbSPeter Wemm REQ_NEXT_LINE 20547a69bbfbSPeter Wemm Move to next line. 20557a69bbfbSPeter Wemm 20567a69bbfbSPeter Wemm REQ_PREV_LINE 20577a69bbfbSPeter Wemm Move to previous line. 20587a69bbfbSPeter Wemm 20597a69bbfbSPeter Wemm REQ_NEXT_WORD 20607a69bbfbSPeter Wemm Move to next word. 20617a69bbfbSPeter Wemm 20627a69bbfbSPeter Wemm REQ_PREV_WORD 20637a69bbfbSPeter Wemm Move to previous word. 20647a69bbfbSPeter Wemm 20657a69bbfbSPeter Wemm REQ_BEG_FIELD 20667a69bbfbSPeter Wemm Move to beginning of field. 20677a69bbfbSPeter Wemm 20687a69bbfbSPeter Wemm REQ_END_FIELD 20697a69bbfbSPeter Wemm Move to end of field. 20707a69bbfbSPeter Wemm 20717a69bbfbSPeter Wemm REQ_BEG_LINE 20727a69bbfbSPeter Wemm Move to beginning of line. 20737a69bbfbSPeter Wemm 20747a69bbfbSPeter Wemm REQ_END_LINE 20757a69bbfbSPeter Wemm Move to end of line. 20767a69bbfbSPeter Wemm 20777a69bbfbSPeter Wemm REQ_LEFT_CHAR 20787a69bbfbSPeter Wemm Move left in field. 20797a69bbfbSPeter Wemm 20807a69bbfbSPeter Wemm REQ_RIGHT_CHAR 20817a69bbfbSPeter Wemm Move right in field. 20827a69bbfbSPeter Wemm 20837a69bbfbSPeter Wemm REQ_UP_CHAR 20847a69bbfbSPeter Wemm Move up in field. 20857a69bbfbSPeter Wemm 20867a69bbfbSPeter Wemm REQ_DOWN_CHAR 20877a69bbfbSPeter Wemm Move down in field. 20887a69bbfbSPeter Wemm 20897a69bbfbSPeter Wemm Each word is separated from the previous and next characters by 20907a69bbfbSPeter Wemm whitespace. The commands to move to beginning and end of line or field 20917a69bbfbSPeter Wemm look for the first or last non-pad character in their ranges. 20927a69bbfbSPeter Wemm 20937a69bbfbSPeter Wemm Scrolling Requests 20947a69bbfbSPeter Wemm 20957a69bbfbSPeter Wemm Fields that are dynamic and have grown and fields explicitly created 20967a69bbfbSPeter Wemm with offscreen rows are scrollable. One-line fields scroll 20977a69bbfbSPeter Wemm horizontally; multi-line fields scroll vertically. Most scrolling is 20987a69bbfbSPeter Wemm triggered by editing and intra-field movement (the library scrolls the 20997a69bbfbSPeter Wemm field to keep the cursor visible). It is possible to explicitly 21007a69bbfbSPeter Wemm request scrolling with the following requests: 21017a69bbfbSPeter Wemm 21027a69bbfbSPeter Wemm REQ_SCR_FLINE 21037a69bbfbSPeter Wemm Scroll vertically forward a line. 21047a69bbfbSPeter Wemm 21057a69bbfbSPeter Wemm REQ_SCR_BLINE 21067a69bbfbSPeter Wemm Scroll vertically backward a line. 21077a69bbfbSPeter Wemm 21087a69bbfbSPeter Wemm REQ_SCR_FPAGE 21097a69bbfbSPeter Wemm Scroll vertically forward a page. 21107a69bbfbSPeter Wemm 21117a69bbfbSPeter Wemm REQ_SCR_BPAGE 21127a69bbfbSPeter Wemm Scroll vertically backward a page. 21137a69bbfbSPeter Wemm 21147a69bbfbSPeter Wemm REQ_SCR_FHPAGE 21157a69bbfbSPeter Wemm Scroll vertically forward half a page. 21167a69bbfbSPeter Wemm 21177a69bbfbSPeter Wemm REQ_SCR_BHPAGE 21187a69bbfbSPeter Wemm Scroll vertically backward half a page. 21197a69bbfbSPeter Wemm 21207a69bbfbSPeter Wemm REQ_SCR_FCHAR 21217a69bbfbSPeter Wemm Scroll horizontally forward a character. 21227a69bbfbSPeter Wemm 21237a69bbfbSPeter Wemm REQ_SCR_BCHAR 21247a69bbfbSPeter Wemm Scroll horizontally backward a character. 21257a69bbfbSPeter Wemm 21267a69bbfbSPeter Wemm REQ_SCR_HFLINE 21277a69bbfbSPeter Wemm Scroll horizontally one field width forward. 21287a69bbfbSPeter Wemm 21297a69bbfbSPeter Wemm REQ_SCR_HBLINE 21307a69bbfbSPeter Wemm Scroll horizontally one field width backward. 21317a69bbfbSPeter Wemm 21327a69bbfbSPeter Wemm REQ_SCR_HFHALF 21337a69bbfbSPeter Wemm Scroll horizontally one half field width forward. 21347a69bbfbSPeter Wemm 21357a69bbfbSPeter Wemm REQ_SCR_HBHALF 21367a69bbfbSPeter Wemm Scroll horizontally one half field width backward. 21377a69bbfbSPeter Wemm 21387a69bbfbSPeter Wemm For scrolling purposes, a page of a field is the height of its visible 21397a69bbfbSPeter Wemm part. 21407a69bbfbSPeter Wemm 21417a69bbfbSPeter Wemm Editing Requests 21427a69bbfbSPeter Wemm 21437a69bbfbSPeter Wemm When you pass the forms driver an ASCII character, it is treated as a 21447a69bbfbSPeter Wemm request to add the character to the field's data buffer. Whether this 21457a69bbfbSPeter Wemm is an insertion or a replacement depends on the field's edit mode 21467a69bbfbSPeter Wemm (insertion is the default. 21477a69bbfbSPeter Wemm 21487a69bbfbSPeter Wemm The following requests support editing the field and changing the edit 21497a69bbfbSPeter Wemm mode: 21507a69bbfbSPeter Wemm 21517a69bbfbSPeter Wemm REQ_INS_MODE 21527a69bbfbSPeter Wemm Set insertion mode. 21537a69bbfbSPeter Wemm 21547a69bbfbSPeter Wemm REQ_OVL_MODE 21557a69bbfbSPeter Wemm Set overlay mode. 21567a69bbfbSPeter Wemm 21577a69bbfbSPeter Wemm REQ_NEW_LINE 21587a69bbfbSPeter Wemm New line request (see below for explanation). 21597a69bbfbSPeter Wemm 21607a69bbfbSPeter Wemm REQ_INS_CHAR 21617a69bbfbSPeter Wemm Insert space at character location. 21627a69bbfbSPeter Wemm 21637a69bbfbSPeter Wemm REQ_INS_LINE 21647a69bbfbSPeter Wemm Insert blank line at character location. 21657a69bbfbSPeter Wemm 21667a69bbfbSPeter Wemm REQ_DEL_CHAR 21677a69bbfbSPeter Wemm Delete character at cursor. 21687a69bbfbSPeter Wemm 21697a69bbfbSPeter Wemm REQ_DEL_PREV 21707a69bbfbSPeter Wemm Delete previous word at cursor. 21717a69bbfbSPeter Wemm 21727a69bbfbSPeter Wemm REQ_DEL_LINE 21737a69bbfbSPeter Wemm Delete line at cursor. 21747a69bbfbSPeter Wemm 21757a69bbfbSPeter Wemm REQ_DEL_WORD 21767a69bbfbSPeter Wemm Delete word at cursor. 21777a69bbfbSPeter Wemm 21787a69bbfbSPeter Wemm REQ_CLR_EOL 21797a69bbfbSPeter Wemm Clear to end of line. 21807a69bbfbSPeter Wemm 21817a69bbfbSPeter Wemm REQ_CLR_EOF 21827a69bbfbSPeter Wemm Clear to end of field. 21837a69bbfbSPeter Wemm 21847a69bbfbSPeter Wemm REQ_CLEAR_FIELD 21857a69bbfbSPeter Wemm Clear entire field. 21867a69bbfbSPeter Wemm 21877a69bbfbSPeter Wemm The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is 21887a69bbfbSPeter Wemm complicated and partly controlled by a pair of forms options. The 21897a69bbfbSPeter Wemm special cases are triggered when the cursor is at the beginning of a 21907a69bbfbSPeter Wemm field, or on the last line of the field. 21917a69bbfbSPeter Wemm 21927a69bbfbSPeter Wemm First, we consider REQ_NEW_LINE: 21937a69bbfbSPeter Wemm 21947a69bbfbSPeter Wemm The normal behavior of REQ_NEW_LINE in insert mode is to break the 21957a69bbfbSPeter Wemm current line at the position of the edit cursor, inserting the portion 21967a69bbfbSPeter Wemm of the current line after the cursor as a new line following the 21977a69bbfbSPeter Wemm current and moving the cursor to the beginning of that new line (you 21987a69bbfbSPeter Wemm may think of this as inserting a newline in the field buffer). 21997a69bbfbSPeter Wemm 22007a69bbfbSPeter Wemm The normal behavior of REQ_NEW_LINE in overlay mode is to clear the 22017a69bbfbSPeter Wemm current line from the position of the edit cursor to end of line. The 22027a69bbfbSPeter Wemm cursor is then moved to the beginning of the next line. 22037a69bbfbSPeter Wemm 22047a69bbfbSPeter Wemm However, REQ_NEW_LINE at the beginning of a field, or on the last line 22057a69bbfbSPeter Wemm of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD option is 22067a69bbfbSPeter Wemm off, this special action is disabled. 22077a69bbfbSPeter Wemm 22087a69bbfbSPeter Wemm Now, let us consider REQ_DEL_PREV: 22097a69bbfbSPeter Wemm 22107a69bbfbSPeter Wemm The normal behavior of REQ_DEL_PREV is to delete the previous 22117a69bbfbSPeter Wemm character. If insert mode is on, and the cursor is at the start of a 22127a69bbfbSPeter Wemm line, and the text on that line will fit on the previous one, it 22137a69bbfbSPeter Wemm instead appends the contents of the current line to the previous one 22147a69bbfbSPeter Wemm and deletes the current line (you may think of this as deleting a 22157a69bbfbSPeter Wemm newline from the field buffer). 22167a69bbfbSPeter Wemm 22177a69bbfbSPeter Wemm However, REQ_DEL_PREV at the beginning of a field is instead treated 22187a69bbfbSPeter Wemm as a REQ_PREV_FIELD. 22197a69bbfbSPeter Wemm 22207a69bbfbSPeter Wemm If the O_BS_OVERLOAD option is off, this special action is disabled 22217a69bbfbSPeter Wemm and the forms driver just returns E_REQUEST_DENIED. 22227a69bbfbSPeter Wemm 22237a69bbfbSPeter Wemm See Form Options for discussion of how to set and clear the overload 22247a69bbfbSPeter Wemm options. 22257a69bbfbSPeter Wemm 22267a69bbfbSPeter Wemm Order Requests 22277a69bbfbSPeter Wemm 22287a69bbfbSPeter Wemm If the type of your field is ordered, and has associated functions for 22297a69bbfbSPeter Wemm getting the next and previous values of the type from a given value, 22307a69bbfbSPeter Wemm there are requests that can fetch that value into the field buffer: 22317a69bbfbSPeter Wemm 22327a69bbfbSPeter Wemm REQ_NEXT_CHOICE 22337a69bbfbSPeter Wemm Place the successor value of the current value in the buffer. 22347a69bbfbSPeter Wemm 22357a69bbfbSPeter Wemm REQ_PREV_CHOICE 22367a69bbfbSPeter Wemm Place the predecessor value of the current value in the buffer. 22377a69bbfbSPeter Wemm 22387a69bbfbSPeter Wemm Of the built-in field types, only TYPE_ENUM has built-in successor and 22397a69bbfbSPeter Wemm predecessor functions. When you define a field type of your own (see 22407a69bbfbSPeter Wemm Custom Validation Types), you can associate our own ordering 22417a69bbfbSPeter Wemm functions. 22427a69bbfbSPeter Wemm 22437a69bbfbSPeter Wemm Application Commands 22447a69bbfbSPeter Wemm 22457a69bbfbSPeter Wemm Form requests are represented as integers above the curses value 22467a69bbfbSPeter Wemm greater than KEY_MAX and less than or equal to the constant 22477a69bbfbSPeter Wemm MAX_COMMAND. If your input-virtualization routine returns a value 22487a69bbfbSPeter Wemm above MAX_COMMAND, the forms driver will ignore it. 22497a69bbfbSPeter Wemm 22507a69bbfbSPeter WemmField Change Hooks 22517a69bbfbSPeter Wemm 22527a69bbfbSPeter Wemm It is possible to set function hooks to be executed whenever the 22537a69bbfbSPeter Wemm current field or form changes. Here are the functions that support 22547a69bbfbSPeter Wemm this: 22557a69bbfbSPeter Wemmtypedef void (*HOOK)(); /* pointer to function returning void */ 22567a69bbfbSPeter Wemm 22577a69bbfbSPeter Wemmint set_form_init(FORM *form, /* form to alter */ 22587a69bbfbSPeter Wemm HOOK hook); /* initialization hook */ 22597a69bbfbSPeter Wemm 22607a69bbfbSPeter WemmHOOK form_init(FORM *form); /* form to query */ 22617a69bbfbSPeter Wemm 22627a69bbfbSPeter Wemmint set_form_term(FORM *form, /* form to alter */ 22637a69bbfbSPeter Wemm HOOK hook); /* termination hook */ 22647a69bbfbSPeter Wemm 22657a69bbfbSPeter WemmHOOK form_term(FORM *form); /* form to query */ 22667a69bbfbSPeter Wemm 22677a69bbfbSPeter Wemmint set_field_init(FORM *form, /* form to alter */ 22687a69bbfbSPeter Wemm HOOK hook); /* initialization hook */ 22697a69bbfbSPeter Wemm 22707a69bbfbSPeter WemmHOOK field_init(FORM *form); /* form to query */ 22717a69bbfbSPeter Wemm 22727a69bbfbSPeter Wemmint set_field_term(FORM *form, /* form to alter */ 22737a69bbfbSPeter Wemm HOOK hook); /* termination hook */ 22747a69bbfbSPeter Wemm 22757a69bbfbSPeter WemmHOOK field_term(FORM *form); /* form to query */ 22767a69bbfbSPeter Wemm 22777a69bbfbSPeter Wemm These functions allow you to either set or query four different hooks. 22787a69bbfbSPeter Wemm In each of the set functions, the second argument should be the 22797a69bbfbSPeter Wemm address of a hook function. These functions differ only in the timing 22807a69bbfbSPeter Wemm of the hook call. 22817a69bbfbSPeter Wemm 22827a69bbfbSPeter Wemm form_init 22837a69bbfbSPeter Wemm This hook is called when the form is posted; also, just after 22847a69bbfbSPeter Wemm each page change operation. 22857a69bbfbSPeter Wemm 22867a69bbfbSPeter Wemm field_init 22877a69bbfbSPeter Wemm This hook is called when the form is posted; also, just after 22887a69bbfbSPeter Wemm each field change 22897a69bbfbSPeter Wemm 22907a69bbfbSPeter Wemm field_term 22917a69bbfbSPeter Wemm This hook is called just after field validation; that is, just 22927a69bbfbSPeter Wemm before the field is altered. It is also called when the form is 22937a69bbfbSPeter Wemm unposted. 22947a69bbfbSPeter Wemm 22957a69bbfbSPeter Wemm form_term 22967a69bbfbSPeter Wemm This hook is called when the form is unposted; also, just 22977a69bbfbSPeter Wemm before each page change operation. 22987a69bbfbSPeter Wemm 22997a69bbfbSPeter Wemm Calls to these hooks may be triggered 23007a69bbfbSPeter Wemm 1. When user editing requests are processed by the forms driver 23017a69bbfbSPeter Wemm 2. When the current page is changed by set_current_field() call 23027a69bbfbSPeter Wemm 3. When the current field is changed by a set_form_page() call 23037a69bbfbSPeter Wemm 23047a69bbfbSPeter Wemm See Field Change Commands for discussion of the latter two cases. 23057a69bbfbSPeter Wemm 23067a69bbfbSPeter Wemm You can set a default hook for all fields by passing one of the set 23077a69bbfbSPeter Wemm functions a NULL first argument. 23087a69bbfbSPeter Wemm 23097a69bbfbSPeter Wemm You can disable any of these hooks by (re)setting them to NULL, the 23107a69bbfbSPeter Wemm default value. 23117a69bbfbSPeter Wemm 23127a69bbfbSPeter WemmField Change Commands 23137a69bbfbSPeter Wemm 23147a69bbfbSPeter Wemm Normally, navigation through the form will be driven by the user's 23157a69bbfbSPeter Wemm input requests. But sometimes it is useful to be able to move the 23167a69bbfbSPeter Wemm focus for editing and viewing under control of your application, or 23177a69bbfbSPeter Wemm ask which field it currently is in. The following functions help you 23187a69bbfbSPeter Wemm accomplish this: 23197a69bbfbSPeter Wemmint set_current_field(FORM *form, /* form to alter */ 23207a69bbfbSPeter Wemm FIELD *field); /* field to shift to */ 23217a69bbfbSPeter Wemm 23227a69bbfbSPeter WemmFIELD *current_field(FORM *form); /* form to query */ 23237a69bbfbSPeter Wemm 23247a69bbfbSPeter Wemmint field_index(FORM *form, /* form to query */ 23257a69bbfbSPeter Wemm FIELD *field); /* field to get index of */ 23267a69bbfbSPeter Wemm 23277a69bbfbSPeter Wemm The function field_index() returns the index of the given field in the 23287a69bbfbSPeter Wemm given form's field array (the array passed to new_form() or 23297a69bbfbSPeter Wemm set_form_fields()). 23307a69bbfbSPeter Wemm 23317a69bbfbSPeter Wemm The initial current field of a form is the first active field on the 23327a69bbfbSPeter Wemm first page. The function set_form_fields() resets this. 23337a69bbfbSPeter Wemm 23347a69bbfbSPeter Wemm It is also possible to move around by pages. 23357a69bbfbSPeter Wemmint set_form_page(FORM *form, /* form to alter */ 23367a69bbfbSPeter Wemm int page); /* page to go to (0-origin) */ 23377a69bbfbSPeter Wemm 23387a69bbfbSPeter Wemmint form_page(FORM *form); /* return form's current page */ 23397a69bbfbSPeter Wemm 23407a69bbfbSPeter Wemm The initial page of a newly-created form is 0. The function 23417a69bbfbSPeter Wemm set_form_fields() resets this. 23427a69bbfbSPeter Wemm 23437a69bbfbSPeter WemmForm Options 23447a69bbfbSPeter Wemm 23457a69bbfbSPeter Wemm Like fields, forms may have control option bits. They can be changed 23467a69bbfbSPeter Wemm or queried with these functions: 23477a69bbfbSPeter Wemmint set_form_opts(FORM *form, /* form to alter */ 23487a69bbfbSPeter Wemm int attr); /* attribute to set */ 23497a69bbfbSPeter Wemm 23507a69bbfbSPeter Wemmint form_opts_on(FORM *form, /* form to alter */ 23517a69bbfbSPeter Wemm int attr); /* attributes to turn on */ 23527a69bbfbSPeter Wemm 23537a69bbfbSPeter Wemmint form_opts_off(FORM *form, /* form to alter */ 23547a69bbfbSPeter Wemm int attr); /* attributes to turn off */ 23557a69bbfbSPeter Wemm 23567a69bbfbSPeter Wemmint form_opts(FORM *form); /* form to query */ 23577a69bbfbSPeter Wemm 23587a69bbfbSPeter Wemm By default, all options are on. Here are the available option bits: 23597a69bbfbSPeter Wemm 23607a69bbfbSPeter Wemm O_NL_OVERLOAD 23617a69bbfbSPeter Wemm Enable overloading of REQ_NEW_LINE as described in Editing 23627a69bbfbSPeter Wemm Requests. The value of this option is ignored on dynamic fields 23637a69bbfbSPeter Wemm that have not reached their size limit; these have no last 23647a69bbfbSPeter Wemm line, so the circumstances for triggering a REQ_NEXT_FIELD 23657a69bbfbSPeter Wemm never arise. 23667a69bbfbSPeter Wemm 23677a69bbfbSPeter Wemm O_BS_OVERLOAD 23687a69bbfbSPeter Wemm Enable overloading of REQ_DEL_PREV as described in Editing 23697a69bbfbSPeter Wemm Requests. 23707a69bbfbSPeter Wemm 23717a69bbfbSPeter Wemm The option values are bit-masks and can be composed with logical-or in 23727a69bbfbSPeter Wemm the obvious way. 23737a69bbfbSPeter Wemm 23747a69bbfbSPeter WemmCustom Validation Types 23757a69bbfbSPeter Wemm 23767a69bbfbSPeter Wemm The form library gives you the capability to define custom validation 23777a69bbfbSPeter Wemm types of your own. Further, the optional additional arguments of 23787a69bbfbSPeter Wemm set_field_type effectively allow you to parameterize validation types. 23797a69bbfbSPeter Wemm Most of the complications in the validation-type interface have to do 23807a69bbfbSPeter Wemm with the handling of the additional arguments within custom validation 23817a69bbfbSPeter Wemm functions. 23827a69bbfbSPeter Wemm 23837a69bbfbSPeter Wemm Union Types 23847a69bbfbSPeter Wemm 23857a69bbfbSPeter Wemm The simplest way to create a custom data type is to compose it from 23867a69bbfbSPeter Wemm two preexisting ones: 23877a69bbfbSPeter WemmFIELD *link_fieldtype(FIELDTYPE *type1, 23887a69bbfbSPeter Wemm FIELDTYPE *type2); 23897a69bbfbSPeter Wemm 23907a69bbfbSPeter Wemm This function creates a field type that will accept any of the values 23917a69bbfbSPeter Wemm legal for either of its argument field types (which may be either 23927a69bbfbSPeter Wemm predefined or programmer-defined). If a set_field_type() call later 23937a69bbfbSPeter Wemm requires arguments, the new composite type expects all arguments for 23947a69bbfbSPeter Wemm the first type, than all arguments for the second. Order functions 23957a69bbfbSPeter Wemm (see Order Requests) associated with the component types will work on 23967a69bbfbSPeter Wemm the composite; what it does is check the validation function for the 23977a69bbfbSPeter Wemm first type, then for the second, to figure what type the buffer 23987a69bbfbSPeter Wemm contents should be treated as. 23997a69bbfbSPeter Wemm 24007a69bbfbSPeter Wemm New Field Types 24017a69bbfbSPeter Wemm 24027a69bbfbSPeter Wemm To create a field type from scratch, you need to specify one or both 24037a69bbfbSPeter Wemm of the following things: 24047a69bbfbSPeter Wemm * A character-validation function, to check each character as it is 24057a69bbfbSPeter Wemm entered. 24067a69bbfbSPeter Wemm * A field-validation function to be applied on exit from the field. 24077a69bbfbSPeter Wemm 24087a69bbfbSPeter Wemm Here is how you do that: 24097a69bbfbSPeter Wemmtypedef int (*HOOK)(); /* pointer to function returning int */ 24107a69bbfbSPeter Wemm 24117a69bbfbSPeter WemmFIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ 24127a69bbfbSPeter Wemm HOOK c_validate) /* character validator */ 24137a69bbfbSPeter Wemm 24147a69bbfbSPeter Wemmint free_fieldtype(FIELDTYPE *ftype); /* type to free */ 24157a69bbfbSPeter Wemm 24167a69bbfbSPeter Wemm At least one of the arguments of new_fieldtype() must be non-NULL. The 24177a69bbfbSPeter Wemm forms driver will automatically call the new type's validation 24187a69bbfbSPeter Wemm functions at appropriate points in processing a field of the new type. 24197a69bbfbSPeter Wemm 24207a69bbfbSPeter Wemm The function free_fieldtype() deallocates the argument fieldtype, 24217a69bbfbSPeter Wemm freeing all storage associated with it. 24227a69bbfbSPeter Wemm 24237a69bbfbSPeter Wemm Normally, a field validator is called when the user attempts to leave 24247a69bbfbSPeter Wemm the field. Its first argument is a field pointer, from which it can 24257a69bbfbSPeter Wemm get to field buffer 0 and test it. If the function returns TRUE, the 24267a69bbfbSPeter Wemm operation succeeds; if it returns FALSE, the edit cursor stays in the 24277a69bbfbSPeter Wemm field. 24287a69bbfbSPeter Wemm 24297a69bbfbSPeter Wemm A character validator gets the character passed in as a first 24307a69bbfbSPeter Wemm argument. It too should return TRUE if the character is valid, FALSE 24317a69bbfbSPeter Wemm otherwise. 24327a69bbfbSPeter Wemm 24337a69bbfbSPeter Wemm Validation Function Arguments 24347a69bbfbSPeter Wemm 24357a69bbfbSPeter Wemm Your field- and character- validation functions will be passed a 24367a69bbfbSPeter Wemm second argument as well. This second argument is the address of a 24377a69bbfbSPeter Wemm structure (which we will call a pile) built from any of the 24387a69bbfbSPeter Wemm field-type-specific arguments passed to set_field_type(). If no such 24397a69bbfbSPeter Wemm arguments are defined for the field type, this pile pointer argument 24407a69bbfbSPeter Wemm will be NULL. 24417a69bbfbSPeter Wemm 24427a69bbfbSPeter Wemm In order to arrange for such arguments to be passed to your validation 24437a69bbfbSPeter Wemm functions, you must associate a small set of storage-management 24447a69bbfbSPeter Wemm functions with the type. The forms driver will use these to synthesize 24457a69bbfbSPeter Wemm a pile from the trailing arguments of each set_field_type() argument, 24467a69bbfbSPeter Wemm and a pointer to the pile will be passed to the validation functions. 24477a69bbfbSPeter Wemm 24487a69bbfbSPeter Wemm Here is how you make the association: 24497a69bbfbSPeter Wemmtypedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ 24507a69bbfbSPeter Wemmtypedef void (*VOIDHOOK)(); /* pointer to function returning void */ 24517a69bbfbSPeter Wemm 24527a69bbfbSPeter Wemmint set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ 24537a69bbfbSPeter Wemm PTRHOOK make_str, /* make structure from args */ 24547a69bbfbSPeter Wemm PTRHOOK copy_str, /* make copy of structure */ 24557a69bbfbSPeter Wemm VOIDHOOK free_str); /* free structure storage */ 24567a69bbfbSPeter Wemm 24577a69bbfbSPeter Wemm Here is how the storage-management hooks are used: 24587a69bbfbSPeter Wemm 24597a69bbfbSPeter Wemm make_str 24607a69bbfbSPeter Wemm This function is called by set_field_type(). It gets one 24617a69bbfbSPeter Wemm argument, a va_list of the type-specific arguments passed to 24627a69bbfbSPeter Wemm set_field_type(). It is expected to return a pile pointer to a 24637a69bbfbSPeter Wemm data structure that encapsulates those arguments. 24647a69bbfbSPeter Wemm 24657a69bbfbSPeter Wemm copy_str 24667a69bbfbSPeter Wemm This function is called by form library functions that allocate 24677a69bbfbSPeter Wemm new field instances. It is expected to take a pile pointer, 24687a69bbfbSPeter Wemm copy the pile to allocated storage, and return the address of 24697a69bbfbSPeter Wemm the pile copy. 24707a69bbfbSPeter Wemm 24717a69bbfbSPeter Wemm free_str 24727a69bbfbSPeter Wemm This function is called by field- and type-deallocation 24737a69bbfbSPeter Wemm routines in the library. It takes a pile pointer argument, and 24747a69bbfbSPeter Wemm is expected to free the storage of that pile. 24757a69bbfbSPeter Wemm 24767a69bbfbSPeter Wemm The make_str and copy_str functions may return NULL to signal 24777a69bbfbSPeter Wemm allocation failure. The library routines will that call them will 24787a69bbfbSPeter Wemm return error indication when this happens. Thus, your validation 24797a69bbfbSPeter Wemm functions should never see a NULL file pointer and need not check 24807a69bbfbSPeter Wemm specially for it. 24817a69bbfbSPeter Wemm 24827a69bbfbSPeter Wemm Order Functions For Custom Types 24837a69bbfbSPeter Wemm 24847a69bbfbSPeter Wemm Some custom field types are simply ordered in the same well-defined 24857a69bbfbSPeter Wemm way that TYPE_ENUM is. For such types, it is possible to define 24867a69bbfbSPeter Wemm successor and predecessor functions to support the REQ_NEXT_CHOICE and 24877a69bbfbSPeter Wemm REQ_PREV_CHOICE requests. Here is how: 24887a69bbfbSPeter Wemmtypedef int (*INTHOOK)(); /* pointer to function returning int */ 24897a69bbfbSPeter Wemm 24907a69bbfbSPeter Wemmint set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ 24917a69bbfbSPeter Wemm INTHOOK succ, /* get successor value */ 24927a69bbfbSPeter Wemm INTHOOK pred); /* get predecessor value */ 24937a69bbfbSPeter Wemm 24947a69bbfbSPeter Wemm The successor and predecessor arguments will each be passed two 24957a69bbfbSPeter Wemm arguments; a field pointer, and a pile pointer (as for the validation 24967a69bbfbSPeter Wemm functions). They are expected to use the function field_buffer() to 24977a69bbfbSPeter Wemm read the current value, and set_field_buffer() on buffer 0 to set the 24987a69bbfbSPeter Wemm next or previous value. Either hook may return TRUE to indicate 24997a69bbfbSPeter Wemm success (a legal next or previous value was set) or FALSE to indicate 25007a69bbfbSPeter Wemm failure. 25017a69bbfbSPeter Wemm 2502 Avoiding Problems 2503 2504 The interface for defining custom types is complicated and tricky. 2505 Rather than attempting to create a custom type entirely from scratch, 2506 you should start by studying the library source code for whichever of 2507 the pre-defined types seems to be closest to what you want. 2508 2509 Use that code as a model, and evolve it towards what you really want. 2510 You will avoid many problems and annoyances that way. The code in the 2511 ncurses library has been specifically exempted from the package 2512 copyright to support this. 2513 2514 If your custom type defines order functions, have do something 2515 intuitive with a blank field. A useful convention is to make the 2516 successor of a blank field the types minimum value, and its 2517 predecessor the maximum. 2518