aboutsummaryrefslogtreecommitdiff
path: root/man/curs_attr.3x
diff options
context:
space:
mode:
authorRong-En Fan <rafan@FreeBSD.org>2008-11-09 09:06:04 +0000
committerRong-En Fan <rafan@FreeBSD.org>2008-11-09 09:06:04 +0000
commita388f199193767bacbb38b172ab89cb84369736c (patch)
treea1816f5667d2280b970ca44e407bac8cc4496c0a /man/curs_attr.3x
parentaa59d4d4c5dda7e1c6f9dc0cc6edc58992a525c7 (diff)
downloadsrc-a388f199193767bacbb38b172ab89cb84369736c.tar.gz
src-a388f199193767bacbb38b172ab89cb84369736c.zip
- Flatten the vendor area
Notes
Notes: svn path=/vendor/ncurses/dist/; revision=184786
Diffstat (limited to 'man/curs_attr.3x')
-rw-r--r--man/curs_attr.3x270
1 files changed, 270 insertions, 0 deletions
diff --git a/man/curs_attr.3x b/man/curs_attr.3x
new file mode 100644
index 000000000000..cf58affee13d
--- /dev/null
+++ b/man/curs_attr.3x
@@ -0,0 +1,270 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright (c) 1998-2006,2007 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 *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" $Id: curs_attr.3x,v 1.31 2007/03/17 20:30:33 tom Exp $
+.TH curs_attr 3X ""
+.na
+.hy 0
+.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,
+\fBPAIR_NUMBER\fR - \fBcurses\fR character and window attribute control routines
+.ad
+.hy
+.SH SYNOPSIS
+\fB#include <curses.h>\fR
+.br
+\fBint attroff(int attrs);\fR
+.br
+\fBint wattroff(WINDOW *win, int attrs);\fR
+.br
+\fBint attron(int attrs);\fR
+.br
+\fBint wattron(WINDOW *win, int attrs);\fR
+.br
+\fBint attrset(int attrs);\fR
+.br
+\fBint wattrset(WINDOW *win, int attrs);\fR
+.br
+\fBint color_set(short color_pair_number, void* opts);\fR
+.br
+\fBint wcolor_set(WINDOW *win, short color_pair_number,\fR
+ \fBvoid* opts);\fR
+.br
+\fBint standend(void);\fR
+.br
+\fBint wstandend(WINDOW *win);\fR
+.br
+\fBint standout(void);\fR
+.br
+\fBint wstandout(WINDOW *win);\fR
+.br
+\fBint attr_get(attr_t *attrs, short *pair, void *opts);\fR
+.br
+\fBint wattr_get(WINDOW *win, attr_t *attrs, short *pair,\fR
+ \fBvoid *opts);\fR
+.br
+\fBint attr_off(attr_t attrs, void *opts);\fR
+.br
+\fBint wattr_off(WINDOW *win, attr_t attrs, void *opts);\fR
+.br
+\fBint attr_on(attr_t attrs, void *opts);\fR
+.br
+\fBint wattr_on(WINDOW *win, attr_t attrs, void *opts);\fR
+.br
+\fBint attr_set(attr_t attrs, short pair, void *opts);\fR
+.br
+\fBint wattr_set(WINDOW *win, attr_t attrs, short pair, void *opts);\fR
+.br
+\fBint chgat(int n, attr_t attr, short color,\fR
+ \fBconst void *opts)\fR
+.br
+\fBint wchgat(WINDOW *win, int n, attr_t attr,\fR
+ \fBshort color, const void *opts)\fR
+.br
+\fBint mvchgat(int y, int x, int n, attr_t attr,\fR
+ \fBshort color, const void *opts)\fR
+.br
+\fBint mvwchgat(WINDOW *win, int y, int x, int n,\fR
+ \fBattr_t attr, short color, const void *opts)\fR
+.br
+.SH DESCRIPTION
+These routines manipulate the current attributes of the named window. The
+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
+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
+displayed as appropriate modifications to the graphic rendition of characters
+put on the screen.
+.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
+as \fBattrset(A_NORMAL)\fR or \fBattrset(0)\fR, that is, it turns off all
+attributes.
+.PP
+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.
+.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
+parameter opts is reserved for future use, applications must supply a null
+pointer.
+.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
+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
+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
+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
+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.
+.PP
+.TS
+center ;
+l l .
+\fBA_NORMAL\fR Normal display (no highlight)
+\fBA_STANDOUT\fR Best highlighting mode of the terminal.
+\fBA_UNDERLINE\fR Underlining
+\fBA_REVERSE\fR Reverse video
+\fBA_BLINK\fR Blinking
+\fBA_DIM\fR Half bright
+\fBA_BOLD\fR Extra bright or bold
+\fBA_PROTECT\fR Protected mode
+\fBA_INVIS\fR Invisible or blank mode
+\fBA_ALTCHARSET\fR Alternate character set
+\fBA_CHARTEXT\fR Bit-mask to extract a character
+\fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR Color-pair number \fIn\fR
+.TE
+.PP
+The following macro is the reverse of \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR:
+.PP
+.br
+\fBPAIR_NUMBER(\fR\fIattrs\fR) Returns the pair number associated
+ with the \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR attribute.
+.br
+.PP
+The return values of many of these routines are not meaningful (they are
+implemented as macro-expanded assignments and simply return their argument).
+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.
+.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
+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.
+.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
+SVr4 curses, these functions correctly manipulate all other highlights
+(specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\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
+a new series of highlight macros prefixed with \fBWA_\fR.
+.PP
+Older 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
+.TS
+center ;
+l l .
+\fBWA_NORMAL\fR Normal display (no highlight)
+\fBWA_STANDOUT\fR Best highlighting mode of the terminal.
+\fBWA_UNDERLINE\fR Underlining
+\fBWA_REVERSE\fR Reverse video
+\fBWA_BLINK\fR Blinking
+\fBWA_DIM\fR Half bright
+\fBWA_BOLD\fR Extra bright or bold
+\fBWA_ALTCHARSET\fR Alternate character set
+.TE
+.PP
+The XSI curses standard specifies that each pair of corresponding \fBA_\fR
+and \fBWA_\fR-using functions operates on the same current-highlight
+information.
+.PP
+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
+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.
+This implementation also provides
+\fBgetattrs\fR
+for compatibility with older versions of curses.
+.SH SEE ALSO
+\fBcurses\fR(3X),
+\fBcurs_addch\fR(3X),
+\fBcurs_addstr\fR(3X),
+\fBcurs_bkgd\fR(3X),
+\fBcurs_printw\fR(3X)
+.\"#
+.\"# The following sets edit modes for GNU EMACS
+.\"# Local Variables:
+.\"# mode:nroff
+.\"# fill-column:79
+.\"# End: