'\" t
.\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 2018-2022,2023 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_attr.3x,v 1.70 2021/12/25 21:49:32 tom Exp $
-.TH curs_attr 3X ""
+.\" $Id: curs_attr.3x,v 1.84 2023/09/16 23:34:43 tom Exp $
+.TH curs_attr 3X 2023-09-16 "ncurses 6.4" "Library calls"
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.el .ds '' ''
+.ie n .ds CW R
+.el \{
+.ie \n(.g .ds CW CR
+.el .ds CW CW
+.\}
.de NS
.ie n .sp
.el .sp .5
.ie n .in +4
.el .in +2
.nf
-.ft C \" Courier
+.ft \*(CW
..
.de NE
.fi
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.na
-.hy 0
.\" ---------------------------------------------------------------------------
.SH NAME
-.\" attr_get
-\fBattr_get\fP,
-\fBwattr_get\fP,
-\fBattr_set\fP,
-\fBwattr_set\fP,
-.\" .br
-\fBattr_off\fP,
-\fBwattr_off\fP,
-\fBattr_on\fP,
-\fBwattr_on\fP,
-.\" .br
-\fBattroff\fP,
-\fBwattroff\fP,
-\fBattron\fP,
-\fBwattron\fP,
-\fBattrset\fP,
-\fBwattrset\fP,
-.\" .br
-\fBchgat\fP,
-\fBwchgat\fP,
-\fBmvchgat\fP,
-\fBmvwchgat\fP,
-.\" .br
-\fBcolor_set\fP,
-\fBwcolor_set\fP,
-.\" .br
-\fBstandend\fP,
-\fBwstandend\fP,
-\fBstandout\fP,
-\fBwstandout\fP \- \fBcurses\fP character and window attribute control routines
-.ad
-.hy
+\fB\%attr_get\fP,
+\fB\%wattr_get\fP,
+\fB\%attr_set\fP,
+\fB\%wattr_set\fP,
+\fB\%attr_off\fP,
+\fB\%wattr_off\fP,
+\fB\%attr_on\fP,
+\fB\%wattr_on\fP,
+\fB\%attroff\fP,
+\fB\%wattroff\fP,
+\fB\%attron\fP,
+\fB\%wattron\fP,
+\fB\%attrset\fP,
+\fB\%wattrset\fP,
+\fB\%chgat\fP,
+\fB\%wchgat\fP,
+\fB\%mvchgat\fP,
+\fB\%mvwchgat\fP,
+\fB\%color_set\fP,
+\fB\%wcolor_set\fP,
+\fB\%standend\fP,
+\fB\%wstandend\fP,
+\fB\%standout\fP,
+\fB\%wstandout\fP \-
+manipulate attributes of character cells in \fIcurses\fR windows
.\" ---------------------------------------------------------------------------
.SH SYNOPSIS
\fB#include <curses.h>\fP
.sp
-\fBint attr_get(attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fP
+\fBint attr_get(attr_t *\fIattrs\fB, short *\fIpair\fB, void *\fIopts\fB);\fR
.br
-\fBint wattr_get(WINDOW *\fP\fIwin\fP\fB, attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB,\fP \fBvoid *\fP\fIopts\fP\fB);\fP
+\fBint wattr_get(WINDOW *\fIwin\fB, attr_t *\fIattrs\fB, short *\fIpair\fB,\fR \fBvoid *\fIopts\fB);\fR
.br
-\fBint attr_set(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fP
+\fBint attr_set(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR
.br
-\fBint wattr_set(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fP
+\fBint wattr_set(WINDOW *\fIwin\fB, attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR
.sp
-\fBint attr_off(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fP
+\fBint attr_off(attr_t \fIattrs\fB, void *\fIopts\fB);\fR
.br
-\fBint wattr_off(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fP
+\fBint wattr_off(WINDOW *\fIwin\fB, attr_t \fIattrs\fB, void *\fIopts\fB);\fR
.br
-\fBint attr_on(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fP
+\fBint attr_on(attr_t \fIattrs\fB, void *\fIopts\fB);\fR
.br
-\fBint wattr_on(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fP
+\fBint wattr_on(WINDOW *\fIwin\fB, attr_t \fIattrs\fB, void *\fIopts\fB);\fR
.sp
-\fBint attroff(int \fP\fIattrs);\fP
+\fBint attroff(int \fIattrs);\fR
.br
-\fBint wattroff(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fP
+\fBint wattroff(WINDOW *\fIwin\fB, int \fIattrs\fB);\fR
.br
-\fBint attron(int \fP\fIattrs\fP\fB);\fP
+\fBint attron(int \fIattrs\fB);\fR
.br
-\fBint wattron(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fP
+\fBint wattron(WINDOW *\fIwin\fB, int \fIattrs\fB);\fR
.br
-\fBint attrset(int \fP\fIattrs\fP\fB);\fP
+\fBint attrset(int \fIattrs\fB);\fR
.br
-\fBint wattrset(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fP
+\fBint wattrset(WINDOW *\fIwin\fB, int \fIattrs\fB);\fR
.sp
-\fBint chgat(int \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB, short \fP\fIpair\fP\fB,\fP \fBconst void *\fP\fIopts\fP\fB);\fP
+\fBint chgat(int \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB,\fR \fBconst void *\fIopts\fB);\fR
.br
-\fBint wchgat(WINDOW *\fP\fIwin\fP\fB,\fP
- \fBint \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fP \fBshort \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fP
+\fBint wchgat(WINDOW *\fIwin\fB,\fR
+ \fBint \fIn\fB, attr_t \fIattr\fB,\fR \fBshort \fIpair\fB, const void *\fIopts\fB);\fR
.br
-\fBint mvchgat(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB,\fP
- \fBint \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fP \fBshort \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fP
+\fBint mvchgat(int \fIy\fB, int \fIx\fB,\fR
+ \fBint \fIn\fB, attr_t \fIattr\fB,\fR \fBshort \fIpair\fB, const void *\fIopts\fB);\fR
.br
-\fBint mvwchgat(WINDOW *\fP\fIwin, int \fP\fIy, int \fP\fIx\fP\fB,\fP
- \fBint \fP\fIn,\fP \fBattr_t \fP\fIattr\fP\fB, short \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fP
+\fBint mvwchgat(WINDOW *\fIwin, int \fIy, int \fIx\fB,\fR
+ \fBint \fIn,\fR \fBattr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR
.sp
-\fBint color_set(short \fP\fIpair\fP\fB, void* \fP\fIopts\fP\fB);\fP
+\fBint color_set(short \fIpair\fB, void* \fIopts\fB);\fR
.br
-\fBint wcolor_set(WINDOW *\fP\fIwin\fP\fB, short \fP\fIpair\fP\fB,\fP \fBvoid* \fP\fIopts);\fP
+\fBint wcolor_set(WINDOW *\fIwin\fB, short \fIpair\fB,\fR \fBvoid* \fIopts);\fR
.sp
\fBint standend(void);\fP
.br
-\fBint wstandend(WINDOW *\fP\fIwin\fP\fB);\fP
+\fBint wstandend(WINDOW *\fIwin\fB);\fR
.br
\fBint standout(void);\fP
.br
-\fBint wstandout(WINDOW *\fP\fIwin\fP\fB);\fP
+\fBint wstandout(WINDOW *\fIwin\fB);\fR
.\" ---------------------------------------------------------------------------
.SH DESCRIPTION
-.PP
These routines manipulate the current attributes of the named window,
which then apply to all characters that are written into
the window with \fBwaddch\fP, \fBwaddstr\fP and \fBwprintw\fP.
\fBattr_set\fP is the \fBstdscr\fP variant of \fBwattr_set\fP.
.\" ---------------------------------------------------------------------------
.SS Window attributes
-.PP
There are two sets of functions:
.bP
functions for manipulating the window attributes and color:
However, if the value does not fit, then the \fBCOLOR_PAIR\fP macro
uses only the bits that fit.
For example, because in ncurses \fBA_COLOR\fP has eight (8) bits,
-then \fBCOLOR_PAIR(\fP\fI259\fP\fB)\fP is 4
+then \fBCOLOR_PAIR(\fI259\fB)\fR is 4
(i.e., 259 is 4 more than the limit 255).
.PP
The \fBPAIR_NUMBER\fP macro extracts a pair number from an \fBint\fP
although ncurses provides \fBgetattrs\fP (see curs_legacy(3X)).
.\" ---------------------------------------------------------------------------
.SS Change character rendition
-.PP
The routine \fBchgat\fP changes the attributes of a given number of characters
starting at the current cursor location of \fBstdscr\fP.
It does not update
foreground/background combination described by the color \fIpair\fP parameter.
.\" ---------------------------------------------------------------------------
.SS Standout
-.PP
The routine \fBstandout\fP is
the same as \fBattron(A_STANDOUT)\fP.
The routine \fBstandend\fP is the same
.PP
These video attributes are supported by \fBattr_on\fP and related functions
(which also support the attributes recognized by \fBattron\fP, etc.):
+.PP
.RS
.TS
l l
as well as clues such as the alternate character set implementation.
A 32-bit library can be used on a 64-bit system,
but not necessarily the reverse.
+.PP
.RS
.TS
l l l l l l
U/Win is rarely used now.
.\" ---------------------------------------------------------------------------
.SH EXTENSIONS
-.PP
This implementation provides the \fBA_ITALIC\fP attribute for terminals
which have the \fBenter_italics_mode\fP (\fBsitm\fP)
and \fBexit_italics_mode\fP (\fBritm\fP) capabilities.
have a color-pair parameter to support \fIextended color pairs\fP:
.bP
For functions which modify the color, e.g.,
-\fBwattr_set\fP,
+\fBwattr_set\fP and \fBwattr_on\fP,
if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
and used to set the color pair instead of the \fBshort\fP \fIpair\fP parameter.
.bP
\fBwattr_get\fP,
if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
and used to retrieve the color pair as an \fBint\fP value,
-in addition
+in addition to
retrieving it via the standard pointer to \fBshort\fP parameter.
-.PP
-The remaining functions which have \fIopts\fP,
-but do not manipulate color,
-e.g., \fBwattr_on\fP and \fBwattr_off\fP
-are not used by this implementation except to check that they are \fBNULL\fP.
+.bP
+For functions which turn attributes off, e.g.,
+\fBwattr_off\fP,
+the \fIopts\fP parameter is ignored except
+except to check that it is \fBNULL\fP.
.\" ---------------------------------------------------------------------------
.SH PORTABILITY
These functions are supported in the XSI Curses standard, Issue 4.
In this implementation (as in many others), the values happen to be
the same because it simplifies copying information between
\fBchtype\fP and \fBcchar_t\fP variables.
+.bP
+Because ncurses's \fBattr_t\fP can hold a color pair
+(in the \fBA_COLOR\fP field),
+a call to
+\fBwattr_on\fP,
+\fBwattr_off\fP, or
+\fBwattr_set\fP
+may alter the window's color.
+If the color pair information in the attribute parameter is zero,
+no change is made to the window's color.
+.IP
+This is consistent with SVr4 curses;
+X/Open Curses does not specify this.
.PP
The XSI standard extended conformance level adds new highlights
\fBA_HORIZONTAL\fP, \fBA_LEFT\fP, \fBA_LOW\fP, \fBA_RIGHT\fP, \fBA_TOP\fP,
projects / ncurses.git / blobdiff