Lines Matching +full:pre +full:- +full:set
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
365 source-code or documentation; the <code>tic</code> and
369 rewritten and much-improved <code>curses</code> library, along
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>
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">
483 </pre>
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">
559 </pre>
562 <pre class="code-block">
564 </pre>
567 <pre class="code-block">
570 </pre>
573 <pre class="code-block">
575 </pre>
585 <pre class="code-block">
587 ------------------------------------------------------------------
590 </pre>
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 */
694 </pre>
714 <p>Once the screen windows have been allocated, you can set them
729 <p>Now that we have set things up, we will want to actually
765 <code>getch()</code> which, if echo is set, will call
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
797 <code>ncurses</code>. These are <code>#define</code> values set
801 <p>The most useful of the ACS defines are the forms-drawing
805 ugly) set of ASCII defaults.</p>
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>
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
898 Bits in this mask will be set, corresponding to the event type
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
1080 variable <code>cur_term</code> is set to point to the current
1104 <dd>This function can be used to explicitly set a trace level.
1109 reporting -- see comments attached to <code>TRACE_</code>
1111 also possible to set a trace level by assigning a trace level
1120 -lncurses_g. It can be used the same way as
1131 more succinct single-line pseudo-operations. These pseudo-ops can
1150 clobbering some control bits set before you started your
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">
1213 </pre>
1239 want the screen re-painted. You will usually have to write
1240 special-purpose code to handle <code>KEY_RESIZE</code>
1253 and <code>stdscr</code> will be set to the last one allocated.
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
1360 describing entire-copy, but it is possible with some effort and
1367 call to guarantee an entire-contents copy anywhere.</p>
1383 current attribute (as set by <strong>wattrset()</strong>,
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
1434 <p>Your panels-using modules must import the panels library
1437 <pre class="code-block">
1439 </pre>
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
1548 some subset of a given set of items. The <code>menu</code>
1559 <p>Your menu-using modules must import the menu library
1562 <pre class="code-block">
1564 </pre>
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,
1625 you get the selected set by looping through the items applying
1627 menu-processing code can use the function
1629 set.</p>
1649 <li>Whatever menu format may have been set by the
1656 <p>The function <code>set_menu_format()</code> allows you to set
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
1706 <p>By default, both windows are <code>stdscr</code>. You can set
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>
1759 pattern buffer. It is also possible to set the pattern buffer
1763 <code>MAX_COMMAND</code> are considered application-specific
1775 requests. It is also possible to explicitly set the top row of
1781 <p>It is possible to set hooks to be called at menu
1793 supports easy programming of on-screen forms for data entry and
1803 <p>Your form-using modules must import the form library
1806 <pre class="code-block">
1808 </pre>
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
1840 type and value. The form library supplies a rich set of
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">
1896 </pre>
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">
1927 </pre>
1933 <pre class="code-block">
1936 </pre>
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">
1959 </pre>
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
1985 used to get and set several basic attributes here.</p>
1989 system default field. In attribute-setting and -fetching
1999 <pre class="code-block">
2005 </pre>
2016 <pre class="code-block">
2018 int top, int left); /* new upper-left corner */
2019 </pre>
2025 <p>One-line fields may be unjustified, justified right, justified
2028 <pre class="code-block">
2030 int justmode); /* mode to set */
2033 </pre>
2042 <p>For each field, you can set a foreground attribute for entered
2051 <pre class="code-block">
2053 chtype attr); /* attribute to set */
2058 chtype attr); /* attribute to set */
2063 int pad); /* pad character to set */
2071 </pre>
2072 <p>The attributes set and returned by the first four functions
2081 set to control various aspects of forms processing. You can
2084 <pre class="code-block">
2086 int attr); /* attribute to set */
2095 </pre>
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
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>
2184 <p>Every field has a status flag, which is set to FALSE when the
2186 changes. This flag can be queried and set directly:</p>
2188 <pre class="code-block">
2190 int status); /* mode to set */
2193 </pre>
2214 applications to store private per-field data. You can manipulate
2217 <pre class="code-block">
2219 char *userptr); /* mode to set */
2222 </pre>(Properly, this user pointer field ought to have <code>(void
2225 <p>It is valid to set the user pointer of the default field (with
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
2247 But it is possible to set an upper limit on the size of a dynamic
2250 <pre class="code-block">
2253 </pre>
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
2269 justification is set up will be retained internally and can be
2273 calls copy dynamic-buffer sizes. If the <code>O_STATIC</code>
2274 option is set on one of a collection of links, buffer resizing
2290 fail. Some validation types also have a character-validity check
2297 <p>The <code>form</code> library provides a rich set of
2298 pre-defined validation types, and gives you the capability to
2302 <pre class="code-block">
2308 </pre>
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).
2321 It is set up with:</p>
2323 <pre class="code-block">
2327 </pre>
2329 Typically you will want to set this to the field width; if it is
2337 no special characters (this is checked at character-entry time).
2338 It is set up with:</p>
2340 <pre class="code-block">
2344 </pre>
2346 As with TYPE_ALPHA, typically you will want to set this to the
2354 a specified set of string values (for example, the two-letter
2355 postal codes for U.S. states). It is set up with:</p>
2357 <pre class="code-block">
2361 int checkcase; /* case-sensitive? */
2363 </pre>
2365 NULL-terminated list of valid strings. The <code>checkcase</code>
2367 case-sensitive.</p>
2387 <p>This field type accepts an integer. It is set up as
2390 <pre class="code-block">
2393 int padding, /* # places to zero-pad to */
2395 </pre>
2410 <p>This field type accepts a decimal number. It is set up as
2413 <pre class="code-block">
2418 </pre>
2436 is set up as follows:</p>
2438 <pre class="code-block">
2442 </pre>
2444 <code>regcomp(3)</code>. The check for regular-expression match
2454 <pre class="code-block">
2457 </pre>
2458 <p>Normally, the state of the zero-numbered buffer for each field
2459 is set by the user's editing actions on that field. It is
2460 sometimes useful to be able to set the value of the zero-numbered
2463 <pre class="code-block">
2466 char *value); /* string value to set */
2467 </pre>
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">
2503 </pre>
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">
2553 </pre>
2558 <pre class="code-block">
2568 </pre>
2577 <pre class="code-block">
2581 </pre>
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">
2596 </pre>
2599 to re-synchronize it.</p>
2609 <pre class="code-block">
2612 </pre>
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
2729 array (as set up by <code>new_form()</code> or
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
2921 <dd>Set insertion mode.</dd>
2926 <dd>Set overlay mode.</dd>
3021 how to set and clear the overload options.</p>
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
3059 <p>It is possible to set function hooks to be executed whenever
3063 <pre class="code-block">
3085 </pre>
3086 <p>These functions allow you to either set or query four
3087 different hooks. In each of the set functions, the second
3130 <p>You can set a default hook for all fields by passing one of
3131 the set functions a NULL first argument.</p>
3144 <pre class="code-block">
3152 </pre>
3164 <pre class="code-block">
3166 int page); /* page to go to (0-origin) */
3169 </pre>
3170 <p>The initial page of a newly-created form is 0. The function
3178 <pre class="code-block">
3180 int attr); /* attribute to set */
3189 </pre>
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">
3230 </pre>
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">
3264 </pre>
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
3294 validation functions, you must associate a small set of
3295 storage-management functions with the type. The forms driver will
3302 <pre class="code-block">
3310 </pre>
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">
3361 </pre>
3366 <code>set_field_buffer()</code> on buffer 0 to set the next or
3368 (a legal next or previous value was set) or FALSE to indicate
3376 code for whichever of the pre-defined types seems to be closest