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