ncurses 5.9 - patch 20150307

[ncurses.git] / man / curs_util.3x

diff --git a/man/curs_util.3x b/man/curs_util.3x
index 444f40e2cffb13cb1092e14b73550ab7749a3de8..a0c05fe427e2da0895c7c0b3ffedf294c0a04acb 100644 (file)
--- a/man/curs_util.3x
+++ b/man/curs_util.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2012,2013 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            *
@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_util.3x,v 1.37 2013/07/20 19:43:45 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 `` ``
@@ -121,7 +121,8 @@ The two functions do not return the same set of strings;
 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.
@@ -198,16 +199,36 @@ ncurses relies on the terminal database to determine size.
 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.
@@ -261,7 +282,8 @@ parameter values outside the 0 to 255 range.
 .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
@@ -282,7 +304,7 @@ output of \fBkeyname\fP, i.e.,
 it determines whether to use the `M\-' prefix
 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
 (or if \fBkeyname\fP is called before initializing curses),
@@ -291,9 +313,9 @@ this implementation returns strings \*(``M\-^@\*('', \*(``M\-^A\*('', etc.
 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