Lines Matching full:code
128 <li><a href="#xterm">Using <code>ncurses</code> under
129 <code>xterm</code></a></li>
140 <code>ncurses</code></a></li>
308 <code>curses</code>. It is not an exhaustive reference for the
310 filled by the <code>curses</code> manual pages. Rather, it is
315 experienced <code>curses</code> programmer, you should
321 <code>ncurses</code> implementation. If you are not so
324 <p>The <code>curses</code> package is a subroutine library for
329 another. <code>Curses</code> uses terminfo, which is a database
333 <p>The <code>curses</code> API may seem something of an archaism
336 <em>xterm(1)</em>; the <code>curses</code> API has the advantage
340 <code>curses</code> will typically be a great deal simpler and
345 <p>Historically, the first ancestor of <code>curses</code> was
347 <code>vi</code> editor; these used the <code>termcap</code>
356 AT&T Bell Labs, and made an improved <code>termcap</code>
357 library called <code>terminfo</code> (i.e.,
363 (<code>tic</code>) to compile the terminal descriptions. As a
365 source-code or documentation; the <code>tic</code> and
366 <code>infocmp</code> programs are the exceptions.</p>
369 rewritten and much-improved <code>curses</code> library, along
370 with the <code>tic</code> program (late 1986).</p>
377 the later AT&T System V releases, <code>curses</code> evolved
383 <p>This document describes <code>ncurses</code>, a free
384 implementation of the System V <code>curses</code> API with some
411 <p>The <code>ncurses</code> package can also capture and use
416 <p>The <code>ncurses</code> package was originated by Pavel
423 Jürgen Pfeifer wrote all of the menu and forms code as well
460 <code>stdscr</code>, is automatically provided for the
481 <pre class="code-block">
485 Standard I/O library, so <code><curses.h></code> includes
486 <code><stdio.h></code>. <code><curses.h></code> also
487 includes <code><termios.h></code>,
488 <code><termio.h></code>, or <code><sgtty.h></code>
491 <code>curses</code> you need to have <code>-lncurses</code> in
503 and its size. One of these (called <code>curscr</code>, for
505 looks like. Another screen (called <code>stdscr</code>, for
516 <code>refresh()</code> (or <code>wrefresh()</code> if the window
517 is not <code>stdscr</code>) is called.</p>
530 are automatically given: <code>curscr</code>, which knows what
531 the terminal looks like, and <code>stdscr</code>, which is what
533 should never actually access <code>curscr</code> directly.
535 <code>refresh()</code> (or <code>wrefresh()</code>) called.</p>
537 <p>Many functions are defined to use <code>stdscr</code> as a
539 <code>stdscr</code>, one calls <code>addch()</code> with the
541 use the routine <code>waddch()</code> (for
549 to another, the routines <code>move()</code> and
550 <code>wmove()</code> are provided. However, it is often desirable
556 <pre class="code-block">
562 <pre class="code-block">
567 <pre class="code-block">
573 <pre class="code-block">
582 <p>The <code>curses</code> library sets some variables describing
585 <pre class="code-block">
591 <p>The <code>curses.h</code> also introduces some
592 <code>#define</code> constants and types of general
596 <dt><code>bool</code>
600 <code>bool doneit;</code>)</dd>
602 <dt><code>TRUE</code>
607 <dt><code>FALSE</code>
612 <dt><code>ERR</code>
617 <dt><code>OK</code>
627 <code>stdscr</code>. These instructions will work on any window,
633 <pre class="code-block">
699 <code>curscr</code> and <code>stdscr</code> must be allocated.
700 These function <code>initscr()</code> does both these things.
703 happens, <code>initscr()</code> will terminate the program with
704 an error message. <code>initscr()</code> must always be called
707 <code>curscr</code> or <code>stdscr</code> are referenced.
710 errors. Terminal status changing routines like <code>nl()</code>
711 and <code>cbreak()</code> should be called after
712 <code>initscr()</code>.</p>
716 scroll, use <code>scrollok()</code>. If you want the cursor to be
717 left in place after the last change, use <code>leaveok()</code>.
718 If this is not done, <code>refresh()</code> will move the cursor
722 <code>newwin()</code>, <code>derwin()</code>, and
723 <code>subwin()</code>. The routine <code>delwin()</code> will
731 go on a window are <code>addch()</code> and <code>move()</code>.
732 <code>addch()</code> adds a character at the current (y, x)
733 coordinates. <code>move()</code> changes the current (y, x)
735 <code>ERR</code> if you try to move off the window. As mentioned
736 above, you can combine the two into <code>mvaddch()</code> to do
739 <p>The other output functions, such as <code>addstr()</code> and
740 <code>printw()</code>, all call <code>addch()</code> to add
745 to look like it, you must call <code>refresh()</code>. In order
746 to optimize finding changes, <code>refresh()</code> assumes that
748 <code>refresh()</code> of that window has not been changed on the
751 routine <code>touchwin()</code> is provided to make it look like
753 <code>refresh()</code> check the whole subsection of the terminal
756 <p>If you call <code>wrefresh()</code> with <code>curscr</code>
758 <code>curscr</code> thinks it looks like. This is useful for
764 <p>The complementary function to <code>addch()</code> is
765 <code>getch()</code> which, if echo is set, will call
766 <code>addch()</code> to echo the character. Since the screen
771 changed before calling <code>getch()</code>; otherwise, the
775 functions <code>wgetstr()</code> and friends are available. There
776 is even a <code>wscanw()</code> function that can do
777 <code>scanf()</code>(3)-style multi-field parsing on window
781 <p>The example code above uses the call <code>keypad(stdscr,
782 TRUE)</code> to enable support for function-key mapping. With
783 this feature, the <code>getch()</code> code watches the input
786 values. The <code>#define</code> values returned are listed in
787 the <code>curses.h</code> The mapping from sequences to
788 <code>#define</code> values is determined by <code>key_</code>
794 <p>The <code>addch()</code> function (and some others, including
795 <code>box()</code> and <code>border()</code>) can accept some
797 <code>ncurses</code>. These are <code>#define</code> values set
798 up in the <code>curses.h</code> header; see there for a complete
799 list (look for the prefix <code>ACS_</code>).</p>
804 <code>curses.h</code> will map them to a recognizable (though
810 <p>The <code>ncurses</code> package supports screen highlights
816 pseudo-character type (<code>chtype</code>) that
817 <code>curses.h</code> uses to represent the contents of a screen
818 cell. See the <code>curses.h</code> header file for a complete
820 <code>A_</code>).</p>
824 of an <code>addch()</code> call, or any other output call that
825 takes a <code>chtype</code> argument.</p>
829 way. You do this with the functions <code>attron()</code>,
830 <code>attroff()</code>, and <code>attrset()</code>; see the
833 of foreground and background colors. The sample code above sets
838 <code>init_pair()</code> values.</p>
840 <p>Once you have done an <code>init_pair()</code> that creates
841 color-pair N, you can use <code>COLOR_PAIR(N)</code> as a
843 that <code>COLOR_PAIR(N)</code>, for constant N, is itself a
848 <p>The <code>ncurses</code> library also provides a mouse
853 <code>ncurses</code>, it is not part of either the XSI Curses
855 Release 4 curses contains code with similar interface
858 how that mouse code works. Thus, we recommend that you wrap
859 mouse-related code in an #ifdef using the feature macro
870 <li>Linux console, when configured with <code>gpm</code>(1),
879 the function <code>mousemask()</code>, passing it as first
887 should watch for a return value of <code>KEY_MOUSE</code> from
888 <code>wgetch()</code>. When you see this, a mouse event report
890 <code>getmouse()</code> (you must do this before the next
891 <code>wgetch()</code>, otherwise another mouse event might come
894 <p>Each call to <code>getmouse()</code> fills a structure (the
910 <code>mousemask()</code>. Events that can be reported include
923 environments, it would be unwise to build <code>ncurses</code>
927 keyboard. Two of the test games in the <code>ncurses</code>
928 distribution (<code>bs</code> and <code>knight</code>) contain
929 code that illustrates how this can be done.</p>
931 <p>See the manual page <code>curs_mouse(3X)</code> for full
936 <p>In order to clean up after the <code>ncurses</code> routines,
937 the routine <code>endwin()</code> is provided. It restores tty
938 modes to what they were when <code>initscr()</code> was first
940 anytime after the call to initscr, <code>endwin()</code> should
952 <dt><code>initscr()</code>
956 <code>initscr()</code>. This will determine the terminal type
957 and initialize curses data structures. <code>initscr()</code>
958 also arranges that the first call to <code>refresh()</code>
962 (<code>slk_init()</code>, <code>filter()</code>,
963 <code>ripoffline()</code>, <code>use_env()</code>, and, if you
964 are using multiple terminals, <code>newterm()</code>.)</dd>
966 <dt><code>endwin()</code>
969 <dd>Your program should always call <code>endwin()</code>
973 non-visual mode. Calling <code>refresh()</code> or
974 <code>doupdate()</code> after a temporary escape from the
978 <dt><code>newterm(type, ofp, ifp)</code>
982 use <code>newterm()</code> instead of <code>initscr()</code>.
983 <code>newterm()</code> should be called once for each terminal.
984 It returns a variable of type <code>SCREEN *</code> which
989 the type of the terminal (a string) and <code>FILE</code>
991 NULL then the environment variable <code>$TERM</code> is used.
992 <code>endwin()</code> should called once at wrapup time for
995 <dt><code>set_term(new)</code>
999 previously opened by <code>newterm()</code>. The screen
1004 <dt><code>delscreen(sp)</code>
1007 <dd>The inverse of <code>newterm()</code>; deallocates the data
1008 structures associated with a given <code>SCREEN</code>
1015 <dt><code>refresh()</code> and <code>wrefresh(win)</code></dt>
1019 structures. <code>wrefresh()</code> copies the named window to
1022 <code>refresh()</code> does a refresh of <code>stdscr</code>.
1023 Unless <code>leaveok()</code> has been enabled, the physical
1027 <dt><code>doupdate()</code> and
1028 <code>wnoutrefresh(win)</code></dt>
1038 (<code>wnoutrefresh()</code>), and then calling the routine to
1039 update the screen (<code>doupdate()</code>). If the programmer
1041 <code>wrefresh</code> will result in alternating calls to
1042 <code>wnoutrefresh()</code> and <code>doupdate()</code>,
1044 <code>wnoutrefresh()</code> for each window, it is then
1045 possible to call <code>doupdate()</code> once, resulting in
1055 <dt><code>setupterm(term, filenum, errret)</code>
1061 or changing the tty-driver mode bits. <code>term</code> is
1063 being used. <code>filenum</code> is the UNIX file descriptor
1064 of the terminal to be used for output. <code>errret</code> is
1069 <p>The value of <code>term</code> can be given as NULL, which
1070 will cause the value of <code>TERM</code> in the environment
1071 to be used. The <code>errret</code> pointer can also be given
1072 as NULL, meaning no error code is wanted. If
1073 <code>errret</code> is defaulted, and something goes wrong,
1074 <code>setupterm()</code> will print an appropriate error
1079 <p>After the call to <code>setupterm()</code>, the global
1080 variable <code>cur_term</code> is set to point to the current
1082 <code>setupterm()</code> for each terminal, and saving and
1083 restoring <code>cur_term</code>, it is possible for a program
1085 <code>Setupterm()</code> also stores the names section of the
1087 <code>ttytype[]</code>. Subsequent calls to
1088 <code>setupterm()</code> will overwrite this array, so you
1101 <dt><code>trace()</code>
1109 reporting -- see comments attached to <code>TRACE_</code>
1110 defines in the <code>curses.h</code> file for details. (It is
1113 <code>NCURSES_TRACE</code>).</dd>
1115 <dt><code>_tracef()</code>
1121 <code>printf()</code>, only it outputs a newline after the end
1123 <code>trace</code> in the current directory.</dd>
1129 <code>ncurses</code> distribution that can alleviate this problem
1137 <p>The <code>ncurses</code> manual pages are a complete reference
1145 <code>noraw()</code> or <code>nocbreak()</code>, think again and
1147 <code>getstr()</code> or one of its relatives to simulate cooked
1148 mode. The <code>noraw()</code> and <code>nocbreak()</code>
1155 <p>Bear in mind that <code>refresh()</code> is a synonym for
1156 <code>wrefresh(stdscr)</code>. Do not try to mix use of
1157 <code>stdscr</code> with use of windows declared by
1158 <code>newwin()</code>; a <code>refresh()</code> call will blow
1160 <code>subwin()</code>, or not touch <code>stdscr</code> at all
1162 <code>wnoutrefresh()</code> somewhere in your program event loop,
1163 with a single <code>doupdate()</code> call to trigger actual
1169 weak, fragile, and poorly documented. The <code>ncurses</code>
1172 <p>There is a panels library included in the <code>ncurses</code>
1177 <code>getmaxyx()</code> on the <code>stdscr</code> context
1178 instead. Reason: your code may be ported to run in an environment
1189 <code>ncurses</code>.</p>
1191 <p>To leave <code>ncurses</code> mode, call <code>endwin()</code>
1194 shell-out. When you want to return to <code>ncurses</code> mode,
1195 simply call <code>refresh()</code> or <code>doupdate()</code>.
1198 <p>There is a boolean function, <code>isendwin()</code>, which
1199 code can use to test whether <code>ncurses</code> screen mode is
1200 active. It returns <code>TRUE</code> in the interval between an
1201 <code>endwin()</code> call and the following
1202 <code>refresh()</code>, <code>FALSE</code> otherwise.</p>
1204 <p>Here is some sample code for shellout:</p>
1206 <pre class="code-block">
1216 <p>A resize operation in X sends <code>SIGWINCH</code> to the
1218 <code>SIGWINCH</code> is to do an <code>endwin</code>, followed
1219 by an <code>refresh</code> and a screen repaint you code
1220 yourself. The <code>refresh</code> will pick up the new screen
1226 subwindows which must be shrunk. <code>Ncurses</code> provides an
1227 extension which works better, the <code>resizeterm</code>
1229 the new screen dimensions, and pads <code>stdscr</code> with
1232 <p>The <code>ncurses</code> library provides a SIGWINCH signal
1233 handler, which pushes a <code>KEY_RESIZE</code> via the wgetch()
1234 calls. When <code>ncurses</code> returns that code, it calls
1235 <code>resizeterm</code> to update the size of the standard
1240 special-purpose code to handle <code>KEY_RESIZE</code>
1246 <p>The <code>initscr()</code> function actually calls a function
1247 named <code>newterm()</code> to do most of its work. If you are
1249 <code>newterm()</code> directly.</p>
1253 and <code>stdscr</code> will be set to the last one allocated.
1254 You will switch between screens with the <code>set_term</code>
1256 <code>def_shell_mode</code> and <code>def_prog_mode</code> on
1264 into <code>ncurses</code> mode. An easy way to do this is to call
1265 <code>setupterm()</code>, then use the functions
1266 <code>tigetflag()</code>, <code>tigetnum()</code>, and
1267 <code>tigetstr()</code> to do your testing.</p>
1273 <code>tigetstr("cup")</code> is non-NULL. Alternatively, you can
1274 include the <code>term.h</code> file and test the value of the
1275 macro <code>cursor_address</code>.</p>
1279 <p>Use the <code>addchstr()</code> family of functions for fast
1282 on your screens. Do not use the <code>immedok()</code>
1288 <p>The <code>wresize()</code> function allows you to resize a
1289 window in place. The associated <code>resizeterm()</code>
1293 <p>The <code>define_key()</code> function allows you to define at
1295 terminal description. The <code>keyok()</code> function allows
1299 <p>The <code>use_default_colors()</code> function allows you to
1314 <code>ncurses</code> and the (undocumented!) behavior of older
1323 overlapping region under historic <code>curses</code> versions
1337 <code>wnoutrefresh()</code> does with its argument -- what
1341 with <code>wtouchln()</code> and friends). Some implementations
1345 <p>The <code>ncurses</code> library itself has not always been
1352 <code>ncurses</code> maintainers) whether they do change copy or
1366 <code>touchwin()</code> before the <code>wnoutrefresh()</code>
1371 <code>update_panels()</code>, it will do all the necessary
1372 <code>wnoutrefresh()</code> calls for whatever panel stacking
1374 <code>doupdate()</code> and there will be a <em>single</em> burst
1380 <code>ncurses</code> (1.8.7 or older) you may be surprised by the
1389 functions <code>bkgdset()</code> or <code>wbkgdset()</code>.</p>
1391 <p>This change in behavior conforms <code>ncurses</code> to
1396 <p>The <code>ncurses</code> library is intended to be base-level
1406 <p>Also, <code>ncurses</code> meets the XSI requirement that
1409 is disabled with <code>#undef</code>.</p>
1413 <p>The <code>ncurses</code> library by itself provides good
1416 overlap, you have to use a series of <code>wnoutrefresh()</code>
1417 calls followed by a <code>doupdate()</code>, and be careful about
1427 <p>The <code>panel</code> library first appeared in AT&T
1428 System V. The version documented here is the <code>panel</code>
1429 code distributed with <code>ncurses</code>.</p>
1437 <pre class="code-block">
1441 <code>-lpanel</code> argument. Note that they must also link the
1442 <code>ncurses</code> library with <code>-lncurses</code>. Many
1444 still good practice to put <code>-lpanel</code> first and
1445 <code>-lncurses</code> second.</p>
1453 <code>refresh()</code>) that displays all panels in the deck in
1455 <code>stdscr</code>, is considered below all panels.</p>
1461 <code>new_panel()</code> on a window pointer. It then becomes the
1463 <code>panel_window()</code> called with the panel pointer as
1467 <code>del_panel</code>. This will not deallocate the associated
1470 <code>replace_window</code>. The new window may be of different
1471 size; the panel code will re-compute all overlaps. This operation
1474 <p>To move a panel's window, use <code>move_panel()</code>. The
1475 <code>mvwin()</code> function on the panel's window is not
1480 <p>Two functions (<code>top_panel()</code>,
1481 <code>bottom_panel()</code>) are provided for rearranging the
1486 <p>The function <code>update_panels()</code> does all the
1487 <code>wnoutrefresh()</code> calls needed to prepare for
1488 <code>doupdate()</code> (which you must call yourself,
1491 <p>Typically, you will want to call <code>update_panels()</code>
1492 and <code>doupdate()</code> just before accepting command input,
1494 <code>update_panels()</code> after each and every panel write,
1501 <p>You should not mix <code>wnoutrefresh()</code> or
1502 <code>wrefresh()</code> operations with panels code; this will
1506 <p>The <code>stsdcr</code> window is a special case. It is
1508 obscure parts of <code>stdscr</code>, though, you should call
1509 <code>update_panels()</code> before <code>doupdate()</code> even
1510 when you only change <code>stdscr</code>.</p>
1512 <p>Note that <code>wgetch</code> automatically calls
1513 <code>wrefresh</code>. Therefore, before requesting input from a
1523 use <code>hide_panel</code> for this. Use
1524 <code>show_panel()</code> to render it visible again. The
1525 predicate function <code>panel_hidden</code> tests whether or not
1528 <p>The <code>panel_update</code> code ignores hidden panels. You
1529 cannot do <code>top_panel()</code> or <code>bottom_panel</code>
1535 <code>panel_above()</code> and <code>panel_below</code>. Handed a
1537 Handed <code>NULL</code>, they return the bottom-most or top-most
1541 panel code, to which you can attach application data. See the man
1542 page documentation of <code>set_panel_userptr()</code> and
1543 <code>panel_userptr</code> for details.</p>
1548 some subset of a given set of items. The <code>menu</code>
1552 <p>The <code>menu</code> library first appeared in AT&T
1553 System V. The version documented here is the <code>menu</code>
1554 code distributed with <code>ncurses</code>.</p>
1562 <pre class="code-block">
1566 <code>-lmenu</code> argument. Note that they must also link the
1567 <code>ncurses</code> library with <code>-lncurses</code>. Many
1569 still good practice to put <code>-lmenu</code> first and
1570 <code>-lncurses</code> second.</p>
1595 <li>Initialize <code>curses</code>.</li>
1597 <li>Create the menu items, using <code>new_item()</code>.</li>
1599 <li>Create the menu using <code>new_menu()</code>.</li>
1601 <li>Post the menu using <code>post_menu()</code>.</li>
1607 <li>Unpost the menu using <code>unpost_menu()</code>.</li>
1609 <li>Free the menu, using <code>free_menu()</code>.</li>
1611 <li>Free the items using <code>free_item()</code>.</li>
1613 <li>Terminate <code>curses</code>.</li>
1619 the manual page <code>menu_opts(3x)</code> to see how to change
1626 the <code>item_value()</code> predicate function. Your
1627 menu-processing code can use the function
1628 <code>set_item_value()</code> to flag the items in the select
1632 <code>set_item_opts()</code> or <code>item_opts_off()</code> with
1633 the <code>O_SELECTABLE</code> argument. This is the only option
1634 so far defined for menus, but it is good practice to code as
1656 <p>The function <code>set_menu_format()</code> allows you to set
1659 associated with a menu with <code>menu_format()</code>. The
1680 selected items; see the <code>menu_mark(3x)</code> manual page
1684 <p>The function <code>scale_menu()</code> returns the minimum
1685 display size that the menu code computes from all these factors.
1691 <code>menu_attribs(3x)</code> manual page.</p>
1706 <p>By default, both windows are <code>stdscr</code>. You can set
1707 them with the functions in <code>menu_win(3x)</code>.</p>
1709 <p>When you call <code>post_menu()</code>, you write the menu to
1710 its subwindow. When you call <code>unpost_menu()</code>, you
1712 the screen. To do that, call <code>wrefresh()</code> or some
1717 <p>The main loop of your menu-processing code should call
1718 <code>menu_driver()</code> repeatedly. The first argument of this
1719 routine is a menu pointer; the second is a menu command code. You
1722 <code>menu_driver()</code>. The menu command codes are fully
1723 documented in <code>menu_driver(3x)</code>.</p>
1726 <code>REQ_NEXT_ITEM</code>, <code>REQ_PREV_ITEM</code>,
1727 <code>REQ_FIRST_ITEM</code>, <code>REQ_LAST_ITEM</code>,
1728 <code>REQ_UP_ITEM</code>, <code>REQ_DOWN_ITEM</code>,
1729 <code>REQ_LEFT_ITEM</code>, <code>REQ_RIGHT_ITEM</code>. These
1735 but the item there does). These are <code>REQ_SCR_DLINE</code>,
1736 <code>REQ_SCR_ULINE</code>, <code>REQ_SCR_DPAGE</code>, and
1737 <code>REQ_SCR_UPAGE</code>.</p>
1739 <p>The <code>REQ_TOGGLE_ITEM</code> selects or deselects the
1741 with <code>O_ONEVALUE</code> on, you will get an error return
1742 (<code>E_REQUEST_DENIED</code>).</p>
1745 <code>menu_driver()</code> logic tries to accumulate printable
1750 <code>menu_driver()</code> returns <code>E_NO_MATCH</code>.</p>
1753 <code>REQ_CLEAR_PATTERN</code>, <code>REQ_BACK_PATTERN</code>,
1754 <code>REQ_NEXT_MATCH</code>, <code>REQ_PREV_MATCH</code>. The
1760 explicitly with <code>set_menu_pattern()</code>.</p>
1763 <code>MAX_COMMAND</code> are considered application-specific
1764 commands. The <code>menu_driver()</code> code ignores them and
1765 returns <code>E_UNKNOWN_COMMAND</code>.</p>
1770 appearance and input processing of menus. See <code>menu_opts(3x)
1771 for details.</code></p>
1774 code; this is useful if you want to write your own navigation
1776 the menu display. See <code>mitem_current(3x)</code>. If your
1778 reason, <code>pos_menu_cursor()</code> will restore it to the
1783 changes. See <code>menu_hook(3x)</code>.</p>
1787 <code>mitem_userptr(3x)</code> and
1788 <code>menu_userptr(3x)</code>.</p>
1792 <p>The <code>form</code> library is a curses extension that
1796 <p>The <code>form</code> library first appeared in AT&T
1797 System V. The version documented here is the <code>form</code>
1798 code distributed with <code>ncurses</code>.</p>
1806 <pre class="code-block">
1810 <code>-lform</code> argument. Note that they must also link the
1811 <code>ncurses</code> library with <code>-lncurses</code>. Many
1813 still good practice to put <code>-lform</code> first and
1814 <code>-lncurses</code> second.</p>
1838 keystroke accepted by <code>curses</code> Fields may have
1853 <li>Initialize <code>curses</code>.</li>
1856 <code>new_field()</code>.</li>
1858 <li>Create the form using <code>new_form()</code>.</li>
1860 <li>Post the form using <code>post_form()</code>.</li>
1866 <li>Unpost the form using <code>unpost_form()</code>.</li>
1868 <li>Free the form, using <code>free_form()</code>.</li>
1870 <li>Free the fields using <code>free_field()</code>.</li>
1872 <li>Terminate <code>curses</code>.</li>
1889 <code>new_field()</code>:</p>
1891 <pre class="code-block">
1898 have multiple rows. So <code>new_field()</code> requires you to
1905 the form subwindow, which will coincide with <code>stdscr</code>
1906 by default but need not be <code>stdscr</code> if you have done
1907 an explicit <code>set_form_win()</code> call.</p>
1915 the <code>offscreen</code> argument was initially zero.</p>
1918 size of each buffer is <code>((height + offscreen)*width +
1919 1</code>, one character for each position in the field plus a NUL
1924 <pre class="code-block">
1928 <p>The function <code>dup_field()</code> duplicates an existing
1931 <code>form_field_new(3X)</code> for details).</p>
1933 <pre class="code-block">
1937 <p>The function <code>link_field()</code> also duplicates an
1939 <code>dup_field()</code> is that it arranges for the new field's
1952 <code>NULL</code> if the field allocation is not possible due to
1957 <pre class="code-block">
1965 <p>Note that <code>new_field()</code> does <em>not</em> copy the
1971 <p>The functions <code>free_field()</code> and
1972 <code>free_form</code> are available to free field and form
1983 <code>O_STATIC</code> bit) involve sufficient complications to be
1988 <code>new_field</code> function are copied from an invisible
1999 <pre class="code-block">
2007 <code>new_field()</code>; instead of setting size and location
2016 <pre class="code-block">
2021 <code>field_info()</code>.</p>
2028 <pre class="code-block">
2035 preprocessor macros <code>NO_JUSTIFICATION</code>,
2036 <code>JUSTIFY_RIGHT</code>, <code>JUSTIFY_LEFT</code>, or
2037 <code>JUSTIFY_CENTER</code>.</p>
2051 <pre class="code-block">
2073 are normal <code>curses(3x)</code> display attribute values
2074 (<code>A_STANDOUT</code>, <code>A_BOLD</code>,
2075 <code>A_REVERSE</code> etc). The page bit of a field controls
2084 <pre class="code-block">
2125 <code>REQ_PREV_CHOICE</code> and <code>REQ_NEXT_CHOICE</code>
2188 <pre class="code-block">
2198 <p>Calling <code>field_status()</code> on a field not currently
2200 <code>field_status()</code> on a field that is currently selected
2204 status value reflects reality, call <code>field_status()</code>
2207 just after a <code>REQ_VALIDATION</code> request has been
2217 <pre class="code-block">
2222 </pre>(Properly, this user pointer field ought to have <code>(void
2223 *)</code> type. The <code>(char *)</code> type is retained for
2226 a <code>set_field_userptr()</code> call passed a NULL field
2250 <pre class="code-block">
2254 <p>If the field is one-line, <code>max_size</code> is taken to be
2265 the field; therefore <code>O_AUTOSKIP</code> and
2266 <code>O_NL_OVERLOAD</code> are ignored.</li>
2272 <li>The <code>dup_field()</code> and <code>link_field()</code>
2273 calls copy dynamic-buffer sizes. If the <code>O_STATIC</code>
2278 <li>The call <code>field_info()</code> will retrieve the
2280 <code>dynamic_field_info()</code> to get the actual dynamic
2294 <code>set_field_buffer()</code> modifies the input buffer, nor
2297 <p>The <code>form</code> library provides a rich set of
2302 <pre class="code-block">
2311 <code>set_field_type()</code> with a <code>NULL</code> field
2323 <pre class="code-block">
2328 <p>The <code>width</code> argument sets a minimum width of data.
2340 <pre class="code-block">
2345 <p>The <code>width</code> argument sets a minimum width of data.
2357 <pre class="code-block">
2364 <p>The <code>valuelist</code> parameter must point at a
2365 NULL-terminated list of valid strings. The <code>checkcase</code>
2377 to the first matching value. But the <code>checkunique</code>
2381 <p>The <code>REQ_NEXT_CHOICE</code> and
2382 <code>REQ_PREV_CHOICE</code> input requests can be particularly
2390 <pre class="code-block">
2405 <p>A <code>TYPE_INTEGER</code> value buffer can conveniently be
2406 interpreted with the C library function <code>atoi(3)</code>.</p>
2413 <pre class="code-block">
2430 <p>A <code>TYPE_NUMERIC</code> value buffer can conveniently be
2431 interpreted with the C library function <code>atof(3)</code>.</p>
2438 <pre class="code-block">
2444 <code>regcomp(3)</code>. The check for regular-expression match
2454 <pre class="code-block">
2463 <pre class="code-block">
2472 <p>Calling <code>field_buffer()</code> with a null field pointer
2473 will raise an error. Calling <code>field_buffer()</code> on a
2475 value. Calling <code>field_buffer()</code> on a field that is
2480 reality, call <code>field_buffer()</code> either (1) in the
2483 <code>REQ_VALIDATION</code> request has been processed by the
2491 argument of <code>NULL</code>.</p>
2496 <pre class="code-block">
2504 <p>The second argument of <code>set_form_fields()</code> may be a
2506 <code>new_form()</code>. In that case, the old fields of the form
2513 <p>The <code>field_count()</code> function simply counts the
2525 full-screen window <code>stdscr</code>.</p>
2549 <pre class="code-block">
2558 <pre class="code-block">
2569 <p>Note that curses operations, including <code>refresh()</code>,
2577 <pre class="code-block">
2582 <p>The function <code>data_ahead()</code> returns TRUE if (a) the
2587 <p>The function <code>data_behind()</code> returns TRUE if the
2594 <pre class="code-block">
2604 <p>The function <code>form_driver()</code> handles virtualized
2606 requests, just as <code>menu_driver</code> does for menus (see
2609 <pre class="code-block">
2611 int request); /* form request code */
2619 field-termination functions) with which your application code can
2629 <dt><code>REQ_NEXT_PAGE</code>
2634 <dt><code>REQ_PREV_PAGE</code>
2639 <dt><code>REQ_FIRST_PAGE</code>
2644 <dt><code>REQ_LAST_PAGE</code>
2651 <code>REQ_NEXT_PAGE</code> from the last page goes to the first,
2652 and <code>REQ_PREV_PAGE</code> from the first page goes to the
2662 <dt><code>REQ_NEXT_FIELD</code>
2667 <dt><code>REQ_PREV_FIELD</code>
2672 <dt><code>REQ_FIRST_FIELD</code>
2677 <dt><code>REQ_LAST_FIELD</code>
2682 <dt><code>REQ_SNEXT_FIELD</code>
2687 <dt><code>REQ_SPREV_FIELD</code>
2692 <dt><code>REQ_SFIRST_FIELD</code>
2697 <dt><code>REQ_SLAST_FIELD</code>
2702 <dt><code>REQ_LEFT_FIELD</code>
2707 <dt><code>REQ_RIGHT_FIELD</code>
2712 <dt><code>REQ_UP_FIELD</code>
2717 <dt><code>REQ_DOWN_FIELD</code>
2724 that is, <code>REQ_NEXT_FIELD</code> from the last field goes to
2725 the first, and <code>REQ_PREV_FIELD</code> from the first field
2727 <code>REQ_FIRST_FIELD</code> and <code>REQ_LAST_FIELD</code>
2729 array (as set up by <code>new_form()</code> or
2730 <code>set_form_fields()</code></p>
2745 left of B and C to the right of B. A <code>REQ_MOVE_RIGHT</code>
2756 <dt><code>REQ_NEXT_CHAR</code>
2761 <dt><code>REQ_PREV_CHAR</code>
2766 <dt><code>REQ_NEXT_LINE</code>
2771 <dt><code>REQ_PREV_LINE</code>
2776 <dt><code>REQ_NEXT_WORD</code>
2781 <dt><code>REQ_PREV_WORD</code>
2786 <dt><code>REQ_BEG_FIELD</code>
2791 <dt><code>REQ_END_FIELD</code>
2796 <dt><code>REQ_BEG_LINE</code>
2801 <dt><code>REQ_END_LINE</code>
2806 <dt><code>REQ_LEFT_CHAR</code>
2811 <dt><code>REQ_RIGHT_CHAR</code>
2816 <dt><code>REQ_UP_CHAR</code>
2821 <dt><code>REQ_DOWN_CHAR</code>
2843 <dt><code>REQ_SCR_FLINE</code>
2848 <dt><code>REQ_SCR_BLINE</code>
2853 <dt><code>REQ_SCR_FPAGE</code>
2858 <dt><code>REQ_SCR_BPAGE</code>
2863 <dt><code>REQ_SCR_FHPAGE</code>
2868 <dt><code>REQ_SCR_BHPAGE</code>
2873 <dt><code>REQ_SCR_FCHAR</code>
2878 <dt><code>REQ_SCR_BCHAR</code>
2883 <dt><code>REQ_SCR_HFLINE</code>
2888 <dt><code>REQ_SCR_HBLINE</code>
2893 <dt><code>REQ_SCR_HFHALF</code>
2898 <dt><code>REQ_SCR_HBHALF</code>
2918 <dt><code>REQ_INS_MODE</code>
2923 <dt><code>REQ_OVL_MODE</code>
2928 <dt><code>REQ_NEW_LINE</code>
2933 <dt><code>REQ_INS_CHAR</code>
2938 <dt><code>REQ_INS_LINE</code>
2943 <dt><code>REQ_DEL_CHAR</code>
2948 <dt><code>REQ_DEL_PREV</code>
2953 <dt><code>REQ_DEL_LINE</code>
2958 <dt><code>REQ_DEL_WORD</code>
2963 <dt><code>REQ_CLR_EOL</code>
2968 <dt><code>REQ_CLR_EOF</code>
2973 <dt><code>REQ_CLEAR_FIELD</code>
2979 <p>The behavior of the <code>REQ_NEW_LINE</code> and
2980 <code>REQ_DEL_PREV</code> requests is complicated and partly
2985 <p>First, we consider <code>REQ_NEW_LINE</code>:</p>
2987 <p>The normal behavior of <code>REQ_NEW_LINE</code> in insert
2994 <p>The normal behavior of <code>REQ_NEW_LINE</code> in overlay
2999 <p>However, <code>REQ_NEW_LINE</code> at the beginning of a
3001 <code>REQ_NEXT_FIELD</code>. <code>O_NL_OVERLOAD</code> option is
3004 <p>Now, let us consider <code>REQ_DEL_PREV</code>:</p>
3006 <p>The normal behavior of <code>REQ_DEL_PREV</code> is to delete
3013 <p>However, <code>REQ_DEL_PREV</code> at the beginning of a field
3014 is instead treated as a <code>REQ_PREV_FIELD</code>.</p>
3016 <p>If the <code>O_BS_OVERLOAD</code> option is off, this special
3018 <code>E_REQUEST_DENIED</code>.</p>
3031 <dt><code>REQ_NEXT_CHOICE</code>
3037 <dt><code>REQ_PREV_CHOICE</code>
3044 <p>Of the built-in field types, only <code>TYPE_ENUM</code> has
3052 <code>curses</code> value greater than <code>KEY_MAX</code> and
3053 less than or equal to the constant <code>MAX_COMMAND</code>. If
3055 <code>MAX_COMMAND</code>, the forms driver will ignore it.</p>
3063 <pre class="code-block">
3121 <code>set_current_field()</code> call</li>
3124 <code>set_form_page()</code> call</li>
3144 <pre class="code-block">
3153 <p>The function <code>field_index()</code> returns the index of
3155 to <code>new_form()</code> or
3156 <code>set_form_fields()</code>).</p>
3159 on the first page. The function <code>set_form_fields()</code>
3164 <pre class="code-block">
3171 <code>set_form_fields()</code> resets this.</p>
3178 <pre class="code-block">
3196 <dd>Enable overloading of <code>REQ_NEW_LINE</code> as
3200 circumstances for triggering a <code>REQ_NEXT_FIELD</code>
3205 <dd>Enable overloading of <code>REQ_DEL_PREV</code> as
3214 <p>The <code>form</code> library gives you the capability to
3216 additional arguments of <code>set_field_type</code> effectively
3227 <pre class="code-block">
3234 <code>set_field_type()</code> call later requires arguments, the
3257 <pre class="code-block">
3265 <p>At least one of the arguments of <code>new_fieldtype()</code>
3270 <p>The function <code>free_fieldtype()</code> deallocates the
3290 <code>set_field_type()</code>. If no such arguments are defined
3297 each <code>set_field_type()</code> argument, and a pointer to the
3302 <pre class="code-block">
3314 <dt><code>make_str</code>
3317 <dd>This function is called by <code>set_field_type()</code>.
3318 It gets one argument, a <code>va_list</code> of the
3320 <code>set_field_type()</code>. It is expected to return a pile
3324 <dt><code>copy_str</code>
3332 <dt><code>free_str</code>
3340 <p>The <code>make_str</code> and <code>copy_str</code> functions
3350 well-defined way that <code>TYPE_ENUM</code> is. For such types,
3352 support the <code>REQ_NEXT_CHOICE</code> and
3353 <code>REQ_PREV_CHOICE</code> requests. Here is how:</p>
3355 <pre class="code-block">
3365 <code>field_buffer()</code> to read the current value, and
3366 <code>set_field_buffer()</code> on buffer 0 to set the next or
3376 code for whichever of the pre-defined types seems to be closest
3379 <p>Use that code as a model, and evolve it towards what you
3381 way. The code in the <code>ncurses</code> library has been