Lines Matching +full:v +full:- +full:blanking
1 <!--
2 $Id: ncurses-intro.html,v 1.57 2022/11/26 19:33:46 tom Exp $
4 * Copyright 2019-2020,2022 Thomas E. Dickey *
5 * Copyright 2000-2013,2017 Free Software Foundation, Inc. *
31 -->
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
38 <link rel="author" href="mailto:bugs-ncurses@gnu.org">
39 <meta http-equiv="Content-Type" content=
40 "text/html; charset=us-ascii">
43 <h1 class="no-header">Writing Programs with NCURSES</h1>
48 by Eric S. Raymond and Zeyd M. Ben-Halim<br>
113 <li><a href="#lowlevel">Low-Level Capability
228 <li><a href="#fdynamic">Variable-Sized Fields</a></li>
260 <li><a href="#ffield">Inter-Field Navigation
263 <li><a href="#fifield">Intra-Field Navigation
325 terminal-independent screen-painting and input-event handling
337 of (a) back-portability to character-cell terminals, and (b)
338 simplicity. For an application that does not require bit-mapped
346 the routines written to provide screen-handling for the
359 this. That was subsequently released in System V Release 2 (early
365 source-code or documentation; the <code>tic</code> and
368 <p>System V Release 3 (System III UNIX) from Bell Labs featured a
369 rewritten and much-improved <code>curses</code> library, along
377 the later AT&T System V releases, <code>curses</code> evolved
384 implementation of the System V <code>curses</code> API with some
385 clearly marked extensions. It includes the following System V
391 reverse-video).</li>
393 <li>Support for line- and box-drawing using forms
418 "mailto:zmbenhal@netcom.com">Zeyd Ben-Halim</a>
426 "mailto:dickey@invisible-island.net">Thomas Dickey</a>
428 "mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</a>.</p>
439 libraries, also cloned from System V, which support easy
440 construction and sequences of menus and fill-in forms.</p>
450 <dd>A data structure describing a sub-rectangle of the screen
481 <pre class="code-block">
491 <code>curses</code> you need to have <code>-lncurses</code> in
542 <strong>w</strong>indow-specific addch()) is provided. This
556 <pre class="code-block">
562 <pre class="code-block">
567 <pre class="code-block">
573 <pre class="code-block">
585 <pre class="code-block">
587 ------------------------------------------------------------------
615 <dd>error flag returned by routines on a failure (-1).</dd>
633 <pre class="code-block">
645 /* initialize your non-curses data structures here */
651 (void) nonl(); /* tell curses not to do NL->CR/NL on output */
653 (void) echo(); /* echo input - in color */
690 /* do your non-curses wrapup here */
774 <p>When you need to accept line-oriented input in a window, the
777 <code>scanf()</code>(3)-style multi-field parsing on window
778 input. These pseudo-line-oriented functions turn on echoing while
782 TRUE)</code> to enable support for function-key mapping. With
785 function keys. These sequences are returned as pseudo-character
796 pseudo-character arguments which are specially defined by
801 <p>The most useful of the ACS defines are the forms-drawing
811 including standout, reverse-video, underline, and blink. It also
816 pseudo-character type (<code>chtype</code>) that
822 <p>There are two ways to make highlights. One is to logical-or
827 <p>The other is to set the current-highlight value. This is
828 <em>logical-OR</em>ed with any highlight you specify the first
834 up eight color pairs, all of the guaranteed-available colors on
836 its foreground color. Any other range of eight non-conflicting
841 color-pair N, you can use <code>COLOR_PAIR(N)</code> as a
844 compile-time constant and can be used in initializers.</p>
854 standard, nor of System V Release 4, nor BSD curses. System V
859 mouse-related code in an #ifdef using the feature macro
861 non-ncurses systems.
880 argument a bit-mask that specifies what kinds of events you want
881 your program to be able to see. It will return the bit-mask of
896 event data includes zero-origin, screen-relative character-cell
905 touch-screens that can return a pressure or duration parameter.
911 presses, releases, single-, double- and triple-clicks (you can
912 set the maximum button-down time for clicks). If you do not make
913 clicks visible, they will be reported as press-release pairs. In
925 you should use the mouse as a shortcut for point-and-shoot
932 details of the mouse-interface functions.</p>
939 called, and moves the cursor down to the lower-left corner. Thus,
973 non-visual mode. Calling <code>refresh()</code> or
1051 <h4><a name="lowlevel" id="lowlevel">Low-Level Capability
1061 or changing the tty-driver mode bits. <code>term</code> is
1067 well), 0 (no such terminal), or -1 (some problem locating the
1109 reporting -- see comments attached to <code>TRACE_</code>
1120 -lncurses_g. It can be used the same way as
1131 more succinct single-line pseudo-operations. These pseudo-ops can
1174 overlapping-windows facilities.</p>
1188 shell-out. This behavior is simple to arrange in
1194 shell-out. When you want to return to <code>ncurses</code> mode,
1206 <pre class="code-block">
1239 want the screen re-painted. You will usually have to write
1240 special-purpose code to handle <code>KEY_RESIZE</code>
1271 “smart” (cursor-addressable) or “stupid”.
1273 <code>tigetstr("cup")</code> is non-NULL. Alternatively, you can
1280 screen-painting of text when you know the text does not contain
1294 runtime function-key control sequences which are not in the
1297 function-key control sequence.</p>
1337 <code>wnoutrefresh()</code> does with its argument -- what
1353 entire copy. We know that System V release 3 curses has logic in
1360 describing entire-copy, but it is possible with some effort and
1367 call to guarantee an entire-contents copy anywhere.</p>
1392 System V Release 4 and the XSI Curses standard.</p>
1396 <p>The <code>ncurses</code> library is intended to be base-level
1398 extended-level features (in fact, almost all features not
1403 described under <a href="#backbug">"Background Erase --
1408 be linked (and will be prototype-checked) if the macro definition
1415 (non-overlapping). In the more general case that windows may
1419 bottom-upwards, otherwise parts of windows that should be
1424 the resulting book-keeping can be tedious and difficult to get
1428 System V. The version documented here is the <code>panel</code>
1434 <p>Your panels-using modules must import the panels library
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
1443 linkers are two-pass and will accept either order, but it is
1444 still good practice to put <code>-lpanel</code> first and
1445 <code>-lncurses</code> second.</p>
1451 has an implicit bottom-to-top visibility order. The panels
1471 size; the panel code will re-compute all overlaps. This operation
1537 Handed <code>NULL</code>, they return the bottom-most or top-most
1553 System V. The version documented here is the <code>menu</code>
1559 <p>Your menu-using modules must import the menu library
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
1568 linkers are two-pass and will accept either order, but it is
1569 still good practice to put <code>-lmenu</code> first and
1570 <code>-lncurses</code> second.</p>
1589 items available for re-use.</p>
1618 <p>Menus may be multi-valued or (the default) single-valued (see
1623 <p>From a single-valued menu you can read the selected value
1624 simply by looking at the current item. From a multi-valued menu,
1627 menu-processing code can use the function
1665 a “raster-scan” pattern, so that if more than one
1667 side-by-side in the top row. The alternative is column-major
1672 all items to fit on-screen will result in a menu display that is
1717 <p>The main loop of your menu-processing code should call
1720 should write an input-fetching routine that maps input characters
1740 current item. It is for use in multi-valued menus; if you use it
1756 one item in a multi-valued menu.</p>
1763 <code>MAX_COMMAND</code> are considered application-specific
1793 supports easy programming of on-screen forms for data entry and
1797 System V. The version documented here is the <code>form</code>
1803 <p>Your form-using modules must import the form library
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
1812 linkers are two-pass and will accept either order, but it is
1813 still good practice to put <code>-lform</code> first and
1814 <code>-lncurses</code> second.</p>
1819 label (explanatory text) or a data-entry location. Long forms may
1841 pre-defined field types, and makes it relatively easy to define
1847 re-use.</p>
1882 Besides menu-like navigation operations, the menu driver loop has
1891 <pre class="code-block">
1910 off-screen rows. If this is zero, the entire field will always be
1912 only one screen-full (initially the top part) displayed at any
1924 <pre class="code-block">
1933 <pre class="code-block">
1951 <p>As you might guess, all these field-allocations return
1953 an out-of-memory error or out-of-bounds arguments.</p>
1957 <pre class="code-block">
1960 <p>This function expects to see a NULL-terminated array of field
1961 pointers. Said fields are connected to a newly-allocated form
1974 form, but not vice-versa; thus, you will generally free your form
1989 system default field. In attribute-setting and -fetching
1999 <pre class="code-block">
2016 <pre class="code-block">
2018 int top, int left); /* new upper-left corner */
2025 <p>One-line fields may be unjustified, justified right, justified
2028 <pre class="code-block">
2051 <pre class="code-block">
2084 <pre class="code-block">
2126 will fail. Such read-only fields may be useful for help
2131 <dd>Controls word-wrapping in multi-line fields. Normally, when
2132 any character of a (blank-separated) word reaches the end of
2139 <dd>Controls field blanking. When this option is on, entering a
2141 (except for the just-entered character).</dd>
2179 <p>The option values are bit-masks and can be composed with
2180 logical-or in the obvious way.</p>
2188 <pre class="code-block">
2214 applications to store private per-field data. You can manipulate
2217 <pre class="code-block">
2224 System V compatibility.)
2227 pointer.) When a new field is created, the default-field user
2230 <h3><a name="fdynamic" id="fdynamic">Variable-Sized Fields</a></h3>
2239 <p>A one-line dynamic field will have a fixed height (1) but
2241 field area as originally dimensioned and located. A multi-line
2250 <pre class="code-block">
2254 <p>If the field is one-line, <code>max_size</code> is taken to be
2255 a column size limit; if it is multi-line, it is taken to be a
2273 calls copy dynamic-buffer sizes. If the <code>O_STATIC</code>
2290 fail. Some validation types also have a character-validity check
2298 pre-defined validation types, and gives you the capability to
2302 <pre class="code-block">
2313 newly-created fields.</p>
2315 <p>Here are the pre-defined validation types:</p>
2320 no special characters (this is checked at character-entry time).
2323 <pre class="code-block">
2337 no special characters (this is checked at character-entry time).
2340 <pre class="code-block">
2354 a specified set of string values (for example, the two-letter
2357 <pre class="code-block">
2361 int checkcase; /* case-sensitive? */
2365 NULL-terminated list of valid strings. The <code>checkcase</code>
2367 case-sensitive.</p>
2390 <pre class="code-block">
2393 int padding, /* # places to zero-pad to */
2413 <pre class="code-block">
2438 <pre class="code-block">
2444 <code>regcomp(3)</code>. The check for regular-expression match
2454 <pre class="code-block">
2458 <p>Normally, the state of the zero-numbered buffer for each field
2460 sometimes useful to be able to set the value of the zero-numbered
2463 <pre class="code-block">
2479 guarantee that the returned buffer value reflects on-screen
2490 queried or set by of these functions using a form-pointer
2496 <pre class="code-block">
2505 NULL-terminated field pointer array like the one required by
2514 number of fields connected to a given from. It returns -1 if the
2515 form-pointer argument is NULL.</p>
2525 full-screen window <code>stdscr</code>.</p>
2549 <pre class="code-block">
2558 <pre class="code-block">
2577 <pre class="code-block">
2583 current field is one-line and has undisplayed data off to the
2584 right, (b) the current field is multi-line and there is data
2585 off-screen below it.</p>
2588 first (upper left hand) character position is off-screen (not
2594 <pre class="code-block">
2599 to re-synchronize it.</p>
2609 <pre class="code-block">
2615 treated as data to be entered in the currently-selected field),
2618 <p>The forms driver provides hooks (through input-validation and
2619 field-termination functions) with which your application code can
2625 <p>These requests cause page-level moves through the form,
2655 <h4><a name="ffield" id="ffield">Inter-Field Navigation
2733 sorted in screen-position order, so the sequence goes
2734 left-to-right and top-to-bottom. To do this, use the second group
2735 of four sorted-movement requests.</p>
2740 a form for purposes of these requests is its upper-left
2743 <p>For example, suppose you have a multi-line field B, and two
2744 single-line fields A and C on the same line with B, with A to the
2749 <h4><a name="fifield" id="fifield">Intra-Field Navigation
2829 end of line or field look for the first or last non-pad character
2835 created with offscreen rows are scrollable. One-line fields
2836 scroll horizontally; multi-line fields scroll vertically. Most
2837 scrolling is triggered by editing and intra-field movement (the
3044 <p>Of the built-in field types, only <code>TYPE_ENUM</code> has
3045 built-in successor and predecessor functions. When you define a
3054 your input-virtualization routine returns a value above
3063 <pre class="code-block">
3144 <pre class="code-block">
3164 <pre class="code-block">
3166 int page); /* page to go to (0-origin) */
3170 <p>The initial page of a newly-created form is 0. The function
3178 <pre class="code-block">
3209 <p>The option values are bit-masks and can be composed with
3210 logical-or in the obvious way.</p>
3218 complications in the validation-type interface have to do with
3227 <pre class="code-block">
3233 either predefined or programmer-defined). If a
3248 <li>A character-validation function, to check each character as
3251 <li>A field-validation function to be applied on exit from the
3257 <pre class="code-block">
3266 must be non-NULL. The forms driver will automatically call the
3286 <p>Your field- and character- validation functions will be passed
3289 of the field-type-specific arguments passed to
3295 storage-management functions with the type. The forms driver will
3302 <pre class="code-block">
3311 <p>Here is how the storage-management hooks are used:</p>
3319 type-specific arguments passed to
3335 <dd>This function is called by field- and type-deallocation
3350 well-defined way that <code>TYPE_ENUM</code> is. For such types,
3355 <pre class="code-block">
3376 code for whichever of the pre-defined types seems to be closest