1.\" $NetBSD: curses_attributes.3,v 1.6 2003/05/21 21:22:15 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 May 21, 2003 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 wattron , 40.Nm wattroff , 41.Nm wattrset , 42.Nm getattrs , 43.Nm attr_on , 44.Nm attr_off , 45.Nm attr_set , 46.Nm color_set , 47.Nm attr_get , 48.Nm wattr_on , 49.Nm wattr_off , 50.Nm wattr_set , 51.Nm wcolor_set , 52.Nm wattr_get 53.Nd curses general attribute manipulation routines 54.Sh LIBRARY 55.Lb libcurses 56.Sh SYNOPSIS 57.In curses.h 58.Ft int 59.Fn attron "int attr" 60.Ft int 61.Fn attroff "int attr" 62.Ft int 63.Fn attrset "int attr" 64.Ft int 65.Fn wattron "WINDOW * win" "int attr" 66.Ft int 67.Fn wattroff "WINDOW * win" "int attr" 68.Ft int 69.Fn wattrset "WINDOW * win" "int attr" 70.Ft chtype 71.Fn getattrs "WINDOW *win" 72.Ft int 73.Fn attr_on "attr_t attr" "void *opt" 74.Ft int 75.Fn attr_off "attr_t attr" "void *opt" 76.Ft int 77.Fn attr_set "attr_t attr" "short pair" "void *opt" 78.Ft int 79.Fn color_set "short pair" "void *opt" 80.Ft int 81.Fn attr_get "attr_t *attr" "short *pair" "void *opt" 82.Ft int 83.Fn wattr_on "WINDOW *win" "attr_t attr" "void *opt" 84.Ft int 85.Fn wattr_off "WINDOW *win" "attr_t attr" "void *opt" 86.Ft int 87.Fn wattr_set "WINDOW *win" "attr_t attr" "short pair" "void *opt" 88.Ft int 89.Fn wcolor_set "WINDOW *win" "short pair" "void *opt" 90.Ft int 91.Fn wattr_get "WINDOW *win" "attr_t *attr" "short *pair" "void *opt" 92.Sh DESCRIPTION 93These functions manipulate attributes on 94.Dv stdscr 95or on the specified window. 96The attributes that can be manipulated are: 97.Pp 98.Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent 99.It A_NORMAL 100no special attributes are applied 101.It A_STANDOUT 102characters are displayed in standout mode 103.It A_UNDERLINE 104characters are displayed underlined 105.It A_REVERSE 106characters are displayed in inverse video 107.It A_BLINK 108characters blink 109.It A_DIM 110characters are displayed at a lower intensity 111.It A_BOLD 112characters are displayed at a higher intensity 113.It A_BLANK 114characters are added as blanks 115.It A_PROTECT 116characters are protected from modification 117.It A_ALTCHARSET 118characters are displayed using the alternate character set (ACS) 119.It COLOR_PAIR(n) 120characters are displayed using color pair n. 121.El 122.Pp 123The functions 124.Fn attron 125and 126.Fn attr_on 127turn on the attributes specified in 128.Fa attr 129on 130.Dv stdscr . 131.Pp 132The functions 133.Fn attroff 134and 135.Fn attr_off 136turn off the attributes specified in 137.Fa attr 138on 139.Dv stdscr . 140.Pp 141The function 142.Fn attrset 143sets the attributes of 144.Dv stdscr 145to those specified in 146.Fa attr , 147turning off any others. 148To turn off all the attributes (including color and alternate character set), 149use 150.Fn attrset A_NORMAL . 151.Pp 152Multiple attributes can be manipulated by combining the attributes 153using a logical 154.Em OR . 155For example, 156.Fn attron "A_REVERSE | A_BOLD" 157will turn on both inverse video and higher intensity. 158.Pp 159The function 160.Fn attr_set 161sets the attributes of 162.Dv stdscr 163to those specified in 164.Fa attr 165and 166.Fa pair , 167turning off any others. 168Note that a color pair specified in 169.Fa pair 170will override any color pair specified in 171.Fa attr . 172.Pp 173The function 174.Fn color_set 175sets the color pair attribute to the pair specified in 176.Fa pair . 177.Pp 178The functions 179.Fn wattron , 180.Fn wattr_on , 181.Fn wattroff , 182.Fn wattr_on , 183.Fn wattrset , 184.Fn wattr_set 185and 186.Fn wcolor_set 187are equivalent to 188.Fn attron , 189.Fn attr_on , 190.Fn attroff 191.Fn attr_off , 192.Fn attrset , 193.Fn attr_set 194and 195.Fn color_set 196respectively, excepting that the character is added to the window specified by 197.Fa win . 198.Pp 199The function 200.Fn getattrs 201returns the attributes that are currently applied to window specified by 202.Fa win . 203.Pp 204The function 205.Fn attr_get 206sets 207.Fa attr 208to the attributes and 209.Fa pair 210to the color pair currently applied to 211.Dv stdscr . 212Either of 213.Fa attr 214and 215.Fa pair 216can be 217.Dv NULL , 218if the relevant value is of no interest. 219.Pp 220The function 221.Fn wattr_get 222is equivalent to 223.Fn attr_get , 224excepting that the attributes and color pair currently applied to 225.Fa win 226are set. 227.Sh RETURN VALUES 228These functions return OK on success and ERR on failure. 229.Sh SEE ALSO 230.Xr curses_addch 3 , 231.Xr curses_addchstr 3 , 232.Xr curses_addstr 3 , 233.Xr curses_background 3 , 234.Xr curses_color 3 , 235.Xr curses_insertch 3 , 236.Xr curses_standout 3 , 237.Xr curses_underscore 3 238.Sh NOTES 239The 240.Fa opt 241argument is not currently used but is reserved for a future version of the 242specification. 243.Sh STANDARDS 244The 245.Nx 246Curses library complies with the X/Open Curses specification, part of the 247Single Unix Specification. 248.Sh HISTORY 249These functions first appeared in 250.Nx 1.5 . 251.Sh BUGS 252Some terminals do not support characters with both color and other attributes 253set. 254In this case, the other attribute is displayed instead of the color attribute. 255