348 lines
8.3 KiB
Groff
348 lines
8.3 KiB
Groff
.\" $NetBSD: curses_attributes.3,v 1.11 2021/08/03 07:58:50 nia 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.
|
|
.\" 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 July 27, 2021
|
|
.Dt CURSES_ATTRIBUTES 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm curses_attributes ,
|
|
.Nm attron ,
|
|
.Nm attroff ,
|
|
.Nm attrset ,
|
|
.Nm color_set ,
|
|
.Nm getattrs ,
|
|
.Nm termattrs ,
|
|
.Nm wattron ,
|
|
.Nm wattroff ,
|
|
.Nm wattrset ,
|
|
.Nm wcolor_set ,
|
|
.Nm attr_on ,
|
|
.Nm attr_off ,
|
|
.Nm attr_set ,
|
|
.Nm attr_get ,
|
|
.Nm term_attrs ,
|
|
.Nm wattr_on ,
|
|
.Nm wattr_off ,
|
|
.Nm wattr_set ,
|
|
.Nm wattr_get
|
|
.Nd curses general attribute manipulation routines
|
|
.Sh LIBRARY
|
|
.Lb libcurses
|
|
.Sh SYNOPSIS
|
|
.In curses.h
|
|
.Ft int
|
|
.Fn attron "int attr"
|
|
.Ft int
|
|
.Fn attroff "int attr"
|
|
.Ft int
|
|
.Fn attrset "int attr"
|
|
.Ft int
|
|
.Fn color_set "short pair" "void *opt"
|
|
.Ft chtype
|
|
.Fn getattrs "WINDOW *win"
|
|
.Ft chtype
|
|
.Fn termattrs "void"
|
|
.Ft int
|
|
.Fn wcolor_set "WINDOW *win" "short pair" "void *opt"
|
|
.Ft int
|
|
.Fn wattron "WINDOW * win" "int attr"
|
|
.Ft int
|
|
.Fn wattroff "WINDOW * win" "int attr"
|
|
.Ft int
|
|
.Fn wattrset "WINDOW * win" "int attr"
|
|
.Ft int
|
|
.Fn attr_on "attr_t attr" "void *opt"
|
|
.Ft int
|
|
.Fn attr_off "attr_t attr" "void *opt"
|
|
.Ft int
|
|
.Fn attr_set "attr_t attr" "short pair" "void *opt"
|
|
.Ft int
|
|
.Fn attr_get "attr_t *attr" "short *pair" "void *opt"
|
|
.Ft attr_t
|
|
.Fn term_attrs "void"
|
|
.Ft int
|
|
.Fn wattr_on "WINDOW *win" "attr_t attr" "void *opt"
|
|
.Ft int
|
|
.Fn wattr_off "WINDOW *win" "attr_t attr" "void *opt"
|
|
.Ft int
|
|
.Fn wattr_set "WINDOW *win" "attr_t attr" "short pair" "void *opt"
|
|
.Ft int
|
|
.Fn wattr_get "WINDOW *win" "attr_t *attr" "short *pair" "void *opt"
|
|
.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 "COLOR_PAIR(n)" -compact -offset indent
|
|
.It A_NORMAL
|
|
no special attributes are applied
|
|
.It A_STANDOUT
|
|
characters are displayed in the "best" supported highlighting mode of the
|
|
terminal
|
|
.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_INVIS
|
|
characters are added invisibly
|
|
.It A_PROTECT
|
|
characters are protected from modification
|
|
.It A_ALTCHARSET
|
|
characters are displayed using the alternate character set (ACS)
|
|
.It COLOR_PAIR(n)
|
|
characters are displayed using color pair n.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn attron
|
|
function turns on the attributes specified in
|
|
.Fa attr
|
|
on
|
|
.Dv stdscr ,
|
|
while the
|
|
.Fn attroff
|
|
function 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 function
|
|
.Fn color_set
|
|
sets the color pair attribute to the pair specified in
|
|
.Fa pair .
|
|
.Pp
|
|
The function
|
|
.Fn getattrs
|
|
returns the attributes that are currently applied to window specified by
|
|
.Fa win .
|
|
.Pp
|
|
The function
|
|
.Fn termattrs
|
|
returns the logical
|
|
.Em OR
|
|
of attributes that can be applied to the screen.
|
|
.Pp
|
|
The functions
|
|
.Fn wattron ,
|
|
.Fn wattroff ,
|
|
.Fn wattrset ,
|
|
and
|
|
.Fn wcolor_set
|
|
are equivalent to
|
|
.Fn attron ,
|
|
.Fn attroff
|
|
.Fn attrset ,
|
|
and
|
|
.Fn color_set
|
|
respectively, excepting that the attributes are applied to the window
|
|
specified by
|
|
.Fa win .
|
|
.Pp
|
|
The following functions additionally manipulate wide attributes on
|
|
.Dv stdscr
|
|
or on the specified window.
|
|
The additional wide attributes that can be manipulated are:
|
|
.Pp
|
|
.Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent
|
|
.It WA_STANDOUT
|
|
characters are displayed in the "best" supported highlighting mode of the
|
|
terminal
|
|
.It WA_UNDERLINE
|
|
characters are displayed underlined
|
|
.It WA_REVERSE
|
|
characters are displayed in inverse video
|
|
.It WA_BLINK
|
|
characters blink
|
|
.It WA_DIM
|
|
characters are displayed at a lower intensity
|
|
.It WA_BOLD
|
|
characters are displayed at a higher intensity
|
|
.It WA_INVIS
|
|
characters are added invisibly
|
|
.It WA_PROTECT
|
|
characters are protected from modification
|
|
.It WA_ALTCHARSET
|
|
characters are displayed using the alternate character set (ACS)
|
|
.It WA_LOW
|
|
characters are displayed with low highlight
|
|
.It WA_TOP
|
|
characters are displayed with top highlight
|
|
.It WA_HORIZONTAL
|
|
characters are displayed with horizontal highlight
|
|
.It WA_VERTICAL
|
|
characters are displayed with vertical highlight
|
|
.It WA_LEFT
|
|
characters are displayed with left highlight
|
|
.It WA_RIGHT
|
|
characters are displayed with right highlight
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn attr_on
|
|
function turns on the wide attributes specified in
|
|
.Fa attr
|
|
on
|
|
.Dv stdscr ,
|
|
while the
|
|
.Fn attr_off
|
|
function turns off the wide attributes specified in
|
|
.Fa attr
|
|
on
|
|
.Dv stdscr .
|
|
.Pp
|
|
The function
|
|
.Fn attr_set
|
|
sets the wide attributes of
|
|
.Dv stdscr
|
|
to those specified in
|
|
.Fa attr
|
|
and
|
|
.Fa pair ,
|
|
turning off any others.
|
|
Note that a color pair specified in
|
|
.Fa pair
|
|
will override any color pair specified in
|
|
.Fa attr .
|
|
.Pp
|
|
The function
|
|
.Fn attr_get
|
|
sets
|
|
.Fa attr
|
|
to the wide attributes and
|
|
.Fa pair
|
|
to the color pair currently applied to
|
|
.Dv stdscr .
|
|
Either of
|
|
.Fa attr
|
|
and
|
|
.Fa pair
|
|
can be
|
|
.Dv NULL ,
|
|
if the relevant value is of no interest.
|
|
.Pp
|
|
The function
|
|
.Fn term_attrs
|
|
returns the logical
|
|
.Em OR
|
|
of wide attributes that can be applied to the screen.
|
|
.Pp
|
|
The functions
|
|
.Fn wattr_on ,
|
|
.Fn wattr_off
|
|
and
|
|
.Fn wattr_set
|
|
are equivalent to
|
|
.Fn attr_on ,
|
|
.Fn attr_off
|
|
and
|
|
.Fn attr_set
|
|
respectively, excepting that the character is added to the window specified by
|
|
.Fa win .
|
|
.Pp
|
|
The function
|
|
.Fn wattr_get
|
|
is equivalent to
|
|
.Fn attr_get ,
|
|
excepting that the wide attributes and color pair currently applied to
|
|
.Fa win
|
|
are set.
|
|
.Pp
|
|
The following constants can be used to extract the components of a
|
|
.Dv chtype :
|
|
.Pp
|
|
.Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent
|
|
.It A_ATTRIBUTES
|
|
bit-mask containing attributes part
|
|
.It A_CHARTEXT
|
|
bit-mask containing character part
|
|
.It A_COLOR
|
|
bit-mask containing color-pair part
|
|
.El
|
|
.Sh RETURN VALUES
|
|
These functions return OK on success and ERR on failure.
|
|
.Sh SEE ALSO
|
|
.Xr curses_addch 3 ,
|
|
.Xr curses_addchstr 3 ,
|
|
.Xr curses_addstr 3 ,
|
|
.Xr curses_background 3 ,
|
|
.Xr curses_color 3 ,
|
|
.Xr curses_insch 3 ,
|
|
.Xr curses_standout 3 ,
|
|
.Xr curses_underscore 3
|
|
.Sh NOTES
|
|
The
|
|
.Fa opt
|
|
argument is not currently used but is reserved for a future version of the
|
|
specification.
|
|
.Sh STANDARDS
|
|
The
|
|
.Nx
|
|
Curses library complies with the X/Open Curses specification, part of the
|
|
Single Unix Specification.
|
|
.Pp
|
|
The
|
|
.Fn getattrs
|
|
function
|
|
is a
|
|
.Nx
|
|
extension.
|
|
.Sh HISTORY
|
|
These functions first appeared in
|
|
.Nx 1.5 .
|
|
.Sh CAVEATS
|
|
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.
|
|
.Pp
|
|
The standout attribute is a higher level alias and should not be mixed with
|
|
other attributes.
|