ncurses 5.5

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

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

-.\" Copyright (c) 1998-2002,2003 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2003,2005 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,19 +27,38 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_attr.3x,v 1.27 2003/12/27 18:50:51 tom Exp $
+.\" $Id: curs_attr.3x,v 1.29 2005/05/15 16:17:25 tom Exp $

 .TH curs_attr 3X ""
 .TH curs_attr 3X ""

+.na
+.hy 0

 .SH NAME
 .SH NAME

-\fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR,
-\fBattrset\fR, \fBwattrset\fR, \fBcolor_set\fR, \fBwcolor_set\fR,
-\fBstandend\fR, \fBwstandend\fR, \fBstandout\fR, \fBwstandout\fR,
-\fBattr_get\fR, \fBwattr_get\fR,
-\fBattr_off\fR, \fBwattr_off\fR,
-\fBattr_on\fR, \fBwattr_on\fR,
-\fBattr_set\fR, \fBwattr_set\fR,
-\fBchgat\fR, \fBwchgat\fR,
-\fBmvchgat\fR, \fBmvwchgat\fR,
+\fBattroff\fR,
+\fBwattroff\fR,
+\fBattron\fR,
+\fBwattron\fR,
+\fBattrset\fR,
+\fBwattrset\fR,
+\fBcolor_set\fR,
+\fBwcolor_set\fR,
+\fBstandend\fR,
+\fBwstandend\fR,
+\fBstandout\fR,
+\fBwstandout\fR,
+\fBattr_get\fR,
+\fBwattr_get\fR,
+\fBattr_off\fR,
+\fBwattr_off\fR,
+\fBattr_on\fR,
+\fBwattr_on\fR,
+\fBattr_set\fR,
+\fBwattr_set\fR,
+\fBchgat\fR,
+\fBwchgat\fR,
+\fBmvchgat\fR,
+\fBmvwchgat\fR,

 \fBPAIR_NUMBER\fR - \fBcurses\fR character and window attribute control routines
 \fBPAIR_NUMBER\fR - \fBcurses\fR character and window attribute control routines

+.ad
+.hy

 .SH SYNOPSIS
 \fB#include <curses.h>\fR
 .br
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
 .br


@@ -146,7 +165,7 @@ since the character values are not modified.
 Use \fBtouchwin\fR to force the screen to match the updated attributes.
 .SS Attributes
 The following video attributes, defined in \fB<curses.h>\fR, can be passed to
 Use \fBtouchwin\fR to force the screen to match the updated attributes.
 .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'ed with the
+the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'd with the

 characters passed to \fBaddch\fR.
 .PP
 .TS
 characters passed to \fBaddch\fR.
 .PP
 .TS


@@ -179,8 +198,15 @@ The SVr4 manual page claims (falsely) that these routines always return \fB1\fR.
 .SH NOTES
 Note that \fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR,
 \fBattrset\fR, \fBwattrset\fR, \fBstandend\fR and \fBstandout\fR may be macros.
 .SH NOTES
 Note that \fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR,
 \fBattrset\fR, \fBwattrset\fR, \fBstandend\fR and \fBstandout\fR may be macros.

+.PP
+\fBCOLOR_PAIR\fP values can only be OR'd with attributes if the pair
+number is less than 256.
+The alternate functions such as \fBcolor_set\fP can pass a color pair
+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
 .SH PORTABILITY

-All 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
 defined in SVr4 curses. The functions taking \fBattr_t\fR arguments are
 not supported under SVr4.
 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
 not supported under SVr4.


@@ -217,7 +243,16 @@ information.
 The XSI standard extended conformance level adds new highlights
 \fBA_HORIZONTAL\fR, \fBA_LEFT\fR, \fBA_LOW\fR, \fBA_RIGHT\fR, \fBA_TOP\fR,
 \fBA_VERTICAL\fR (and corresponding \fBWA_\fR macros for each) which this
 The XSI standard extended conformance level adds new highlights
 \fBA_HORIZONTAL\fR, \fBA_LEFT\fR, \fBA_LOW\fR, \fBA_RIGHT\fR, \fBA_TOP\fR,
 \fBA_VERTICAL\fR (and corresponding \fBWA_\fR macros for each) which this

-curses does not yet support.
+implementation does not yet support.
+.SH RETURN VALUE
+All routines return the integer \fBOK\fR on success, or \fBERR\fP on failure.
+.PP
+X/Open does not define any error conditions.
+.PP
+This implementation returns an error
+if the window pointer is null.
+The \fBwcolor_set\fP function returns an error if the color pair parameter
+is outside the range 0..COLOR_PAIRS-1.

 .SH SEE ALSO
 \fBcurses\fR(3X),
 \fBcurs_addch\fR(3X),
 .SH SEE ALSO
 \fBcurses\fR(3X),
 \fBcurs_addch\fR(3X),