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