Lines Matching +full:fast +full:- +full:charge +full:- +full:current +full:- +full:limit
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. *
7 * Permission is hereby granted, free of charge, to any person obtaining a *
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>
427 (maintainer). Contact the current maintainers at <a href=
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">
491 <code>curses</code> you need to have <code>-lncurses</code> in
504 current screen) is a screen image of what the terminal currently
542 <strong>w</strong>indow-specific addch()) is provided. This
548 <p>In order to move the current (y, x) coordinates from one point
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 */
719 to the window's current (y, x) coordinates after updating it.</p>
732 <code>addch()</code> adds a character at the current (y, x)
733 coordinates. <code>move()</code> changes the current (y, x)
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>
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
1002 affect only the current terminal.</dd>
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
1106 generate a file called “trace” in the current
1109 reporting -- see comments attached to <code>TRACE_</code>
1120 -lncurses_g. It can be used the same way as
1123 <code>trace</code> in the current directory.</dd>
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">
1208 def_prog_mode(); /* save current tty modes */
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
1279 <p>Use the <code>addchstr()</code> family of functions for fast
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">
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
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
1620 the default). Both types always have a <dfn>current
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
1703 <dfn>subwindow</dfn> is where the current menu page is
1717 <p>The main loop of your menu-processing code should call
1720 should write an input-fetching routine that maps input characters
1734 the current item (because the select location does not change,
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
1773 <p>It is possible to change the current item from application
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">
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
1836 in a current field. The form library allows you (the forms
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 */
2020 <p>You can, of course. query the current location through
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
2133 the current line, the entire word is wrapped to the next line
2141 (except for the just-entered character).</dd>
2150 have not reached their size limit.</dd>
2177 fields that are not current.</p>
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">
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
2246 <p>Normally, a dynamic field is allowed to grow without limit.
2247 But it is possible to set an upper limit on the size of a dynamic
2250 <pre class="code-block">
2252 int max_size); /* upper limit on field size */
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
2256 line size limit. To disable any limit, use an argument of zero.
2257 The growth limit can be changed whether or not the O_STATIC bit
2264 <li>If there is no growth limit, there is no final position of
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>
2542 subwindow is where the current form page is actually
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
2988 mode is to break the current line at the position of the edit
2989 cursor, inserting the portion of the current line after the
2990 cursor as a new line following the current and moving the cursor
2995 mode is to clear the current line from the position of the edit
3009 previous one, it instead appends the contents of the current line
3010 to the previous one and deletes the current line (you may think
3034 <dd>Place the successor value of the current value in the
3040 <dd>Place the predecessor value of the current value in 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
3060 the current field or form changes. Here are the functions that
3063 <pre class="code-block">
3120 <li>When the current page is changed by
3123 <li>When the current field is changed by a
3144 <pre class="code-block">
3158 <p>The initial current field of a form is the first active field
3164 <pre class="code-block">
3166 int page); /* page to go to (0-origin) */
3168 int form_page(FORM *form); /* return form's current page */
3170 <p>The initial page of a newly-created form is 0. The function
3178 <pre class="code-block">
3199 reached their size limit; these have no last line, so the
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">
3365 <code>field_buffer()</code> to read the current value, and
3376 code for whichever of the pre-defined types seems to be closest