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.89 2023/11/25 15:33:56 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-11-25 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-11-25 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><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG>
  99              <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>
 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><H3><a name="h3-Video-Attributes">Video Attributes</a></H3><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-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 260        All routines return the integer <STRONG>OK</STRONG> on success, or <STRONG>ERR</STRONG> on failure.
 261
 262        X/Open does not define any error conditions.
 263
 264        This implementation
 265
 266        <STRONG>o</STRONG>   returns an error if the window pointer is null.
 267
 268        <STRONG>o</STRONG>   returns  an  error  if  the  color pair parameter for <STRONG>wcolor_set</STRONG> is
 269            outside the range 0..COLOR_PAIRS-1.
 270
 271        <STRONG>o</STRONG>   does not return an error if either of the parameters  of  <STRONG>wattr_get</STRONG>
 272            used for retrieving attribute or color-pair values is <STRONG>NULL</STRONG>.
 273
 274        Functions  with  a  "mv"  prefix  first perform a cursor movement using
 275        <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
 276        the window pointer is null.
 277
 278
 279 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 280        These functions may be macros:
 281
 282               <STRONG>attroff</STRONG>,  <STRONG>wattroff</STRONG>, <STRONG>attron</STRONG>, <STRONG>wattron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>, <STRONG>standend</STRONG>
 283               and <STRONG>standout</STRONG>.
 284
 285        Color pair values can only be OR'd with attributes if the  pair  number
 286        is less than 256.  The alternate functions such as <STRONG>color_set</STRONG> can pass a
 287        color pair value directly.  However, ncurses ABI 4 and 5 simply OR this
 288        value  within  the  alternate functions.  You must use ncurses ABI 6 to
 289        support more than 256 color pairs.
 290
 291
 292 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 293        This implementation provides the <STRONG>A_ITALIC</STRONG> attribute for terminals which
 294        have   the   <STRONG>enter_italics_mode</STRONG>  (<STRONG>sitm</STRONG>)  and  <STRONG>exit_italics_mode</STRONG>  (<STRONG>ritm</STRONG>)
 295        capabilities.  Italics are not mentioned in X/Open Curses.  Unlike  the
 296        other  video  attributes,  <STRONG>A_ITALIC</STRONG>  is unrelated to the <STRONG>set_attributes</STRONG>
 297        capabilities.   This   implementation   makes   the   assumption   that
 298        <STRONG>exit_attribute_mode</STRONG> may also reset italics.
 299
 300        Each  of  the functions added by XSI Curses has a parameter <EM>opts</EM>, which
 301        X/Open Curses  still  (after  more  than  twenty  years)  documents  as
 302        reserved  for  future  use,  saying  that  it  should  be  <STRONG>NULL</STRONG>.   This
 303        implementation uses that parameter in ABI 6  for  the  functions  which
 304        have a color-pair parameter to support <EM>extended</EM> <EM>color</EM> <EM>pairs</EM>:
 305
 306        <STRONG>o</STRONG>   For functions which modify the color, e.g., <STRONG>wattr_set</STRONG> and <STRONG>wattr_on</STRONG>,
 307            if <EM>opts</EM> is set it is treated as a pointer to <STRONG>int</STRONG>, and used  to  set
 308            the color pair instead of the <STRONG>short</STRONG> <EM>pair</EM> parameter.
 309
 310        <STRONG>o</STRONG>   For functions which retrieve the color, e.g., <STRONG>wattr_get</STRONG>, if <EM>opts</EM> is
 311            set it is treated as a pointer to <STRONG>int</STRONG>, and  used  to  retrieve  the
 312            color  pair  as  an <STRONG>int</STRONG> value, in addition to retrieving it via the
 313            standard pointer to <STRONG>short</STRONG> parameter.
 314
 315        <STRONG>o</STRONG>   For functions which turn attributes off, e.g., <STRONG>wattr_off</STRONG>, the  <EM>opts</EM>
 316            parameter is ignored except except to check that it is <STRONG>NULL</STRONG>.
 317
 318
 319 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 320        These functions are described in the XSI Curses standard, Issue 4.  The
 321        standard defined the dedicated type for highlights, <STRONG>attr_t</STRONG>,  which  was
 322        not defined in SVr4 curses.  The functions taking <STRONG>attr_t</STRONG> arguments were
 323        not supported under SVr4.
 324
 325        Very old versions of this library did not force an update of the screen
 326        when  changing  the  attributes.   Use  <STRONG>touchwin</STRONG> to force the screen to
 327        match the updated attributes.
 328
 329        The XSI Curses standard states that whether the  traditional  functions
 330        <STRONG>attron</STRONG>/<STRONG>attroff</STRONG>/<STRONG>attrset</STRONG>  can  manipulate  attributes other than <STRONG>A_BLINK</STRONG>,
 331        <STRONG>A_BOLD</STRONG>, <STRONG>A_DIM</STRONG>, <STRONG>A_REVERSE</STRONG>, <STRONG>A_STANDOUT</STRONG>, or <STRONG>A_UNDERLINE</STRONG> is  "unspecified".
 332        Under  this  implementation  as  well  as  SVr4 curses, these functions
 333        correctly manipulate all other highlights (specifically,  <STRONG>A_ALTCHARSET</STRONG>,
 334        <STRONG>A_PROTECT</STRONG>, and <STRONG>A_INVIS</STRONG>).
 335
 336        XSI Curses added these entry points:
 337
 338               <STRONG>attr_get</STRONG>,  <STRONG>attr_on</STRONG>,  <STRONG>attr_off</STRONG>,  <STRONG>attr_set</STRONG>,  <STRONG>wattr_on</STRONG>,  <STRONG>wattr_off</STRONG>,
 339               <STRONG>wattr_get</STRONG>, <STRONG>wattr_set</STRONG>
 340
 341        The new functions are intended to work with a new series  of  highlight
 342        macros prefixed with <STRONG>WA_</STRONG>.  The older macros have direct counterparts in
 343        the newer set of names:
 344
 345               <STRONG>Name</STRONG>            <STRONG>Description</STRONG>
 346               ------------------------------------------------------------
 347               <STRONG>WA_NORMAL</STRONG>       Normal display (no highlight)
 348               <STRONG>WA_STANDOUT</STRONG>     Best highlighting mode of the terminal.
 349               <STRONG>WA_UNDERLINE</STRONG>    Underlining
 350               <STRONG>WA_REVERSE</STRONG>      Reverse video
 351               <STRONG>WA_BLINK</STRONG>        Blinking
 352               <STRONG>WA_DIM</STRONG>          Half bright
 353               <STRONG>WA_BOLD</STRONG>         Extra bright or bold
 354               <STRONG>WA_ALTCHARSET</STRONG>   Alternate character set
 355
 356        XSI curses does not assign values to these symbols, nor does  it  state
 357        whether or not they are related to the similarly-named A_NORMAL, etc.:
 358
 359        <STRONG>o</STRONG>   The  XSI  curses standard specifies that each pair of corresponding
 360            <STRONG>A_</STRONG> and <STRONG>WA_</STRONG>-using functions operates on the  same  current-highlight
 361            information.
 362
 363        <STRONG>o</STRONG>   However,  in  some  implementations,  those  symbols have unrelated
 364            values.
 365
 366            For example, the Solaris <EM>xpg4</EM> (X/Open) curses declares <STRONG>attr_t</STRONG> to be
 367            an  unsigned  short  integer  (16-bits), while <STRONG>chtype</STRONG> is a unsigned
 368            integer (32-bits).  The <STRONG>WA_</STRONG> symbols in this case are different from
 369            the  <STRONG>A_</STRONG>  symbols because they are used for a smaller datatype which
 370            does not represent <STRONG>A_CHARTEXT</STRONG> or <STRONG>A_COLOR</STRONG>.
 371
 372            In this implementation (as in many others), the values happen to be
 373            the  same  because it simplifies copying information between <STRONG>chtype</STRONG>
 374            and <STRONG>cchar_t</STRONG> variables.
 375
 376        <STRONG>o</STRONG>   Because ncurses's <STRONG>attr_t</STRONG> can hold a  color  pair  (in  the  <STRONG>A_COLOR</STRONG>
 377            field),  a  call to <STRONG>wattr_on</STRONG>, <STRONG>wattr_off</STRONG>, or <STRONG>wattr_set</STRONG> may alter the
 378            window's color.  If the color pair  information  in  the  attribute
 379            parameter is zero, no change is made to the window's color.
 380
 381            This is consistent with SVr4 curses; X/Open Curses does not specify
 382            this.
 383
 384        The  XSI  standard  extended  conformance  level  adds  new  highlights
 385        <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
 386        corresponding <STRONG>WA_</STRONG> macros for  each).   As  of  August  2013,  no  known
 387        terminal provides these highlights (i.e., via the <STRONG>sgr1</STRONG> capability).
 388
 389
 390 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 391        X/Open  Curses  is  largely  based  on  SVr4 curses, adding support for
 392        "wide-characters" (not  specific  to  Unicode).   Some  of  the  X/Open
 393        differences  from  SVr4  curses address the way video attributes can be
 394        applied to wide-characters.  But aside from that, <STRONG>attrset</STRONG> and  <STRONG>attr_set</STRONG>
 395        are  similar.  SVr4 curses provided the basic features for manipulating
 396        video attributes.  However, earlier versions of curses provided a  part
 397        of these features.
 398
 399        As  seen  in  2.8BSD, curses assumed 7-bit characters, using the eighth
 400        bit of a byte to represent the <EM>standout</EM> feature (often  implemented  as
 401        bold  and/or reverse video).  The BSD curses library provided functions
 402        <STRONG>standout</STRONG> and <STRONG>standend</STRONG> which were carried along into X/Open  Curses  due
 403        to their pervasive use in legacy applications.
 404
 405        Some   terminals  in  the  1980s  could  support  a  variety  of  video
 406        attributes, although the BSD  curses  library  could  do  nothing  with
 407        those.   System  V  (1983)  provided  an  improved  curses library.  It
 408        defined the <STRONG>A_</STRONG> symbols for use by applications to manipulate the  other
 409        attributes.  There are few useful references for the chronology.
 410
 411        Goodheart's  book  <EM>UNIX</EM>  <EM>Curses</EM> <EM>Explained</EM> (1991) describes SVr3 (1987),
 412        commenting on several functions:
 413
 414        <STRONG>o</STRONG>   the <STRONG>attron</STRONG>, <STRONG>attroff</STRONG>, <STRONG>attrset</STRONG> functions (and most of  the  functions
 415            found in SVr4 but not in BSD curses) were introduced by System V,
 416
 417        <STRONG>o</STRONG>   the  alternate character set feature with <STRONG>A_ALTCHARSET</STRONG> was added in
 418            SVr2 and improved in SVr3 (by adding <STRONG>acs_map[]</STRONG>),
 419
 420        <STRONG>o</STRONG>   <STRONG>start_color</STRONG> and related color-functions were introduced  by  System
 421            V.3.2,
 422
 423        <STRONG>o</STRONG>   pads, soft-keys were added in SVr3, and
 424
 425        Goodheart did not mention the background character or the <STRONG>cchar_t</STRONG> type.
 426        Those are respectively SVr4 and X/Open features.  He did mention the <STRONG>A_</STRONG>
 427        constants,  but did not indicate their values.  Those were not the same
 428        in different systems, even for those marked as System V.
 429
 430        Different Unix systems used  different  sizes  for  the  bit-fields  in
 431        <STRONG>chtype</STRONG>  for  <EM>characters</EM> and <EM>colors</EM>, and took into account the different
 432        integer sizes (32-bit versus 64-bit).
 433
 434        This table showing the number of bits for <STRONG>A_COLOR</STRONG>  and  <STRONG>A_CHARTEXT</STRONG>  was
 435        gleaned  from the curses header files for various operating systems and
 436        architectures.  The inferred architecture and notes reflect the  format
 437        and  size  of  the  defined  constants  as  well  as  clues such as the
 438        alternate character set implementation.  A 32-bit library can  be  used
 439        on a 64-bit system, but not necessarily the reverse.
 440
 441               <STRONG>Year</STRONG>   <STRONG>System</STRONG>        <STRONG>Arch</STRONG>    <STRONG>Color</STRONG>   <STRONG>Char</STRONG>   <STRONG>Notes</STRONG>
 442               ----------------------------------------------------------------
 443               1992   Solaris 5.2   32      6       17     SVr4 curses
 444               1992   HP-UX 9       32      no      8      SVr2 curses
 445               1992   AIX 3.2       32      no      23     SVr2 curses
 446               1994   OSF/1 r3      32      no      23     SVr2 curses
 447               1995   HP-UX 10.00   32      6       16     SVr3 "curses_colr"
 448               1995   HP-UX 10.00   32      6       8      SVr4, X/Open curses
 449               1995   Solaris 5.4   32/64   7       16     X/Open curses
 450               1996   AIX 4.2       32      7       16     X/Open curses
 451               1996   OSF/1 r4      32      6       16     X/Open curses
 452               1997   HP-UX 11.00   32      6       8      X/Open curses
 453               2000   U/Win         32/64   7/31    16     uses <STRONG>chtype</STRONG>
 454
 455        Notes:
 456
 457           Regarding HP-UX,
 458
 459           <STRONG>o</STRONG>   HP-UX  10.20  (1996) added support for 64-bit PA-RISC processors
 460               in 1996.
 461
 462           <STRONG>o</STRONG>   HP-UX 10.30 (1997) marked "curses_colr" obsolete.  That  version
 463               of curses was dropped with HP-UX 11.30 in 2006.
 464
 465           Regarding OSF/1 (and Tru64),
 466
 467           <STRONG>o</STRONG>   These  used  64-bit  hardware.   Like  ncurses, the OSF/1 curses
 468               interface is not customized for 32-bit and 64-bit versions.
 469
 470           <STRONG>o</STRONG>   Unlike  other  systems  which  evolved  from  AT&amp;T  code,  OSF/1
 471               provided a new implementation for X/Open curses.
 472
 473           Regarding Solaris,
 474
 475           <STRONG>o</STRONG>   The initial release of Solaris was in 1992.
 476
 477           <STRONG>o</STRONG>   The <EM>xpg4</EM> (X/Open) curses was developed by MKS from 1990 to 1995.
 478               Sun's copyright began in 1996.
 479
 480           <STRONG>o</STRONG>   Sun updated the X/Open curses interface after 64-bit support was
 481               introduced   in  1997,  but  did  not  modify  the  SVr4  curses
 482               interface.
 483
 484           Regarding U/Win,
 485
 486           <STRONG>o</STRONG>   Development of the curses library  began  in  1991,  stopped  in
 487               2000.
 488
 489           <STRONG>o</STRONG>   Color support was added in 1998.
 490
 491           <STRONG>o</STRONG>   The library uses only <STRONG>chtype</STRONG> (no <STRONG>cchar_t</STRONG>).
 492
 493        Once  X/Open  curses  was adopted in the mid-1990s, the constraint of a
 494        32-bit interface with many colors and wide-characters for <STRONG>chtype</STRONG> became
 495        a  moot  point.   The <STRONG>cchar_t</STRONG> structure (whose size and members are not
 496        specified in X/Open Curses) could be extended as needed.
 497
 498        Other interfaces are rarely used now:
 499
 500        <STRONG>o</STRONG>   BSD curses was improved slightly in 1993/1994 using Keith  Bostic's
 501            modification  to make the library 8-bit clean for <STRONG>nvi(1)</STRONG>.  He moved
 502            <EM>standout</EM> attribute to a structure member.
 503
 504            The resulting 4.4BSD curses was replaced by ncurses over  the  next
 505            ten years.
 506
 507        <STRONG>o</STRONG>   U/Win is rarely used now.
 508
 509
 510 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 511        <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>,
 512        <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 513
 514
 515
 516 ncurses 6.4                       2023-11-25                     <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
 517 </PRE>
 518 <div class="nav">
 519 <ul>
 520 <li><a href="#h2-NAME">NAME</a></li>
 521 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 522 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 523 <ul>
 524 <li><a href="#h3-Window-attributes">Window attributes</a></li>
 525 <li><a href="#h3-Legacy-window-attributes">Legacy window attributes</a></li>
 526 <li><a href="#h3-Change-character-rendition">Change character rendition</a></li>
 527 <li><a href="#h3-Change-window-color">Change window color</a></li>
 528 <li><a href="#h3-Standout">Standout</a></li>
 529 <li><a href="#h3-Video-Attributes">Video Attributes</a></li>
 530 </ul>
 531 </li>
 532 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 533 <li><a href="#h2-NOTES">NOTES</a></li>
 534 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 535 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 536 <li><a href="#h2-HISTORY">HISTORY</a></li>
 537 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 538 </ul>
 539 </div>
 540 </BODY>
 541 </HTML>