X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_attr.3x;h=8199977ab69058a4069685215d89c01458647754;hp=f1983b7a9ecf1a1b668120d1be6cb36c5a610d8f;hb=14d46fadc442db9df4567357cda396235418120e;hpb=58552e8c761a70f8f0bd591fecdf576fa8216e3e;ds=sidebyside diff --git a/man/curs_attr.3x b/man/curs_attr.3x index f1983b7a..8199977a 100644 --- a/man/curs_attr.3x +++ b/man/curs_attr.3x @@ -1,6 +1,7 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc. * +.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 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 * @@ -27,13 +28,33 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_attr.3x,v 1.49 2017/01/07 19:25:15 tom Exp $ +.\" $Id: curs_attr.3x,v 1.66 2020/02/02 23:34:34 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 -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. .na .hy 0 +.\" --------------------------------------------------------------------------- .SH NAME .\" attr_get \fBattr_get\fR, @@ -67,6 +88,7 @@ \fBwstandout\fR \- \fBcurses\fR character and window attribute control routines .ad .hy +.\" --------------------------------------------------------------------------- .SH SYNOPSIS \fB#include \fR .sp @@ -120,6 +142,7 @@ \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, @@ -138,16 +161,23 @@ 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 -The \fBattr_set\fP and \fBwattr_set\fP functions set the current attributes +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. -X/Open specified an additional parameter \fIopts\fP which is unused in -all implementations. .PP -Use \fBattr_get\fP and \fBwattr_get\fP to retrieve attributes for -the given window. +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, @@ -157,10 +187,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. @@ -187,14 +250,10 @@ the \fBmvwchgat\fR function does a cursor move before acting. 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)). -The \fBopts\fR argument is not -presently used, but is reserved for the future (leave it \fBNULL\fR). .\" --------------------------------------------------------------------------- .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. -The parameter \fIopts\fP is reserved for future use; -applications must supply a null pointer. .\" --------------------------------------------------------------------------- .SS Standout .PP @@ -204,7 +263,7 @@ 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 +X/Open does not mark these \*(``restricted\*('', because .bP they have well established legacy use, and .bP @@ -234,6 +293,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 @@ -257,32 +317,156 @@ 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 +.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. +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 PORTABILITY -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. +.\" --------------------------------------------------------------------------- +.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 -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 -SVr4 curses, these functions correctly manipulate all other highlights -(specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\fR). +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 which have the \fBenter_italics_mode\fP (\fBsitm\fP) @@ -293,10 +477,56 @@ to the \fBset_attributes\fP capabilities. This implementation makes the assumption that \fBexit_attribute_mode\fP may also reset italics. .PP -XSI Curses added the new entry points, \fBattr_get\fR, \fBattr_on\fR, +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 +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 +SVr4 curses, these functions correctly manipulate all other highlights +(specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\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 @@ -318,13 +548,26 @@ l l . .TE .RE .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 +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, @@ -332,6 +575,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 @@ -343,10 +587,14 @@ 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 +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),