X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_attr.3x;h=ac448b4ecc7dfddfbf684b0e1e86caabebdc4cda;hb=6641601a9dd7f34deeaa978899b3730b27635afb;hp=71a2bb56cc0cb7eeb680212f6de37dd9160c36d9;hpb=74433bcf4f6fe40862a28f3c00edaedcd5054b01;p=ncurses.git

diff --git a/man/curs_attr.3x b/man/curs_attr.3x
index 71a2bb56..ac448b4e 100644
--- a/man/curs_attr.3x
+++ b/man/curs_attr.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey                                *
+.\" Copyright 2018-2021,2022 Thomas E. Dickey                                *
 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
@@ -28,7 +28,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_attr.3x,v 1.70 2021/12/25 21:49:32 tom Exp $
+.\" $Id: curs_attr.3x,v 1.72 2022/04/16 19:18:32 tom Exp $
 .TH curs_attr 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -92,56 +92,56 @@
 .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
@@ -212,7 +212,7 @@ attr_set(A_BOLD, \fIpair\fP, NULL);
 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
@@ -484,7 +484,7 @@ This implementation uses that parameter in ABI 6 for the functions which
 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
@@ -492,13 +492,13 @@ For functions which retrieve the color, e.g.,
 \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.
@@ -568,6 +568,19 @@ represent \fBA_CHARTEXT\fP or \fBA_COLOR\fP.
 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,