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