| '\" t |
| .\"*************************************************************************** |
| .\" 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 * |
| .\" "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.40 2015/07/20 23:35:38 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 \fP\fIattrs);\fR |
| .br |
| \fBint wattroff(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR |
| .br |
| \fBint attron(int \fP\fIattrs\fP\fB);\fR |
| .br |
| \fBint wattron(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR |
| .br |
| \fBint attrset(int \fP\fIattrs\fP\fB);\fR |
| .br |
| \fBint wattrset(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR |
| .br |
| \fBint color_set(short \fP\fIcolor_pair_number\fP\fB, void* \fP\fIopts\fP\fB);\fR |
| .br |
| \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 |
| \fBint wstandend(WINDOW *\fP\fIwin\fP\fB);\fR |
| .br |
| \fBint standout(void);\fR |
| .br |
| \fBint wstandout(WINDOW *\fP\fIwin\fP\fB);\fR |
| .br |
| \fBint attr_get(attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR |
| .br |
| \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 |
| \fBint attr_off(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR |
| .br |
| \fBint wattr_off(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR |
| .br |
| \fBint attr_on(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR |
| .br |
| \fBint wattr_on(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR |
| .br |
| \fBint attr_set(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\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);\fR |
| .br |
| \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 |
| \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 |
| \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 |
| \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 |
| 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. |
| .SS attrset |
| .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. |
| .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: |
| compatbility. |
| 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 |
| foreground/background combination described by the color_pair_number. |
| The |
| 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 |
| 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 |
| 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 (see curs_addch(3x)). |
| .PP |
| .RS |
| .TS |
| l l |
| _ _ _ |
| l l . |
| \fIName\fR \fIDescription\fR |
| \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_ITALIC\fR Italics (non-X/Open extension) |
| \fBA_CHARTEXT\fR Bit-mask to extract a character |
| \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR Color-pair number \fIn\fR |
| .TE |
| .RE |
| .PP |
| These video attributes are supported by \fBattr_on\fP and related functions |
| (which also support the attributes recognized by \fBattron\fP, etc.): |
| .RS |
| .TS |
| l l |
| _ _ _ |
| l l . |
| \fIName\fR \fIDescription\fR |
| \fBWA_HORIZONTAL\fR Horizontal highlight |
| \fBWA_LEFT\fR Left highlight |
| \fBWA_LOW\fR Low highlight |
| \fBWA_RIGHT\fR Right highlight |
| \fBWA_TOP\fR Top highlight |
| \fBWA_VERTICAL\fR Vertical highlight |
| .TE |
| .RE |
| .PP |
| For consistency |
| .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 |
| This implementation provides the \fBA_ITALIC\fP attribute for terminals |
| which have the \fIenter_italics_mode\fP (sitm) and \fIexit_italics_mode\fP (ritm) capabilities. |
| Italics are not mentioned in X/Open Curses. |
| Unlike the other video attributes, \fBI_ITALIC\fP is unrelated |
| to the \fIset_attributes\fP capabilities. |
| This implementation makes the assumption that |
| \fIexit_attribute_mode\fP may also reset italics. |
| .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. |
| The older macros have direct counterparts in the newer set of names: |
| .PP |
| .RS |
| .ne 9 |
| .TS |
| l l |
| _ _ _ |
| l l . |
| \fIName\fR \fIDescription\fR |
| \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 |
| .RE |
| .PP |
| 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 |
| 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). |
| As of August 2013, |
| no known terminal provides these highlights |
| (i.e., via the \fBsgr1\fP capability). |
| .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 |
| .na |
| \fBcurses\fR(3X), |
| \fBcurs_addch\fR(3X), |
| \fBcurs_addstr\fR(3X), |
| \fBcurs_bkgd\fR(3X), |
| \fBcurs_printw\fR(3X), |
| \fBcurs_variables\fR(3X) |
