ncurses 5.3
[ncurses.git] / doc / html / man / curs_attr.3x.html
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2 <!-- 
3   * t
4   ****************************************************************************
5   * Copyright (c) 1998-2000,2002 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.26 2002/09/21 19:50:06 tom Exp @
32 -->
33 <HTML>
34 <HEAD>
35 <TITLE>curs_attr 3x</TITLE>
36 <link rev=made href="mailto:bug-ncurses@gnu.org">
37 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
38 </HEAD>
39 <BODY>
40 <H1>curs_attr 3x</H1>
41 <HR>
42 <PRE>
43 <!-- Manpage converted by man2html 3.0.1 -->
44
45 </PRE>
46 <H2>NAME</H2><PRE>
47        <STRONG>attroff</STRONG>,  <STRONG>wattroff</STRONG>,  <STRONG>attron</STRONG>,  <STRONG>wattron</STRONG>,  <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>,
48        <STRONG>color_set</STRONG>,  <STRONG>wcolor_set</STRONG>,  <STRONG>standend</STRONG>,  <STRONG>wstandend</STRONG>,   <STRONG>standout</STRONG>,
49        <STRONG>wstandout</STRONG>,   <STRONG>attr_get</STRONG>,   <STRONG>wattr_get</STRONG>,  <STRONG>attr_off</STRONG>,  <STRONG>wattr_off</STRONG>,
50        <STRONG>attr_on</STRONG>, <STRONG>wattr_on</STRONG>,  <STRONG>attr_set</STRONG>,  <STRONG>wattr_set</STRONG>,  <STRONG>chgat</STRONG>,  <STRONG>wchgat</STRONG>,
51        <STRONG>mvchgat</STRONG>, <STRONG>mvwchgat</STRONG>, <STRONG>PAIR_NUMBER</STRONG> - <STRONG>curses</STRONG> character and win-
52        dow attribute control routines
53
54
55 </PRE>
56 <H2>SYNOPSIS</H2><PRE>
57        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
58        <STRONG>int</STRONG> <STRONG>attroff(int</STRONG> <STRONG>attrs);</STRONG>
59        <STRONG>int</STRONG> <STRONG>wattroff(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>attrs);</STRONG>
60        <STRONG>int</STRONG> <STRONG>attron(int</STRONG> <STRONG>attrs);</STRONG>
61        <STRONG>int</STRONG> <STRONG>wattron(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>attrs);</STRONG>
62        <STRONG>int</STRONG> <STRONG>attrset(int</STRONG> <STRONG>attrs);</STRONG>
63        <STRONG>int</STRONG> <STRONG>wattrset(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>attrs);</STRONG>
64        <STRONG>int</STRONG> <STRONG>color_set(short</STRONG> <STRONG>color_pair_number,</STRONG> <STRONG>void*</STRONG> <STRONG>opts);</STRONG>
65        <STRONG>int</STRONG> <STRONG>wcolor_set(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>short</STRONG> <STRONG>color_pair_number,</STRONG>
66              <STRONG>void*</STRONG> <STRONG>opts);</STRONG>
67        <STRONG>int</STRONG> <STRONG>standend(void);</STRONG>
68        <STRONG>int</STRONG> <STRONG>wstandend(WINDOW</STRONG> <STRONG>*win);</STRONG>
69        <STRONG>int</STRONG> <STRONG>standout(void);</STRONG>
70        <STRONG>int</STRONG> <STRONG>wstandout(WINDOW</STRONG> <STRONG>*win);</STRONG>
71        <STRONG>int</STRONG> <STRONG>attr_get(attr_t</STRONG> <STRONG>*attrs,</STRONG> <STRONG>short</STRONG> <STRONG>*pair,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
72        <STRONG>int</STRONG> <STRONG>wattr_get(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>attr_t</STRONG> <STRONG>*attrs,</STRONG> <STRONG>short</STRONG> <STRONG>*pair,</STRONG>
73               <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
74        <STRONG>int</STRONG> <STRONG>attr_off(attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
75        <STRONG>int</STRONG> <STRONG>wattr_off(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
76        <STRONG>int</STRONG> <STRONG>attr_on(attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
77        <STRONG>int</STRONG> <STRONG>wattr_on(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
78        <STRONG>int</STRONG> <STRONG>attr_set(attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>short</STRONG> <STRONG>pair,</STRONG> <STRONG>void</STRONG> <STRONG>*opts);</STRONG>
79        <STRONG>int</STRONG> <STRONG>wattr_set(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>short</STRONG> <STRONG>pair,</STRONG>  <STRONG>void</STRONG>
80        <STRONG>*opts);</STRONG>
81        <STRONG>int</STRONG> <STRONG>chgat(int</STRONG> <STRONG>n,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attr,</STRONG> <STRONG>short</STRONG> <STRONG>color,</STRONG>
82              <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
83        <STRONG>int</STRONG> <STRONG>wchgat(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>n,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attr,</STRONG>
84              <STRONG>short</STRONG> <STRONG>color,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
85        <STRONG>int</STRONG> <STRONG>mvchgat(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>int</STRONG> <STRONG>n,</STRONG> <STRONG>attr_t</STRONG> <STRONG>attr,</STRONG>
86              <STRONG>short</STRONG> <STRONG>color,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
87        <STRONG>int</STRONG> <STRONG>mvwchgat(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>int</STRONG> <STRONG>n,</STRONG>
88              <STRONG>attr_t</STRONG> <STRONG>attr,</STRONG> <STRONG>short</STRONG> <STRONG>color,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*opts)</STRONG>
89
90
91 </PRE>
92 <H2>DESCRIPTION</H2><PRE>
93        These  routines  manipulate  the current attributes of the
94        named window.  The current attributes of a window apply to
95        all  characters that are written into the window with <STRONG>wad-</STRONG>
96        <STRONG>dch</STRONG>, <STRONG>waddstr</STRONG> and <STRONG>wprintw</STRONG>.  Attributes are  a  property  of
97        the  character,  and  move  with the character through any
98        scrolling and insert/delete line/character operations.  To
99        the  extent  possible,  they  are displayed as appropriate
100        modifications to the graphic rendition of  characters  put
101        on the screen.
102
103        The  routine  <STRONG>attrset</STRONG>  sets  the current attributes of the
104        given window to <EM>attrs</EM>.  The routine <STRONG>attroff</STRONG> turns off  the
105        named  attributes  without turning any other attributes on
106        or off.  The routine <STRONG>attron</STRONG> turns on the named  attributes
107        without affecting any others.  The routine <STRONG>standout</STRONG> is the
108        same as <STRONG>attron(A_STANDOUT)</STRONG>.  The routine <STRONG>standend</STRONG>  is  the
109        same as <STRONG>attrset(A_NORMAL)</STRONG> or <STRONG>attrset(0)</STRONG>, that is, it turns
110        off all attributes.
111
112        The  <STRONG>attrset</STRONG>  and  related  routines  do  not  affect  the
113        attributes  used when erasing portions of the window.  See
114        <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> for functions which  modify  the  attributes
115        used for erasing and clearing.
116
117        The  routine <STRONG>color_set</STRONG> sets the current color of the given
118        window to the foreground/background combination  described
119        by  the  color_pair_number. The parameter opts is reserved
120        for future use, applications must supply a null pointer.
121
122        The routine <STRONG>wattr_get</STRONG> returns the  current  attribute  and
123        color pair for the given window; <STRONG>attr_get</STRONG> returns the cur-
124        rent attribute and color pair for <STRONG>stdscr</STRONG>.   The  remaining
125        <STRONG>attr_</STRONG>*  functions  operate  exactly like the corresponding
126        <STRONG>attr</STRONG>* functions, except that they take arguments  of  type
127        <STRONG>attr_t</STRONG> rather than <STRONG>int</STRONG>.
128
129        The routine <STRONG>chgat</STRONG> changes the attributes of a given number
130        of characters starting at the current cursor  location  of
131        <STRONG>stdscr</STRONG>.   It  does not update the cursor and does not per-
132        form wrapping.  A character count of -1  or  greater  than
133        the  remaining window width means to change attributes all
134        the way to the end of the current line.  The <STRONG>wchgat</STRONG>  func-
135        tion generalizes this to any window; the <STRONG>mvwchgat</STRONG> function
136        does a cursor move before acting.  In these functions, the
137        color  argument  is  a  color-pair  index (as in the first
138        argument of  <EM>init</EM><STRONG>_</STRONG><EM>pair</EM>,  see  <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>).   The  <STRONG>opts</STRONG>
139        argument  is  not  presently used, but is reserved for the
140        future (leave it <STRONG>NULL</STRONG>).  Note that changing the attributes
141        does  not  imply that a subsequent <STRONG>refresh</STRONG> will update the
142        screen to match, since the character values are not  modi-
143        fied.   Use  <STRONG>touchwin</STRONG>  to  force  the  screen to match the
144        updated attributes.
145
146    <STRONG>Attributes</STRONG>
147        The following video attributes, defined in <STRONG>&lt;curses.h&gt;</STRONG>, can
148        be passed to the routines <STRONG>attron</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attrset</STRONG>, or
149        OR'ed with the characters passed to <STRONG>addch</STRONG>.
150
151         <STRONG>A_NORMAL</STRONG>        Normal display (no highlight)
152         <STRONG>A_STANDOUT</STRONG>      Best highlighting mode of the terminal.
153         <STRONG>A_UNDERLINE</STRONG>     Underlining
154         <STRONG>A_REVERSE</STRONG>       Reverse video
155         <STRONG>A_BLINK</STRONG>         Blinking
156         <STRONG>A_DIM</STRONG>           Half bright
157
158         <STRONG>A_BOLD</STRONG>          Extra bright or bold
159         <STRONG>A_PROTECT</STRONG>       Protected mode
160         <STRONG>A_INVIS</STRONG>         Invisible or blank mode
161         <STRONG>A_ALTCHARSET</STRONG>    Alternate character set
162         <STRONG>A_CHARTEXT</STRONG>      Bit-mask to extract a character
163         <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG>   Color-pair number <EM>n</EM>
164
165        The following macro is the reverse of <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG>:
166
167        <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM>) Returns the pair number associated
168                           with the <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> attribute.
169
170        The return values of many of these routines are not  mean-
171        ingful (they are implemented as macro-expanded assignments
172        and simply return their argument).  The SVr4  manual  page
173        claims (falsely) that these routines always return <STRONG>1</STRONG>.
174
175
176 </PRE>
177 <H2>NOTES</H2><PRE>
178        Note  that  <STRONG>attroff</STRONG>,  <STRONG>wattroff</STRONG>,  <STRONG>attron</STRONG>, <STRONG>wattron</STRONG>, <STRONG>attrset</STRONG>,
179        <STRONG>wattrset</STRONG>, <STRONG>standend</STRONG> and <STRONG>standout</STRONG> may be macros.
180
181
182 </PRE>
183 <H2>PORTABILITY</H2><PRE>
184        All these functions are supported in the XSI Curses  stan-
185        dard,  Issue  4.   The standard defined the dedicated type
186        for highlights, <STRONG>attr_t</STRONG>,  which  is  not  defined  in  SVr4
187        curses. The functions taking <STRONG>attr_t</STRONG> arguments are not sup-
188        ported under SVr4.
189
190        The XSI Curses standard states  that  whether  the  tradi-
191        tional  functions  <STRONG>attron</STRONG>/<STRONG>attroff</STRONG>/<STRONG>attrset</STRONG>  can  manipulate
192        attributes other than <STRONG>A_BLINK</STRONG>, <STRONG>A_BOLD</STRONG>,  <STRONG>A_DIM</STRONG>,  <STRONG>A_REVERSE</STRONG>,
193        <STRONG>A_STANDOUT</STRONG>,  or  <STRONG>A_UNDERLINE</STRONG> is "unspecified".  Under this
194        implementation as well as  SVr4  curses,  these  functions
195        correctly  manipulate  all other highlights (specifically,
196        <STRONG>A_ALTCHARSET</STRONG>, <STRONG>A_PROTECT</STRONG>, and <STRONG>A_INVIS</STRONG>).
197
198        XSI Curses added the new entry points, <STRONG>attr_get</STRONG>,  <STRONG>attr_on</STRONG>,
199        <STRONG>attr_off</STRONG>,   <STRONG>attr_set</STRONG>,   <STRONG>wattr_on</STRONG>,   <STRONG>wattr_off</STRONG>,  <STRONG>wattr_get</STRONG>,
200        <STRONG>wattr_set</STRONG>.  These are intended to work with a  new  series
201        of highlight macros prefixed with <STRONG>WA_</STRONG>.
202
203         <STRONG>WA_NORMAL</STRONG>       Normal display (no highlight)
204         <STRONG>WA_STANDOUT</STRONG>     Best highlighting mode of the terminal.
205         <STRONG>WA_UNDERLINE</STRONG>    Underlining
206         <STRONG>WA_REVERSE</STRONG>      Reverse video
207         <STRONG>WA_BLINK</STRONG>        Blinking
208         <STRONG>WA_DIM</STRONG>          Half bright
209         <STRONG>WA_BOLD</STRONG>         Extra bright or bold
210         <STRONG>WA_ALTCHARSET</STRONG>   Alternate character set
211
212        The XSI curses standard specifies that each pair of corre-
213        sponding <STRONG>A_</STRONG> and <STRONG>WA_</STRONG>-using functions operates on  the  same
214        current-highlight information.
215
216        The XSI standard extended conformance level adds new high-
217        lights <STRONG>A_HORIZONTAL</STRONG>, <STRONG>A_LEFT</STRONG>, <STRONG>A_LOW</STRONG>, <STRONG>A_RIGHT</STRONG>, <STRONG>A_TOP</STRONG>, <STRONG>A_VER-</STRONG>
218        <STRONG>TICAL</STRONG>  (and  corresponding <STRONG>WA_</STRONG> macros for each) which this
219        curses does not yet support.
220
221
222 </PRE>
223 <H2>SEE ALSO</H2><PRE>
224        <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>,
225        <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>, <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272 </PRE>
273 <HR>
274 <ADDRESS>
275 Man(1) output converted with
276 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
277 </ADDRESS>
278 </BODY>
279 </HTML>