'\" t
.\"***************************************************************************
-.\" Copyright 2018-2021,2022 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.71 2022/02/12 20:07:29 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
\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:
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