'\" t
.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_attr.3x,v 1.91 2023/12/02 21:05:24 tom Exp $
-.TH curs_attr 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_attr.3x,v 1.105 2024/04/27 17:54:42 tom Exp $
+.TH curs_attr 3X 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
See \fBcurs_bkgd\fP(3X) for functions which modify the attributes used for
erasing and clearing.
.\" ---------------------------------------------------------------------------
-.SS Window attributes
+.SS "Window Attributes"
There are two sets of functions:
.bP
functions for manipulating the window attributes and color:
again values OR'd together in \fIattr\fP,
without affecting other attributes.
.\" ---------------------------------------------------------------------------
-.SS Legacy window attributes
+.SS "Legacy Window Attributes"
The X/Open window attribute routines which \fIset\fP or \fIget\fP,
turn \fIon\fP or \fIoff\fP
are extensions of older routines
.PP
However, if the value does not fit, then the \fBCOLOR_PAIR\fP macro
uses only the bits that fit.
-For example, because in ncurses \fBA_COLOR\fP has eight (8) bits,
+For example,
+because in \fI\%ncurses\fP \fBA_COLOR\fP has eight (8) bits,
then \fBCOLOR_PAIR(\fI259\fB)\fR is 4
(i.e., 259 is 4 more than the limit 255).
.PP
\fBattr_\fP* functions, except that they take arguments of type \fBint\fP
rather than \fBattr_t\fP.
.PP
-There is no corresponding \fBattrget\fP function as such in X/Open Curses,
-although ncurses provides \fBgetattrs\fP (see curs_legacy(3X)).
+There is no corresponding \fB\%attrget\fP function as such
+in X/Open Curses,
+although \fI\%ncurses\fP provides \fB\%getattrs\fP
+(see \fB\%curs_legacy\fP(3X)).
.\" ---------------------------------------------------------------------------
-.SS Change character rendition
+.SS "Change Character Rendition"
The routine \fBchgat\fP changes the attributes of a given number of characters
starting at the current cursor location of \fBstdscr\fP.
It does not update
the \fBmvwchgat\fP function does a cursor move before acting.
.PP
In these functions,
-the color \fIpair\fP argument is a color-pair index
+the color \fIpair\fP argument is a color pair index
(as in the first argument of \fBinit_pair\fP, see \fBcurs_color\fP(3X)).
.\" ---------------------------------------------------------------------------
-.SS Change window color
+.SS "Change Window Color"
The routine \fBcolor_set\fP sets the current color of the given window to the
foreground/background combination described by the color \fIpair\fP parameter.
.\" ---------------------------------------------------------------------------
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
.ne 15
.RS
.TS
-l l
-_ _ _
-l l .
-\fBName\fP \fBDescription\fP
-\fBA_NORMAL\fP Normal display (no highlight)
-\fBA_STANDOUT\fP Best highlighting mode of the terminal.
-\fBA_UNDERLINE\fP Underlining
-\fBA_REVERSE\fP Reverse video
-\fBA_BLINK\fP Blinking
-\fBA_DIM\fP Half bright
-\fBA_BOLD\fP Extra bright or bold
-\fBA_PROTECT\fP Protected mode
-\fBA_INVIS\fP Invisible or blank mode
-\fBA_ALTCHARSET\fP Alternate character set
-\fBA_ITALIC\fP Italics (non-X/Open extension)
-\fBA_CHARTEXT\fP Bit-mask to extract a character
-\fBA_COLOR\fP Bit-mask to extract a color (legacy routines)
+Lb Lb
+Lb Lx.
+Name Description
+_
+A_NORMAL Normal display (no highlight)
+A_STANDOUT T{
+Best highlighting mode of the terminal
+T}
+A_UNDERLINE Underlining
+A_REVERSE Reverse video
+A_BLINK Blinking
+A_DIM Half bright
+A_BOLD Extra bright or bold
+A_PROTECT Protected mode
+A_INVIS Invisible or blank mode
+A_ALTCHARSET Alternate character set
+A_ITALIC Italics (non-X/Open extension)
+A_CHARTEXT Bit-mask to extract a character
+A_COLOR T{
+Bit-mask to extract a color (legacy routines)
+T}
.TE
.RE
.PP
.PP
.RS
.TS
-l l
-_ _ _
-l l .
-\fBName\fP \fBDescription\fP
-\fBWA_HORIZONTAL\fP Horizontal highlight
-\fBWA_LEFT\fP Left highlight
-\fBWA_LOW\fP Low highlight
-\fBWA_RIGHT\fP Right highlight
-\fBWA_TOP\fP Top highlight
-\fBWA_VERTICAL\fP Vertical highlight
+Lb Lb
+Lb Lx.
+Name Description
+_
+WA_HORIZONTAL Horizontal highlight
+WA_LEFT Left highlight
+WA_LOW Low highlight
+WA_RIGHT Right highlight
+WA_TOP Top highlight
+WA_VERTICAL Vertical highlight
.TE
.RE
.PP
.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
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.
+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:
number is less than 256.
The alternate functions such as \fBcolor_set\fP can pass a color pair
value directly.
-However, ncurses ABI 4 and 5 simply OR this value
+However, \fI\%ncurses\fP ABI 4 and 5 simply OR this value
within the alternate functions.
-You must use ncurses ABI 6 to support more than 256 color pairs.
+You must use \fI\%ncurses\fP ABI 6 to support more than 256 color pairs.
.\" ---------------------------------------------------------------------------
.SH EXTENSIONS
This implementation provides the \fBA_ITALIC\fP attribute for terminals
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:
+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,
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.
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\*(''.
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,
.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
+Lb Lb
+Lb Lx.
+Name Description
+_
+WA_NORMAL Normal display (no highlight)
+WA_STANDOUT T{
+Best highlighting mode of the terminal
+T}
+WA_UNDERLINE Underlining
+WA_REVERSE Reverse video
+WA_BLINK Blinking
+WA_DIM Half bright
+WA_BOLD Extra bright or bold
+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
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
+Because \fI\%ncurses\fP's \fBattr_t\fP can hold a color pair
(in the \fBA_COLOR\fP field),
a call to
\fBwattr_on\fP,
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,
A 32-bit library can be used on a 64-bit system,
but not necessarily the reverse.
.PP
-.RS
.TS
-l l l l l l
-_ _ _ _ _ _
-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 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\*(''
-1995 HP-UX 10.00 32 6 8 SVr4, X/Open curses
-1995 Solaris 5.4 32/64 7 16 X/Open curses
-1996 AIX 4.2 32 7 16 X/Open curses
-1996 OSF/1 r4 32 6 16 X/Open curses
-1997 HP-UX 11.00 32 6 8 X/Open curses
-2000 U/Win 32/64 7/31 16 uses \fBchtype\fP
+Lb Lb Lb Cb S Lb
+Lb2 Lb Lb2 Lb2 Lb2 Lb
+L L L L L Lx.
+\& \& \& Bits \&
+Year System Arch Color Char Notes
+_
+1992 Solaris 5.2 32 6 17 SVr4 \fIcurses\fP
+1992 HP-UX 9 32 no 8 SVr2 \fIcurses\fP
+1992 AIX 3.2 32 no 23 SVr2 \fIcurses\fP
+1994 OSF/1 r3 32 no 23 SVr2 \fIcurses\fP
+1995 HP-UX 10.00 32 6 16 SVr3 \fIcurses_colr\fP
+1995 HP-UX 10.00 32 6 8 SVr4, X/Open \fIcurses\fP
+1995 Solaris 5.4 32/64 7 16 X/Open \fIcurses\fP
+1996 AIX 4.2 32 7 16 X/Open \fIcurses\fP
+1996 OSF/1 r4 32 6 16 X/Open \fIcurses\fP
+1997 HP-UX 11.00 32 6 8 X/Open \fIcurses\fP
+2000 U/Win 32/64 7/31 16 uses \fIchtype\fP
.TE
-.RE
.PP
Notes:
.RS 3
Regarding OSF/1 (and Tru64),
.bP
These used 64-bit hardware.
-Like ncurses, the OSF/1 curses interface is not customized for 32-bit
-and 64-bit versions.
+Like \fI\%ncurses\fP,
+the OSF/1 curses interface is not customized for 32-bit and 64-bit
+versions.
.bP
Unlike other systems which evolved from AT&T code,
OSF/1 provided a new implementation for X/Open curses.
modification to make the library 8-bit clean for \fBnvi\fP(1).
He moved \fIstandout\fP attribute to a structure member.
.IP
-The resulting 4.4BSD curses was replaced by ncurses over the next ten years.
+The resulting 4.4BSD curses was replaced by \fI\%ncurses\fP over the
+next ten years.
.bP
U/Win is rarely used now.
.\" ---------------------------------------------------------------------------
projects / ncurses.git / blobdiff