| blob | 307ea858b2c8a08bc20e2974c9b4c681a38e4715 |
1 .\" $NetBSD: curses_attributes.3,v 1.8 2008/04/30 13:10:51 martin Exp $
2 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
3 .\" All rights reserved.
4 .\"
5 .\" This code is derived from software contributed to The NetBSD Foundation
6 .\" by Julian Coleman.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
17 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
18 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
19 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 .\" POSSIBILITY OF SUCH DAMAGE.
27 .\"
28 .Dd March 14, 2008
29 .Dt CURSES_ATTRIBUTES 3
30 .Os
31 .Sh NAME
32 .Nm curses_attributes ,
33 .Nm attron ,
34 .Nm attroff ,
35 .Nm attrset ,
36 .Nm color_set ,
37 .Nm getattrs ,
38 .Nm termattrs ,
39 .Nm wattron ,
40 .Nm wattroff ,
41 .Nm wattrset ,
42 .Nm wcolor_set ,
43 .Nm attr_on ,
44 .Nm attr_off ,
45 .Nm attr_set ,
46 .Nm attr_get ,
47 .Nm term_attrs ,
48 .Nm wattr_on ,
49 .Nm wattr_off ,
50 .Nm wattr_set ,
51 .Nm wattr_get
52 .Nd curses general attribute manipulation routines
53 .Sh LIBRARY
54 .Lb libcurses
55 .Sh SYNOPSIS
56 .In curses.h
57 .Ft int
58 .Fn attron "int attr"
59 .Ft int
60 .Fn attroff "int attr"
61 .Ft int
62 .Fn attrset "int attr"
63 .Ft int
64 .Fn color_set "short pair" "void *opt"
65 .Ft chtype
66 .Fn getattrs "WINDOW *win"
67 .Ft chtype
68 .Fn termattrs "void"
69 .Ft int
70 .Fn wcolor_set "WINDOW *win" "short pair" "void *opt"
71 .Ft int
72 .Fn wattron "WINDOW * win" "int attr"
73 .Ft int
74 .Fn wattroff "WINDOW * win" "int attr"
75 .Ft int
76 .Fn wattrset "WINDOW * win" "int attr"
77 .Ft int
78 .Fn attr_on "attr_t attr" "void *opt"
79 .Ft int
80 .Fn attr_off "attr_t attr" "void *opt"
81 .Ft int
82 .Fn attr_set "attr_t attr" "short pair" "void *opt"
83 .Ft int
84 .Fn attr_get "attr_t *attr" "short *pair" "void *opt"
85 .Ft attr_t
86 .Fn term_attrs "void"
87 .Ft int
88 .Fn wattr_on "WINDOW *win" "attr_t attr" "void *opt"
89 .Ft int
90 .Fn wattr_off "WINDOW *win" "attr_t attr" "void *opt"
91 .Ft int
92 .Fn wattr_set "WINDOW *win" "attr_t attr" "short pair" "void *opt"
93 .Ft int
94 .Fn wattr_get "WINDOW *win" "attr_t *attr" "short *pair" "void *opt"
95 .Sh DESCRIPTION
96 These functions manipulate attributes on
97 .Dv stdscr
98 or on the specified window.
99 The attributes that can be manipulated are:
100 .Pp
101 .Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent
102 .It A_NORMAL
103 no special attributes are applied
104 .It A_STANDOUT
105 characters are displayed in standout mode
106 .It A_UNDERLINE
107 characters are displayed underlined
108 .It A_REVERSE
109 characters are displayed in inverse video
110 .It A_BLINK
111 characters blink
112 .It A_DIM
113 characters are displayed at a lower intensity
114 .It A_BOLD
115 characters are displayed at a higher intensity
116 .It A_INVIS
117 characters are added invisibly
118 .It A_PROTECT
119 characters are protected from modification
120 .It A_ALTCHARSET
121 characters are displayed using the alternate character set (ACS)
122 .It COLOR_PAIR(n)
123 characters are displayed using color pair n.
124 .El
125 .Pp
126 The
127 .Fn attron
128 function turns on the attributes specified in
129 .Fa attr
130 on
131 .Dv stdscr ,
132 while the
133 .Fn attroff
134 function turns off the attributes specified in
135 .Fa attr
136 on
137 .Dv stdscr .
138 .Pp
139 The function
140 .Fn attrset
141 sets the attributes of
142 .Dv stdscr
143 to those specified in
144 .Fa attr ,
145 turning off any others.
146 To turn off all the attributes (including color and alternate character set),
147 use
148 .Fn attrset A_NORMAL .
149 .Pp
150 Multiple attributes can be manipulated by combining the attributes
151 using a logical
152 .Em OR .
153 For example,
154 .Fn attron "A_REVERSE | A_BOLD"
155 will turn on both inverse video and higher intensity.
156 .Pp
157 The function
158 .Fn color_set
159 sets the color pair attribute to the pair specified in
160 .Fa pair .
161 .Pp
162 The function
163 .Fn getattrs
164 returns the attributes that are currently applied to window specified by
165 .Fa win .
166 .Pp
167 The function
168 .Fn termattrs
169 returns the logical
170 .Em OR
171 of attributes that can be applied to the screen.
172 .Pp
173 The functions
174 .Fn wattron ,
175 .Fn wattroff ,
176 .Fn wattrset ,
177 and
178 .Fn wcolor_set
179 are equivalent to
180 .Fn attron ,
181 .Fn attroff
182 .Fn attrset ,
183 and
184 .Fn color_set
185 respectively, excepting that the attributes are applied to the window
186 specified by
187 .Fa win .
188 .Pp
189 The following functions additionally manipulate wide attributes on
190 .Dv stdscr
191 or on the specified window.
192 The additional wide attributes that can be manipulated are:
193 .Pp
194 .Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent
195 .It WA_STANDOUT
196 characters are displayed in standout mode
197 .It WA_UNDERLINE
198 characters are displayed underlined
199 .It WA_REVERSE
200 characters are displayed in inverse video
201 .It WA_BLINK
202 characters blink
203 .It WA_DIM
204 characters are displayed at a lower intensity
205 .It WA_BOLD
206 characters are displayed at a higher intensity
207 .It WA_INVIS
208 characters are added invisibly
209 .It WA_PROTECT
210 characters are protected from modification
211 .It WA_ALTCHARSET
212 characters are displayed using the alternate character set (ACS)
213 .It WA_LOW
214 characters are displayed with low highlight
215 .It WA_TOP
216 characters are displayed with top highlight
217 .It WA_HORIZONTAL
218 characters are displayed with horizontal highlight
219 .It WA_VERTICAL
220 characters are displayed with vertical highlight
221 .It WA_LEFT
222 characters are displayed with left highlight
223 .It WA_RIGHT
224 characters are displayed with right highlight
225 .El
226 .Pp
227 The
228 .Fn attr_on
229 function turns on the wide attributes specified in
230 .Fa attr
231 on
232 .Dv stdscr ,
233 while the
234 .Fn attr_off
235 function turns off the wide attributes specified in
236 .Fa attr
237 on
238 .Dv stdscr .
239 .Pp
240 The function
241 .Fn attr_set
242 sets the wide attributes of
243 .Dv stdscr
244 to those specified in
245 .Fa attr
246 and
247 .Fa pair ,
248 turning off any others.
249 Note that a color pair specified in
250 .Fa pair
251 will override any color pair specified in
252 .Fa attr .
253 .Pp
254 The function
255 .Fn attr_get
256 sets
257 .Fa attr
258 to the wide attributes and
259 .Fa pair
260 to the color pair currently applied to
261 .Dv stdscr .
262 Either of
263 .Fa attr
264 and
265 .Fa pair
266 can be
267 .Dv NULL ,
268 if the relevant value is of no interest.
269 .Pp
270 The function
271 .Fn term_attrs
272 returns the logical
273 .Em OR
274 of wide attributes that can be applied to the screen.
275 .Pp
276 The functions
277 .Fn wattr_on ,
278 .Fn wattr_off
279 and
280 .Fn wattr_set
281 are equivalent to
282 .Fn attr_on ,
283 .Fn attr_off
284 and
285 .Fn attr_set
286 respectively, excepting that the character is added to the window specified by
287 .Fa win .
288 .Pp
289 The function
290 .Fn wattr_get
291 is equivalent to
292 .Fn attr_get ,
293 excepting that the wide attributes and color pair currently applied to
294 .Fa win
295 are set.
296 .Pp
297 The following constants can be used to extract the components of a
298 .Dv chtype :
299 .Pp
300 .Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent
301 .It A_ATTRIBUTES
302 bit-mask containing attributes part
303 .It A_CHARTEXT
304 bit-mask containing character part
305 .It A_COLOR
306 bit-mask containing color-pair part
307 .El
308 .Sh RETURN VALUES
309 These functions return OK on success and ERR on failure.
310 .Sh SEE ALSO
311 .Xr curses_addch 3 ,
312 .Xr curses_addchstr 3 ,
313 .Xr curses_addstr 3 ,
314 .Xr curses_background 3 ,
315 .Xr curses_color 3 ,
316 .Xr curses_insertch 3 ,
317 .Xr curses_standout 3 ,
318 .Xr curses_underscore 3
319 .Sh NOTES
320 The
321 .Fa opt
322 argument is not currently used but is reserved for a future version of the
323 specification.
324 .Sh STANDARDS
325 The
326 .Nx
327 Curses library complies with the X/Open Curses specification, part of the
328 Single Unix Specification.
329 .Pp
330 The
331 .Fn getattrs
332 function
333 is a
334 .Nx
335 extension.
336 .Sh HISTORY
337 These functions first appeared in
338 .Nx 1.5 .
339 .Sh BUGS
340 Some terminals do not support characters with both color and other attributes
341 set.
342 In this case, the other attribute is displayed instead of the color attribute.