ncurses 6.1 - patch 20180728
[ncurses.git] / doc / html / man / curs_attr.3x.html
index 56844fd7375cf9c5f155a2b91d58776d387d1741..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,7 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_attr.3x,v 1.60 2017/10/14 20:01:13 tom Exp @
+  * @Id: curs_attr.3x,v 1.64 2018/07/28 22:15:59 tom Exp @
   * ---------------------------------------------------------------------------
   * attr_get
   * .br
@@ -54,7 +54,7 @@
 <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.):
               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>