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 96These functions manipulate attributes on 97.Dv stdscr 98or on the specified window. 99The attributes that can be manipulated are: 100.Pp 101.Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent 102.It A_NORMAL 103no special attributes are applied 104.It A_STANDOUT 105characters are displayed in standout mode 106.It A_UNDERLINE 107characters are displayed underlined 108.It A_REVERSE 109characters are displayed in inverse video 110.It A_BLINK 111characters blink 112.It A_DIM 113characters are displayed at a lower intensity 114.It A_BOLD 115characters are displayed at a higher intensity 116.It A_INVIS 117characters are added invisibly 118.It A_PROTECT 119characters are protected from modification 120.It A_ALTCHARSET 121characters are displayed using the alternate character set (ACS) 122.It COLOR_PAIR(n) 123characters are displayed using color pair n. 124.El 125.Pp 126The 127.Fn attron 128function turns on the attributes specified in 129.Fa attr 130on 131.Dv stdscr , 132while the 133.Fn attroff 134function turns off the attributes specified in 135.Fa attr 136on 137.Dv stdscr . 138.Pp 139The function 140.Fn attrset 141sets the attributes of 142.Dv stdscr 143to those specified in 144.Fa attr , 145turning off any others. 146To turn off all the attributes (including color and alternate character set), 147use 148.Fn attrset A_NORMAL . 149.Pp 150Multiple attributes can be manipulated by combining the attributes 151using a logical 152.Em OR . 153For example, 154.Fn attron "A_REVERSE | A_BOLD" 155will turn on both inverse video and higher intensity. 156.Pp 157The function 158.Fn color_set 159sets the color pair attribute to the pair specified in 160.Fa pair . 161.Pp 162The function 163.Fn getattrs 164returns the attributes that are currently applied to window specified by 165.Fa win . 166.Pp 167The function 168.Fn termattrs 169returns the logical 170.Em OR 171of attributes that can be applied to the screen. 172.Pp 173The functions 174.Fn wattron , 175.Fn wattroff , 176.Fn wattrset , 177and 178.Fn wcolor_set 179are equivalent to 180.Fn attron , 181.Fn attroff 182.Fn attrset , 183and 184.Fn color_set 185respectively, excepting that the attributes are applied to the window 186specified by 187.Fa win . 188.Pp 189The following functions additionally manipulate wide attributes on 190.Dv stdscr 191or on the specified window. 192The additional wide attributes that can be manipulated are: 193.Pp 194.Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent 195.It WA_STANDOUT 196characters are displayed in standout mode 197.It WA_UNDERLINE 198characters are displayed underlined 199.It WA_REVERSE 200characters are displayed in inverse video 201.It WA_BLINK 202characters blink 203.It WA_DIM 204characters are displayed at a lower intensity 205.It WA_BOLD 206characters are displayed at a higher intensity 207.It WA_INVIS 208characters are added invisibly 209.It WA_PROTECT 210characters are protected from modification 211.It WA_ALTCHARSET 212characters are displayed using the alternate character set (ACS) 213.It WA_LOW 214characters are displayed with low highlight 215.It WA_TOP 216characters are displayed with top highlight 217.It WA_HORIZONTAL 218characters are displayed with horizontal highlight 219.It WA_VERTICAL 220characters are displayed with vertical highlight 221.It WA_LEFT 222characters are displayed with left highlight 223.It WA_RIGHT 224characters are displayed with right highlight 225.El 226.Pp 227The 228.Fn attr_on 229function turns on the wide attributes specified in 230.Fa attr 231on 232.Dv stdscr , 233while the 234.Fn attr_off 235function turns off the wide attributes specified in 236.Fa attr 237on 238.Dv stdscr . 239.Pp 240The function 241.Fn attr_set 242sets the wide attributes of 243.Dv stdscr 244to those specified in 245.Fa attr 246and 247.Fa pair , 248turning off any others. 249Note that a color pair specified in 250.Fa pair 251will override any color pair specified in 252.Fa attr . 253.Pp 254The function 255.Fn attr_get 256sets 257.Fa attr 258to the wide attributes and 259.Fa pair 260to the color pair currently applied to 261.Dv stdscr . 262Either of 263.Fa attr 264and 265.Fa pair 266can be 267.Dv NULL , 268if the relevant value is of no interest. 269.Pp 270The function 271.Fn term_attrs 272returns the logical 273.Em OR 274of wide attributes that can be applied to the screen. 275.Pp 276The functions 277.Fn wattr_on , 278.Fn wattr_off 279and 280.Fn wattr_set 281are equivalent to 282.Fn attr_on , 283.Fn attr_off 284and 285.Fn attr_set 286respectively, excepting that the character is added to the window specified by 287.Fa win . 288.Pp 289The function 290.Fn wattr_get 291is equivalent to 292.Fn attr_get , 293excepting that the wide attributes and color pair currently applied to 294.Fa win 295are set. 296.Pp 297The 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 302bit-mask containing attributes part 303.It A_CHARTEXT 304bit-mask containing character part 305.It A_COLOR 306bit-mask containing color-pair part 307.El 308.Sh RETURN VALUES 309These 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 320The 321.Fa opt 322argument is not currently used but is reserved for a future version of the 323specification. 324.Sh STANDARDS 325The 326.Nx 327Curses library complies with the X/Open Curses specification, part of the 328Single Unix Specification. 329.Pp 330The 331.Fn getattrs 332function 333is a 334.Nx 335extension. 336.Sh HISTORY 337These functions first appeared in 338.Nx 1.5 . 339.Sh BUGS 340Some terminals do not support characters with both color and other attributes 341set. 342In this case, the other attribute is displayed instead of the color attribute. 343