X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_util.3x.html;h=760298dc891aa64ecf8a7f0fd7a0a8234b99d999;hp=5fc178cc7f76474098c556f4266173906a0714f6;hb=55ccd2b959766810cf7db8d1c4462f338ce0afc8;hpb=b1f61d9f3aa244512045a6b02e759825d7049d34 diff --git a/doc/html/man/curs_util.3x.html b/doc/html/man/curs_util.3x.html index 5fc178cc..760298dc 100644 --- a/doc/html/man/curs_util.3x.html +++ b/doc/html/man/curs_util.3x.html @@ -1,129 +1,182 @@ + + +
++curs_util(3x) curs_util(3x) + + +
- unctrl, keyname, filter, use_env, putwin, getwin, - delay_output, flushinp - miscellaneous curses utility rou- - tines + delay_output, filter, flushinp, getwin, key_name, keyname, + putwin, unctrl, use_env, wunctrl - miscellaneous curses + utility routines
- #include <curses.h> + #include <curses.h> - char *unctrl(chtype c); - char *keyname(int c); - void filter(void); - void use_env(char bool); - int putwin(WINDOW *win, FILE *filep); - WINDOW *getwin(FILE *filep); - int delay_output(int ms); - int flushinp(void); + char *unctrl(chtype c); + char *wunctrl(cchar_t *c); + char *keyname(int c); + char *key_name(wchar_t w); + void filter(void); + void use_env(bool f); + int putwin(WINDOW *win, FILE *filep); + WINDOW *getwin(FILE *filep); + int delay_output(int ms); + int flushinp(void);
- The unctrl macro expands to a character string which is a - printable representation of the character c. Control - characters are displayed in the ^X notation. Printing - characters are displayed as is. - - The keyname routine returns a character string correspond- - ing to the key c. - - The filter routine, if used, must be called before initscr - or newterm are called. The effect is that, during those - calls, LINES is set to 1; the capabilities clear, cup, - cud, cud1, cuu1, cuu, vpa are disabled; and the home - string is set to the value of cr. - - The use_env routine, if used, is called before initscr or - newterm are called. When called with FALSE as an argu- - ment, the values of lines and columns specified in the - terminfo database will be used, even if environment vari- - ables LINES and COLUMNS (used by default) are set, or if - curses is running in a window (in which case default - behavior would be to use the window size if LINES and - COLUMNS are not set). - - The putwin routine writes all data associated with window - win into the file to which filep points. This information - can be later retrieved using the getwin function. - - The getwin routine reads window related data stored in the - file by putwin. The routine then creates and initializes + The unctrl routine returns a character string which is a + printable representation of the character c, ignoring at- + tributes. Control characters are displayed in the ^X no- + tation. Printing characters are displayed as is. The + corresponding wunctrl returns a printable representation + of a wide-character. + + The keyname routine returns a character string correspond- + ing to the key c. Control characters are displayed in the + ^X notation. Values above 128 are either meta characters, + shown in the M-X notation, or the names of function keys, + or null. The corresponding key_name returns a character + string corresponding to the wide-character value w. The + two functions do not return the same set of strings; the + latter returns null where the former would display a meta + character. + + The filter routine, if used, must be called before initscr + or newterm are called. The effect is that, during those + calls, LINES is set to 1; the capabilities clear, cup, + cud, cud1, cuu1, cuu, vpa are disabled; and the home + string is set to the value of cr. + + The use_env routine, if used, is called before initscr or + newterm are called. When called with FALSE as an argu- + ment, the values of lines and columns specified in the + terminfo database will be used, even if environment vari- + ables LINES and COLUMNS (used by default) are set, or if + curses is running in a window (in which case default be- + havior would be to use the window size if LINES and + COLUMNS are not set). Note that setting LINES or COLUMNS + overrides the corresponding size which may be obtained + from the operating system. + + The putwin routine writes all data associated with window + win into the file to which filep points. This information + can be later retrieved using the getwin function. + + The getwin routine reads window related data stored in the + file by putwin. The routine then creates and initializes a new window using that data. It returns a pointer to the new window. - The delay_output routine inserts an ms millisecond pause - in output. This routine should not be used extensively - because padding characters are used rather than a CPU - pause. - The flushinp routine throws away any typeahead that has + The delay_output routine inserts an ms millisecond pause + in output. This routine should not be used extensively + because padding characters are used rather than a CPU + pause. If no padding character is specified, this uses + napms to perform the delay. + + The flushinp routine throws away any typeahead that has been typed by the user and has not yet been read by the program.
- Except for flushinp, routines that return an integer - return ERR upon failure and OK (SVr4 specifies only "an - integer value other than ERR") upon successful completion. + Except for flushinp, routines that return an integer re- + turn ERR upon failure and OK (SVr4 specifies only "an in- + teger value other than ERR") upon successful completion. + + Routines that return pointers return NULL on error. - flushinp always returns OK. + X/Open does not define any error conditions. In this im- + plementation - Routines that return pointers return NULL on error. + flushinp + returns an error if the terminal was not ini- + tialized. + + putwin + returns an error if the associated fwrite + calls return an error.
The XSI Curses standard, Issue 4 describes these func- - tions. + tions. It states that unctrl and wunctrl will return a + null pointer if unsuccessful, but does not define any er- + ror conditions. - The SVr4 documentation describes the action of filter only + The SVr4 documentation describes the action of filter only in the vaguest terms. The description here is adapted from the XSI Curses standard (which erroneously fails to - describe the disabling of cuu). + describe the disabling of cuu). + The strings returned by unctrl in this implementation are + determined at compile time, showing C1 controls from the + upper-128 codes with a `~' prefix rather than `^'. Other + implementations typically show both sets of control char- + acters with `^', and may strip the parameter to 7 bits. + This implementation uses 8 bits but does not modify the + string to reflect locale. --
- Note that unctrl is a macro, which is defined in <unc- - trl.h>. + The keyname function may return the names of user-defined + string capabilities which are defined in the terminfo en- + try via the -x option of tic.
- curses(3x), curs_initscr(3x), curs_scr_dump(3x). - - - - - - - - - - - - - - - - - - - - - - - + curses(3x), curs_initscr(3x), curs_kernel(3x), + curs_scr_dump(3x). + curs_util(3x)