ncurses 6.0 - patch 20170826
[ncurses.git] / man / curs_attr.3x
index d6ad62471acf13b59a21f4cb7b89d0fe81e0ecb7..4d336083347498ebaa5b94a0a8b4d81ecc5c864f 100644 (file)
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998 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.19 1998/12/26 19:25:35 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 - \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, 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, 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
@@ -147,45 +235,115 @@ l l .
 \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
@@ -195,21 +353,41 @@ l l .
 \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)