ncurses 6.0 - patch 20171014
[ncurses.git] / man / curs_attr.3x
index 4d336083347498ebaa5b94a0a8b4d81ecc5c864f..c3113e151e9c72faf09b9775fe801a4736fa7e6c 100644 (file)
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_attr.3x,v 1.53 2017/03/28 23:31:39 tom Exp $
+.\" $Id: curs_attr.3x,v 1.60 2017/10/14 20:01:13 tom Exp $
 .TH curs_attr 3X ""
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
 .de bP
 .IP \(bu 4
 ..
 .na
 .hy 0
+.\" ---------------------------------------------------------------------------
 .SH NAME
 .\" attr_get
 \fBattr_get\fR,
@@ -67,6 +72,7 @@
 \fBwstandout\fR \- \fBcurses\fR character and window attribute control routines
 .ad
 .hy
+.\" ---------------------------------------------------------------------------
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
 .sp
 \fBint standout(void);\fR
 .br
 \fBint wstandout(WINDOW *\fP\fIwin\fP\fB);\fR
+.\" ---------------------------------------------------------------------------
 .SH DESCRIPTION
 .PP
 These routines manipulate the current attributes of the named window,
@@ -260,6 +267,7 @@ l l .
 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
 These functions may be macros:
 .sp
@@ -274,6 +282,137 @@ 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 HISTORY
+X/Open Curses is largely based on SVr4 curses,
+adding support for \*(``wide-characters\*('' (not specific to Unicode).
+Some of the X/Open differences from SVr4 curses address the way
+video attributes can be applied to wide-characters.
+But aside from that, \fBattrset\fP and \fBattr_set\fP are similar.
+SVr4 curses provided the basic features for manipulating video attributes.
+However, earlier versions of curses provided a part of these features.
+.PP
+As seen in 2.8BSD, curses assumed 7-bit characters,
+using the eighth bit of a byte to represent the \fIstandout\fP
+feature (often implemented as bold and/or reverse video).
+The BSD curses library provided functions \fBstandout\fP and \fBstandend\fP
+which were carried along into X/Open Curses due to their pervasive use
+in legacy applications.
+.PP
+Some terminals in the 1980s could support a variety of video attributes,
+although the BSD curses library could do nothing with those.
+System V (1983) provided an improved curses library.
+It defined the \fBA_\fP symbols for use by applications to manipulate the
+other attributes.
+There are few useful references for the chronology.
+.PP
+Goodheart's book
+\fIUNIX Curses Explained\fP (1991) describes SVr3 (1987),
+commenting on several functions:
+.bP
+the \fBattron\fP, \fBattroff\fP, \fBattrset\fP functions
+(and most of the functions found in SVr4 but not in BSD curses) were
+introduced by System V,
+.bP
+the alternate character set feature with \fBA_ALTCHARSET\fP was
+added in SVr2 and improved in SVr3 (by adding \fBacs_map[]\fP),
+.bP
+\fBstart_color\fP and related color-functions were introduced by System V.3.2,
+.bP
+pads, soft-keys were added in SVr3, and
+.PP
+Goodheart did not mention the background character or the \fBcchar_t\fP type.
+Those are respectively SVr4 and X/Open features.
+He did mention the \fBA_\fP constants, but did not indicate their values.
+Those were not the same in different systems,
+even for those marked as System V.
+.PP
+Different Unix systems used different sizes for the bit-fields in \fBchtype\fP
+for \fIcharacters\fP and \fIcolors\fP, and took into account the different
+integer sizes (32-bit versus 64-bit).
+.PP
+This table showing the number of bits for \fBA_COLOR\fP
+and \fBA_CHARTEXT\fP
+was gleaned from the curses header files for
+various operating systems and architectures.
+The inferred architecture and notes reflect
+the format and size of the defined constants
+as well as clues such as the alternate character set implementation.
+A 32-bit library can be used on a 64-bit system,
+but not necessarily the reverse.
+.RS
+.TS
+l l l l l l
+_ _ _ _ _ _
+l l l l l l .
+\fIYear\fR     \fISystem\fR    \fIArch\fP      \fIColor\fR     \fIChar\fR      \fINotes\fR
+1992   Solaris 5.2     32      6       17      SVr4 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       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
+.TE
+.RE
+.PP
+Notes:
+.RS 3
+.PP
+Regarding HP-UX,
+.bP
+HP-UX 10.20 (1996) added support for 64-bit PA-RISC processors in 1996.
+.bP
+HP-UX 10.30 (1997) marked \*(``curses_colr\*('' obsolete.
+That version of curses was dropped with HP-UX 11.30 in 2006.
+.PP
+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.
+.bP
+Unlike other systems which evolved from AT&T code,
+OSF/1 provided a new implementation for X/Open curses.
+.PP
+Regarding Solaris,
+.bP
+The initial release of Solaris was in 1992.
+.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,
+but did not modify the SVr4 curses interface.
+.PP
+Regarding U/Win,
+.bP
+Development of the curses library began in 1991, stopped in 2000. 
+.bP
+Color support was added in 1998.
+.bP
+The library uses only \fBchtype\fP (no \fBcchar_t\fP).
+.RE
+.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
+members are not specified in X/Open Curses) could be extended as needed.
+.PP
+Other interfaces are rarely used now:
+.bP
+BSD curses was improved slightly in 1993/1994 using Keith Bostic's
+modification to make the library 8-bit clean for \fBnvi\fP.
+He moved \fIstandout\fP attribute to a structure member.
+.IP
+The resulting 4.4BSD curses was replaced by ncurses over the next ten years.
+.bP
+U/Win is rarely used now.
+.\" ---------------------------------------------------------------------------
 .SH EXTENSIONS
 .PP
 This implementation provides the \fBA_ITALIC\fP attribute for terminals
@@ -307,6 +446,7 @@ 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
 These functions are supported in the XSI Curses standard, Issue 4.
 The standard defined the dedicated type for highlights,
@@ -355,9 +495,26 @@ l l .
 .TE
 .RE
 .PP
+XSI 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_\fR
 and \fBWA_\fR-using functions operates on the same current-highlight
 information.
+.bP
+However, in some implementations, those symbols have unrelated values.
+.IP
+For example, the Solaris \fIxpg4\fP (X/Open) curses declares
+\fBattr_t\fP to be an unsigned short integer (16-bits),
+while \fBchtype\fP is a unsigned integer (32-bits).
+The \fBWA_\fP symbols in this case are different from the \fBA_\fP symbols
+because they are used for a smaller datatype which does not
+represent \fBA_CHARTEXT\fP or \fBA_COLOR\fP.
+.IP
+In this implementation (as in many others), the values happen to be
+the same because it simplifies copying information between
+\fBchtype\fP and \fBcchar_t\fP variables.
 .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,
@@ -365,6 +522,7 @@ The XSI standard extended conformance level adds new highlights
 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
@@ -383,6 +541,7 @@ used for retrieving attribute or color-pair values is \fBNULL\fP.
 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
 .na
 \fBcurses\fR(3X),