ncurses 6.1 - patch 20190209

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

diff --git a/man/curs_attr.3x b/man/curs_attr.3x
index 611df4b36a8c656d7564e78fa855c0a9d3f737d7..73ea47a84ad2e96d5fdc629b4168afeda29e5ff0 100644 (file)
--- a/man/curs_attr.3x
+++ b/man/curs_attr.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
 '\" t
 .\"***************************************************************************

-.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2017,2018 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            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *


@@ -27,12 +27,26 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_attr.3x,v 1.61 2017/11/18 23:47:37 tom Exp $
+.\" $Id: curs_attr.3x,v 1.64 2018/07/28 22:15:59 tom Exp $

 .TH curs_attr 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''
 .TH curs_attr 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''

+.de NS
+.ie n  .sp
+.el    .sp .5
+.ie n  .in +4
+.el    .in +2
+.nf
+.ft C                  \" Courier
+..
+.de NE
+.fi
+.ft R
+.ie n  .in -4
+.el    .in -2
+..

 .de bP
 .ie n  .IP \(bu 4
 .el    .IP \(bu 2
 .de bP
 .ie n  .IP \(bu 4
 .el    .IP \(bu 2


@@ -172,10 +186,43 @@ again values OR'd together in \fIattr\fP,
 without affecting other attributes.
 .\" ---------------------------------------------------------------------------
 .SS Legacy window attributes
 without affecting other attributes.
 .\" ---------------------------------------------------------------------------
 .SS Legacy window attributes

-Most of the window attribute routines are extensions of older routines
+The X/Open window attribute routines which \fIset\fP or \fIget\fP,
+turn \fIon\fP or \fIoff\fP
+are extensions of older routines

 which assume that color pairs are OR'd into the attribute parameter.
 which assume that color pairs are OR'd into the attribute parameter.

-These older routines use the same name, omitting an underscore (\fB_\fP).
-
+These newer routines use similar names, because
+X/Open simply added an underscore (\fB_\fP) for the newer names.
+.PP
+The \fBint\fP datatype used in the legacy routines is treated as if
+it is the same size as \fBchtype\fP (used by \fBaddch\fP(3X)).
+It holds the common video attributes (such as bold, reverse),
+as well as a few bits for color.
+Those bits correspond to the \fBA_COLOR\fP symbol.
+The \fBCOLOR_PAIR\fP macro provides a value which can be OR'd into
+the attribute parameter.
+For example,
+as long as that value fits into the \fBA_COLOR\fP mask,
+then these calls produce similar results:
+.NS
+attrset(A_BOLD | COLOR_PAIR(\fIpair\fP));
+attr_set(A_BOLD, \fIpair\fP, NULL);
+.NE
+.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,
+then \fBCOLOR_PAIR(\fP\fI259\fP\fB)\fP is 4
+(i.e., 259 is 4 more than the limit 255).
+.PP
+The \fBPAIR_NUMBER\fP macro extracts a pair number from an \fBint\fP
+(or \fBchtype\fP).
+For example, the \fIinput\fP and \fIoutput\fP values in these statements
+would be the same:
+.NS
+int value = A_BOLD | COLOR_PAIR(\fIinput\fP);
+int \fIoutput\fP = PAIR_NUMBER(value);
+.NE
+.PP

 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.
 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.


@@ -245,6 +292,7 @@ l l .
 \fBA_ALTCHARSET\fR     Alternate character set
 \fBA_ITALIC\fR Italics (non-X/Open extension)
 \fBA_CHARTEXT\fR       Bit-mask to extract a character
 \fBA_ALTCHARSET\fR     Alternate character set
 \fBA_ITALIC\fR Italics (non-X/Open extension)
 \fBA_CHARTEXT\fR       Bit-mask to extract a character

+\fBA_COLOR\fR  Bit-mask to extract a color (legacy routines)

 .TE
 .RE
 .PP
 .TE
 .RE
 .PP


@@ -281,7 +329,8 @@ 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.
 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.
+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 HISTORY
 You must use ncurses ABI 6 to support more than 256 color pairs.
 .\" ---------------------------------------------------------------------------
 .SH HISTORY


@@ -351,7 +400,7 @@ l l l l l l .
 1992   HPUX 9  32      no      8       SVr2 curses
 1992   AIX 3.2 32      no      23      SVr2 curses
 1994   OSF/1 r3        32      no      23      SVr2 curses
 1992   HPUX 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       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
 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


@@ -387,12 +436,13 @@ The initial release of Solaris was in 1992.
 The \fIxpg4\fP (X/Open) curses was developed by MKS from 1990 to 1995.
 Sun's copyright began in 1996.
 .bP
 The \fIxpg4\fP (X/Open) curses was developed by MKS from 1990 to 1995.
 Sun's copyright began in 1996.
 .bP

-Sun updated the X/Open curses interface after 64-bit support was introduced in 1997,
+Sun updated the X/Open curses interface
+after 64-bit support was introduced in 1997,

 but did not modify the SVr4 curses interface.
 .PP
 Regarding U/Win,
 .bP
 but did not modify the SVr4 curses interface.
 .PP
 Regarding U/Win,
 .bP

-Development of the curses library began in 1991, stopped in 2000. 
+Development of the curses library began in 1991, stopped in 2000.

 .bP
 Color support was added in 1998.
 .bP
 .bP
 Color support was added in 1998.
 .bP


@@ -401,7 +451,8 @@ The library uses only \fBchtype\fP (no \fBcchar_t\fP).
 .PP
 Once X/Open curses was adopted in the mid-1990s, the constraint of
 a 32-bit interface with many colors and wide-characters for \fBchtype\fP
 .PP
 Once X/Open curses was adopted in the mid-1990s, the constraint of
 a 32-bit interface with many colors and wide-characters for \fBchtype\fP

-became a moot point.  The \fBcchar_t\fP structure (whose size and
+became a moot point.
+The \fBcchar_t\fP structure (whose size and

 members are not specified in X/Open Curses) could be extended as needed.
 .PP
 Other interfaces are rarely used now:
 members are not specified in X/Open Curses) could be extended as needed.
 .PP
 Other interfaces are rarely used now: