diff options
Diffstat (limited to 'ncurses-5.9/man/curs_attr.3x')
| -rw-r--r-- | ncurses-5.9/man/curs_attr.3x | 270 |
1 files changed, 270 insertions, 0 deletions
diff --git a/ncurses-5.9/man/curs_attr.3x b/ncurses-5.9/man/curs_attr.3x new file mode 100644 index 0000000..0cad8d5 --- /dev/null +++ b/ncurses-5.9/man/curs_attr.3x @@ -0,0 +1,270 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2009,2010 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$ +.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 +.ne 9 +.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. +.PP +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 +\fBcurses\fR(3X), +\fBcurs_addch\fR(3X), +\fBcurs_addstr\fR(3X), +\fBcurs_bkgd\fR(3X), +\fBcurs_printw\fR(3X), +\fBcurs_variables\fR(3X) |