1 <!DOCTYPE HTML PUBLIC
"-//IETF//DTD HTML 2.0//EN">
3 ****************************************************************************
4 * Copyright (c) 1998-2008,2010 Free Software Foundation, Inc. *
6 * Permission is hereby granted, free of charge, to any person obtaining a *
7 * copy of this software and associated documentation files (the *
8 * "Software"), to deal in the Software without restriction, including *
9 * without limitation the rights to use, copy, modify, merge, publish, *
10 * distribute, distribute with modifications, sublicense, and/or sell *
11 * copies of the Software, and to permit persons to whom the Software is *
12 * furnished to do so, subject to the following conditions: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 * Except as contained in this notice, the name(s) of the above copyright *
26 * holders shall not be used in advertising or otherwise to promote the *
27 * sale, use or other dealings in this Software without prior written *
29 ****************************************************************************
30 * @Id: curs_util.3x,v 1.32 2010/12/04 18:38:55 tom Exp @
34 <TITLE>curs_util
3x
</TITLE>
35 <link rev=made
href=
"mailto:bug-ncurses@gnu.org">
36 <meta http-equiv=
"Content-Type" content=
"text/html; charset=iso-8859-1">
42 <!-- Manpage converted by man2html 3.0.1 -->
43 <STRONG><A HREF=
"curs_util.3x.html">curs_util(
3x)
</A></STRONG> <STRONG><A HREF=
"curs_util.3x.html">curs_util(
3x)
</A></STRONG>
50 <STRONG>delay_output
</STRONG>,
<STRONG>filter
</STRONG>,
<STRONG>flushinp
</STRONG>,
<STRONG>getwin
</STRONG>,
<STRONG>key_name
</STRONG>,
<STRONG>keyname
</STRONG>,
51 <STRONG>nofilter
</STRONG>,
<STRONG>putwin
</STRONG>,
<STRONG>unctrl
</STRONG>,
<STRONG>use_env
</STRONG>,
<STRONG>wunctrl
</STRONG> - miscellaneous
52 <STRONG>curses
</STRONG> utility routines
56 <H2>SYNOPSIS
</H2><PRE>
57 <STRONG>#include
</STRONG> <STRONG><curses.h
></STRONG>
59 <STRONG>char
</STRONG> <STRONG>*unctrl(chtype
</STRONG> <STRONG>c);
</STRONG>
60 <STRONG>wchar_t
</STRONG> <STRONG>*wunctrl(cchar_t
</STRONG> <STRONG>*c);
</STRONG>
61 <STRONG>char
</STRONG> <STRONG>*keyname(int
</STRONG> <STRONG>c);
</STRONG>
62 <STRONG>char
</STRONG> <STRONG>*key_name(wchar_t
</STRONG> <STRONG>w);
</STRONG>
63 <STRONG>void
</STRONG> <STRONG>filter(void);
</STRONG>
64 <STRONG>void
</STRONG> <STRONG>nofilter(void);
</STRONG>
65 <STRONG>void
</STRONG> <STRONG>use_env(bool
</STRONG> <STRONG>f);
</STRONG>
66 <STRONG>int
</STRONG> <STRONG>putwin(WINDOW
</STRONG> <STRONG>*win,
</STRONG> <STRONG>FILE
</STRONG> <STRONG>*filep);
</STRONG>
67 <STRONG>WINDOW
</STRONG> <STRONG>*getwin(FILE
</STRONG> <STRONG>*filep);
</STRONG>
68 <STRONG>int
</STRONG> <STRONG>delay_output(int
</STRONG> <STRONG>ms);
</STRONG>
69 <STRONG>int
</STRONG> <STRONG>flushinp(void);
</STRONG>
73 <H2>DESCRIPTION
</H2><PRE>
74 The
<STRONG>unctrl
</STRONG> routine returns a character string which is a
75 printable representation of the character
<EM>c
</EM>, ignoring at-
76 tributes. Control characters are displayed in the
<STRONG>^
</STRONG><EM>X
</EM> no-
77 tation. Printing characters are displayed as is. The
78 corresponding
<STRONG>wunctrl
</STRONG> returns a printable representation
81 The
<STRONG>keyname
</STRONG> routine returns a character string correspond-
82 ing to the key
<EM>c
</EM>:
84 <STRONG>o
</STRONG> Printable characters are displayed as themselves,
85 e.g., a one-character string containing the key.
87 <STRONG>o
</STRONG> Control characters are displayed in the
<STRONG>^
</STRONG><EM>X
</EM> nota-
90 <STRONG>o
</STRONG> DEL (character
127) is displayed as
<STRONG>^?
</STRONG>.
92 <STRONG>o
</STRONG> Values above
128 are either meta characters (if the
93 screen has not been initialized, or if
<STRONG>meta
</STRONG> has
94 been called with a TRUE parameter), shown in the
95 <STRONG>M-
</STRONG><EM>X
</EM> notation, or are displayed as themselves. In
96 the latter case, the values may not be printable;
97 this follows the X/Open specification.
99 <STRONG>o
</STRONG> Values above
256 may be the names of the names of
102 <STRONG>o
</STRONG> Otherwise (if there is no corresponding name) the
103 function returns null, to denote an error. X/Open
104 also lists an
"UNKNOWN KEY" return value, which
105 some implementations return rather than null.
107 The corresponding
<STRONG>key_name
</STRONG> returns a character string cor-
108 responding to the wide-character value
<EM>w
</EM>. The two func-
109 tions do not return the same set of strings; the latter
110 returns null where the former would display a meta charac-
113 The
<STRONG>filter
</STRONG> routine, if used, must be called before
<STRONG>initscr
</STRONG>
114 or
<STRONG>newterm
</STRONG> are called. The effect is that, during those
115 calls,
<STRONG>LINES
</STRONG> is set to
1; the capabilities
<STRONG>clear
</STRONG>,
<STRONG>cup
</STRONG>,
116 <STRONG>cud
</STRONG>,
<STRONG>cud1
</STRONG>,
<STRONG>cuu1
</STRONG>,
<STRONG>cuu
</STRONG>,
<STRONG>vpa
</STRONG> are disabled; and the
<STRONG>home
</STRONG>
117 string is set to the value of
<STRONG>cr
</STRONG>.
119 The
<STRONG>nofilter
</STRONG> routine cancels the effect of a preceding
120 <STRONG>filter
</STRONG> call. That allows the caller to initialize a
121 screen on a different device, using a different value of
122 <STRONG>$TERM
</STRONG>. The limitation arises because the
<STRONG>filter
</STRONG> routine
123 modifies the in-memory copy of the terminal information.
125 The
<STRONG>use_env
</STRONG> routine, if used, is called before
<STRONG>initscr
</STRONG> or
126 <STRONG>newterm
</STRONG> are called. When called with
<STRONG>FALSE
</STRONG> as an argu-
127 ment, the values of
<STRONG>lines
</STRONG> and
<STRONG>columns
</STRONG> specified in the
128 <EM>terminfo
</EM> database will be used, even if environment vari-
129 ables
<STRONG>LINES
</STRONG> and
<STRONG>COLUMNS
</STRONG> (used by default) are set, or if
130 <STRONG>curses
</STRONG> is running in a window (in which case default be-
131 havior would be to use the window size if
<STRONG>LINES
</STRONG> and
132 <STRONG>COLUMNS
</STRONG> are not set). Note that setting
<STRONG>LINES
</STRONG> or
<STRONG>COLUMNS
</STRONG>
133 overrides the corresponding size which may be obtained
134 from the operating system.
136 The
<STRONG>putwin
</STRONG> routine writes all data associated with window
137 <EM>win
</EM> into the file to which
<EM>filep
</EM> points. This information
138 can be later retrieved using the
<STRONG>getwin
</STRONG> function.
140 The
<STRONG>getwin
</STRONG> routine reads window related data stored in the
141 file by
<STRONG>putwin
</STRONG>. The routine then creates and initializes
142 a new window using that data. It returns a pointer to the
145 The
<STRONG>delay_output
</STRONG> routine inserts an
<EM>ms
</EM> millisecond pause
146 in output. This routine should not be used extensively
147 because padding characters are used rather than a CPU
148 pause. If no padding character is specified, this uses
149 <STRONG>napms
</STRONG> to perform the delay.
151 The
<STRONG>flushinp
</STRONG> routine throws away any typeahead that has
152 been typed by the user and has not yet been read by the
157 <H2>RETURN VALUE
</H2><PRE>
158 Except for
<STRONG>flushinp
</STRONG>, routines that return an integer re-
159 turn
<STRONG>ERR
</STRONG> upon failure and
<STRONG>OK
</STRONG> (SVr4 specifies only
"an in-
160 teger value other than <STRONG>ERR</STRONG>") upon successful completion.
162 Routines that return pointers return
<STRONG>NULL
</STRONG> on error.
164 X/Open does not define any error conditions. In this im-
167 <STRONG>flushinp
</STRONG>
168 returns an error if the terminal was not initial-
171 <STRONG>meta
</STRONG> returns an error if the terminal was not initial-
174 <STRONG>putwin
</STRONG>
175 returns an error if the associated
<STRONG>fwrite
</STRONG> calls
180 <H2>PORTABILITY
</H2><PRE>
181 The XSI Curses standard, Issue
4 describes these func-
182 tions. It states that
<STRONG>unctrl
</STRONG> and
<STRONG>wunctrl
</STRONG> will return a
183 null pointer if unsuccessful, but does not define any er-
184 ror conditions. This implementation checks for three cas-
187 <STRONG>o
</STRONG> the parameter is a
7-bit US-ASCII code. This is
188 the case that X/Open Curses documented.
190 <STRONG>o
</STRONG> the parameter is in the range
128-
159, i.e., a C1
191 control code. If
<STRONG>use_legacy_coding
</STRONG> has been called
192 with a
<STRONG>2</STRONG> parameter,
<STRONG>unctrl
</STRONG> returns the parameter,
193 i.e., a one-character string with the parameter as
194 the first character. Otherwise, it returns ``~@'',
195 ``~A'', etc., analogous to ``^@'', ``^A'', C0 con-
198 X/Open Curses does not document whether
<STRONG>unctrl
</STRONG> can
199 be called before initializing curses. This imple-
200 mentation permits that, and returns the ``~@'',
201 etc., values in that case.
203 <STRONG>o
</STRONG> parameter values outside the
0 to
255 range.
<STRONG>unc-
</STRONG>
204 <STRONG>trl
</STRONG> returns a null pointer.
206 The SVr4 documentation describes the action of
<STRONG>filter
</STRONG> only
207 in the vaguest terms. The description here is adapted
208 from the XSI Curses standard (which erroneously fails to
209 describe the disabling of
<STRONG>cuu
</STRONG>).
211 The strings returned by
<STRONG>unctrl
</STRONG> in this implementation are
212 determined at compile time, showing C1 controls from the
213 upper-
128 codes with a `~' prefix rather than `^'. Other
214 implementations have different conventions. For example,
215 they may show both sets of control characters with `^',
216 and strip the parameter to
7 bits. Or they may ignore C1
217 controls and treat all of the upper-
128 codes as print-
218 able. This implementation uses
8 bits but does not modify
219 the string to reflect locale. The
<STRONG>use_legacy_coding
</STRONG> func-
220 tion allows the caller to change the output of
<STRONG>unctrl
</STRONG>.
222 Likewise, the
<STRONG>meta
</STRONG> function allows the caller to change
223 the output of
<STRONG>keyname
</STRONG>, i.e., it determines whether to use
224 the `M-' prefix for ``meta'' keys (codes in the range
128
225 to
255). Both
<STRONG>use_legacy_coding
</STRONG> and
<STRONG>meta
</STRONG> succeed only af-
226 ter curses is initialized. X/Open Curses does not docu-
227 ment the treatment of codes
128 to
159. When treating
228 them as ``meta'' keys (or if
<STRONG>keyname
</STRONG> is called before ini-
229 tializing curses), this implementation returns strings
230 ``M-^@'', ``M-^A'', etc.
232 The
<STRONG>keyname
</STRONG> function may return the names of user-defined
233 string capabilities which are defined in the terminfo en-
234 try via the
<STRONG>-x
</STRONG> option of
<STRONG>tic
</STRONG>. This implementation auto-
235 matically assigns at run-time keycodes to user-defined
236 strings which begin with
"k". The keycodes start at
237 KEY_MAX, but are not guaranteed to be the same value for
238 different runs because user-defined codes are merged from
239 all terminal descriptions which have been loaded. The
240 <STRONG>use_extended_names
</STRONG> function controls whether this data is
241 loaded when the terminal description is read by the li-
244 The
<STRONG>nofilter
</STRONG> routine is specific to ncurses. It was not
245 supported on Version
7, BSD or System V implementations.
246 It is recommended that any code depending on ncurses ex-
247 tensions be conditioned using NCURSES_VERSION.
251 <H2>SEE ALSO
</H2><PRE>
252 <STRONG><A HREF=
"legacy_coding.3x.html">legacy_coding(
3x)
</A></STRONG>,
<STRONG><A HREF=
"ncurses.3x.html">curses(
3x)
</A></STRONG>,
<STRONG><A HREF=
"curs_initscr.3x.html">curs_initscr(
3x)
</A></STRONG>,
<STRONG>curs_ker-
</STRONG>
253 <STRONG><A HREF=
"curs_kernel.3x.html">nel(
3x)
</A></STRONG>,
<STRONG><A HREF=
"curs_scr_dump.3x.html">curs_scr_dump(
3x)
</A></STRONG>,
<STRONG><A HREF=
"curs_variables.3x.html">curs_variables(
3x)
</A></STRONG>,
<STRONG>lega-
</STRONG>
254 <STRONG><A HREF=
"legacy_coding.3x.html">cy_coding(
3x)
</A></STRONG>.
258 <STRONG><A HREF=
"curs_util.3x.html">curs_util(
3x)
</A></STRONG>
262 Man(
1) output converted with
263 <a href=
"http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html
</a>