.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_attr.3x,v 1.87 2023/10/07 22:21:46 tom Exp $
-.TH curs_attr 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_attr.3x,v 1.89 2023/11/25 15:33:56 tom Exp $
+.TH curs_attr 3X 2023-11-25 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint wchgat(WINDOW *\fIwin\fP,
\fBint \fIn\fB, attr_t \fIattr\fB,\fR \fBshort \fIpair\fB, const void *\fIopts\fB);\fR
\fBint mvchgat(int \fIy\fB, int \fIx\fB,\fR
- \fBint \fIn\fB, attr_t \fIattr\fB,\fR \fBshort \fIpair\fB, const void *\fIopts\fB);\fR
-\fBint mvwchgat(WINDOW *\fIwin, int \fIy, int \fIx\fB,\fR
- \fBint \fIn,\fR \fBattr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR
+ \fBint \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR
+\fBint mvwchgat(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB,\fR
+ \fBint \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR
.PP
\fBint color_set(short \fIpair\fB, void* \fIopts\fB);\fR
\fBint wcolor_set(WINDOW *\fIwin\fB, short \fIpair\fB,\fR \fBvoid* \fIopts\fP);\fR
there is no ambiguity about the way the attributes
might be combined with a color pair.
.\" ---------------------------------------------------------------------------
-.SH VIDEO ATTRIBUTES
+.SS "Video Attributes"
The following video attributes, defined in \fB<curses.h>\fP, can be passed to
the routines \fBattron\fP, \fBattroff\fP, and \fBattrset\fP, or OR'd with the
characters passed to \fBaddch\fP (see \fBcurs_addch\fP(3X)).
implemented as macro-expanded assignments and simply return their argument).
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.
+.PP
+This implementation
+.bP
+returns an error if the window pointer is null.
+.bP
+returns an error 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
+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.
+.\" ---------------------------------------------------------------------------
.SH NOTES
These functions may be macros:
.sp
within the alternate functions.
You must use ncurses ABI 6 to support more than 256 color pairs.
.\" ---------------------------------------------------------------------------
+.SH EXTENSIONS
+This implementation provides the \fBA_ITALIC\fP attribute for terminals
+which have the \fBenter_italics_mode\fP (\fBsitm\fP)
+and \fBexit_italics_mode\fP (\fBritm\fP) capabilities.
+Italics are not mentioned in X/Open Curses.
+Unlike the other video attributes, \fBA_ITALIC\fP is unrelated
+to the \fBset_attributes\fP capabilities.
+This implementation makes the assumption that
+\fBexit_attribute_mode\fP may also reset italics.
+.PP
+Each of the functions added by XSI Curses has a parameter \fIopts\fP,
+which X/Open Curses still (after more than twenty years) documents
+as reserved for future use, saying that it should be \fBNULL\fP.
+This implementation uses that parameter in ABI 6 for the functions which
+have a color-pair parameter to support \fIextended color pairs\fP:
+.bP
+For functions which modify the color, e.g.,
+\fBwattr_set\fP and \fBwattr_on\fP,
+if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
+and used to set the color pair instead of the \fBshort\fP \fIpair\fP parameter.
+.bP
+For functions which retrieve the color, e.g.,
+\fBwattr_get\fP,
+if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
+and used to retrieve the color pair as an \fBint\fP value,
+in addition to
+retrieving it via the standard pointer to \fBshort\fP parameter.
+.bP
+For functions which turn attributes off, e.g.,
+\fBwattr_off\fP,
+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.
+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.
+.PP
+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
+\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\*(''.
+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:
+.sp
+.RS
+\fBattr_get\fP, \fBattr_on\fP,
+\fBattr_off\fP, \fBattr_set\fP, \fBwattr_on\fP, \fBwattr_off\fP,
+\fBwattr_get\fP, \fBwattr_set\fP
+.RE
+.PP
+The new functions are intended to work with
+a new series of highlight macros prefixed with \fBWA_\fP.
+The older macros have direct counterparts in the newer set of names:
+.PP
+.RS
+.ne 9
+.TS
+l l
+_ _ _
+l l .
+\fBName\fP \fBDescription\fP
+\fBWA_NORMAL\fP Normal display (no highlight)
+\fBWA_STANDOUT\fP Best highlighting mode of the terminal.
+\fBWA_UNDERLINE\fP Underlining
+\fBWA_REVERSE\fP Reverse video
+\fBWA_BLINK\fP Blinking
+\fBWA_DIM\fP Half bright
+\fBWA_BOLD\fP Extra bright or bold
+\fBWA_ALTCHARSET\fP Alternate character set
+.TE
+.RE
+.PP
+XSI 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
+and \fBWA_\fP-using functions operates on the same current-highlight
+information.
+.bP
+However, in some implementations, those symbols have unrelated values.
+.IP
+For example, the Solaris \fIxpg4\fP (X/Open) curses declares
+\fBattr_t\fP to be an unsigned short integer (16-bits),
+while \fBchtype\fP is a unsigned integer (32-bits).
+The \fBWA_\fP symbols in this case are different from the \fBA_\fP symbols
+because they are used for a smaller datatype which does not
+represent \fBA_CHARTEXT\fP or \fBA_COLOR\fP.
+.IP
+In this implementation (as in many others), the values happen to be
+the same because it simplifies copying information between
+\fBchtype\fP and \fBcchar_t\fP variables.
+.bP
+Because ncurses's \fBattr_t\fP can hold a color pair
+(in the \fBA_COLOR\fP field),
+a call to
+\fBwattr_on\fP,
+\fBwattr_off\fP, or
+\fBwattr_set\fP
+may alter the window's color.
+If the color pair information in the attribute parameter is zero,
+no change is made to the window's color.
+.IP
+This is consistent with SVr4 curses;
+X/Open Curses does not specify this.
+.PP
+The XSI standard 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,
+no known terminal provides these highlights
+(i.e., via the \fBsgr1\fP capability).
+.\" ---------------------------------------------------------------------------
.SH HISTORY
X/Open Curses is largely based on SVr4 curses,
adding support for \*(``wide-characters\*('' (not specific to Unicode).
l l l l l l .
\fBYear\fP \fBSystem\fP \fBArch\fP \fBColor\fP \fBChar\fP \fBNotes\fP
1992 Solaris 5.2 32 6 17 SVr4 curses
-1992 HPUX 9 32 no 8 SVr2 curses
+1992 HP-UX 9 32 no 8 SVr2 curses
1992 AIX 3.2 32 no 23 SVr2 curses
1994 OSF/1 r3 32 no 23 SVr2 curses
1995 HP-UX 10.00 32 6 16 SVr3 \*(``curses_colr\*(''
.bP
U/Win is rarely used now.
.\" ---------------------------------------------------------------------------
-.SH EXTENSIONS
-This implementation provides the \fBA_ITALIC\fP attribute for terminals
-which have the \fBenter_italics_mode\fP (\fBsitm\fP)
-and \fBexit_italics_mode\fP (\fBritm\fP) capabilities.
-Italics are not mentioned in X/Open Curses.
-Unlike the other video attributes, \fBA_ITALIC\fP is unrelated
-to the \fBset_attributes\fP capabilities.
-This implementation makes the assumption that
-\fBexit_attribute_mode\fP may also reset italics.
-.PP
-Each of the functions added by XSI Curses has a parameter \fIopts\fP,
-which X/Open Curses still (after more than twenty years) documents
-as reserved for future use, saying that it should be \fBNULL\fP.
-This implementation uses that parameter in ABI 6 for the functions which
-have a color-pair parameter to support \fIextended color pairs\fP:
-.bP
-For functions which modify the color, e.g.,
-\fBwattr_set\fP and \fBwattr_on\fP,
-if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
-and used to set the color pair instead of the \fBshort\fP \fIpair\fP parameter.
-.bP
-For functions which retrieve the color, e.g.,
-\fBwattr_get\fP,
-if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
-and used to retrieve the color pair as an \fBint\fP value,
-in addition to
-retrieving it via the standard pointer to \fBshort\fP parameter.
-.bP
-For functions which turn attributes off, e.g.,
-\fBwattr_off\fP,
-the \fIopts\fP parameter is ignored except
-except to check that it is \fBNULL\fP.
-.\" ---------------------------------------------------------------------------
-.SH PORTABILITY
-These functions are supported in the XSI Curses standard, 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.
-.PP
-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
-\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\*(''.
-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:
-.sp
-.RS
-\fBattr_get\fP, \fBattr_on\fP,
-\fBattr_off\fP, \fBattr_set\fP, \fBwattr_on\fP, \fBwattr_off\fP,
-\fBwattr_get\fP, \fBwattr_set\fP
-.RE
-.PP
-The new functions are intended to work with
-a new series of highlight macros prefixed with \fBWA_\fP.
-The older macros have direct counterparts in the newer set of names:
-.PP
-.RS
-.ne 9
-.TS
-l l
-_ _ _
-l l .
-\fBName\fP \fBDescription\fP
-\fBWA_NORMAL\fP Normal display (no highlight)
-\fBWA_STANDOUT\fP Best highlighting mode of the terminal.
-\fBWA_UNDERLINE\fP Underlining
-\fBWA_REVERSE\fP Reverse video
-\fBWA_BLINK\fP Blinking
-\fBWA_DIM\fP Half bright
-\fBWA_BOLD\fP Extra bright or bold
-\fBWA_ALTCHARSET\fP Alternate character set
-.TE
-.RE
-.PP
-XSI 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
-and \fBWA_\fP-using functions operates on the same current-highlight
-information.
-.bP
-However, in some implementations, those symbols have unrelated values.
-.IP
-For example, the Solaris \fIxpg4\fP (X/Open) curses declares
-\fBattr_t\fP to be an unsigned short integer (16-bits),
-while \fBchtype\fP is a unsigned integer (32-bits).
-The \fBWA_\fP symbols in this case are different from the \fBA_\fP symbols
-because they are used for a smaller datatype which does not
-represent \fBA_CHARTEXT\fP or \fBA_COLOR\fP.
-.IP
-In this implementation (as in many others), the values happen to be
-the same because it simplifies copying information between
-\fBchtype\fP and \fBcchar_t\fP variables.
-.bP
-Because ncurses's \fBattr_t\fP can hold a color pair
-(in the \fBA_COLOR\fP field),
-a call to
-\fBwattr_on\fP,
-\fBwattr_off\fP, or
-\fBwattr_set\fP
-may alter the window's color.
-If the color pair information in the attribute parameter is zero,
-no change is made to the window's color.
-.IP
-This is consistent with SVr4 curses;
-X/Open Curses does not specify this.
-.PP
-The XSI standard 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,
-no known terminal provides these highlights
-(i.e., via the \fBsgr1\fP capability).
-.\" ---------------------------------------------------------------------------
-.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.
-.PP
-This implementation
-.bP
-returns an error if the window pointer is null.
-.bP
-returns an error 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
-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.
-.\" ---------------------------------------------------------------------------
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_addch\fP(3X),
projects / ncurses.git / blobdiff