doc/html/man/curs_attr.3x.html

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright 2018-2022,2023 Thomas E. Dickey                                *
   5   * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   6   *                                                                          *
   7   * Permission is hereby granted, free of charge, to any person obtaining a  *
   8   * copy of this software and associated documentation files (the            *
   9   * "Software"), to deal in the Software without restriction, including      *
  10   * without limitation the rights to use, copy, modify, merge, publish,      *
  11   * distribute, distribute with modifications, sublicense, and/or sell       *
  12   * copies of the Software, and to permit persons to whom the Software is    *
  13   * furnished to do so, subject to the following conditions:                 *
  14   *                                                                          *
  15   * The above copyright notice and this permission notice shall be included  *
  16   * in all copies or substantial portions of the Software.                   *
  17   *                                                                          *
  18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  19   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  20   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  21   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  22   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  23   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  24   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  25   *                                                                          *
  26   * Except as contained in this notice, the name(s) of the above copyright   *
  27   * holders shall not be used in advertising or otherwise to promote the     *
  28   * sale, use or other dealings in this Software without prior written       *
  29   * authorization.                                                           *
  30   ****************************************************************************
  31   * @Id: curs_attr.3x,v 1.87 2023/10/07 22:21:46 tom Exp @
  32   * ---------------------------------------------------------------------------
  33   * ---------------------------------------------------------------------------
  34   * ---------------------------------------------------------------------------
  35   * ---------------------------------------------------------------------------
  36   * ---------------------------------------------------------------------------
  37   * ---------------------------------------------------------------------------
  38   * ---------------------------------------------------------------------------
  39   * ---------------------------------------------------------------------------
  40   * ---------------------------------------------------------------------------
  41   * ---------------------------------------------------------------------------
  42   * ---------------------------------------------------------------------------
  43   * ---------------------------------------------------------------------------
  44   * ---------------------------------------------------------------------------
  45   * ---------------------------------------------------------------------------
  46   * ---------------------------------------------------------------------------
  47 -->
  48 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  49 <HTML>
  50 <HEAD>
  51 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  52 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  53 <TITLE>curs_attr 3x 2023-10-07 ncurses 6.4 Library calls</TITLE>
  54 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  55
  56 </HEAD>
  57 <BODY>
  58 <H1 class="no-header">curs_attr 3x 2023-10-07 ncurses 6.4 Library calls</H1>
  59 <PRE>
  60 <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>                    Library calls                   <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
  61
  62
  63
  64
  65 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  66        <STRONG>attr_get</STRONG>, <STRONG>wattr_get</STRONG>, <STRONG>attr_set</STRONG>, <STRONG>wattr_set</STRONG>, <STRONG>attr_off</STRONG>, <STRONG>wattr_off</STRONG>, <STRONG>attr_on</STRONG>,
  67        <STRONG>wattr_on</STRONG>, <STRONG>attroff</STRONG>, <STRONG>wattroff</STRONG>, <STRONG>attron</STRONG>, <STRONG>wattron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>, <STRONG>chgat</STRONG>,
  68        <STRONG>wchgat</STRONG>,  <STRONG>mvchgat</STRONG>, <STRONG>mvwchgat</STRONG>, <STRONG>color_set</STRONG>, <STRONG>wcolor_set</STRONG>, <STRONG>standend</STRONG>, <STRONG>wstandend</STRONG>,
  69        <STRONG>standout</STRONG>, <STRONG>wstandout</STRONG> -  manipulate  attributes  of  character  cells  in
  70        <EM>curses</EM> windows
  71
  72
  73 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  74        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  75
  76        <STRONG>int</STRONG> <STRONG>attr_get(attr_t</STRONG> <STRONG>*</STRONG><EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  77        <STRONG>int</STRONG> <STRONG>wattr_get(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <STRONG>*</STRONG><EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  78        <STRONG>int</STRONG> <STRONG>attr_set(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  79        <STRONG>int</STRONG> <STRONG>wattr_set(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  80
  81        <STRONG>int</STRONG> <STRONG>attr_off(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  82        <STRONG>int</STRONG> <STRONG>wattr_off(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  83        <STRONG>int</STRONG> <STRONG>attr_on(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  84        <STRONG>int</STRONG> <STRONG>wattr_on(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  85
  86        <STRONG>int</STRONG> <STRONG>attroff(int</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  87        <STRONG>int</STRONG> <STRONG>wattroff(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  88        <STRONG>int</STRONG> <STRONG>attron(int</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  89        <STRONG>int</STRONG> <STRONG>wattron(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  90        <STRONG>int</STRONG> <STRONG>attrset(int</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  91        <STRONG>int</STRONG> <STRONG>wattrset(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  92
  93        <STRONG>int</STRONG> <STRONG>chgat(int</STRONG> <EM>n</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <EM>attr</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  94        <STRONG>int</STRONG> <STRONG>wchgat(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG>
  95              <STRONG>int</STRONG> <EM>n</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <EM>attr</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  96        <STRONG>int</STRONG> <STRONG>mvchgat(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG>
  97              <STRONG>int</STRONG> <EM>n</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <EM>attr</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  98        <STRONG>int</STRONG> <STRONG>mvwchgat(WINDOW</STRONG> <STRONG>*</STRONG><EM>win,</EM> <EM>int</EM> <EM>y,</EM> <EM>int</EM> <EM>x</EM><STRONG>,</STRONG>
  99              <STRONG>int</STRONG> <EM>n,</EM> <STRONG>attr_t</STRONG> <EM>attr</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
 100
 101        <STRONG>int</STRONG> <STRONG>color_set(short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void*</STRONG> <EM>opts</EM><STRONG>);</STRONG>
 102        <STRONG>int</STRONG> <STRONG>wcolor_set(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void*</STRONG> <EM>opts</EM><STRONG>);</STRONG>
 103
 104        <STRONG>int</STRONG> <STRONG>standend(void);</STRONG>
 105        <STRONG>int</STRONG> <STRONG>wstandend(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG>
 106        <STRONG>int</STRONG> <STRONG>standout(void);</STRONG>
 107        <STRONG>int</STRONG> <STRONG>wstandout(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG>
 108
 109
 110 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 111        These  routines  manipulate the current attributes of the named window,
 112        which then apply to all characters that are  written  into  the  window
 113        with  <STRONG>waddch</STRONG>,  <STRONG>waddstr</STRONG>  and  <STRONG>wprintw</STRONG>.  Attributes are a property of the
 114        character, and move  with  the  character  through  any  scrolling  and
 115        insert/delete  line/character operations.  To the extent possible, they
 116        are displayed as appropriate modifications to the graphic rendition  of
 117        characters put on the screen.
 118
 119        These  routines do not affect the attributes used when erasing portions
 120        of the window.   See  <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>  for  functions  which  modify  the
 121        attributes used for erasing and clearing.
 122
 123        Routines  which  do  not have a <STRONG>WINDOW*</STRONG> parameter apply to <STRONG>stdscr</STRONG>.  For
 124        example, <STRONG>attr_set</STRONG> is the <STRONG>stdscr</STRONG> variant of <STRONG>wattr_set</STRONG>.
 125
 126
 127 </PRE><H3><a name="h3-Window-attributes">Window attributes</a></H3><PRE>
 128        There are two sets of functions:
 129
 130        <STRONG>o</STRONG>   functions  for  manipulating  the  window  attributes  and   color:
 131            <STRONG>wattr_set</STRONG> and <STRONG>wattr_get</STRONG>.
 132
 133        <STRONG>o</STRONG>   functions  for manipulating only the window attributes (not color):
 134            <STRONG>wattr_on</STRONG> and <STRONG>wattr_off</STRONG>.
 135
 136        The <STRONG>wattr_set</STRONG> function sets the current attributes of the given  window
 137        to <EM>attrs</EM>, with color specified by <EM>pair</EM>.
 138
 139        Use <STRONG>wattr_get</STRONG> to retrieve attributes for the given window.
 140
 141        Use  <STRONG>attr_on</STRONG>  and  <STRONG>wattr_on</STRONG>  to turn on window attributes, i.e., values
 142        OR'd  together  in  <EM>attr</EM>,  without  affecting  other  attributes.   Use
 143        <STRONG>attr_off</STRONG> and <STRONG>wattr_off</STRONG> to turn off window attributes, again values OR'd
 144        together in <EM>attr</EM>, without affecting other attributes.
 145
 146
 147 </PRE><H3><a name="h3-Legacy-window-attributes">Legacy window attributes</a></H3><PRE>
 148        The X/Open window attribute routines which <EM>set</EM> or <EM>get</EM>, turn <EM>on</EM>  or  <EM>off</EM>
 149        are extensions of older routines which assume that color pairs are OR'd
 150        into the attribute parameter.  These newer routines use similar  names,
 151        because X/Open simply added an underscore (<STRONG>_</STRONG>) for the newer names.
 152
 153        The <STRONG>int</STRONG> datatype used in the legacy routines is treated as if it is the
 154        same size as <STRONG>chtype</STRONG> (used by <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>).  It  holds  the  common  video
 155        attributes  (such  as  bold, reverse), as well as a few bits for color.
 156        Those bits correspond to the  <STRONG>A_COLOR</STRONG>  symbol.   The  <STRONG>COLOR_PAIR</STRONG>  macro
 157        provides  a  value which can be OR'd into the attribute parameter.  For
 158        example, as long as that value fits into the <STRONG>A_COLOR</STRONG> mask,  then  these
 159        calls produce similar results:
 160
 161            attrset(A_BOLD | COLOR_PAIR(<EM>pair</EM>));
 162            attr_set(A_BOLD, <EM>pair</EM>, NULL);
 163
 164        However, if the value does not fit, then the <STRONG>COLOR_PAIR</STRONG> macro uses only
 165        the bits that fit.  For example, because in ncurses <STRONG>A_COLOR</STRONG>  has  eight
 166        (8) bits, then <STRONG>COLOR_PAIR(</STRONG><EM>259</EM><STRONG>)</STRONG> is 4 (i.e., 259 is 4 more than the limit
 167        255).
 168
 169        The <STRONG>PAIR_NUMBER</STRONG> macro extracts a pair number from an <STRONG>int</STRONG>  (or  <STRONG>chtype</STRONG>).
 170        For  example,  the <EM>input</EM> and <EM>output</EM> values in these statements would be
 171        the same:
 172
 173            int value = A_BOLD | COLOR_PAIR(<EM>input</EM>);
 174            int <EM>output</EM> = PAIR_NUMBER(value);
 175
 176        The <STRONG>attrset</STRONG> routine is a legacy feature predating SVr4 curses but  kept
 177        in  X/Open  Curses  for  the  same  reason  that  SVr4  curses kept it:
 178        compatibility.
 179
 180        The remaining <STRONG>attr</STRONG>* functions operate exactly  like  the  corresponding
 181        <STRONG>attr_</STRONG>*  functions,  except  that they take arguments of type <STRONG>int</STRONG> rather
 182        than <STRONG>attr_t</STRONG>.
 183
 184        There is no corresponding <STRONG>attrget</STRONG> function as such  in  X/Open  Curses,
 185        although ncurses provides <STRONG>getattrs</STRONG> (see <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>).
 186
 187
 188 </PRE><H3><a name="h3-Change-character-rendition">Change character rendition</a></H3><PRE>
 189        The  routine  <STRONG>chgat</STRONG>  changes  the  attributes  of  a  given  number  of
 190        characters starting at the current cursor location of <STRONG>stdscr</STRONG>.  It  does
 191        not update the cursor and does not perform wrapping.  A character count
 192        of -1 or greater than  the  remaining  window  width  means  to  change
 193        attributes  all  the  way  to  the end of the current line.  The <STRONG>wchgat</STRONG>
 194        function generalizes this to any window; the <STRONG>mvwchgat</STRONG> function  does  a
 195        cursor move before acting.
 196
 197        In  these  functions, the color <EM>pair</EM> argument is a color-pair index (as
 198        in the first argument of <STRONG>init_pair</STRONG>, see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>).
 199
 200
 201 </PRE><H3><a name="h3-Change-window-color">Change window color</a></H3><PRE>
 202        The routine <STRONG>color_set</STRONG> sets the current color of the given window to the
 203        foreground/background   combination   described   by   the  color  <EM>pair</EM>
 204        parameter.
 205
 206
 207 </PRE><H3><a name="h3-Standout">Standout</a></H3><PRE>
 208        The routine <STRONG>standout</STRONG> is the same as  <STRONG>attron(A_STANDOUT)</STRONG>.   The  routine
 209        <STRONG>standend</STRONG>  is  the  same as <STRONG>attrset(A_NORMAL)</STRONG> or <STRONG>attrset(0)</STRONG>, that is, it
 210        turns off all attributes.
 211
 212        X/Open does not mark these "restricted", because
 213
 214        <STRONG>o</STRONG>   they have well established legacy use, and
 215
 216        <STRONG>o</STRONG>   there is no  ambiguity  about  the  way  the  attributes  might  be
 217            combined with a color pair.
 218
 219
 220 </PRE><H2><a name="h2-VIDEO-ATTRIBUTES">VIDEO ATTRIBUTES</a></H2><PRE>
 221        The following video attributes, defined in <STRONG>&lt;curses.h&gt;</STRONG>, can be passed to
 222        the routines <STRONG>attron</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attrset</STRONG>, or OR'd with the  characters
 223        passed to <STRONG>addch</STRONG> (see <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>).
 224
 225               <STRONG>Name</STRONG>           <STRONG>Description</STRONG>
 226               -----------------------------------------------------------------
 227               <STRONG>A_NORMAL</STRONG>       Normal display (no highlight)
 228               <STRONG>A_STANDOUT</STRONG>     Best highlighting mode of the terminal.
 229               <STRONG>A_UNDERLINE</STRONG>    Underlining
 230               <STRONG>A_REVERSE</STRONG>      Reverse video
 231               <STRONG>A_BLINK</STRONG>        Blinking
 232               <STRONG>A_DIM</STRONG>          Half bright
 233               <STRONG>A_BOLD</STRONG>         Extra bright or bold
 234               <STRONG>A_PROTECT</STRONG>      Protected mode
 235               <STRONG>A_INVIS</STRONG>        Invisible or blank mode
 236               <STRONG>A_ALTCHARSET</STRONG>   Alternate character set
 237               <STRONG>A_ITALIC</STRONG>       Italics (non-X/Open extension)
 238               <STRONG>A_CHARTEXT</STRONG>     Bit-mask to extract a character
 239               <STRONG>A_COLOR</STRONG>        Bit-mask to extract a color (legacy routines)
 240
 241        These  video  attributes are supported by <STRONG>attr_on</STRONG> and related functions
 242        (which also support the attributes recognized by <STRONG>attron</STRONG>, etc.):
 243
 244               <STRONG>Name</STRONG>            <STRONG>Description</STRONG>
 245               -----------------------------------------
 246               <STRONG>WA_HORIZONTAL</STRONG>   Horizontal highlight
 247               <STRONG>WA_LEFT</STRONG>         Left highlight
 248               <STRONG>WA_LOW</STRONG>          Low highlight
 249               <STRONG>WA_RIGHT</STRONG>        Right highlight
 250               <STRONG>WA_TOP</STRONG>          Top highlight
 251               <STRONG>WA_VERTICAL</STRONG>     Vertical highlight
 252
 253        The return values of many of these routines are  not  meaningful  (they
 254        are  implemented  as macro-expanded assignments and simply return their
 255        argument).  The SVr4 manual page claims (falsely) that  these  routines
 256        always return <STRONG>1</STRONG>.
 257
 258
 259 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 260        These functions may be macros:
 261
 262               <STRONG>attroff</STRONG>,  <STRONG>wattroff</STRONG>, <STRONG>attron</STRONG>, <STRONG>wattron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>, <STRONG>standend</STRONG>
 263               and <STRONG>standout</STRONG>.
 264
 265        Color pair values can only be OR'd with attributes if the  pair  number
 266        is less than 256.  The alternate functions such as <STRONG>color_set</STRONG> can pass a
 267        color pair value directly.  However, ncurses ABI 4 and 5 simply OR this
 268        value  within  the  alternate functions.  You must use ncurses ABI 6 to
 269        support more than 256 color pairs.
 270
 271
 272 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 273        X/Open Curses is largely based  on  SVr4  curses,  adding  support  for
 274        "wide-characters"  (not  specific  to  Unicode).   Some  of  the X/Open
 275        differences from SVr4 curses address the way video  attributes  can  be
 276        applied  to wide-characters.  But aside from that, <STRONG>attrset</STRONG> and <STRONG>attr_set</STRONG>
 277        are similar.  SVr4 curses provided the basic features for  manipulating
 278        video  attributes.  However, earlier versions of curses provided a part
 279        of these features.
 280
 281        As seen in 2.8BSD, curses assumed 7-bit characters,  using  the  eighth
 282        bit  of  a byte to represent the <EM>standout</EM> feature (often implemented as
 283        bold and/or reverse video).  The BSD curses library provided  functions
 284        <STRONG>standout</STRONG>  and  <STRONG>standend</STRONG> which were carried along into X/Open Curses due
 285        to their pervasive use in legacy applications.
 286
 287        Some  terminals  in  the  1980s  could  support  a  variety  of   video
 288        attributes,  although  the  BSD  curses  library  could do nothing with
 289        those.  System V  (1983)  provided  an  improved  curses  library.   It
 290        defined  the <STRONG>A_</STRONG> symbols for use by applications to manipulate the other
 291        attributes.  There are few useful references for the chronology.
 292
 293        Goodheart's book <EM>UNIX</EM> <EM>Curses</EM> <EM>Explained</EM> (1991)  describes  SVr3  (1987),
 294        commenting on several functions:
 295
 296        <STRONG>o</STRONG>   the  <STRONG>attron</STRONG>,  <STRONG>attroff</STRONG>, <STRONG>attrset</STRONG> functions (and most of the functions
 297            found in SVr4 but not in BSD curses) were introduced by System V,
 298
 299        <STRONG>o</STRONG>   the alternate character set feature with <STRONG>A_ALTCHARSET</STRONG> was added  in
 300            SVr2 and improved in SVr3 (by adding <STRONG>acs_map[]</STRONG>),
 301
 302        <STRONG>o</STRONG>   <STRONG>start_color</STRONG>  and  related color-functions were introduced by System
 303            V.3.2,
 304
 305        <STRONG>o</STRONG>   pads, soft-keys were added in SVr3, and
 306
 307        Goodheart did not mention the background character or the <STRONG>cchar_t</STRONG> type.
 308        Those are respectively SVr4 and X/Open features.  He did mention the <STRONG>A_</STRONG>
 309        constants, but did not indicate their values.  Those were not the  same
 310        in different systems, even for those marked as System V.
 311
 312        Different  Unix  systems  used  different  sizes  for the bit-fields in
 313        <STRONG>chtype</STRONG> for <EM>characters</EM> and <EM>colors</EM>, and took into account  the  different
 314        integer sizes (32-bit versus 64-bit).
 315
 316        This  table  showing  the number of bits for <STRONG>A_COLOR</STRONG> and <STRONG>A_CHARTEXT</STRONG> was
 317        gleaned from the curses header files for various operating systems  and
 318        architectures.   The inferred architecture and notes reflect the format
 319        and size of the  defined  constants  as  well  as  clues  such  as  the
 320        alternate  character  set implementation.  A 32-bit library can be used
 321        on a 64-bit system, but not necessarily the reverse.
 322
 323               <STRONG>Year</STRONG>   <STRONG>System</STRONG>        <STRONG>Arch</STRONG>    <STRONG>Color</STRONG>   <STRONG>Char</STRONG>   <STRONG>Notes</STRONG>
 324               ----------------------------------------------------------------
 325               1992   Solaris 5.2   32      6       17     SVr4 curses
 326               1992   HPUX 9        32      no      8      SVr2 curses
 327               1992   AIX 3.2       32      no      23     SVr2 curses
 328               1994   OSF/1 r3      32      no      23     SVr2 curses
 329               1995   HP-UX 10.00   32      6       16     SVr3 "curses_colr"
 330               1995   HP-UX 10.00   32      6       8      SVr4, X/Open curses
 331               1995   Solaris 5.4   32/64   7       16     X/Open curses
 332               1996   AIX 4.2       32      7       16     X/Open curses
 333               1996   OSF/1 r4      32      6       16     X/Open curses
 334
 335               1997   HP-UX 11.00   32      6       8      X/Open curses
 336               2000   U/Win         32/64   7/31    16     uses <STRONG>chtype</STRONG>
 337
 338        Notes:
 339
 340           Regarding HP-UX,
 341
 342           <STRONG>o</STRONG>   HP-UX 10.20 (1996) added support for 64-bit  PA-RISC  processors
 343               in 1996.
 344
 345           <STRONG>o</STRONG>   HP-UX  10.30 (1997) marked "curses_colr" obsolete.  That version
 346               of curses was dropped with HP-UX 11.30 in 2006.
 347
 348           Regarding OSF/1 (and Tru64),
 349
 350           <STRONG>o</STRONG>   These used 64-bit hardware.   Like  ncurses,  the  OSF/1  curses
 351               interface is not customized for 32-bit and 64-bit versions.
 352
 353           <STRONG>o</STRONG>   Unlike  other  systems  which  evolved  from  AT&amp;T  code,  OSF/1
 354               provided a new implementation for X/Open curses.
 355
 356           Regarding Solaris,
 357
 358           <STRONG>o</STRONG>   The initial release of Solaris was in 1992.
 359
 360           <STRONG>o</STRONG>   The <EM>xpg4</EM> (X/Open) curses was developed by MKS from 1990 to 1995.
 361               Sun's copyright began in 1996.
 362
 363           <STRONG>o</STRONG>   Sun updated the X/Open curses interface after 64-bit support was
 364               introduced  in  1997,  but  did  not  modify  the  SVr4   curses
 365               interface.
 366
 367           Regarding U/Win,
 368
 369           <STRONG>o</STRONG>   Development  of  the  curses  library  began in 1991, stopped in
 370               2000.
 371
 372           <STRONG>o</STRONG>   Color support was added in 1998.
 373
 374           <STRONG>o</STRONG>   The library uses only <STRONG>chtype</STRONG> (no <STRONG>cchar_t</STRONG>).
 375
 376        Once X/Open curses was adopted in the mid-1990s, the  constraint  of  a
 377        32-bit interface with many colors and wide-characters for <STRONG>chtype</STRONG> became
 378        a moot point.  The <STRONG>cchar_t</STRONG> structure (whose size and  members  are  not
 379        specified in X/Open Curses) could be extended as needed.
 380
 381        Other interfaces are rarely used now:
 382
 383        <STRONG>o</STRONG>   BSD  curses was improved slightly in 1993/1994 using Keith Bostic's
 384            modification to make the library 8-bit clean for <STRONG>nvi(1)</STRONG>.  He  moved
 385            <EM>standout</EM> attribute to a structure member.
 386
 387            The  resulting  4.4BSD curses was replaced by ncurses over the next
 388            ten years.
 389
 390        <STRONG>o</STRONG>   U/Win is rarely used now.
 391
 392
 393 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 394        This implementation provides the <STRONG>A_ITALIC</STRONG> attribute for terminals which
 395        have   the   <STRONG>enter_italics_mode</STRONG>  (<STRONG>sitm</STRONG>)  and  <STRONG>exit_italics_mode</STRONG>  (<STRONG>ritm</STRONG>)
 396        capabilities.  Italics are not mentioned in X/Open Curses.  Unlike  the
 397        other  video  attributes,  <STRONG>A_ITALIC</STRONG>  is unrelated to the <STRONG>set_attributes</STRONG>
 398        capabilities.   This   implementation   makes   the   assumption   that
 399        <STRONG>exit_attribute_mode</STRONG> may also reset italics.
 400
 401        Each  of  the functions added by XSI Curses has a parameter <EM>opts</EM>, which
 402        X/Open Curses  still  (after  more  than  twenty  years)  documents  as
 403        reserved  for  future  use,  saying  that  it  should  be  <STRONG>NULL</STRONG>.   This
 404        implementation uses that parameter in ABI 6  for  the  functions  which
 405        have a color-pair parameter to support <EM>extended</EM> <EM>color</EM> <EM>pairs</EM>:
 406
 407        <STRONG>o</STRONG>   For functions which modify the color, e.g., <STRONG>wattr_set</STRONG> and <STRONG>wattr_on</STRONG>,
 408            if <EM>opts</EM> is set it is treated as a pointer to <STRONG>int</STRONG>, and used  to  set
 409            the color pair instead of the <STRONG>short</STRONG> <EM>pair</EM> parameter.
 410
 411        <STRONG>o</STRONG>   For functions which retrieve the color, e.g., <STRONG>wattr_get</STRONG>, if <EM>opts</EM> is
 412            set it is treated as a pointer to <STRONG>int</STRONG>, and  used  to  retrieve  the
 413            color  pair  as  an <STRONG>int</STRONG> value, in addition to retrieving it via the
 414            standard pointer to <STRONG>short</STRONG> parameter.
 415
 416        <STRONG>o</STRONG>   For functions which turn attributes off, e.g., <STRONG>wattr_off</STRONG>, the  <EM>opts</EM>
 417            parameter is ignored except except to check that it is <STRONG>NULL</STRONG>.
 418
 419
 420 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 421        These functions are supported in the XSI Curses standard, Issue 4.  The
 422        standard defined the dedicated type for highlights, <STRONG>attr_t</STRONG>,  which  was
 423        not defined in SVr4 curses.  The functions taking <STRONG>attr_t</STRONG> arguments were
 424        not supported under SVr4.
 425
 426        Very old versions of this library did not force an update of the screen
 427        when  changing  the  attributes.   Use  <STRONG>touchwin</STRONG> to force the screen to
 428        match the updated attributes.
 429
 430        The XSI Curses standard states that whether the  traditional  functions
 431        <STRONG>attron</STRONG>/<STRONG>attroff</STRONG>/<STRONG>attrset</STRONG>  can  manipulate  attributes other than <STRONG>A_BLINK</STRONG>,
 432        <STRONG>A_BOLD</STRONG>, <STRONG>A_DIM</STRONG>, <STRONG>A_REVERSE</STRONG>, <STRONG>A_STANDOUT</STRONG>, or <STRONG>A_UNDERLINE</STRONG> is  "unspecified".
 433        Under  this  implementation  as  well  as  SVr4 curses, these functions
 434        correctly manipulate all other highlights (specifically,  <STRONG>A_ALTCHARSET</STRONG>,
 435        <STRONG>A_PROTECT</STRONG>, and <STRONG>A_INVIS</STRONG>).
 436
 437        XSI Curses added these entry points:
 438
 439               <STRONG>attr_get</STRONG>,  <STRONG>attr_on</STRONG>,  <STRONG>attr_off</STRONG>,  <STRONG>attr_set</STRONG>,  <STRONG>wattr_on</STRONG>,  <STRONG>wattr_off</STRONG>,
 440               <STRONG>wattr_get</STRONG>, <STRONG>wattr_set</STRONG>
 441
 442        The new functions are intended to work with a new series  of  highlight
 443        macros prefixed with <STRONG>WA_</STRONG>.  The older macros have direct counterparts in
 444        the newer set of names:
 445
 446               <STRONG>Name</STRONG>            <STRONG>Description</STRONG>
 447               ------------------------------------------------------------
 448               <STRONG>WA_NORMAL</STRONG>       Normal display (no highlight)
 449               <STRONG>WA_STANDOUT</STRONG>     Best highlighting mode of the terminal.
 450               <STRONG>WA_UNDERLINE</STRONG>    Underlining
 451               <STRONG>WA_REVERSE</STRONG>      Reverse video
 452               <STRONG>WA_BLINK</STRONG>        Blinking
 453               <STRONG>WA_DIM</STRONG>          Half bright
 454               <STRONG>WA_BOLD</STRONG>         Extra bright or bold
 455               <STRONG>WA_ALTCHARSET</STRONG>   Alternate character set
 456
 457        XSI curses does not assign values to these symbols, nor does  it  state
 458        whether or not they are related to the similarly-named A_NORMAL, etc.:
 459
 460        <STRONG>o</STRONG>   The  XSI  curses standard specifies that each pair of corresponding
 461            <STRONG>A_</STRONG> and <STRONG>WA_</STRONG>-using functions operates on the  same  current-highlight
 462            information.
 463
 464        <STRONG>o</STRONG>   However,  in  some  implementations,  those  symbols have unrelated
 465            values.
 466
 467            For example, the Solaris <EM>xpg4</EM> (X/Open) curses declares <STRONG>attr_t</STRONG> to be
 468            an  unsigned  short  integer  (16-bits), while <STRONG>chtype</STRONG> is a unsigned
 469            integer (32-bits).  The <STRONG>WA_</STRONG> symbols in this case are different from
 470            the  <STRONG>A_</STRONG>  symbols because they are used for a smaller datatype which
 471            does not represent <STRONG>A_CHARTEXT</STRONG> or <STRONG>A_COLOR</STRONG>.
 472
 473            In this implementation (as in many others), the values happen to be
 474            the  same  because it simplifies copying information between <STRONG>chtype</STRONG>
 475            and <STRONG>cchar_t</STRONG> variables.
 476
 477        <STRONG>o</STRONG>   Because ncurses's <STRONG>attr_t</STRONG> can hold a  color  pair  (in  the  <STRONG>A_COLOR</STRONG>
 478            field),  a  call to <STRONG>wattr_on</STRONG>, <STRONG>wattr_off</STRONG>, or <STRONG>wattr_set</STRONG> may alter the
 479            window's color.  If the color pair  information  in  the  attribute
 480            parameter is zero, no change is made to the window's color.
 481
 482            This is consistent with SVr4 curses; X/Open Curses does not specify
 483            this.
 484
 485        The  XSI  standard  extended  conformance  level  adds  new  highlights
 486        <STRONG>A_HORIZONTAL</STRONG>,   <STRONG>A_LEFT</STRONG>,   <STRONG>A_LOW</STRONG>,   <STRONG>A_RIGHT</STRONG>,   <STRONG>A_TOP</STRONG>,   <STRONG>A_VERTICAL</STRONG>  (and
 487        corresponding <STRONG>WA_</STRONG> macros for  each).   As  of  August  2013,  no  known
 488        terminal provides these highlights (i.e., via the <STRONG>sgr1</STRONG> capability).
 489
 490
 491 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 492        All routines return the integer <STRONG>OK</STRONG> on success, or <STRONG>ERR</STRONG> on failure.
 493
 494        X/Open does not define any error conditions.
 495
 496        This implementation
 497
 498        <STRONG>o</STRONG>   returns an error if the window pointer is null.
 499
 500        <STRONG>o</STRONG>   returns  an  error  if  the  color pair parameter for <STRONG>wcolor_set</STRONG> is
 501            outside the range 0..COLOR_PAIRS-1.
 502
 503        <STRONG>o</STRONG>   does not return an error if either of the parameters  of  <STRONG>wattr_get</STRONG>
 504            used for retrieving attribute or color-pair values is <STRONG>NULL</STRONG>.
 505
 506        Functions  with  a  "mv"  prefix  first perform a cursor movement using
 507        <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
 508        the window pointer is null.
 509
 510
 511 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 512        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,     <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>,     <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>,     <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>,
 513        <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 514
 515
 516
 517 ncurses 6.4                       2023-10-07                     <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
 518 </PRE>
 519 <div class="nav">
 520 <ul>
 521 <li><a href="#h2-NAME">NAME</a></li>
 522 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 523 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 524 <ul>
 525 <li><a href="#h3-Window-attributes">Window attributes</a></li>
 526 <li><a href="#h3-Legacy-window-attributes">Legacy window attributes</a></li>
 527 <li><a href="#h3-Change-character-rendition">Change character rendition</a></li>
 528 <li><a href="#h3-Change-window-color">Change window color</a></li>
 529 <li><a href="#h3-Standout">Standout</a></li>
 530 </ul>
 531 </li>
 532 <li><a href="#h2-VIDEO-ATTRIBUTES">VIDEO ATTRIBUTES</a></li>
 533 <li><a href="#h2-NOTES">NOTES</a></li>
 534 <li><a href="#h2-HISTORY">HISTORY</a></li>
 535 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 536 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 537 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 538 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 539 </ul>
 540 </div>
 541 </BODY>
 542 </HTML>