X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_attr.3x;h=55c89c3e3774d39ec1ef2befd4793660a51519fe;hp=d6ad62471acf13b59a21f4cb7b89d0fe81e0ecb7;hb=b11cef1e315b58820ea0cde239ebf2f741ef8948;hpb=0eb88fc5281804773e2a0c7a488a4452463535ce diff --git a/man/curs_attr.3x b/man/curs_attr.3x index d6ad6247..55c89c3e 100644 --- a/man/curs_attr.3x +++ b/man/curs_attr.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998 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 * @@ -27,116 +27,177 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_attr.3x,v 1.19 1998/12/26 19:25:35 tom Exp $ +.\" $Id: curs_attr.3x,v 1.43 2015/12/05 18:46:04 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 - \fBcurses\fR character and window attribute control routines +\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 \fR .br -\fBint attroff(int attrs);\fR +\fBint attroff(int \fP\fIattrs);\fR .br -\fBint wattroff(WINDOW *win, int attrs);\fR +\fBint wattroff(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR .br -\fBint attron(int attrs);\fR +\fBint attron(int \fP\fIattrs\fP\fB);\fR .br -\fBint wattron(WINDOW *win, int attrs);\fR +\fBint wattron(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR .br -\fBint attrset(int attrs);\fR +\fBint attrset(int \fP\fIattrs\fP\fB);\fR .br -\fBint wattrset(WINDOW *win, int attrs);\fR +\fBint wattrset(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR .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 -\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 -\fBint wstandend(WINDOW *win);\fR +\fBint wstandend(WINDOW *\fP\fIwin\fP\fB);\fR .br \fBint standout(void);\fR .br -\fBint wstandout(WINDOW *win);\fR +\fBint wstandout(WINDOW *\fP\fIwin\fP\fB);\fR .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 -\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 -\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 -\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 -\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 -\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 -\fBint attr_set(attr_t attrs, void *opts);\fR +\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 *win, attr_t attrs, 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 -\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 -\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 -\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 -\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 +\fBPAIR_NUMBER(\fR\fIattrs\fR\fB);\fP .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 -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 -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. - +.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 +\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: +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 -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. - +.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. -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 -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 -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 -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\fR, can be passed to -the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'ed with the -characters passed to \fBaddch\fR. - +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 -center ; +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 @@ -147,45 +208,89 @@ l l . \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: - -.DS C +.PP +.br \fBPAIR_NUMBER(\fR\fIattrs\fR) Returns the pair number associated with the \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR attribute. -.DE - +.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 -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 +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 +\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 +\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 -center ; +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 @@ -195,21 +300,43 @@ l l . \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) which this -curses does not yet support. +\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 -\fBcurses\fR(3X), \fBcurs_addch\fR(3X), \fBcurs_addstr\fR(3X), -\fBcurs_printw\fR(3X) -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +.na +\fBcurses\fR(3X), +\fBcurs_addch\fR(3X), +\fBcurs_addstr\fR(3X), +\fBcurs_bkgd\fR(3X), +\fBcurs_printw\fR(3X), +\fBcurs_variables\fR(3X)