ncurses 5.6 - patch 20070128

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

diff --git a/man/curs_util.3x b/man/curs_util.3x
index 7b2617e6c21e6884d1eb54f26196d2039a6372a4..d74b988e3723b712208adacfaa80b05271603eb7 100644 (file)
--- a/man/curs_util.3x
+++ b/man/curs_util.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2004,2005 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2005,2006 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            *
@@ -26,7 +26,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_util.3x,v 1.17 2005/06/25 21:51:37 tom Exp $
+.\" $Id: curs_util.3x,v 1.22 2006/12/24 14:55:31 tom Exp $
 .TH curs_util 3X ""
 .na
 .hy 0
@@ -37,6 +37,7 @@
 \fBgetwin\fR,
 \fBkey_name\fR,
 \fBkeyname\fR,
+\fBnofilter\fR,
 \fBputwin\fR,
 \fBunctrl\fR,
 \fBuse_env\fR,
@@ -56,6 +57,8 @@
 .br
 \fBvoid filter(void);\fR
 .br
+\fBvoid nofilter(void);\fR
+.br
 \fBvoid use_env(bool f);\fR
 .br
 \fBint putwin(WINDOW *win, FILE *filep);\fR
@@ -89,6 +92,13 @@ 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.
 .PP
+The \fBnofilter\fP routine cancels the effect of a preceding \fBfilter\fP
+call.
+That allows the caller to initialize a screen on a different device,
+using a different value of \fB$TERM\fP.
+The limitation arises because the \fBfilter\fP routine modifies the
+in-memory copy of the terminal information.
+.PP
 The \fBuse_env\fR routine, if used, is called before \fBinitscr\fR or
 \fBnewterm\fR are called.  When called with \fBFALSE\fR as an
 argument, the values of \fBlines\fR and \fBcolumns\fR specified in the
@@ -142,17 +152,33 @@ 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
-at compile time, showing C1 controls from the upper-128 codes with a `~'
-prefix rather than `^'.
-Other implementations typically show both sets of control characters with `^',
-and may strip the parameter to 7 bits.
+at compile time,
+showing C1 controls from the upper-128 codes with a `~' prefix rather than `^'.
+Other implementations have different conventions.
+For example, they may show both sets of control characters with `^',
+and strip the parameter to 7 bits.
+Or they may ignore C1 controls and treat all of the upper-1280 codes as
+printable.
 This implementation uses 8 bits but does not modify the string to reflect
 locale.
+The \fBuse_legacy_coding\fP function allows the caller to
+change the output of \fBunctrl\fP.
 .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 \fBtic\fP.
+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 same value for different runs because user-defined codes are
+merged from all terminal descriptions which have been loaded.
+.PP
+The \fBnofilter\fP routine is specific to ncurses.
+It was not supported on Version 7, BSD or System V implementations.
+It is recommended that any code depending on ncurses extensions
+be conditioned using NCURSES_VERSION.
 .SH SEE ALSO
+\fBlegacy_coding\fR(3X),
 \fBcurses\fR(3X),
 \fBcurs_initscr\fR(3X),
 \fBcurs_kernel\fR(3X),