X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_util.3x.html;h=b377bcbee4a84371693e8312f6762facf650f28b;hb=ca276baf720e3a44721b9e18955d3f546955c6c8;hp=760298dc891aa64ecf8a7f0fd7a0a8234b99d999;hpb=55ccd2b959766810cf7db8d1c4462f338ce0afc8;p=ncurses.git diff --git a/doc/html/man/curs_util.3x.html b/doc/html/man/curs_util.3x.html index 760298dc..b377bcbe 100644 --- a/doc/html/man/curs_util.3x.html +++ b/doc/html/man/curs_util.3x.html @@ -1,7 +1,7 @@ @@ -48,8 +48,8 @@

NAME

        delay_output, filter, flushinp, getwin, key_name, keyname,
-       putwin, unctrl, use_env, wunctrl - miscellaneous curses
-       utility routines
+       nofilter, putwin, unctrl, use_env, wunctrl - miscellaneous
+       curses utility routines
@@ -57,10 +57,11 @@ #include <curses.h> char *unctrl(chtype c); - char *wunctrl(cchar_t *c); + wchar_t *wunctrl(cchar_t *c); char *keyname(int c); char *key_name(wchar_t w); void filter(void); + void nofilter(void); void use_env(bool f); int putwin(WINDOW *win, FILE *filep); WINDOW *getwin(FILE *filep); @@ -93,6 +94,12 @@ cud, cud1, cuu1, cuu, vpa are disabled; and the home string is set to the value of cr. + The nofilter routine cancels the effect of a preceding + filter call. That allows the caller to initialize a + screen on a different device, using a different value of + $TERM. The limitation arises because the filter routine + modifies the in-memory copy of the terminal information. + 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 @@ -149,7 +156,27 @@ The XSI Curses standard, Issue 4 describes these func- tions. It states that unctrl and wunctrl will return a null pointer if unsuccessful, but does not define any er- - ror conditions. + ror conditions. This implementation checks for three cas- + es: + + - the parameter is a 7-bit US-ASCII code. This + is the case that X/Open Curses documented. + + - the parameter is in the range 128-159, i.e., a + C1 control code. If use_legacy_coding has + been called with a 2 parameter, unctrl returns + the parameter, i.e., a one-character string + with the parameter as the first character. + Otherwise, it returns ``~@'', ``~A'', etc., + analogous to ``^@'', ``^A'', C0 controls. + + X/Open Curses does not document whether unctrl + can be called before initializing curses. + This implementation permits that, and returns + the ``~@'', etc., values in that case. + + - parameter values outside the 0 to 255 range. + unctrl returns a null pointer. The SVr4 documentation describes the action of filter only in the vaguest terms. The description here is adapted @@ -159,20 +186,43 @@ 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. - - 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. + implementations have different conventions. For example, + they may show both sets of control characters with `^', + and strip the parameter to 7 bits. Or they may ignore C1 + controls and treat all of the upper-128 codes as print- + able. This implementation uses 8 bits but does not modify + the string to reflect locale. The use_legacy_coding func- + tion allows the caller to change the output of unctrl. + + Likewise, the meta function allows the caller to change + the output of keyname, i.e., it determines whether to use + the `M-' prefix for ``meta'' keys (codes in the range 128 + to 255). Both use_legacy_coding and meta succeed only af- + ter curses is initialized. X/Open Curses does not docu- + ment the treatment of codes 128 to 159. When treating + them as ``meta'' keys (or if keyname is called before ini- + tializing curses), this implementation returns strings + ``M-^@'', ``M-^A'', etc. + + 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. This implementation auto- + matically assigns at run-time keycodes to user-defined + strings which begin with "k". The keycodes start at + KEY_MAX, but are not guaranteed to be the same value for + different runs because user-defined codes are merged from + all terminal descriptions which have been loaded. + + The nofilter routine is specific to ncurses. It was not + supported on Version 7, BSD or System V implementations. + It is recommended that any code depending on ncurses ex- + tensions be conditioned using NCURSES_VERSION.

SEE ALSO

-       curses(3x),       curs_initscr(3x),       curs_kernel(3x),
-       curs_scr_dump(3x).
+       legacy_coding(3x), curses(3x), curs_initscr(3x), curs_ker-
+       nel(3x), curs_scr_dump(3x), legacy_coding(3x).