'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2011,2012 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_util.3x,v 1.36 2012/07/21 18:51:10 tom Exp $
+.\" $Id: curs_util.3x,v 1.38 2015/03/07 23:33:38 tom Exp $
.TH curs_util 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.de bP
.IP \(bu 4
..
The corresponding \fBwunctrl\fR returns a printable representation of
a wide character.
.PP
-The \fBkeyname\fR routine returns a character string corresponding to the key \fIc\fR:
+The \fBkeyname\fR routine returns a character string
+corresponding to the key \fIc\fR:
.RS 3
.bP
-Printable characters are displayed as themselves, e.g., a one-character string containing the key.
+Printable characters are displayed as themselves,
+e.g., a one-character string containing the key.
.bP
Control characters are displayed in the \fB^\fR\fIX\fR notation.
.bP
the latter returns null where the former would display a meta character.
.PP
The \fBfilter\fR routine, if used, must be called before \fBinitscr\fR or
-\fBnewterm\fR are called. The effect is that, during those calls, \fBLINES\fR
+\fBnewterm\fR are called.
+The effect is that, during those calls, \fBLINES\fR
is set to 1; the capabilities \fBclear\fR, \fBcup\fR, \fBcud\fR, \fBcud1\fR,
\fBcuu1\fR, \fBcuu\fR, \fBvpa\fR are disabled; and the \fBhome\fR string is
set to the value of \fBcr\fR.
T}
.TE
.PP
-The \fBputwin\fR routine writes all data associated with window \fIwin\fR into
-the file to which \fIfilep\fR points. This information can be later retrieved
+The \fBputwin\fR routine writes all data associated
+with window (or pad) \fIwin\fR into
+the file to which \fIfilep\fR points.
+This information can be later retrieved
using the \fBgetwin\fR function.
.PP
The \fBgetwin\fR routine reads window related data stored in the file by
-\fBputwin\fR. The routine then creates and initializes a new window using that
-data. It returns a pointer to the new window.
+\fBputwin\fR.
+The routine then creates and initializes a new window using that
+data.
+It returns a pointer to the new window.
+There are a few caveats:
+.bP
+the data written is a copy of the \fBWINDOW\fP structure,
+and its associated character cells.
+The format differs between the wide-character (ncursesw) and
+non-wide (ncurses) libraries.
+.bP
+the retrieved window is always created as a top-level window (or pad),
+rather than a subwindow.
+.bP
+the window's character cells contain the color pair \fIvalue\fP,
+but not the actual color \fInumbers\fP.
+If cells in the retrieved window use color pairs which have not been
+created in the application using \fBinit_pair\fP,
+they will not be colored when the window is refreshed.
.PP
The \fBdelay_output\fR routine inserts an \fIms\fR millisecond pause
-in output. This routine should not be used extensively because
+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 \fBnapms\fR to perform the delay.
+If no padding character is specified,
+this uses \fBnapms\fR to perform the delay.
.PP
The \fBflushinp\fR routine throws away any typeahead that has been typed by the
user and has not yet been read by the program.
If \fBuse_legacy_coding\fP has been called with a \fB2\fP parameter,
\fBunctrl\fP 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.
+Otherwise, it returns \*(``~@\*('', \*(``~A\*('', etc.,
+analogous to \*(``^@\*('', \*(``^A\*('', C0 controls.
.IP
X/Open Curses does not document whether \fBunctrl\fP can be called before
initializing curses.
This implementation permits that,
-and returns the ``~@'', etc., values in that case.
+and returns the \*(``~@\*('', etc., values in that case.
.bP
parameter values outside the 0 to 255 range.
\fBunctrl\fP returns a null pointer.
.RE
.PP
The SVr4 documentation describes the action of \fBfilter\fR only in the vaguest
-terms. The description here is adapted from the XSI Curses standard (which
+terms.
+The description here is adapted from the XSI Curses standard (which
erroneously fails to describe the disabling of \fBcuu\fR).
.PP
The strings returned by \fBunctrl\fR in this implementation are determined
Likewise, the \fBmeta\fP function allows the caller to change the
output of \fBkeyname\fP, i.e.,
it determines whether to use the `M\-' prefix
-for ``meta'' keys (codes in the range 128 to 255).
+for \*(``meta\*('' keys (codes in the range 128 to 255).
Both \fBuse_legacy_coding\fP and \fBmeta\fP succeed only after
-curses is initialized.
+curses is initialized.
X/Open Curses does not document the treatment of codes 128 to 159.
-When treating them as ``meta'' keys
+When treating them as \*(``meta\*('' keys
(or if \fBkeyname\fP is called before initializing curses),
-this implementation returns strings ``M\-^@'', ``M\-^A'', etc.
+this implementation returns strings \*(``M\-^@\*('', \*(``M\-^A\*('', etc.
.PP
The \fBkeyname\fP function may return the names of user-defined
string capabilities which are defined in the terminfo entry via the \fB\-x\fP
option of \fB@TIC@\fP.
-This implementation automatically assigns at run-time keycodes to
+This implementation automatically 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 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 \fBuse_extended_names\fP function controls whether this data is
projects / ncurses.git / blobdiff