X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_util.3x;h=6781de7b3cfab0e781e920e1703978c0d7197982;hp=4c8929abfce752bed172900ab494d051912a007a;hb=cef50b3afcd58166f3541b701c97bce538844c76;hpb=2c829dd4faf4c7933e06804793e84079300e34e9 diff --git a/man/curs_util.3x b/man/curs_util.3x index 4c8929ab..6781de7b 100644 --- a/man/curs_util.3x +++ b/man/curs_util.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2006,2007 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2008,2010 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,8 +26,11 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_util.3x,v 1.25 2007/05/26 21:44:42 tom Exp $ +.\" $Id: curs_util.3x,v 1.31 2010/10/02 23:21:45 tom Exp $ .TH curs_util 3X "" +.de bP +.IP \(bu 4 +.. .na .hy 0 .SH NAME @@ -41,7 +44,7 @@ \fBputwin\fR, \fBunctrl\fR, \fBuse_env\fR, -\fBwunctrl\fR - miscellaneous \fBcurses\fR utility routines +\fBwunctrl\fR \- miscellaneous \fBcurses\fR utility routines .ad .hy .SH SYNOPSIS @@ -75,12 +78,33 @@ representation of the character \fIc\fR, ignoring attributes. Control characters are displayed in the \fB^\fR\fIX\fR notation. Printing characters are displayed as is. The corresponding \fBwunctrl\fR returns a printable representation of -a wide-character. +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. +.bP Control characters are displayed in the \fB^\fR\fIX\fR notation. -Values above 128 are either meta characters, shown in the \fBM-\fR\fIX\fR notation, -or the names of function keys, or null. +.bP +DEL (character 127) is displayed as \fB^?\fP. +.bP +Values above 128 are either meta characters +(if the screen has not been initialized, +or if \fBmeta\fP has been called with a TRUE parameter), +shown in the \fBM\-\fR\fIX\fR notation, +or are displayed as themselves. +In the latter case, the values may not be printable; +this follows the X/Open specification. +.bP +Values above 256 may be the names of the names of function keys. +.bP +Otherwise (if there is no corresponding name) the function returns null, +to denote an error. +X/Open also lists an "UNKNOWN KEY" return value, which some implementations +return rather than null. +.RE +.LP The corresponding \fBkey_name\fR returns a character string corresponding to the wide-character value \fIw\fR. The two functions do not return the same set of strings; @@ -134,11 +158,14 @@ Routines that return pointers return \fBNULL\fR on error. .PP X/Open does not define any error conditions. In this implementation -.RS +.RS 3 .TP 5 \fBflushinp\fR returns an error if the terminal was not initialized. .TP 5 +\fBmeta\fR +returns an error if the terminal was not initialized. +.TP 5 \fBputwin\fP returns an error if the associated \fBfwrite\fP calls return an error. .RE @@ -147,14 +174,12 @@ The XSI Curses standard, Issue 4 describes these functions. It states that \fBunctrl\fR and \fBwunctrl\fR will return a null pointer if unsuccessful, but does not define any error conditions. This implementation checks for three cases: -.RS -.TP 5 -- -the parameter is a 7-bit US-ASCII code. +.RS 3 +.bP +the parameter is a 7-bit US\-ASCII code. This is the case that X/Open Curses documented. -.TP 5 -- -the parameter is in the range 128-159, i.e., a C1 control code. +.bP +the parameter is in the range 128\-159, i.e., a C1 control code. 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. @@ -164,8 +189,7 @@ 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. -.TP 5 -- +.bP parameter values outside the 0 to 255 range. \fBunctrl\fP returns a null pointer. .RE @@ -189,23 +213,25 @@ change the output of \fBunctrl\fP. .PP 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 +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. 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), -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 +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. +The \fBuse_extended_names\fP function controls whether this data is +loaded when the terminal description is read by the library. .PP The \fBnofilter\fP routine is specific to ncurses. It was not supported on Version 7, BSD or System V implementations. @@ -217,6 +243,7 @@ be conditioned using NCURSES_VERSION. \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_scr_dump\fR(3X), +\fBcurs_variables\fR(3X), \fBlegacy_coding\fR(3X). .\"# .\"# The following sets edit modes for GNU EMACS