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