ncurses 6.1 - patch 20180728
[ncurses.git] / doc / html / man / curs_attr.3x.html
index f359177eafb2575cacbd3ed6209644b171b1b851..fc5eee050a123ef2852fd8363885ca3ca9b0bc33 100644 (file)
@@ -1,7 +1,7 @@
 <!-- 
   * 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,7 +27,8 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_attr.3x,v 1.53 2017/03/28 23:31:39 tom Exp @
+  * @Id: curs_attr.3x,v 1.64 2018/07/28 22:15:59 tom Exp @
+  * ---------------------------------------------------------------------------
   * attr_get
   * .br
   * .br
   * ---------------------------------------------------------------------------
   * ---------------------------------------------------------------------------
   * ---------------------------------------------------------------------------
+  * ---------------------------------------------------------------------------
+  * ---------------------------------------------------------------------------
+  * ---------------------------------------------------------------------------
+  * ---------------------------------------------------------------------------
+  * ---------------------------------------------------------------------------
+  * ---------------------------------------------------------------------------
+  * ---------------------------------------------------------------------------
+  * ---------------------------------------------------------------------------
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 <HEAD>
 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
-<meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
+<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
 <TITLE>curs_attr 3x</TITLE>
 <link rev=made href="mailto:bug-ncurses@gnu.org">
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 
 
 </PRE><H3><a name="h3-Legacy-window-attributes">Legacy window attributes</a></H3><PRE>
-       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 (<STRONG>_</STRONG>).
+       The X/Open window attribute routines which <EM>set</EM> or <EM>get</EM>, turn <EM>on</EM>  or  <EM>off</EM>
+       are extensions of older routines which assume that color pairs are OR'd
+       into the attribute parameter.  These newer routines use similar  names,
+       because X/Open simply added an underscore (<STRONG>_</STRONG>) for the newer names.
+
+       The <STRONG>int</STRONG> datatype used in the legacy routines is treated as if it is the
+       same size as <STRONG>chtype</STRONG> (used by <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>).  It holds the common video at-
+       tributes  (such  as  bold,  reverse),  as well as a few bits for color.
+       Those bits correspond to the <STRONG>A_COLOR</STRONG> symbol.  The <STRONG>COLOR_PAIR</STRONG> macro pro-
+       vides  a value which can be OR'd into the attribute parameter.  For ex-
+       ample, as long as that value fits into the  <STRONG>A_COLOR</STRONG>  mask,  then  these
+       calls produce similar results:
+
+           attrset(A_BOLD | COLOR_PAIR(<EM>pair</EM>));
+           attr_set(A_BOLD, <EM>pair</EM>, NULL);
+
+       However, if the value does not fit, then the <STRONG>COLOR_PAIR</STRONG> macro uses only
+       the bits that fit.  For example, because in ncurses <STRONG>A_COLOR</STRONG>  has  eight
+       (8) bits, then <STRONG>COLOR_PAIR(</STRONG><EM>259</EM><STRONG>)</STRONG> is 4 (i.e., 259 is 4 more than the limit
+       255).
+
+       The <STRONG>PAIR_NUMBER</STRONG> macro extracts a pair number from an <STRONG>int</STRONG>  (or  <STRONG>chtype</STRONG>).
+       For  example,  the <EM>input</EM> and <EM>output</EM> values in these statements would be
+       the same:
+
+           int value = A_BOLD | COLOR_PAIR(<EM>input</EM>);
+           int <EM>output</EM> = PAIR_NUMBER(value);
 
        The <STRONG>attrset</STRONG> routine is a legacy feature predating SVr4 curses but  kept
        in X/Open Curses for the same reason that SVr4 curses kept it: compati-
        passed to <STRONG>addch</STRONG> (see <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>).
 
               <EM>Name</EM>           <EM>Description</EM>
-              -----------------------------------------------------------
+              -----------------------------------------------------------------
               <STRONG>A_NORMAL</STRONG>       Normal display (no highlight)
               <STRONG>A_STANDOUT</STRONG>     Best highlighting mode of the terminal.
               <STRONG>A_UNDERLINE</STRONG>    Underlining
               <STRONG>A_ALTCHARSET</STRONG>   Alternate character set
               <STRONG>A_ITALIC</STRONG>       Italics (non-X/Open extension)
               <STRONG>A_CHARTEXT</STRONG>     Bit-mask to extract a character
