X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_attr.3x;h=73ea47a84ad2e96d5fdc629b4168afeda29e5ff0;hp=611df4b36a8c656d7564e78fa855c0a9d3f737d7;hb=b60a2772d9f149d8e900c1d5a09a53a56a0837a8;hpb=06078d3fa68db669ed37178c01873546b4b28745 diff --git a/man/curs_attr.3x b/man/curs_attr.3x index 611df4b3..73ea47a8 100644 --- a/man/curs_attr.3x +++ b/man/curs_attr.3x @@ -1,6 +1,6 @@ '\" 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 * @@ -27,12 +27,26 @@ .\" 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 '' '' +.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 @@ -172,10 +186,43 @@ 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 +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. -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. @@ -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_COLOR\fR Bit-mask to extract a color (legacy routines) .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. -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 @@ -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 -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 @@ -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 -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 -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 @@ -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 -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: