NetBSD/lib/libcurses/curses_attributes.3

.\"	$NetBSD: curses_attributes.3,v 1.2 2002/10/21 14:17:54 wiz Exp $
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Julian Coleman.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 13, 2002
.Dt CURSES_ATTRIBUTES 3
.Os
.Sh NAME
.Nm curses_attributes ,
.Nm attron ,
.Nm attroff ,
.Nm attrset ,
.Nm wattron ,
.Nm wattroff ,
.Nm wattrset ,
.Nm getattrs
.Nd curses general attribute manipulation routines
.Sh LIBRARY
.Lb libcurses
.Sh SYNOPSIS
.Fd #include \*[Lt]curses.h\*[Gt]
.Ft int
.Fn attron int
.Ft int
.Fn attroff int
.Ft int
.Fn attrset int
.Ft int
.Fn wattron int
.Ft int
.Fn wattroff int
.Ft int
.Fn wattrset int
.Ft chtype
.Fn getattrs "WINDOW *win"
.Sh DESCRIPTION
These functions manipulate attributes on
.Dv stdscr
or on the specified window.
The attributes that can be manipulated are:
.Pp
.Bl -tag -width "A_ALTCHARSET" -compact -offset indent
.It A_NORMAL
no special attributes are applied
.It A_STANDOUT
characters are displayed in standout mode
.It A_UNDERLINE
characters are displayed underlined
.It A_REVERSE
characters are displayed in inverse video
.It A_BLINK
characters blink
.It A_DIM
characters are displayed at a lower intensity
.It A_BOLD
characters are displayed at a higher intensity
.It A_BLANK
characters are added as blanks
.It A_PROTECT
characters are protected from modification
.It A_ALTCHARSET
characters are displayed using the alternate character set (ACS)
.El
along with color.
.Pp
The function
.Fn attron
turns on the attributes specified in
.Fa attr
on
.Dv stdscr .
.Pp
The function
.Fn attroff
turns off the attributes specified in
.Fa attr
on
.Dv stdscr .
.Pp
The function
.Fn attrset
sets the attributes of
.Dv stdscr
to those specified in
.Fa attr ,
turning off any others.
To turn off all the attributes (including color and alternate character set),
use
.Fn attrset A_NORMAL .
.Pp
Multiple attributes can be manipulated by combining the attributes
using a logical
.Em OR .
For example,
.Fn attron "A_REVERSE | A_BOLD"
will turn on both inverse video and higher intensity.
.Pp
The functions
.Fn wattron ,
.Fn wattroff
and
.Fn wattrset
are equivalent to
.Fn attron ,
.Fn attroff
and
.Fn attrset ,
respectively, excepting that the character is added to the window specified by
.Fa win .
.Pp
The function
.Fn getattrs
returns the attributes that are currently applied to window specified by
.Fa win .
.Sh RETURN VALUES
These functions return OK on success and ERR on failure.
.Sh SEE ALSO
.Xr curses_addch 3 ,
.Xr curses_addstr 3 ,
.Xr curses_background 3 ,
.Xr curses_color 3 ,
.Xr curses_insertch 3 ,
.Xr curses_standout 3 ,
.Xr curses_underscore 3
.Sh STANDARDS
The
.Nx
Curses library complies with the X/Open Curses specification, part of the
Single Unix Specification.
.Sh HISTORY
These functions first appeared in
.Nx 1.5 .
.Sh BUGS
Some terminals do not support characters with both color and other attributes
set.
In this case, the other attribute is displayed instead of the color attribute.