2002-10-13 11:35:53 +08:00
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<!--
****************************************************************************
2005-10-10 02:41:57 +08:00
* Copyright (c) 1998-2004,2005 Free Software Foundation, Inc. *
2002-10-13 11:35:53 +08:00
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
* copy of this software and associated documentation files (the *
* "Software"), to deal in the Software without restriction, including *
* without limitation the rights to use, copy, modify, merge, publish, *
* distribute, distribute with modifications, sublicense, and/or sell *
* copies of the Software, and to permit persons to whom the Software is *
* furnished to do so, subject to the following conditions: *
* *
* The above copyright notice and this permission notice shall be included *
* in all copies or substantial portions of the Software. *
* *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
* IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
* *
* Except as contained in this notice, the name(s) of the above copyright *
* holders shall not be used in advertising or otherwise to promote the *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
2005-10-10 02:41:57 +08:00
* @Id: curs_util.3x,v 1.17 2005/06/25 21:51:37 tom Exp @
2002-10-13 11:35:53 +08:00
-->
2000-07-09 10:46:08 +08:00
< HTML >
2002-10-13 11:35:53 +08:00
< HEAD >
< TITLE > curs_util 3x< / TITLE >
< link rev = made href = "mailto:bug-ncurses@gnu.org" >
< meta http-equiv = "Content-Type" content = "text/html; charset=iso-8859-1" >
< / HEAD >
2000-07-09 10:46:08 +08:00
< BODY >
2002-10-13 11:35:53 +08:00
< H1 > curs_util 3x< / H1 >
< HR >
2000-07-09 10:46:08 +08:00
< PRE >
<!-- Manpage converted by man2html 3.0.1 -->
2005-10-10 02:41:57 +08:00
< STRONG > < A HREF = "curs_util.3x.html" > curs_util(3x)< / A > < / STRONG > < STRONG > < A HREF = "curs_util.3x.html" > curs_util(3x)< / A > < / STRONG >
2004-02-09 10:15:26 +08:00
2000-07-09 10:46:08 +08:00
< / PRE >
< H2 > NAME< / H2 > < PRE >
2002-10-13 11:35:53 +08:00
< STRONG > delay_output< / STRONG > , < STRONG > filter< / STRONG > , < STRONG > flushinp< / STRONG > , < STRONG > getwin< / STRONG > , < STRONG > key_name< / STRONG > , < STRONG > keyname< / STRONG > ,
2005-10-10 02:41:57 +08:00
< STRONG > putwin< / STRONG > , < STRONG > unctrl< / STRONG > , < STRONG > use_env< / STRONG > , < STRONG > wunctrl< / STRONG > - miscellaneous < STRONG > curses< / STRONG >
2002-10-13 11:35:53 +08:00
utility routines
2000-07-09 10:46:08 +08:00
< / PRE >
< H2 > SYNOPSIS< / H2 > < PRE >
2002-10-13 11:35:53 +08:00
< STRONG > #include< / STRONG > < STRONG > < curses.h> < / STRONG >
2000-07-09 10:46:08 +08:00
2002-10-13 11:35:53 +08:00
< STRONG > char< / STRONG > < STRONG > *unctrl(chtype< / STRONG > < STRONG > c);< / STRONG >
2004-02-09 10:15:26 +08:00
< STRONG > char< / STRONG > < STRONG > *wunctrl(cchar_t< / STRONG > < STRONG > *c);< / STRONG >
2002-10-13 11:35:53 +08:00
< STRONG > char< / STRONG > < STRONG > *keyname(int< / STRONG > < STRONG > c);< / STRONG >
< STRONG > char< / STRONG > < STRONG > *key_name(wchar_t< / STRONG > < STRONG > w);< / STRONG >
< STRONG > void< / STRONG > < STRONG > filter(void);< / STRONG >
< STRONG > void< / STRONG > < STRONG > use_env(bool< / STRONG > < STRONG > f);< / STRONG >
< STRONG > int< / STRONG > < STRONG > putwin(WINDOW< / STRONG > < STRONG > *win,< / STRONG > < STRONG > FILE< / STRONG > < STRONG > *filep);< / STRONG >
< STRONG > WINDOW< / STRONG > < STRONG > *getwin(FILE< / STRONG > < STRONG > *filep);< / STRONG >
< STRONG > int< / STRONG > < STRONG > delay_output(int< / STRONG > < STRONG > ms);< / STRONG >
< STRONG > int< / STRONG > < STRONG > flushinp(void);< / STRONG >
2000-07-09 10:46:08 +08:00
< / PRE >
< H2 > DESCRIPTION< / H2 > < PRE >
2002-10-13 11:35:53 +08:00
The < STRONG > unctrl< / STRONG > routine returns a character string which is a
2005-10-10 02:41:57 +08:00
printable representation of the character < EM > c< / EM > , ignoring at-
tributes. Control characters are displayed in the < STRONG > ^< / STRONG > < EM > X< / EM > no-
tation. Printing characters are displayed as is. The
2002-10-13 11:35:53 +08:00
corresponding < STRONG > wunctrl< / STRONG > returns a printable representation
of a wide-character.
The < STRONG > keyname< / STRONG > routine returns a character string correspond-
ing to the key < EM > c< / EM > . Control characters are displayed in the
< STRONG > ^< / STRONG > < EM > X< / EM > notation. Values above 128 are either meta characters,
shown in the < STRONG > M-< / STRONG > < EM > X< / EM > notation, or the names of function keys,
or null. The corresponding < STRONG > key_name< / STRONG > returns a character
string corresponding to the wide-character value < EM > w< / EM > . The
two functions do not return the same set of strings; the
latter returns null where the former would display a meta
character.
The < STRONG > filter< / STRONG > routine, if used, must be called before < STRONG > initscr< / STRONG >
or < STRONG > newterm< / STRONG > are called. The effect is that, during those
calls, < STRONG > LINES< / STRONG > is set to 1; the capabilities < STRONG > clear< / STRONG > , < STRONG > cup< / STRONG > ,
< STRONG > cud< / STRONG > , < STRONG > cud1< / STRONG > , < STRONG > cuu1< / STRONG > , < STRONG > cuu< / STRONG > , < STRONG > vpa< / STRONG > are disabled; and the < STRONG > home< / STRONG >
string is set to the value of < STRONG > cr< / STRONG > .
The < STRONG > use_env< / STRONG > routine, if used, is called before < STRONG > initscr< / STRONG > or
< STRONG > newterm< / STRONG > are called. When called with < STRONG > FALSE< / STRONG > as an argu-
ment, the values of < STRONG > lines< / STRONG > and < STRONG > columns< / STRONG > specified in the
< EM > terminfo< / EM > database will be used, even if environment vari-
ables < STRONG > LINES< / STRONG > and < STRONG > COLUMNS< / STRONG > (used by default) are set, or if
2005-10-10 02:41:57 +08:00
< STRONG > curses< / STRONG > is running in a window (in which case default be-
havior would be to use the window size if < STRONG > LINES< / STRONG > and
< STRONG > COLUMNS< / STRONG > are not set). Note that setting < STRONG > LINES< / STRONG > or < STRONG > COLUMNS< / STRONG >
overrides the corresponding size which may be obtained
from the operating system.
2002-10-13 11:35:53 +08:00
The < STRONG > putwin< / STRONG > routine writes all data associated with window
< EM > win< / EM > into the file to which < EM > filep< / EM > points. This information
can be later retrieved using the < STRONG > getwin< / STRONG > function.
The < STRONG > getwin< / STRONG > routine reads window related data stored in the
file by < STRONG > putwin< / STRONG > . The routine then creates and initializes
2000-07-09 10:46:08 +08:00
a new window using that data. It returns a pointer to the
new window.
2002-10-13 11:35:53 +08:00
The < STRONG > delay_output< / STRONG > routine inserts an < EM > ms< / EM > millisecond pause
in output. This routine should not be used extensively
because padding characters are used rather than a CPU
2004-02-09 10:15:26 +08:00
pause. If no padding character is specified, this uses
< STRONG > napms< / STRONG > to perform the delay.
2002-10-13 11:35:53 +08:00
2004-02-09 10:15:26 +08:00
The < STRONG > flushinp< / STRONG > routine throws away any typeahead that has
been typed by the user and has not yet been read by the
2000-07-09 10:46:08 +08:00
program.
< / PRE >
< H2 > RETURN VALUE< / H2 > < PRE >
2005-10-10 02:41:57 +08:00
Except for < STRONG > flushinp< / STRONG > , routines that return an integer re-
turn < STRONG > ERR< / STRONG > upon failure and < STRONG > OK< / STRONG > (SVr4 specifies only "an in-
teger value other than < STRONG > ERR< / STRONG > ") upon successful completion.
2000-07-09 10:46:08 +08:00
2002-10-13 11:35:53 +08:00
Routines that return pointers return < STRONG > NULL< / STRONG > on error.
2000-07-09 10:46:08 +08:00
2005-10-10 02:41:57 +08:00
X/Open does not define any error conditions. In this im-
plementation
< STRONG > flushinp< / STRONG >
returns an error if the terminal was not ini-
tialized.
< STRONG > putwin< / STRONG >
returns an error if the associated < STRONG > fwrite< / STRONG >
calls return an error.
2000-07-09 10:46:08 +08:00
< / PRE >
< H2 > PORTABILITY< / H2 > < PRE >
2004-02-09 10:15:26 +08:00
The XSI Curses standard, Issue 4 describes these func-
tions. It states that < STRONG > unctrl< / STRONG > and < STRONG > wunctrl< / STRONG > will return a
2005-10-10 02:41:57 +08:00
null pointer if unsuccessful, but does not define any er-
ror conditions.
2000-07-09 10:46:08 +08:00
2002-10-13 11:35:53 +08:00
The SVr4 documentation describes the action of < STRONG > filter< / STRONG > only
2004-02-09 10:15:26 +08:00
in the vaguest terms. The description here is adapted
from the XSI Curses standard (which erroneously fails to
2002-10-13 11:35:53 +08:00
describe the disabling of < STRONG > cuu< / STRONG > ).
2000-07-09 10:46:08 +08:00
2005-10-10 02:41:57 +08:00
The strings returned by < STRONG > unctrl< / STRONG > 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 < STRONG > keyname< / STRONG > function may return the names of user-defined
string capabilities which are defined in the terminfo en-
try via the < STRONG > -x< / STRONG > option of < STRONG > tic< / STRONG > .
2000-07-09 10:46:08 +08:00
< / PRE >
< H2 > SEE ALSO< / H2 > < PRE >
2004-02-09 10:15:26 +08:00
< STRONG > < A HREF = "ncurses.3x.html" > curses(3x)< / A > < / STRONG > , < STRONG > < A HREF = "curs_initscr.3x.html" > curs_initscr(3x)< / A > < / STRONG > , < STRONG > < A HREF = "curs_kernel.3x.html" > curs_kernel(3x)< / A > < / STRONG > ,
< STRONG > < A HREF = "curs_scr_dump.3x.html" > curs_scr_dump(3x)< / A > < / STRONG > .
2000-07-09 10:46:08 +08:00
2005-10-10 02:41:57 +08:00
< STRONG > < A HREF = "curs_util.3x.html" > curs_util(3x)< / A > < / STRONG >
2000-07-09 10:46:08 +08:00
< / PRE >
< HR >
< ADDRESS >
Man(1) output converted with
< a href = "http://www.oac.uci.edu/indiv/ehood/man2html.html" > man2html< / a >
< / ADDRESS >
< / BODY >
< / HTML >
