ncurses 6.5 - patch 20240615

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

diff --git a/man/curs_attr.3x b/man/curs_attr.3x
index 3053c350be89ecbb84957a365aafea02e10fe4f6..d15995e2552b1ac8842038ab561e2d3bd91862c9 100644 (file)
--- a/man/curs_attr.3x
+++ b/man/curs_attr.3x
@@ -28,8 +28,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_attr.3x,v 1.96 2024/01/13 22:05:39 tom Exp $
-.TH curs_attr 3X 2024-01-13 "ncurses 6.4" "Library calls"
+.\" $Id: curs_attr.3x,v 1.108 2024/05/25 20:10:58 tom Exp $
+.TH curs_attr 3X 2024-05-25 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
@@ -232,7 +232,7 @@ The routine \fBstandend\fP is the same
 as \fBattrset(A_NORMAL)\fP or \fBattrset(0)\fP, that is, it turns off all
 attributes.
 .PP
-X/Open does not mark these \*(``restricted\*('', because
+X/Open Curses does not mark these \*(``restricted\*('', because
 .bP
 they have well established legacy use, and
 .bP
@@ -271,6 +271,16 @@ T}
 .TE
 .RE
 .PP
+You can thus use
+.B \%A_CHARTEXT
+to extract the character from a
+.IR chtype ","
+.B \%A_ATTRIBUTES
+to obtain its rendering attributes,
+and
+.B \%A_COLOR
+to find the color pair it uses.
+.PP
 These video attributes are supported by \fBattr_on\fP and related functions
 (which also support the attributes recognized by \fBattron\fP, etc.):
 .PP
@@ -296,21 +306,27 @@ The SVr4 manual page claims (falsely) that these routines always return \fB1\fP.
 .SH RETURN VALUE
 All routines return the integer \fBOK\fP on success, or \fBERR\fP on failure.
 .PP
-X/Open does not define any error conditions.
+X/Open Curses does not specify any error conditions.
 .PP
 This implementation
 .bP
-returns an error if the window pointer is null.
+returns
+.B ERR
+if the window pointer is null.
 .bP
-returns an error if the color pair parameter
+returns
+.B ERR
+if the color pair parameter
 for \fBwcolor_set\fP is outside the range 0..COLOR_PAIRS\-1.
 .bP
-does not return an error if either of the parameters of \fBwattr_get\fP
+does not fail if either of the parameters of \fBwattr_get\fP
 used for retrieving attribute or color pair values is \fBNULL\fP.
 .PP
-Functions with a \*(``mv\*('' prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
 .\" ---------------------------------------------------------------------------
 .SH NOTES
 These functions may be macros:
@@ -362,7 +378,7 @@ the \fIopts\fP parameter is ignored except
 except to check that it is \fBNULL\fP.
 .\" ---------------------------------------------------------------------------
 .SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+These functions are described in X/Open Curses, Issue 4.
 The standard defined the dedicated type for highlights,
 \fBattr_t\fP, which was not defined in SVr4 curses.
 The functions taking \fBattr_t\fP arguments were not supported under SVr4.
@@ -371,7 +387,7 @@ Very old versions of this library did not force an update of the screen
 when changing the attributes.
 Use \fBtouchwin\fP to force the screen to match the updated attributes.
 .PP
-The XSI Curses standard states that whether the traditional functions
+X/Open Curses states that whether the traditional functions
 \fBattron\fP/\fBattroff\fP/\fBattrset\fP can manipulate attributes other than
 \fBA_BLINK\fP, \fBA_BOLD\fP, \fBA_DIM\fP, \fBA_REVERSE\fP, \fBA_STANDOUT\fP, or
 \fBA_UNDERLINE\fP is \*(``unspecified\*(''.
@@ -379,7 +395,7 @@ Under this implementation as well as
 SVr4 curses, these functions correctly manipulate all other highlights
 (specifically, \fBA_ALTCHARSET\fP, \fBA_PROTECT\fP, and \fBA_INVIS\fP).
 .PP
-XSI Curses added these entry points:
+X/Open Curses added these entry points:
 .sp
 .RS
 \fBattr_get\fP, \fBattr_on\fP,
@@ -411,11 +427,11 @@ WA_ALTCHARSET     Alternate character set
 .TE
 .RE
 .PP
-XSI curses does not assign values to these symbols,
+X/Open Curses does not assign values to these symbols,
 nor does it state whether or not they are related to the
 similarly-named A_NORMAL, etc.:
 .bP
-The XSI curses standard specifies that each pair of corresponding \fBA_\fP
+X/Open Curses specifies that each pair of corresponding \fBA_\fP
 and \fBWA_\fP-using functions operates on the same current-highlight
 information.
 .bP
@@ -445,7 +461,7 @@ no change is made to the window's color.
 This is consistent with SVr4 curses;
 X/Open Curses does not specify this.
 .PP
-The XSI standard extended conformance level adds new highlights
+The X/Open Curses extended conformance level adds new highlights
 \fBA_HORIZONTAL\fP, \fBA_LEFT\fP, \fBA_LOW\fP, \fBA_RIGHT\fP, \fBA_TOP\fP,
 \fBA_VERTICAL\fP (and corresponding \fBWA_\fP macros for each).
 As of August 2013,
@@ -512,7 +528,7 @@ but not necessarily the reverse.
 .PP
 .TS
 Lb  Lb Lb  Cb  S   Lb
-Lb2 Lb Lb2 Lbz Lb2 Lb
+Lb2 Lb Lb2 Lb2 Lb2 Lb
 L   L  L   L   L   Lx.
 \&     \&      \&      Bits    \&
 Year   System  Arch    Color   Char    Notes