ncurses 6.0 - patch 20151024

[ncurses.git] / man / curs_attr.3x

diff --git a/man/curs_attr.3x b/man/curs_attr.3x
index 7a0d1588d516c8c3163418f3df8cea9adc2e2ee2..d126b8b3189843945869973cbb13e723c7be9ce8 100644 (file)
--- a/man/curs_attr.3x
+++ b/man/curs_attr.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
 '\" t
 .\"***************************************************************************

-.\" Copyright (c) 1998-2010,2013 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2013,2015 Free Software Foundation, Inc.              *

 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *


@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_attr.3x,v 1.39 2013/09/21 20:39:49 Sven.Joachim Exp $
+.\" $Id: curs_attr.3x,v 1.42 2015/10/24 19:10:42 Sven.Joachim Exp $

 .TH curs_attr 3X ""
 .na
 .hy 0
 .TH curs_attr 3X ""
 .na
 .hy 0


@@ -62,74 +62,82 @@
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
 .br
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
 .br

-\fBint attroff(int attrs);\fR
+\fBint attroff(int \fP\fIattrs);\fR

 .br
 .br

-\fBint wattroff(WINDOW *win, int attrs);\fR
+\fBint wattroff(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR

 .br
 .br

-\fBint attron(int attrs);\fR
+\fBint attron(int \fP\fIattrs\fP\fB);\fR

 .br
 .br

-\fBint wattron(WINDOW *win, int attrs);\fR
+\fBint wattron(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR

 .br
 .br

-\fBint attrset(int attrs);\fR
+\fBint attrset(int \fP\fIattrs\fP\fB);\fR

 .br
 .br

-\fBint wattrset(WINDOW *win, int attrs);\fR
+\fBint wattrset(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR

 .br
 .br

-\fBint color_set(short color_pair_number, void* opts);\fR
+\fBint color_set(short \fP\fIcolor_pair_number\fP\fB, void* \fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint wcolor_set(WINDOW *win, short color_pair_number,\fR
-      \fBvoid* opts);\fR
+\fBint wcolor_set(WINDOW *\fP\fIwin\fP\fB, short \fP\fIcolor_pair_number\fP\fB,\fR
+      \fBvoid* \fP\fIopts);\fR

 .br
 \fBint standend(void);\fR
 .br
 .br
 \fBint standend(void);\fR
 .br

-\fBint wstandend(WINDOW *win);\fR
+\fBint wstandend(WINDOW *\fP\fIwin\fP\fB);\fR

 .br
 \fBint standout(void);\fR
 .br
 .br
 \fBint standout(void);\fR
 .br

-\fBint wstandout(WINDOW *win);\fR
+\fBint wstandout(WINDOW *\fP\fIwin\fP\fB);\fR

 .br
 .br

-\fBint attr_get(attr_t *attrs, short *pair, void *opts);\fR
+\fBint attr_get(attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint wattr_get(WINDOW *win, attr_t *attrs, short *pair,\fR
-       \fBvoid *opts);\fR
+\fBint wattr_get(WINDOW *\fP\fIwin\fP\fB, attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB,\fR
+       \fBvoid *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint attr_off(attr_t attrs, void *opts);\fR
+\fBint attr_off(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint wattr_off(WINDOW *win, attr_t attrs, void *opts);\fR
+\fBint wattr_off(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint attr_on(attr_t attrs, void *opts);\fR
+\fBint attr_on(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint wattr_on(WINDOW *win, attr_t attrs, void *opts);\fR
+\fBint wattr_on(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint attr_set(attr_t attrs, short pair, void *opts);\fR
+\fBint attr_set(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint wattr_set(WINDOW *win, attr_t attrs, short pair, void *opts);\fR
+\fBint wattr_set(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint chgat(int n, attr_t attr, short color,\fR
-      \fBconst void *opts)\fR
+\fBint chgat(int \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB, short \fP\fIcolor\fP\fB,\fR
+      \fBconst void *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint wchgat(WINDOW *win, int n, attr_t attr,\fR
-      \fBshort color, const void *opts)\fR
+\fBint wchgat(WINDOW *\fP\fIwin\fP\fB, int \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fR
+      \fBshort \fP\fIcolor\fP\fB, const void *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint mvchgat(int y, int x, int n, attr_t attr,\fR
-      \fBshort color, const void *opts)\fR
+\fBint mvchgat(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, int \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fR
+      \fBshort \fP\fIcolor\fP\fB, const void *\fP\fIopts\fP\fB);\fR

 .br
 .br

-\fBint mvwchgat(WINDOW *win, int y, int x, int n,\fR
-      \fBattr_t attr, short color, const void *opts)\fR
+\fBint mvwchgat(WINDOW *\fP\fIwin, int \fP\fIy, int \fP\fIx, int \fP\fIn,\fR
+      \fBattr_t \fP\fIattr\fP\fB, short \fP\fIcolor\fP\fB, const void *\fP\fIopts\fP\fB);\fR

 .br
 .SH DESCRIPTION
 .br
 .SH DESCRIPTION

-These routines manipulate the current attributes of the named window.  The
+These routines manipulate the current attributes of the named window.
+The

 current attributes of a window apply to all characters that are written into
 current attributes of a window apply to all characters that are written into

-the window with \fBwaddch\fR, \fBwaddstr\fR and \fBwprintw\fR.  Attributes are
+the window with \fBwaddch\fR, \fBwaddstr\fR and \fBwprintw\fR.
+Attributes are

 a property of the character, and move with the character through any scrolling
 a property of the character, and move with the character through any scrolling

-and insert/delete line/character operations.  To the extent possible, they are
+and insert/delete line/character operations.
+To the extent possible, they are

 displayed as appropriate modifications to the graphic rendition of characters
 put on the screen.
 displayed as appropriate modifications to the graphic rendition of characters
 put on the screen.

+.SS attrset

 .PP
 The routine \fBattrset\fR sets the current attributes of the given window to
 .PP
 The routine \fBattrset\fR sets the current attributes of the given window to

-\fIattrs\fR.  The routine \fBattroff\fR turns off the named attributes without
-turning any other attributes on or off.  The routine \fBattron\fR turns on the
-named attributes without affecting any others.  The routine \fBstandout\fR is
-the same as \fBattron(A_STANDOUT)\fR.  The routine \fBstandend\fR is the same
+\fIattrs\fR.
+The routine \fBattroff\fR turns off the named attributes without
+turning any other attributes on or off.
+The routine \fBattron\fR turns on the
+named attributes without affecting any others.
+The routine \fBstandout\fR is
+the same as \fBattron(A_STANDOUT)\fR.
+The routine \fBstandend\fR is the same

 as \fBattrset(A_NORMAL)\fR or \fBattrset(0)\fR, that is, it turns off all
 attributes.
 .PP
 as \fBattrset(A_NORMAL)\fR or \fBattrset(0)\fR, that is, it turns off all
 attributes.
 .PP


@@ -137,36 +145,54 @@ The \fBattrset\fR and related routines do not affect the attributes used
 when erasing portions of the window.
 See \fBcurs_bkgd\fR(3X) for functions which modify the attributes used for
 erasing and clearing.
 when erasing portions of the window.
 See \fBcurs_bkgd\fR(3X) for functions which modify the attributes used for
 erasing and clearing.

+.SS attr_set
+The \fBattrset\fP routine is actually a legacy feature predating SVr4 curses
+but kept in X/Open Curses for the same reason that SVr4 curses kept it:
+compatibility.
+The routine \fBattr_set\fP provides for passing a color-pair parameter.
+.PP
+The remaining \fBattr_\fR* functions operate exactly like the corresponding
+\fBattr\fR* functions, except that they take arguments of type \fBattr_t\fR
+rather than \fBint\fR.
+.SS color_set

 .PP
 The routine \fBcolor_set\fR sets the current color of the given window to the
 .PP
 The routine \fBcolor_set\fR sets the current color of the given window to the

-foreground/background combination described by the color_pair_number. The
+foreground/background combination described by the color_pair_number.
+The

 parameter opts is reserved for future use, applications must supply a null
 pointer.
 parameter opts is reserved for future use, applications must supply a null
 pointer.

+.SS attr_get

 .PP
 The routine \fBwattr_get\fR returns the current attribute and color pair for
 the given window; \fBattr_get\fR returns the current attribute and color pair
 for \fBstdscr\fR.
 .PP
 The routine \fBwattr_get\fR returns the current attribute and color pair for
 the given window; \fBattr_get\fR returns the current attribute and color pair
 for \fBstdscr\fR.

-The remaining \fBattr_\fR* functions operate exactly like the corresponding
-\fBattr\fR* functions, except that they take arguments of type \fBattr_t\fR
-rather than \fBint\fR.
+.PP
+There is no corresponding \fBattrget\fP function as such in X/Open Curses,
+although ncurses provides \fBgetattrs\fP (see curs_legacy(3X)).
+.SS chgat

 .PP
 The routine \fBchgat\fR changes the attributes of a given number of characters
 .PP
 The routine \fBchgat\fR changes the attributes of a given number of characters

-starting at the current cursor location of \fBstdscr\fR.  It does not update
-the cursor and does not perform wrapping.  A character count of \-1 or greater
+starting at the current cursor location of \fBstdscr\fR.
+It does not update
+the cursor and does not perform wrapping.
+A character count of \-1 or greater

 than the remaining window width means to change attributes all the way to the
 than the remaining window width means to change attributes all the way to the

-end of the current line.  The \fBwchgat\fR function generalizes this to any
-window; the \fBmvwchgat\fR function does a cursor move before acting.  In these
+end of the current line.
+The \fBwchgat\fR function generalizes this to any
+window; the \fBmvwchgat\fR function does a cursor move before acting.
+In these

 functions, the color argument is a color-pair index (as in the first argument
 functions, the color argument is a color-pair index (as in the first argument

-of \fIinit_pair\fR, see \fBcurs_color\fR(3X)).  The \fBopts\fR argument is not
+of \fIinit_pair\fR, see \fBcurs_color\fR(3X)).
+The \fBopts\fR argument is not

 presently used, but is reserved for the future (leave it \fBNULL\fR).
 .SS Attributes
 The following video attributes, defined in \fB<curses.h>\fR, can be passed to
 the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'd with the
 presently used, but is reserved for the future (leave it \fBNULL\fR).
 .SS Attributes
 The following video attributes, defined in \fB<curses.h>\fR, can be passed to
 the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'd with the

-characters passed to \fBaddch\fR.
+characters passed to \fBaddch\fR (see curs_addch(3X)).

 .PP
 .RS
 .TS
 .PP
 .RS
 .TS

-l l 
+l l

 _ _ _
 l l .
 \fIName\fR     \fIDescription\fR
 _ _ _
 l l .
 \fIName\fR     \fIDescription\fR


@@ -190,7 +216,7 @@ These video attributes are supported by \fBattr_on\fP and related functions
 (which also support the attributes recognized by \fBattron\fP, etc.):
 .RS
 .TS
 (which also support the attributes recognized by \fBattron\fP, etc.):
 .RS
 .TS

-l l 
+l l

 _ _ _
 l l .
 \fIName\fR     \fIDescription\fR
 _ _ _
 l l .
 \fIName\fR     \fIDescription\fR


@@ -226,15 +252,18 @@ value directly.
 However, ncurses ABI 4 and 5 simply OR this value within the alternate functions.
 You must use ncurses ABI 6 to support more than 256 color pairs.
 .SH PORTABILITY
 However, ncurses ABI 4 and 5 simply OR this value within the alternate functions.
 You must use ncurses ABI 6 to support more than 256 color pairs.
 .SH PORTABILITY

-These functions are supported in the XSI Curses standard, Issue 4.  The
+These functions are supported in the XSI Curses standard, Issue 4.
+The

 standard defined the dedicated type for highlights, \fBattr_t\fR, which is not
 standard defined the dedicated type for highlights, \fBattr_t\fR, which is not

-defined in SVr4 curses. The functions taking \fBattr_t\fR arguments are
+defined in SVr4 curses.
+The functions taking \fBattr_t\fR arguments are

 not supported under SVr4.
 .PP
 The XSI Curses standard states that whether the traditional functions
 \fBattron\fR/\fBattroff\fR/\fBattrset\fR can manipulate attributes other than
 \fBA_BLINK\fR, \fBA_BOLD\fR, \fBA_DIM\fR, \fBA_REVERSE\fR, \fBA_STANDOUT\fR, or
 not supported under SVr4.
 .PP
 The XSI Curses standard states that whether the traditional functions
 \fBattron\fR/\fBattroff\fR/\fBattrset\fR can manipulate attributes other than
 \fBA_BLINK\fR, \fBA_BOLD\fR, \fBA_DIM\fR, \fBA_REVERSE\fR, \fBA_STANDOUT\fR, or

-\fBA_UNDERLINE\fR is "unspecified".  Under this implementation as well as
+\fBA_UNDERLINE\fR is "unspecified".
+Under this implementation as well as

 SVr4 curses, these functions correctly manipulate all other highlights
 (specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\fR).
 .PP
 SVr4 curses, these functions correctly manipulate all other highlights
 (specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\fR).
 .PP


@@ -248,14 +277,15 @@ This implementation makes the assumption that
 .PP
 XSI Curses added the new entry points, \fBattr_get\fR, \fBattr_on\fR,
 \fBattr_off\fR, \fBattr_set\fR, \fBwattr_on\fR, \fBwattr_off\fR,
 .PP
 XSI Curses added the new entry points, \fBattr_get\fR, \fBattr_on\fR,
 \fBattr_off\fR, \fBattr_set\fR, \fBwattr_on\fR, \fBwattr_off\fR,

-\fBwattr_get\fR, \fBwattr_set\fR.  These are intended to work with
+\fBwattr_get\fR, \fBwattr_set\fR.
+These are intended to work with

 a new series of highlight macros prefixed with \fBWA_\fR.
 The older macros have direct counterparts in the newer set of names:
 .PP
 .RS
 .ne 9
 .TS
 a new series of highlight macros prefixed with \fBWA_\fR.
 The older macros have direct counterparts in the newer set of names:
 .PP
 .RS
 .ne 9
 .TS

-l l 
+l l

 _ _ _
 l l .
 \fIName\fR     \fIDescription\fR
 _ _ _
 l l .
 \fIName\fR     \fIDescription\fR


@@ -270,7 +300,7 @@ l l .
 .TE
 .RE
 .PP
 .TE
 .RE
 .PP

-Older versions of this library did not force an update of the screen
+Very old versions of this library did not force an update of the screen

 when changing the attributes.
 Use \fBtouchwin\fR to force the screen to match the updated attributes.
 .PP
 when changing the attributes.
 Use \fBtouchwin\fR to force the screen to match the updated attributes.
 .PP


@@ -301,6 +331,7 @@ Functions with a "mv" prefix first perform a cursor movement using
 \fBwmove\fP, and return an error if the position is outside the window,
 or if the window pointer is null.
 .SH SEE ALSO
 \fBwmove\fP, and return an error if the position is outside the window,
 or if the window pointer is null.
 .SH SEE ALSO

+.na

 \fBcurses\fR(3X),
 \fBcurs_addch\fR(3X),
 \fBcurs_addstr\fR(3X),
 \fBcurses\fR(3X),
 \fBcurs_addch\fR(3X),
 \fBcurs_addstr\fR(3X),