2002-10-13 11:35:53 +08:00
<!--
2013-03-10 08:35:23 +08:00
* t
2002-10-13 11:35:53 +08:00
****************************************************************************
2017-01-08 09:40:29 +08:00
* Copyright (c) 1998-2015,2017 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. *
****************************************************************************
2017-02-19 10:52:26 +08:00
* @Id: curs_util.3x,v 1.47 2017/02/18 16:43:03 tom Exp @
2002-10-13 11:35:53 +08:00
-->
2015-02-15 09:42:27 +08:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
2000-07-09 10:46:08 +08:00
< HTML >
2002-10-13 11:35:53 +08:00
< HEAD >
2015-02-15 09:42:27 +08:00
< meta http-equiv = "Content-Type" content = "text/html; charset=us-ascii" >
< meta name = "generator" content = "Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts" >
2002-10-13 11:35:53 +08:00
< 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 >
2015-05-17 05:01:22 +08:00
< H1 class = "no-header" > curs_util 3x< / H1 >
2000-07-09 10:46:08 +08:00
< PRE >
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
2016-01-31 10:15:39 +08:00
< / PRE > < H2 > < a name = "h2-NAME" > NAME< / a > < / 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 > ,
2013-03-10 08:35:23 +08:00
< STRONG > nofilter< / STRONG > , < STRONG > putwin< / STRONG > , < STRONG > unctrl< / STRONG > , < STRONG > use_env< / STRONG > , < STRONG > use_tioctl< / STRONG > , < STRONG > wunctrl< / STRONG > -
miscellaneous < STRONG > curses< / STRONG > utility routines
2000-07-09 10:46:08 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H2 > < a name = "h2-SYNOPSIS" > SYNOPSIS< / a > < / 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 >
2007-03-04 08:18:45 +08:00
< STRONG > wchar_t< / 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 >
2006-12-18 12:32:42 +08:00
< STRONG > void< / STRONG > < STRONG > nofilter(void);< / STRONG >
2002-10-13 11:35:53 +08:00
< STRONG > void< / STRONG > < STRONG > use_env(bool< / STRONG > < STRONG > f);< / STRONG >
2013-03-10 08:35:23 +08:00
< STRONG > void< / STRONG > < STRONG > use_tioctl(bool< / STRONG > < STRONG > f);< / STRONG >
2002-10-13 11:35:53 +08:00
< 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
2016-01-31 10:15:39 +08:00
< / PRE > < H2 > < a name = "h2-DESCRIPTION" > DESCRIPTION< / a > < / H2 > < PRE >
2015-06-07 09:16:17 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-unctrl" > unctrl< / a > < / H3 > < 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
2010-09-19 08:45:46 +08:00
of a wide character.
2002-10-13 11:35:53 +08:00
2015-06-07 09:16:17 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-keyname_key_name" > keyname/key_name< / a > < / H3 > < PRE >
2002-10-13 11:35:53 +08:00
The < STRONG > keyname< / STRONG > routine returns a character string correspond-
2008-10-12 07:44:29 +08:00
ing to the key < EM > c< / EM > :
2015-05-17 05:01:22 +08:00
< STRONG > o< / STRONG > Printable characters are displayed as themselves,
e.g., a one-character string containing the key.
2008-10-12 07:44:29 +08:00
2015-05-17 05:01:22 +08:00
< STRONG > o< / STRONG > Control characters are displayed in the < STRONG > ^< / STRONG > < EM > X< / EM > notation.
2008-10-12 07:44:29 +08:00
2015-05-17 05:01:22 +08:00
< STRONG > o< / STRONG > DEL (character 127) is displayed as < STRONG > ^?< / STRONG > .
2008-10-12 07:44:29 +08:00
2015-05-17 05:01:22 +08:00
< STRONG > o< / STRONG > Values above 128 are either meta characters (if the
2017-01-08 09:40:29 +08:00
screen has not been initialized, or if < STRONG > < A HREF = "curs_inopts.3x.html" > meta(3x)< / A > < / STRONG > has
been called with a < STRONG > TRUE< / STRONG > parameter), shown in the < STRONG > M-< / STRONG > < EM > X< / EM >
notation, or are displayed as themselves. In the lat-
ter case, the values may not be printable; this fol-
lows the X/Open specification.
2008-10-12 07:44:29 +08:00
2015-05-17 05:01:22 +08:00
< STRONG > o< / STRONG > Values above 256 may be the names of the names of
function keys.
2008-10-12 07:44:29 +08:00
2015-05-17 05:01:22 +08:00
< STRONG > o< / STRONG > Otherwise (if there is no corresponding name) the
function returns null, to denote an error. X/Open al-
so lists an "UNKNOWN KEY" return value, which some im-
plementations return rather than null.
2008-10-12 07:44:29 +08:00
The corresponding < STRONG > key_name< / STRONG > returns a character string cor-
2015-05-17 05:01:22 +08:00
responding to the wide-character value < EM > w< / EM > . The two func-
tions do not return the same set of strings; the latter
2008-10-12 07:44:29 +08:00
returns null where the former would display a meta charac-
ter.
2002-10-13 11:35:53 +08:00
2015-06-07 09:16:17 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-filter_nofilter" > filter/nofilter< / a > < / H3 > < PRE >
2002-10-13 11:35:53 +08:00
The < STRONG > filter< / STRONG > routine, if used, must be called before < STRONG > initscr< / STRONG >
2015-05-17 05:01:22 +08:00
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 >
2002-10-13 11:35:53 +08:00
string is set to the value of < STRONG > cr< / STRONG > .
2015-05-17 05:01:22 +08:00
The < STRONG > nofilter< / STRONG > routine cancels the effect of a preceding
< STRONG > filter< / STRONG > call. That allows the caller to initialize a
screen on a different device, using a different value of
< STRONG > $TERM< / STRONG > . The limitation arises because the < STRONG > filter< / STRONG > routine
2006-12-18 12:32:42 +08:00
modifies the in-memory copy of the terminal information.
2015-06-07 09:16:17 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-use_env" > use_env< / a > < / H3 > < PRE >
2015-05-17 05:01:22 +08:00
The < STRONG > use_env< / STRONG > routine, if used, should be called before
< STRONG > initscr< / STRONG > or < STRONG > newterm< / STRONG > are called (because those compute the
2013-03-10 08:35:23 +08:00
screen size). It modifies the way < STRONG > ncurses< / STRONG > treats environ-
ment variables when determining the screen size.
2017-01-08 09:40:29 +08:00
< STRONG > o< / STRONG > Normally < STRONG > ncurses< / STRONG > looks first at the terminal database
2013-03-10 08:35:23 +08:00
for the screen size.
2015-05-17 05:01:22 +08:00
If < STRONG > use_env< / STRONG > was called with < STRONG > FALSE< / STRONG > for parameter, it
stops here unless If < STRONG > use_tioctl< / STRONG > was also called with
2013-03-10 08:35:23 +08:00
< STRONG > TRUE< / STRONG > for parameter.
2015-05-17 05:01:22 +08:00
< STRONG > o< / STRONG > Then it asks for the screen size via operating system
calls. If successful, it overrides the values from
2013-03-10 08:35:23 +08:00
the terminal database.
2015-05-17 05:01:22 +08:00
< STRONG > o< / STRONG > Finally (unless < STRONG > use_env< / STRONG > was called with < STRONG > FALSE< / STRONG > parame-
2017-01-08 09:40:29 +08:00
ter), < STRONG > ncurses< / STRONG > examines the < STRONG > LINES< / STRONG > or < STRONG > COLUMNS< / STRONG > environ-
2013-03-10 08:35:23 +08:00
ment variables, using a value in those to override the
2015-05-17 05:01:22 +08:00
results from the operating system or terminal data-
2013-03-10 08:35:23 +08:00
base.
2017-01-08 09:40:29 +08:00
< STRONG > Ncurses< / STRONG > also updates the screen size in response to
2015-05-17 05:01:22 +08:00
SIGWINCH, unless overridden by the < STRONG > LINES< / STRONG > or < STRONG > COLUMNS< / STRONG >
2013-03-10 08:35:23 +08:00
environment variables,
2015-06-07 09:16:17 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-use_tioctl" > use_tioctl< / a > < / H3 > < PRE >
2015-05-17 05:01:22 +08:00
The < STRONG > use_tioctl< / STRONG > routine, if used, should be called before
< STRONG > initscr< / STRONG > or < STRONG > newterm< / STRONG > are called (because those compute the
screen size). After < STRONG > use_tioctl< / STRONG > is called with < STRONG > TRUE< / STRONG > as an
2017-01-08 09:40:29 +08:00
argument, < STRONG > ncurses< / STRONG > modifies the last step in its computa-
2013-03-10 08:35:23 +08:00
tion of screen size as follows:
2015-05-17 05:01:22 +08:00
< STRONG > o< / STRONG > checks if the < STRONG > LINES< / STRONG > and < STRONG > COLUMNS< / STRONG > environment variables
2013-03-10 08:35:23 +08:00
are set to a number greater than zero.
2017-01-08 09:40:29 +08:00
< STRONG > o< / STRONG > for each, < STRONG > ncurses< / STRONG > updates the corresponding environ-
2015-05-17 05:01:22 +08:00
ment variable with the value that it has obtained via
2013-03-10 08:35:23 +08:00
operating system call or from the terminal database.
2017-01-08 09:40:29 +08:00
< STRONG > o< / STRONG > < STRONG > ncurses< / STRONG > re-fetches the value of the environment vari-
2015-05-17 05:01:22 +08:00
ables so that it is still the environment variables
2013-03-10 08:35:23 +08:00
which set the screen size.
2015-05-17 05:01:22 +08:00
The < STRONG > use_env< / STRONG > and < STRONG > use_tioctl< / STRONG > routines combine as summarized
2013-03-10 08:35:23 +08:00
here:
< EM > use< / EM > < STRONG > _< / STRONG > < EM > env< / EM > < EM > use< / EM > < STRONG > _< / STRONG > < EM > tioctl< / EM > < EM > Summary< / EM >
----------------------------------------------------------------
2015-06-07 09:16:17 +08:00
2017-01-08 09:40:29 +08:00
TRUE FALSE This is the default behavior. < STRONG > ncurses< / STRONG >
2013-03-10 08:35:23 +08:00
uses operating system calls unless over-
ridden by $LINES or $COLUMNS environment
variables.
2017-01-08 09:40:29 +08:00
TRUE TRUE < STRONG > ncurses< / STRONG > updates $LINES and $COLUMNS
2013-03-10 08:35:23 +08:00
based on operating system calls.
2017-01-08 09:40:29 +08:00
FALSE TRUE < STRONG > ncurses< / STRONG > ignores $LINES and $COLUMNS, us-
2013-03-10 08:35:23 +08:00
es operating system calls to obtain
size.
2017-01-08 09:40:29 +08:00
FALSE FALSE < STRONG > ncurses< / STRONG > relies on the terminal database
2013-03-10 08:35:23 +08:00
to determine size.
2002-10-13 11:35:53 +08:00
2015-06-07 09:16:17 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-putwin_getwin" > putwin/getwin< / a > < / H3 > < PRE >
2015-05-17 05:01:22 +08:00
The < STRONG > putwin< / STRONG > routine writes all data associated with window
(or pad) < EM > win< / EM > into the file to which < EM > filep< / EM > points. This
information can be later retrieved using the < STRONG > getwin< / STRONG > func-
tion.
2002-10-13 11:35:53 +08:00
The < STRONG > getwin< / STRONG > routine reads window related data stored in the
2010-09-19 08:45:46 +08:00
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
2015-05-17 05:01:22 +08:00
new window. There are a few caveats:
< STRONG > o< / STRONG > the data written is a copy of the < STRONG > WINDOW< / STRONG > structure,
and its associated character cells. The format dif-
fers between the wide-character (ncursesw) and non-
wide (ncurses) libraries. You can transfer data be-
tween the two, however.
< STRONG > o< / STRONG > the retrieved window is always created as a top-level
window (or pad), rather than a subwindow.
< STRONG > o< / STRONG > the window's character cells contain the color pair
< EM > value< / EM > , but not the actual color < EM > numbers< / EM > . If cells in
the retrieved window use color pairs which have not
been created in the application using < STRONG > init_pair< / STRONG > , they
will not be colored when the window is refreshed.
2015-06-07 09:16:17 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-delay_output" > delay_output< / a > < / H3 > < PRE >
2015-05-17 05:01:22 +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
pause. If no padding character is specified, this uses
2004-02-09 10:15:26 +08:00
< STRONG > napms< / STRONG > to perform the delay.
2002-10-13 11:35:53 +08:00
2015-06-07 09:16:17 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-flushinp" > flushinp< / a > < / H3 > < PRE >
2015-05-17 05:01:22 +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.
2016-01-31 10:15:39 +08:00
< / PRE > < H2 > < a name = "h2-RETURN-VALUE" > RETURN VALUE< / a > < / H2 > < PRE >
2015-05-17 05:01:22 +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-
2005-10-10 02:41:57 +08:00
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
2015-05-17 05:01:22 +08:00
X/Open does not define any error conditions. In this im-
2005-10-10 02:41:57 +08:00
plementation
2010-01-10 09:50:23 +08:00
< STRONG > flushinp< / STRONG >
2015-05-17 05:01:22 +08:00
returns an error if the terminal was not initial-
2010-01-10 09:50:23 +08:00
ized.
2005-10-10 02:41:57 +08:00
2010-01-10 09:50:23 +08:00
< STRONG > putwin< / STRONG >
2017-01-08 09:40:29 +08:00
returns an error if the associated < STRONG > fwrite< / STRONG > calls
2010-01-10 09:50:23 +08:00
return an error.
2005-10-10 02:41:57 +08:00
2000-07-09 10:46:08 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H2 > < a name = "h2-PORTABILITY" > PORTABILITY< / a > < / H2 > < PRE >
2000-07-09 10:46:08 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-filter" > filter< / a > < / H3 > < PRE >
2002-10-13 11:35:53 +08:00
The SVr4 documentation describes the action of < STRONG > filter< / STRONG > only
2017-01-08 09:40:29 +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
2013-12-22 07:12:46 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-keyname" > keyname< / a > < / H3 > < PRE >
2017-01-08 09:40:29 +08:00
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 > . 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
< STRONG > use_extended_names< / STRONG > function controls whether this data is
loaded when the terminal description is read by the li-
2008-10-12 07:44:29 +08:00
brary.
2015-05-17 05:01:22 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-nofilter_use_tioctl" > nofilter/use_tioctl< / a > < / H3 > < PRE >
2017-01-08 09:40:29 +08:00
The < STRONG > nofilter< / STRONG > and < STRONG > use_tioctl< / STRONG > routines are specific to
< STRONG > ncurses< / STRONG > . They were not supported on Version 7, BSD or
2013-03-10 08:35:23 +08:00
System V implementations. It is recommended that any code
2017-01-08 09:40:29 +08:00
depending on < STRONG > ncurses< / STRONG > extensions be conditioned using
2013-03-10 08:35:23 +08:00
NCURSES_VERSION.
2005-10-10 02:41:57 +08:00
2000-07-09 10:46:08 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-putwin_getwin" > putwin/getwin< / a > < / H3 > < PRE >
2017-01-08 09:40:29 +08:00
The < STRONG > putwin< / STRONG > and < STRONG > getwin< / STRONG > functions have several issues with
2015-05-17 05:01:22 +08:00
portability:
2017-01-08 09:40:29 +08:00
< STRONG > o< / STRONG > The files written and read by these functions use an
implementation-specific format. Although the format
is an obvious target for standardization, it has been
2015-05-17 05:01:22 +08:00
overlooked.
Interestingly enough, according to the copyright dates
in Solaris source, the functions (along with < STRONG > scr_init< / STRONG > ,
2017-01-08 09:40:29 +08:00
etc.) originated with the University of California,
Berkeley (in 1982) and were later (in 1988) incorpo-
rated into SVr4. Oddly, there are no such functions
2015-05-17 05:01:22 +08:00
in the 4.3BSD curses sources.
2017-01-08 09:40:29 +08:00
< STRONG > o< / STRONG > Most implementations simply dump the binary < STRONG > WINDOW< / STRONG >
structure to the file. These include SVr4 curses,
NetBSD and PDCurses, as well as older < STRONG > ncurses< / STRONG > ver-
sions. This implementation (as well as the X/Open
variant of Solaris curses, dated 1995) uses textual
2015-05-17 05:01:22 +08:00
dumps.
2017-01-08 09:40:29 +08:00
The implementations which use binary dumps use block-
I/O (the < STRONG > fwrite< / STRONG > and < STRONG > fread< / STRONG > functions). Those that use
textual dumps use buffered-I/O. A few applications
2015-05-17 05:01:22 +08:00
may happen to write extra data in the file using these
2017-01-08 09:40:29 +08:00
functions. Doing that can run into problems mixing
block- and buffered-I/O. This implementation reduces
the problem on writes by flushing the output. Howev-
er, reading from a file written using mixed schemes
2015-05-17 05:01:22 +08:00
may not be successful.
2016-01-31 10:15:39 +08:00
< / PRE > < H3 > < a name = "h3-unctrl_wunctrl" > unctrl/wunctrl< / a > < / H3 > < PRE >
2017-01-08 09:40:29 +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
null pointer if unsuccessful, but does not define any er-
2015-05-17 05:01:22 +08:00
ror conditions. This implementation checks for three cas-
es:
2017-01-08 09:40:29 +08:00
< STRONG > o< / STRONG > the parameter is a 7-bit US-ASCII code. This is the
2015-05-17 05:01:22 +08:00
case that X/Open Curses documented.
< STRONG > o< / STRONG > the parameter is in the range 128-159, i.e., a C1 con-
2017-01-08 09:40:29 +08:00
trol code. If < STRONG > use_legacy_coding< / STRONG > has been called with
a < STRONG > 2< / STRONG > parameter, < STRONG > unctrl< / STRONG > returns the parameter, i.e., a
one-character string with the parameter as the first
character. Otherwise, it returns "~@", "~A", etc.,
2015-05-17 05:01:22 +08:00
analogous to "^@", "^A", C0 controls.
2017-01-08 09:40:29 +08:00
X/Open Curses does not document whether < STRONG > unctrl< / STRONG > can be
called before initializing curses. This implementa-
tion permits that, and returns the "~@", etc., values
2015-05-17 05:01:22 +08:00
in that case.
2017-01-08 09:40:29 +08:00
< STRONG > o< / STRONG > parameter values outside the 0 to 255 range. < STRONG > unctrl< / STRONG >
2015-05-17 05:01:22 +08:00
returns a null pointer.
2017-01-08 09:40:29 +08:00
The strings returned by < STRONG > unctrl< / STRONG > in this implementation are
determined at compile time, showing C1 controls from the
2017-02-19 10:52:26 +08:00
upper-128 codes with a "~" prefix rather than "^". Other
2017-01-08 09:40:29 +08:00
implementations have different conventions. For example,
2017-02-19 10:52:26 +08:00
they may show both sets of control characters with "^",
2017-01-08 09:40:29 +08:00
and strip the parameter to 7 bits. Or they may ignore C1
controls and treat all of the upper-128 codes as print-
2015-05-17 05:01:22 +08:00
able. This implementation uses 8 bits but does not modify
the string to reflect locale. The < STRONG > use_legacy_coding< / STRONG > func-
tion allows the caller to change the output of < STRONG > unctrl< / STRONG > .
2017-01-08 09:40:29 +08:00
Likewise, the < STRONG > < A HREF = "curs_inopts.3x.html" > meta(3x)< / A > < / STRONG > function allows the caller to
change the output of < STRONG > keyname< / STRONG > , i.e., it determines whether
2017-02-19 10:52:26 +08:00
to use the "M-" prefix for "meta" keys (codes in the range
2017-01-08 09:40:29 +08:00
128 to 255). Both < STRONG > use_legacy_coding< / STRONG > and < STRONG > meta< / STRONG > succeed only
after 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 < STRONG > keyname< / STRONG > is called before ini-
tializing curses), this implementation returns strings
"M-^@", "M-^A", etc.
< / PRE > < H3 > < a name = "h3-use_env_use_tioctl" > use_env/use_tioctl< / a > < / H3 > < PRE >
If < STRONG > ncurses< / STRONG > is configured to provide the sp-functions ex-
tension, the state of < STRONG > use_env< / STRONG > and < STRONG > use_tioctl< / STRONG > may be updat-
ed before creating each < EM > screen< / EM > rather than once only
(< STRONG > < A HREF = "curs_sp_funcs.3x.html" > curs_sp_funcs(3x)< / A > < / STRONG > ). This feature of < STRONG > use_env< / STRONG > is not pro-
vided by other implementation of curses.
2015-05-17 05:01:22 +08:00
2016-01-31 10:15:39 +08:00
< / PRE > < H2 > < a name = "h2-SEE-ALSO" > SEE ALSO< / a > < / H2 > < PRE >
2017-01-08 09:40:29 +08:00
< 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_in-< / STRONG >
< STRONG > < A HREF = "curs_inopts.3x.html" > opts(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 > ,
< STRONG > < A HREF = "curs_sp_funcs.3x.html" > curs_sp_funcs(3x)< / A > < / STRONG > , < STRONG > < A HREF = "curs_variables.3x.html" > curs_variables(3x)< / A > < / STRONG > , < STRONG > < A HREF = "legacy_coding.3x.html" > legacy_coding(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 >
2015-02-15 09:42:27 +08:00
< div class = "nav" >
< ul >
< li > < a href = "#h2-NAME" > NAME< / a > < / li >
< li > < a href = "#h2-SYNOPSIS" > SYNOPSIS< / a > < / li >
2015-06-07 09:16:17 +08:00
< li > < a href = "#h2-DESCRIPTION" > DESCRIPTION< / a >
< ul >
< li > < a href = "#h3-unctrl" > unctrl< / a > < / li >
< li > < a href = "#h3-keyname_key_name" > keyname/key_name< / a > < / li >
< li > < a href = "#h3-filter_nofilter" > filter/nofilter< / a > < / li >
< li > < a href = "#h3-use_env" > use_env< / a > < / li >
< li > < a href = "#h3-use_tioctl" > use_tioctl< / a > < / li >
< li > < a href = "#h3-putwin_getwin" > putwin/getwin< / a > < / li >
< li > < a href = "#h3-delay_output" > delay_output< / a > < / li >
< li > < a href = "#h3-flushinp" > flushinp< / a > < / li >
< / ul >
< / li >
2015-02-15 09:42:27 +08:00
< li > < a href = "#h2-RETURN-VALUE" > RETURN VALUE< / a > < / li >
2015-05-17 05:01:22 +08:00
< li > < a href = "#h2-PORTABILITY" > PORTABILITY< / a >
< ul >
< li > < a href = "#h3-filter" > filter< / a > < / li >
< li > < a href = "#h3-keyname" > keyname< / a > < / li >
< li > < a href = "#h3-nofilter_use_tioctl" > nofilter/use_tioctl< / a > < / li >
< li > < a href = "#h3-putwin_getwin" > putwin/getwin< / a > < / li >
< li > < a href = "#h3-unctrl_wunctrl" > unctrl/wunctrl< / a > < / li >
2017-01-08 09:40:29 +08:00
< li > < a href = "#h3-use_env_use_tioctl" > use_env/use_tioctl< / a > < / li >
2015-05-17 05:01:22 +08:00
< / ul >
< / li >
2015-02-15 09:42:27 +08:00
< li > < a href = "#h2-SEE-ALSO" > SEE ALSO< / a > < / li >
< / ul >
< / div >
2000-07-09 10:46:08 +08:00
< / BODY >
< / HTML >
