'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2016,2017 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_attr.3x,v 1.22 2000/07/08 11:59:58 tom Exp $
+.\" $Id: curs_attr.3x,v 1.53 2017/03/28 23:31:39 tom Exp $
.TH curs_attr 3X ""
+.de bP
+.IP \(bu 4
+..
+.na
+.hy 0
.SH NAME
-\fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR,
-\fBattrset\fR, \fBwattrset\fR, \fBcolor_set\fR, \fBwcolor_set\fR,
-\fBstandend\fR, \fBwstandend\fR, \fBstandout\fR, \fBwstandout\fR,
-\fBattr_get\fR, \fBwattr_get\fR,
-\fBattr_off\fR, \fBwattr_off\fR,
-\fBattr_on\fR, \fBwattr_on\fR,
-\fBattr_set\fR, \fBwattr_set\fR,
-\fBchgat\fR, \fBwchgat\fR,
-\fBmvchgat\fR, \fBmvwchgat\fR,
-\fBPAIR_NUMBER\fR - \fBcurses\fR character and window attribute control routines
+.\" attr_get
+\fBattr_get\fR,
+\fBwattr_get\fR,
+\fBattr_set\fR,
+\fBwattr_set\fR,
+.\" .br
+\fBattr_off\fR,
+\fBwattr_off\fR,
+\fBattr_on\fR,
+\fBwattr_on\fR,
+.\" .br
+\fBattroff\fR,
+\fBwattroff\fR,
+\fBattron\fR,
+\fBwattron\fR,
+\fBattrset\fR,
+\fBwattrset\fR,
+.\" .br
+\fBchgat\fR,
+\fBwchgat\fR,
+\fBmvchgat\fR,
+\fBmvwchgat\fR,
+.\" .br
+\fBcolor_set\fR,
+\fBwcolor_set\fR,
+.\" .br
+\fBstandend\fR,
+\fBwstandend\fR,
+\fBstandout\fR,
+\fBwstandout\fR \- \fBcurses\fR character and window attribute control routines
+.ad
+.hy
.SH SYNOPSIS
\fB#include <curses.h>\fR
+.sp
+\fBint attr_get(attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
.br
-\fBint attroff(int attrs);\fR
-.br
-\fBint wattroff(WINDOW *win, int attrs);\fR
-.br
-\fBint attron(int attrs);\fR
-.br
-\fBint wattron(WINDOW *win, int attrs);\fR
-.br
-\fBint attrset(int attrs);\fR
+\fBint wattr_get(WINDOW *\fP\fIwin\fP\fB, attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB,\fR \fBvoid *\fP\fIopts\fP\fB);\fR
.br
-\fBint wattrset(WINDOW *win, int attrs);\fR
-.br
-\fBint color_set(short color_pair_number, void* opts);\fR
-.br
-\fBint wcolor_set(WINDOW *win, short color_pair_number,\fR
- \fBvoid* opts);\fR
-.br
-\fBint standend(void);\fR
+\fBint attr_set(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
.br
-\fBint wstandend(WINDOW *win);\fR
+\fBint wattr_set(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
+.sp
+\fBint attr_off(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
.br
-\fBint standout(void);\fR
+\fBint wattr_off(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
.br
-\fBint wstandout(WINDOW *win);\fR
+\fBint attr_on(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
.br
-\fBint attr_get(attr_t *attrs, short *pair, void *opts);\fR
+\fBint wattr_on(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
+.sp
+\fBint attroff(int \fP\fIattrs);\fR
.br
-\fBint wattr_get(WINDOW *win, attr_t *attrs, short *pair,\fR
- \fBvoid *opts);\fR
+\fBint wattroff(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
.br
-\fBint attr_off(attr_t attrs, void *opts);\fR
+\fBint attron(int \fP\fIattrs\fP\fB);\fR
.br
-\fBint wattr_off(WINDOW *win, attr_t attrs, void *opts);\fR
+\fBint wattron(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
.br
-\fBint attr_on(attr_t attrs, void *opts);\fR
+\fBint attrset(int \fP\fIattrs\fP\fB);\fR
.br
-\fBint wattr_on(WINDOW *win, attr_t attrs, void *opts);\fR
+\fBint wattrset(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
+.sp
+\fBint chgat(int \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB, short \fP\fIpair\fP\fB,\fR \fBconst void *\fP\fIopts\fP\fB);\fR
.br
-\fBint attr_set(attr_t attrs, short pair, void *opts);\fR
+\fBint wchgat(WINDOW *\fP\fIwin\fP\fB,\fP
+ \fBint \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fR \fBshort \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fR
.br
-\fBint wattr_set(WINDOW *win, attr_t attrs, short pair, void *opts);\fR
+\fBint mvchgat(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB,\fP
+ \fBint \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fR \fBshort \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fR
.br
-\fBint chgat(int n, attr_t attr, short color,\fR
- \fBconst void *opts)\fR
+\fBint mvwchgat(WINDOW *\fP\fIwin, int \fP\fIy, int \fP\fIx\fP\fB,\fP
+ \fBint \fP\fIn,\fR \fBattr_t \fP\fIattr\fP\fB, short \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fR
+.sp
+\fBint color_set(short \fP\fIpair\fP\fB, void* \fP\fIopts\fP\fB);\fR
.br
-\fBint wchgat(WINDOW *win, int n, attr_t attr,\fR
- \fBshort color, const void *opts)\fR
+\fBint wcolor_set(WINDOW *\fP\fIwin\fP\fB, short \fP\fIpair\fP\fB,\fR \fBvoid* \fP\fIopts);\fR
+.sp
+\fBint standend(void);\fR
.br
-\fBint mvchgat(int y, int x, int n, attr_t attr,\fR
- \fBshort color, const void *opts)\fR
+\fBint wstandend(WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBint mvwchgat(WINDOW *win, int y, int x, int n,\fR
- \fBattr_t attr, short color, const void *opts)\fR
+\fBint standout(void);\fR
.br
+\fBint wstandout(WINDOW *\fP\fIwin\fP\fB);\fR
.SH DESCRIPTION
-These routines manipulate the current attributes of the named window. The
-current attributes of a window apply to all characters that are written into
-the window with \fBwaddch\fR, \fBwaddstr\fR and \fBwprintw\fR. Attributes are
+.PP
+These routines manipulate the current attributes of the named window,
+which then apply to all characters that are written into
+the window with \fBwaddch\fR, \fBwaddstr\fR and \fBwprintw\fR.
+Attributes are
a property of the character, and move with the character through any scrolling
-and insert/delete line/character operations. To the extent possible, they are
+and insert/delete line/character operations.
+To the extent possible, they are
displayed as appropriate modifications to the graphic rendition of characters
put on the screen.
+.PP
+These routines do not affect the attributes used
+when erasing portions of the window.
+See \fBcurs_bkgd\fR(3X) for functions which modify the attributes used for
+erasing and clearing.
+.PP
+Routines which do not have a \fBWINDOW*\fP parameter apply to \fBstdscr\fP.
+For example,
+\fBattr_set\fP is the \fBstdscr\fP variant of \fBwattr_set\fP.
+.\" ---------------------------------------------------------------------------
+.SS Window attributes
+.PP
+There are two sets of functions:
+.bP
+functions for manipulating the window attributes and color:
+\fBwattr_set\fP and \fBwattr_get\fP.
+.bP
+functions for manipulating only the window attributes (not color):
+\fBwattr_on\fP and \fBwattr_off\fP.
+.PP
+The \fBwattr_set\fP function sets the current attributes
+of the given window to \fIattrs\fP, with color specified by \fIpair\fP.
+.PP
+Use \fBwattr_get\fP to retrieve attributes for the given window.
+.PP
+Use \fBattr_on\fP and \fBwattr_on\fP to turn on window attributes, i.e.,
+values OR'd together in \fIattr\fP,
+without affecting other attributes.
+Use \fBattr_off\fP and \fBwattr_off\fP to turn off window attributes,
+again values OR'd together in \fIattr\fP,
+without affecting other attributes.
+.\" ---------------------------------------------------------------------------
+.SS Legacy window attributes
+Most of the window attribute routines are extensions of older routines
+which assume that color pairs are OR'd into the attribute parameter.
+These older routines use the same name, omitting an underscore (\fB_\fP).
-The routine \fBattrset\fR sets the current attributes of the given window to
-\fIattrs\fR. The routine \fBattroff\fR turns off the named attributes without
-turning any other attributes on or off. The routine \fBattron\fR turns on the
-named attributes without affecting any others. The routine \fBstandout\fR is
-the same as \fBattron(A_STANDOUT)\fR. The routine \fBstandend\fR is the same
-as \fBattrset(A_NORMAL)\fR or \fBattrset(0)\fR, that is, it turns off all
-attributes.
-
-The routine \fBcolor_set\fR sets the current color of the given window to the
-foreground/background combination described by the color_pair_number. The
-parameter opts is reserved for future use, applications must supply a null
-pointer.
-
-The routine \fBwattr_get\fR returns the current attribute and color pair for
-the given window; \fBattr_get\fR returns the current attribute and color pair
-for \fBstdscr\fR.
-The remaining \fBattr_\fR* functions operate exactly like the corresponding
-\fBattr\fR* functions, except that they take arguments of type \fBattr_t\fR
-rather than \fBint\fR.
-
+The \fBattrset\fP routine is a legacy feature predating SVr4 curses
+but kept in X/Open Curses for the same reason that SVr4 curses kept it:
+compatibility.
+.PP
+The remaining \fBattr\fR* functions operate exactly like the corresponding
+\fBattr_\fR* functions, except that they take arguments of type \fBint\fR
+rather than \fBattr_t\fR.
+.PP
+There is no corresponding \fBattrget\fP function as such in X/Open Curses,
+although ncurses provides \fBgetattrs\fP (see curs_legacy(3X)).
+.\" ---------------------------------------------------------------------------
+.SS Change character rendition
+.PP
The routine \fBchgat\fR changes the attributes of a given number of characters
-starting at the current cursor location of \fBstdscr\fR. It does not update
-the cursor and does not perform wrapping. A character count of -1 or greater
+starting at the current cursor location of \fBstdscr\fR.
+It does not update
+the cursor and does not perform wrapping.
+A character count of \-1 or greater
than the remaining window width means to change attributes all the way to the
-end of the current line. The \fBwchgat\fR function generalizes this to any
-window; the \fBmvwchgat\fR function does a cursor move before acting. In these
-functions, the color argument is a color-pair index (as in the first argument
-of \fIinit_pair\fR, see \fBcurs_color\fR(3X)). The \fBopts\fR argument is not
-presently used, but is reserved for the future (leave it \fBNULL\fR).
-.SS Attributes
+end of the current line.
+The \fBwchgat\fR function generalizes this to any window;
+the \fBmvwchgat\fR function does a cursor move before acting.
+.PP
+In these functions,
+the color \fIpair\fP argument is a color-pair index
+(as in the first argument of \fBinit_pair\fR, see \fBcurs_color\fR(3X)).
+.\" ---------------------------------------------------------------------------
+.SS Change window color
+The routine \fBcolor_set\fR sets the current color of the given window to the
+foreground/background combination described by the color \fIpair\fP parameter.
+.\" ---------------------------------------------------------------------------
+.SS Standout
+.PP
+The routine \fBstandout\fR is
+the same as \fBattron(A_STANDOUT)\fR.
+The routine \fBstandend\fR is the same
+as \fBattrset(A_NORMAL)\fR or \fBattrset(0)\fR, that is, it turns off all
+attributes.
+.PP
+X/Open does not mark these "restricted", because
+.bP
+they have well established legacy use, and
+.bP
+there is no ambiguity about the way the attributes
+might be combined with a color pair.
+.\" ---------------------------------------------------------------------------
+.SH VIDEO ATTRIBUTES
The following video attributes, defined in \fB<curses.h>\fR, can be passed to
-the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'ed with the
-characters passed to \fBaddch\fR.
-
+the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'd with the
+characters passed to \fBaddch\fR (see \fBcurs_addch\fR(3X)).
+.PP
+.RS
.TS
-center ;
+l l
+_ _ _
l l .
+\fIName\fR \fIDescription\fR
\fBA_NORMAL\fR Normal display (no highlight)
\fBA_STANDOUT\fR Best highlighting mode of the terminal.
\fBA_UNDERLINE\fR Underlining
\fBA_PROTECT\fR Protected mode
\fBA_INVIS\fR Invisible or blank mode
\fBA_ALTCHARSET\fR Alternate character set
+\fBA_ITALIC\fR Italics (non-X/Open extension)
\fBA_CHARTEXT\fR Bit-mask to extract a character
-\fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR Color-pair number \fIn\fR
.TE
-
-The following macro is the reverse of \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR:
-
-.DS C
-\fBPAIR_NUMBER(\fR\fIattrs\fR) Returns the pair number associated
- with the \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR attribute.
-.DE
-
+.RE
+.PP
+These video attributes are supported by \fBattr_on\fP and related functions
+(which also support the attributes recognized by \fBattron\fP, etc.):
+.RS
+.TS
+l l
+_ _ _
+l l .
+\fIName\fR \fIDescription\fR
+\fBWA_HORIZONTAL\fR Horizontal highlight
+\fBWA_LEFT\fR Left highlight
+\fBWA_LOW\fR Low highlight
+\fBWA_RIGHT\fR Right highlight
+\fBWA_TOP\fR Top highlight
+\fBWA_VERTICAL\fR Vertical highlight
+.TE
+.RE
+.PP
The return values of many of these routines are not meaningful (they are
implemented as macro-expanded assignments and simply return their argument).
The SVr4 manual page claims (falsely) that these routines always return \fB1\fR.
-
.SH NOTES
-Note that \fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR,
-\fBattrset\fR, \fBwattrset\fR, \fBstandend\fR and \fBstandout\fR may be macros.
+These functions may be macros:
+.sp
+.RS
+\fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR,
+\fBattrset\fR, \fBwattrset\fR, \fBstandend\fR and \fBstandout\fR.
+.RE
+.PP
+Color pair values can only be OR'd with attributes if the pair
+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 within the alternate functions.
+You must use ncurses ABI 6 to support more than 256 color pairs.
+.SH EXTENSIONS
+.PP
+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,
+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
+retrieving it via the standard pointer to \fBshort\fP parameter.
+.PP
+The remaining functions which have \fIopts\fP,
+but do not manipulate color,
+e.g., \fBwattr_on\fP and \fBwattr_off\fP
+are not used by this implementation except to check that they are \fBNULL\fP.
.SH PORTABILITY
-All these functions are supported in the XSI Curses standard, Issue 4. The
-standard defined the dedicated type for highlights, \fBattr_t\fR, which is not
-defined in SVr4 curses. The functions taking \fBattr_t\fR arguments are
-not supported under SVr4.
-
+These functions are supported in the XSI Curses standard, Issue 4.
+The standard defined the dedicated type for highlights,
+\fBattr_t\fR, which was not defined in SVr4 curses.
+The functions taking \fBattr_t\fR 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\fR to force the screen to match the updated attributes.
+.PP
The XSI Curses standard states that whether the traditional functions
\fBattron\fR/\fBattroff\fR/\fBattrset\fR can manipulate attributes other than
\fBA_BLINK\fR, \fBA_BOLD\fR, \fBA_DIM\fR, \fBA_REVERSE\fR, \fBA_STANDOUT\fR, or
-\fBA_UNDERLINE\fR is "unspecified". Under this implementation as well as
+\fBA_UNDERLINE\fR is "unspecified".
+Under this implementation as well as
SVr4 curses, these functions correctly manipulate all other highlights
(specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\fR).
-
-XSI Curses added the new entry points, \fBattr_get\fR, \fBattr_on\fR,
+.PP
+XSI Curses added these entry points:
+.sp
+.RS
+\fBattr_get\fR, \fBattr_on\fR,
\fBattr_off\fR, \fBattr_set\fR, \fBwattr_on\fR, \fBwattr_off\fR,
-\fBwattr_get\fR, \fBwattr_set\fR. These are intended to work with
+\fBwattr_get\fR, \fBwattr_set\fR
+.RE
+.PP
+The new functions are intended to work with
a new series of highlight macros prefixed with \fBWA_\fR.
-
+The older macros have direct counterparts in the newer set of names:
+.PP
+.RS
+.ne 9
.TS
-center ;
+l l
+_ _ _
l l .
+\fIName\fR \fIDescription\fR
\fBWA_NORMAL\fR Normal display (no highlight)
\fBWA_STANDOUT\fR Best highlighting mode of the terminal.
\fBWA_UNDERLINE\fR Underlining
\fBWA_BOLD\fR Extra bright or bold
\fBWA_ALTCHARSET\fR Alternate character set
.TE
-
+.RE
+.PP
The XSI curses standard specifies that each pair of corresponding \fBA_\fR
and \fBWA_\fR-using functions operates on the same current-highlight
information.
-
+.PP
The XSI standard extended conformance level adds new highlights
\fBA_HORIZONTAL\fR, \fBA_LEFT\fR, \fBA_LOW\fR, \fBA_RIGHT\fR, \fBA_TOP\fR,
-\fBA_VERTICAL\fR (and corresponding \fBWA_\fR macros for each) which this
-curses does not yet support.
+\fBA_VERTICAL\fR (and corresponding \fBWA_\fR 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\fR 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
-\fBcurses\fR(3X), \fBcurs_addch\fR(3X), \fBcurs_addstr\fR(3X),
-\fBcurs_printw\fR(3X)
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+.na
+\fBcurses\fR(3X),
+\fBcurs_addch\fR(3X),
+\fBcurs_addstr\fR(3X),
+\fBcurs_bkgd\fR(3X),
+\fBcurs_printw\fR(3X),
+\fBcurs_variables\fR(3X)
projects / ncurses.git / blobdiff