+              <STRONG>A_COLOR</STRONG>        Bit-mask to extract a color (legacy routines)
 
        These  video  attributes are supported by <STRONG>attr_on</STRONG> and related functions
        (which also support the attributes recognized by <STRONG>attron</STRONG>, etc.):
        support more than 256 color pairs.
 
 
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+       X/Open Curses is largely based  on  SVr4  curses,  adding  support  for
+       "wide-characters"  (not  specific to Unicode).  Some of the X/Open dif-
+       ferences from SVr4 curses address the way video attributes can  be  ap-
+       plied  to  wide-characters.   But aside from that, <STRONG>attrset</STRONG> and <STRONG>attr_set</STRONG>
+       are similar.  SVr4 curses provided the basic features for  manipulating
+       video  attributes.  However, earlier versions of curses provided a part
+       of these features.
+
+       As seen in 2.8BSD, curses assumed 7-bit characters,  using  the  eighth
+       bit  of  a byte to represent the <EM>standout</EM> feature (often implemented as
+       bold and/or reverse video).  The BSD curses library provided  functions
+       <STRONG>standout</STRONG>  and  <STRONG>standend</STRONG> which were carried along into X/Open Curses due
+       to their pervasive use in legacy applications.
+
+       Some terminals in the 1980s  could  support  a  variety  of  video  at-
+       tributes,  although the BSD curses library could do nothing with those.
+       System V (1983) provided an improved curses library.  It defined the <STRONG>A_</STRONG>
+       symbols  for  use  by  applications to manipulate the other attributes.
+       There are few useful references for the chronology.
+
+       Goodheart's book <EM>UNIX</EM> <EM>Curses</EM> <EM>Explained</EM> (1991)  describes  SVr3  (1987),
+       commenting on several functions:
+
+       <STRONG>o</STRONG>   the  <STRONG>attron</STRONG>,  <STRONG>attroff</STRONG>, <STRONG>attrset</STRONG> functions (and most of the functions
+           found in SVr4 but not in BSD curses) were introduced by System V,
+
+       <STRONG>o</STRONG>   the alternate character set feature with <STRONG>A_ALTCHARSET</STRONG> was added  in
+           SVr2 and improved in SVr3 (by adding <STRONG>acs_map[]</STRONG>),
+
+       <STRONG>o</STRONG>   <STRONG>start_color</STRONG>  and  related color-functions were introduced by System
+           V.3.2,
+
+       <STRONG>o</STRONG>   pads, soft-keys were added in SVr3, and
+
+       Goodheart did not mention the background character or the <STRONG>cchar_t</STRONG> type.
+       Those are respectively SVr4 and X/Open features.  He did mention the <STRONG>A_</STRONG>
+       constants, but did not indicate their values.  Those were not the  same
+       in different systems, even for those marked as System V.
+
+       Different  Unix  systems  used  different  sizes  for the bit-fields in
+       <STRONG>chtype</STRONG> for <EM>characters</EM> and <EM>colors</EM>, and took into account  the  different
+       integer sizes (32-bit versus 64-bit).
+
+       This  table  showing  the number of bits for <STRONG>A_COLOR</STRONG> and <STRONG>A_CHARTEXT</STRONG> 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  alter-
+       nate  character  set implementation.  A 32-bit library can be used on a
+       64-bit system, but not necessarily the reverse.
+
+              <EM>Year</EM>   <EM>System</EM>        <EM>Arch</EM>    <EM>Color</EM>   <EM>Char</EM>   <EM>Notes</EM>
+              ----------------------------------------------------------------
+              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 <STRONG>chtype</STRONG>
+
+       Notes:
+
+          Regarding HP-UX,
+
+          <STRONG>o</STRONG>   HP-UX 10.20 (1996) added support for 64-bit  PA-RISC  processors
+              in 1996.
+
+          <STRONG>o</STRONG>   HP-UX  10.30 (1997) marked "curses_colr" obsolete.  That version
+              of curses was dropped with HP-UX 11.30 in 2006.
+
+          Regarding OSF/1 (and Tru64),
+
+          <STRONG>o</STRONG>   These used 64-bit hardware.  Like ncurses, the OSF/1 curses  in-
+              terface is not customized for 32-bit and 64-bit versions.
+
+          <STRONG>o</STRONG>   Unlike other systems which evolved from AT&amp;T code, OSF/1 provid-
+              ed a new implementation for X/Open curses.
+
+          Regarding Solaris,
+
+          <STRONG>o</STRONG>   The initial release of Solaris was in 1992.
+
+          <STRONG>o</STRONG>   The <EM>xpg4</EM> (X/Open) curses was developed by MKS from 1990 to 1995.
+              Sun's copyright began in 1996.
+
+          <STRONG>o</STRONG>   Sun updated the X/Open curses interface after 64-bit support was
+              introduced in 1997, but did not modify the  SVr4  curses  inter-
+              face.
+
+          Regarding U/Win,
+
+          <STRONG>o</STRONG>   Development  of  the  curses  library  began in 1991, stopped in
+              2000.
+
+          <STRONG>o</STRONG>   Color support was added in 1998.
+
+          <STRONG>o</STRONG>   The library uses only <STRONG>chtype</STRONG> (no <STRONG>cchar_t</STRONG>).
+
+       Once X/Open curses was adopted in the mid-1990s, the  constraint  of  a
+       32-bit interface with many colors and wide-characters for <STRONG>chtype</STRONG> became
+       a moot point.  The <STRONG>cchar_t</STRONG> structure (whose size and  members  are  not
+       specified in X/Open Curses) could be extended as needed.
+
+       Other interfaces are rarely used now:
+
+       <STRONG>o</STRONG>   BSD  curses was improved slightly in 1993/1994 using Keith Bostic's
+           modification to make the library 8-bit clean  for  <STRONG>nvi</STRONG>.   He  moved
+           <EM>standout</EM> attribute to a structure member.
+
+           The  resulting  4.4BSD curses was replaced by ncurses over the next
+           ten years.
+
+       <STRONG>o</STRONG>   U/Win is rarely used now.
+
+
 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
        This implementation provides the <STRONG>A_ITALIC</STRONG> attribute for terminals which
        have  the  <STRONG>enter_italics_mode</STRONG> (<STRONG>sitm</STRONG>) and <STRONG>exit_italics_mode</STRONG> (<STRONG>ritm</STRONG>) capa-
               <STRONG>WA_BOLD</STRONG>         Extra bright or bold
               <STRONG>WA_ALTCHARSET</STRONG>   Alternate character set
 
