X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=57f28a07111c8f87a8135c63a183bbdd1194e5b0;hp=d49f4840b592319b058f32557be1b9a8a695a55b;hb=f86cbeb5f9bd96ab041d34039c35749a14965039;hpb=90ffd624948c543a457324ee777717e4130f2ad2 diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html index d49f4840..57f28a07 100644 --- a/doc/html/man/ncurses.3x.html +++ b/doc/html/man/ncurses.3x.html @@ -63,7 +63,7 @@ sonable optimization. This implementation is ``new curses'' (ncurses) and is the approved replacement for 4.4BSD classic curses, which has been discontinued. This - describes ncurses version 5.7 (patch 20110212). + describes ncurses version 5.8 (patch 20110226). The ncurses library emulates the curses library of System V Release 4 UNIX, and XPG4 (X/Open Portability Guide) @@ -150,48 +150,48 @@ Among those, the most basic routines are move and addch. More general versions of these routines are included with names beginning with w, allowing the user to specify a - window. The routines not beginning with w affect stdscr. + window. The routines not beginning with w affect stdscr. - After using routines to manipulate a window, refresh is - called, telling curses to make the user's CRT screen look - like stdscr. The characters in a window are actually of - type chtype, (character and attribute data) so that other - information about the character may also be stored with + After using routines to manipulate a window, refresh is + called, telling curses to make the user's CRT screen look + like stdscr. The characters in a window are actually of + type chtype, (character and attribute data) so that other + information about the character may also be stored with each character. - Special windows called pads may also be manipulated. + Special windows called pads may also be manipulated. These are windows which are not constrained to the size of - the screen and whose contents need not be completely dis- + the screen and whose contents need not be completely dis- played. See curs_pad(3x) for more information. - In addition to drawing characters on the screen, video - attributes and colors may be supported, causing the char- - acters to show up in such modes as underlined, in reverse - video, or in color on terminals that support such display + In addition to drawing characters on the screen, video + attributes and colors may be supported, causing the char- + acters to show up in such modes as underlined, in reverse + video, or in color on terminals that support such display enhancements. Line drawing characters may be specified to - be output. On input, curses is also able to translate - arrow and function keys that transmit escape sequences - into single values. The video attributes, line drawing - characters, and input values use names, defined in + be output. On input, curses is also able to translate + arrow and function keys that transmit escape sequences + into single values. The video attributes, line drawing + characters, and input values use names, defined in <curses.h>, such as A_REVERSE, ACS_HLINE, and KEY_LEFT. If the environment variables LINES and COLUMNS are set, or - if the program is executing in a window environment, line - and column information in the environment will override + if the program is executing in a window environment, line + and column information in the environment will override information read by terminfo. This would affect a program - running in an AT&T 630 layer, for example, where the size + running in an AT&T 630 layer, for example, where the size of a screen is changeable (see ENVIRONMENT). - If the environment variable TERMINFO is defined, any pro- - gram using curses checks for a local terminal definition - before checking in the standard place. For example, if + If the environment variable TERMINFO is defined, any pro- + gram using curses checks for a local terminal definition + before checking in the standard place. For example, if TERM is set to att4424, then the compiled terminal defini- tion is found in /usr/share/terminfo/a/att4424. (The a is copied from the first letter of att4424 to avoid - creation of huge directories.) However, if TERMINFO is + creation of huge directories.) However, if TERMINFO is set to $HOME/myterms, curses first checks $HOME/myterms/a/att4424, @@ -200,117 +200,119 @@ /usr/share/terminfo/a/att4424. - This is useful for developing experimental definitions or + This is useful for developing experimental definitions or when write permission in /usr/share/terminfo is not avail- able. - The integer variables LINES and COLS are defined in - <curses.h> and will be filled in by initscr with the size + The integer variables LINES and COLS are defined in + <curses.h> and will be filled in by initscr with the size of the screen. The constants TRUE and FALSE have the val- ues 1 and 0, respectively. - The curses routines also define the WINDOW * variable + The curses routines also define the WINDOW * variable curscr which is used for certain low-level operations like - clearing and redrawing a screen containing garbage. The + clearing and redrawing a screen containing garbage. The curscr can be used in only a few routines. Routine and Argument Names - Many curses routines have two or more versions. The rou- + Many curses routines have two or more versions. The rou- tines prefixed with w require a window argument. The rou- tines prefixed with p require a pad argument. Those with- out a prefix generally use stdscr. The routines prefixed with mv require a y and x coordinate - to move to before performing the appropriate action. The - mv routines imply a call to move before the call to the - other routine. The coordinate y always refers to the row - (of the window), and x always refers to the column. The + to move to before performing the appropriate action. The + mv routines imply a call to move before the call to the + other routine. The coordinate y always refers to the row + (of the window), and x always refers to the column. The upper left-hand corner is always (0,0), not (1,1). The routines prefixed with mvw take both a window argument - and x and y coordinates. The window argument is always + and x and y coordinates. The window argument is always specified before the coordinates. - In each case, win is the window affected, and pad is the + In each case, win is the window affected, and pad is the pad affected; win and pad are always pointers to type WIN- DOW. Option setting routines require a Boolean flag bf with the - value TRUE or FALSE; bf is always of type bool. Most of - the data types used in the library routines, such as WIN- - DOW, SCREEN, bool, and chtype are defined in <curses.h>. - Types used for the terminfo routines such as TERMINAL are + value TRUE or FALSE; bf is always of type bool. Most of + the data types used in the library routines, such as WIN- + DOW, SCREEN, bool, and chtype are defined in <curses.h>. + Types used for the terminfo routines such as TERMINAL are defined in <term.h>. - This manual page describes functions which may appear in - any configuration of the library. There are two common + This manual page describes functions which may appear in + any configuration of the library. There are two common configurations of the library: ncurses the "normal" library, which handles 8-bit characters. The normal (8-bit) library stores - characters combined with attributes in chtype + characters combined with attributes in chtype data. - Attributes alone (no corresponding character) - may be stored in chtype or the equivalent - attr_t data. In either case, the data is + Attributes alone (no corresponding character) + may be stored in chtype or the equivalent + attr_t data. In either case, the data is stored in something like an integer. - Each cell (row and column) in a WINDOW is + Each cell (row and column) in a WINDOW is stored as a chtype. ncursesw - the so-called "wide" library, which handles - multibyte characters (see the section on + the so-called "wide" library, which handles + multibyte characters (see the section on ALTERNATE CONFIGURATIONS). The "wide" library - includes all of the calls from the "normal" - library. It adds about one third more calls + includes all of the calls from the "normal" + library. It adds about one third more calls using data types which store multibyte charac- ters: cchar_t - corresponds to chtype. However it is a - structure, because more data is stored - than can fit into an integer. The char- + corresponds to chtype. However it is a + structure, because more data is stored + than can fit into an integer. The char- acters are large enough to require a full - integer value - and there may be more - than one character per cell. The video - attributes and color are stored in sepa- + integer value - and there may be more + than one character per cell. The video + attributes and color are stored in sepa- rate fields of the structure. Each cell (row and column) in a WINDOW is stored as a cchar_t. wchar_t - stores a "wide" character. Like chtype, + stores a "wide" character. Like chtype, this may be an integer. wint_t - stores a wchar_t or WEOF - not the same, + stores a wchar_t or WEOF - not the same, though both may have the same size. The "wide" library provides new functions - which are analogous to functions in the "nor- - mal" library. There is a naming convention - which relates many of the normal/wide vari- - ants: a "_w" is inserted into the name. For + which are analogous to functions in the "nor- + mal" library. There is a naming convention + which relates many of the normal/wide vari- + ants: a "_w" is inserted into the name. For example, waddch becomes wadd_wch. + Routine Name Index The following table lists each curses routine and the name - of the manual page on which it is described. Routines - flagged with `*' are ncurses-specific, not described by + of the manual page on which it is described. Routines + flagged with `*' are ncurses-specific, not described by XPG4 or present in SVr4. + curses Routine Name Manual Page Name -------------------------------------------- COLOR_PAIR curs_color(3x) PAIR_NUMBER curs_attr(3x) _nc_free_and_exit curs_memleaks(3x)* + _nc_freeall curs_memleaks(3x)* _nc_tracebits curs_trace(3x)* - _traceattr curs_trace(3x)* _traceattr2 curs_trace(3x)* _tracechar curs_trace(3x)* @@ -374,9 +376,9 @@ echo curs_inopts(3x) echo_wchar curs_add_wch(3x) echochar curs_addch(3x) + endwin curs_initscr(3x) erase curs_clear(3x) - erasechar curs_termattrs(3x) erasewchar curs_termattrs(3x) filter curs_util(3x) @@ -440,9 +442,9 @@ intrflush curs_inopts(3x) inwstr curs_inwstr(3x) is_cleared curs_opaque(3x)* + is_idcok curs_opaque(3x)* is_idlok curs_opaque(3x)* - is_immedok curs_opaque(3x)* is_keypad curs_opaque(3x)* is_leaveok curs_opaque(3x)* @@ -506,9 +508,9 @@ mvinsch curs_insch(3x) mvinsnstr curs_insstr(3x) mvinsstr curs_insstr(3x) + mvinstr curs_instr(3x) mvinwstr curs_inwstr(3x) - mvprintw curs_printw(3x) mvscanw curs_scanw(3x) mvvline curs_border(3x) @@ -572,9 +574,9 @@ pair_content curs_color(3x) pechochar curs_pad(3x) pnoutrefresh curs_pad(3x) + prefresh curs_pad(3x) printw curs_printw(3x) - putp curs_terminfo(3x) putwin curs_util(3x) qiflush curs_inopts(3x) @@ -638,9 +640,9 @@ tigetstr curs_terminfo(3x) timeout curs_inopts(3x) touchline curs_touch(3x) + touchwin curs_touch(3x) tparm curs_terminfo(3x) - tputs curs_termcap(3x) tputs curs_terminfo(3x) trace curs_trace(3x)* @@ -704,9 +706,9 @@ wgetbkgrnd curs_bkgrnd(3x) wgetch curs_getch(3x) wgetn_wstr curs_get_wstr(3x) + wgetnstr curs_getstr(3x) wgetstr curs_getstr(3x) - whline curs_border(3x) whline_set curs_border_set(3x) win_wch curs_in_wch(3x) @@ -750,14 +752,14 @@
- Routines that return an integer return ERR upon failure - and an integer value other than ERR upon successful com- - pletion, unless otherwise noted in the routine descrip- + Routines that return an integer return ERR upon failure + and an integer value other than ERR upon successful com- + pletion, unless otherwise noted in the routine descrip- tions. - All macros return the value of the w version, except + All macros return the value of the w version, except setscrreg, wsetscrreg, getyx, getbegyx, and getmaxyx. The - return values of setscrreg, wsetscrreg, getyx, getbegyx, + return values of setscrreg, wsetscrreg, getyx, getbegyx, and getmaxyx are undefined (i.e., these should not be used as the right-hand side of assignment statements). @@ -771,46 +773,46 @@ important ones have been already discussed in detail. BAUDRATE - The debugging library checks this environment symbol + The debugging library checks this environment symbol when the application has redirected output to a file. - The symbol's numeric value is used for the baudrate. + The symbol's numeric value is used for the baudrate. If no value is found, ncurses uses 9600. This allows - testers to construct repeatable test-cases that take + testers to construct repeatable test-cases that take into account costs that depend on baudrate. CC When set, change occurrences of the command_character - (i.e., the cmdch capability) of the loaded terminfo - entries to the value of this symbol. Very few ter- + (i.e., the cmdch capability) of the loaded terminfo + entries to the value of this symbol. Very few ter- minfo entries provide this feature. - Because this name is also used in development envi- - ronments to represent the C compiler's name, ncurses + Because this name is also used in development envi- + ronments to represent the C compiler's name, ncurses ignores it if it does not happen to be a single char- acter. COLUMNS Specify the width of the screen in characters. - Applications running in a windowing environment usu- - ally are able to obtain the width of the window in - which they are executing. If neither the COLUMNS - value nor the terminal's screen size is available, - ncurses uses the size which may be specified in the + Applications running in a windowing environment usu- + ally are able to obtain the width of the window in + which they are executing. If neither the COLUMNS + value nor the terminal's screen size is available, + ncurses uses the size which may be specified in the terminfo database (i.e., the cols capability). - It is important that your application use a correct - size for the screen. This is not always possible - because your application may be running on a host - which does not honor NAWS (Negotiations About Window - Size), or because you are temporarily running as - another user. However, setting COLUMNS and/or LINES + It is important that your application use a correct + size for the screen. This is not always possible + because your application may be running on a host + which does not honor NAWS (Negotiations About Window + Size), or because you are temporarily running as + another user. However, setting COLUMNS and/or LINES overrides the library's use of the screen size obtained from the operating system. - Either COLUMNS or LINES symbols may be specified - independently. This is mainly useful to circumvent - legacy misfeatures of terminal descriptions, e.g., + Either COLUMNS or LINES symbols may be specified + independently. This is mainly useful to circumvent + legacy misfeatures of terminal descriptions, e.g., xterm which commonly specifies a 65 line screen. For - best results, lines and cols should not be specified + best results, lines and cols should not be specified in a terminal description for terminals which are run as emulations. @@ -819,35 +821,35 @@ the screen size. ESCDELAY - Specifies the total time, in milliseconds, for which - ncurses will await a character sequence, e.g., a - function key. The default value, 1000 milliseconds, + Specifies the total time, in milliseconds, for which + ncurses will await a character sequence, e.g., a + function key. The default value, 1000 milliseconds, is enough for most uses. However, it is made a vari- able to accommodate unusual applications. The most common instance where you may wish to change - this value is to work with slow hosts, e.g., running - on a network. If the host cannot read characters - rapidly enough, it will have the same effect as if - the terminal did not send characters rapidly enough. + this value is to work with slow hosts, e.g., running + on a network. If the host cannot read characters + rapidly enough, it will have the same effect as if + the terminal did not send characters rapidly enough. The library will still see a timeout. - Note that xterm mouse events are built up from char- - acter sequences received from the xterm. If your + Note that xterm mouse events are built up from char- + acter sequences received from the xterm. If your application makes heavy use of multiple-clicking, you - may wish to lengthen this default value because the - timeout applies to the composed multi-click event as + may wish to lengthen this default value because the + timeout applies to the composed multi-click event as well as the individual clicks. - In addition to the environment variable, this imple- - mentation provides a global variable with the same + In addition to the environment variable, this imple- + mentation provides a global variable with the same name. Portable applications should not rely upon the - presence of ESCDELAY in either form, but setting the - environment variable rather than the global variable - does not create problems when compiling an applica- + presence of ESCDELAY in either form, but setting the + environment variable rather than the global variable + does not create problems when compiling an applica- tion. - HOME Tells ncurses where your home directory is. That is + HOME Tells ncurses where your home directory is. That is where it may read and write auxiliary terminal descriptions: @@ -855,8 +857,8 @@ $HOME/.terminfo LINES - Like COLUMNS, specify the height of the screen in - characters. See COLUMNS for a detailed description. + Like COLUMNS, specify the height of the screen in + characters. See COLUMNS for a detailed description. MOUSE_BUTTONS_123 This applies only to the OS/2 EMX port. It specifies @@ -1113,10 +1115,10 @@ --with-profile The shared and normal (static) library names differ - by their suffixes, e.g., libncurses.so and libn- - curses.a. The debug and profiling libraries add a - "_g" and a "_p" to the root names respectively, e.g., - libncurses_g.a and libncurses_p.a. + by their suffixes, e.g., libncurses.so and + libncurses.a. The debug and profiling libraries add + a "_g" and a "_p" to the root names respectively, + e.g., libncurses_g.a and libncurses_p.a. --with-trace The trace function normally resides in the debug @@ -1225,31 +1227,31 @@ o This implementation can also be configured to provide a set of functions which improve the ability to manage - multiple screens. See curs_sp_funcs(3x) for details. + multiple screens. See curs_sp_funcs(3x) for details. - In historic curses versions, delays embedded in the capa- + In historic curses versions, delays embedded in the capa- bilities cr, ind, cub1, ff and tab activated corresponding - delay bits in the UNIX tty driver. In this implementa- - tion, all padding is done by sending NUL bytes. This - method is slightly more expensive, but narrows the inter- - face to the UNIX kernel significantly and increases the + delay bits in the UNIX tty driver. In this implementa- + tion, all padding is done by sending NUL bytes. This + method is slightly more expensive, but narrows the inter- + face to the UNIX kernel significantly and increases the package's portability correspondingly.
- The header file <curses.h> automatically includes the + The header file <curses.h> automatically includes the header files <stdio.h> and <unctrl.h>. - If standard output from a ncurses program is re-directed - to something which is not a tty, screen updates will be + If standard output from a ncurses program is re-directed + to something which is not a tty, screen updates will be directed to standard error. This was an undocumented fea- ture of AT&T System V Release 3 curses.
- Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. + Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on pcurses by Pavel Curtis.