Debian Codegraph @

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

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