-       The  XSI  curses  standard specifies that each pair of corresponding <STRONG>A_</STRONG>
-       and <STRONG>WA_</STRONG>-using functions operates on the same current-highlight informa-
-       tion.
+       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.:
+
+       <STRONG>o</STRONG>   The XSI curses standard specifies that each pair  of  corresponding
+           <STRONG>A_</STRONG>  and  <STRONG>WA_</STRONG>-using functions operates on the same current-highlight
+           information.
+
+       <STRONG>o</STRONG>   However, in some implementations, those symbols have unrelated val-
+           ues.
+
+           For example, the Solaris <EM>xpg4</EM> (X/Open) curses declares <STRONG>attr_t</STRONG> to be
+           an unsigned short integer (16-bits), while <STRONG>chtype</STRONG> is a unsigned in-
+           teger  (32-bits).   The <STRONG>WA_</STRONG> symbols in this case are different from
+           the <STRONG>A_</STRONG> symbols because they are used for a smaller  datatype  which
+           does not represent <STRONG>A_CHARTEXT</STRONG> or <STRONG>A_COLOR</STRONG>.
+
+           In this implementation (as in many others), the values happen to be
+           the same because it simplifies copying information  between  <STRONG>chtype</STRONG>
+           and <STRONG>cchar_t</STRONG> variables.
 
        The XSI standard extended conformance level adds new highlights <STRONG>A_HORI-</STRONG>
        <STRONG>ZONTAL</STRONG>, <STRONG>A_LEFT</STRONG>, <STRONG>A_LOW</STRONG>, <STRONG>A_RIGHT</STRONG>, <STRONG>A_TOP</STRONG>,  <STRONG>A_VERTICAL</STRONG>  (and  corresponding
 </li>
 <li><a href="#h2-VIDEO-ATTRIBUTES">VIDEO ATTRIBUTES</a></li>
 <li><a href="#h2-NOTES">NOTES</a></li>
+<li><a href="#h2-HISTORY">HISTORY</a></li>
 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>