lib/libcurses/curses_attributes.3

   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 .\" 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.