diff options
Diffstat (limited to 'upstream/archlinux/man3/curs_attr.3x')
| -rw-r--r-- | upstream/archlinux/man3/curs_attr.3x | 620 |
1 files changed, 300 insertions, 320 deletions
diff --git a/upstream/archlinux/man3/curs_attr.3x b/upstream/archlinux/man3/curs_attr.3x index ac448b4e..5a196e52 100644 --- a/upstream/archlinux/man3/curs_attr.3x +++ b/upstream/archlinux/man3/curs_attr.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,123 +28,90 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_attr.3x,v 1.72 2022/04/16 19:18:32 tom Exp $ -.TH curs_attr 3X "" -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' -.de NS -.ie n .sp -.el .sp .5 -.ie n .in +4 -.el .in +2 -.nf -.ft C \" Courier -.. -.de NE -.fi -.ft R -.ie n .in -4 -.el .in -2 -.. +.\" $Id: curs_attr.3x,v 1.105 2024/04/27 17:54:42 tom Exp $ +.TH curs_attr 3X 2024-04-27 "ncurses 6.5" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 .. -.na -.hy 0 .\" --------------------------------------------------------------------------- .SH NAME -.\" attr_get -\fBattr_get\fP, -\fBwattr_get\fP, -\fBattr_set\fP, -\fBwattr_set\fP, -.\" .br -\fBattr_off\fP, -\fBwattr_off\fP, -\fBattr_on\fP, -\fBwattr_on\fP, -.\" .br -\fBattroff\fP, -\fBwattroff\fP, -\fBattron\fP, -\fBwattron\fP, -\fBattrset\fP, -\fBwattrset\fP, -.\" .br -\fBchgat\fP, -\fBwchgat\fP, -\fBmvchgat\fP, -\fBmvwchgat\fP, -.\" .br -\fBcolor_set\fP, -\fBwcolor_set\fP, -.\" .br -\fBstandend\fP, -\fBwstandend\fP, -\fBstandout\fP, -\fBwstandout\fP \- \fBcurses\fP character and window attribute control routines -.ad -.hy +\fB\%attr_get\fP, +\fB\%wattr_get\fP, +\fB\%attr_set\fP, +\fB\%wattr_set\fP, +\fB\%attr_off\fP, +\fB\%wattr_off\fP, +\fB\%attr_on\fP, +\fB\%wattr_on\fP, +\fB\%attroff\fP, +\fB\%wattroff\fP, +\fB\%attron\fP, +\fB\%wattron\fP, +\fB\%attrset\fP, +\fB\%wattrset\fP, +\fB\%chgat\fP, +\fB\%wchgat\fP, +\fB\%mvchgat\fP, +\fB\%mvwchgat\fP, +\fB\%color_set\fP, +\fB\%wcolor_set\fP, +\fB\%standend\fP, +\fB\%wstandend\fP, +\fB\%standout\fP, +\fB\%wstandout\fP \- +manipulate attributes of character cells in \fIcurses\fR windows .\" --------------------------------------------------------------------------- .SH SYNOPSIS -\fB#include <curses.h>\fP -.sp -\fBint attr_get(attr_t *\fIattrs\fB, short *\fIpair\fB, void *\fIopts\fB);\fR -.br -\fBint wattr_get(WINDOW *\fIwin\fB, attr_t *\fIattrs\fB, short *\fIpair\fB,\fR \fBvoid *\fIopts\fB);\fR -.br -\fBint attr_set(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR -.br -\fBint wattr_set(WINDOW *\fIwin\fB, attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR -.sp -\fBint attr_off(attr_t \fIattrs\fB, void *\fIopts\fB);\fR -.br -\fBint wattr_off(WINDOW *\fIwin\fB, attr_t \fIattrs\fB, void *\fIopts\fB);\fR -.br -\fBint attr_on(attr_t \fIattrs\fB, void *\fIopts\fB);\fR -.br -\fBint wattr_on(WINDOW *\fIwin\fB, attr_t \fIattrs\fB, void *\fIopts\fB);\fR -.sp -\fBint attroff(int \fIattrs);\fR -.br -\fBint wattroff(WINDOW *\fIwin\fB, int \fIattrs\fB);\fR -.br -\fBint attron(int \fIattrs\fB);\fR -.br -\fBint wattron(WINDOW *\fIwin\fB, int \fIattrs\fB);\fR -.br -\fBint attrset(int \fIattrs\fB);\fR -.br -\fBint wattrset(WINDOW *\fIwin\fB, int \fIattrs\fB);\fR -.sp -\fBint chgat(int \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB,\fR \fBconst void *\fIopts\fB);\fR -.br -\fBint wchgat(WINDOW *\fIwin\fB,\fR +.nf +\fB#include <curses.h> +.PP +\fBint attr_get(attr_t *\fIattrs\fP, short *\fIpair\fP, void *\fIopts\fP); +\fBint wattr_get(WINDOW *\fIwin\fP, attr_t *\fIattrs\fP, short *\fIpair\fP,\fR \fPvoid *\fIopts\fP); +\fBint attr_set(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP); +\fBint wattr_set(WINDOW *\fIwin\fP, attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP); +.PP +\fBint attr_off(attr_t \fIattrs\fP, void *\fIopts\fP); +\fBint wattr_off(WINDOW *\fIwin\fP, attr_t \fIattrs\fP, void *\fIopts\fP); +\fBint attr_on(attr_t \fIattrs\fP, void *\fIopts\fP); +\fBint wattr_on(WINDOW *\fIwin\fP, attr_t \fIattrs\fP, void *\fIopts\fP); +.PP +\fBint attroff(int \fIattrs\fP); +\fBint wattroff(WINDOW *\fIwin\fP, int \fIattrs\fP); +\fBint attron(int \fIattrs\fP); +\fBint wattron(WINDOW *\fIwin\fP, int \fIattrs\fP); +\fBint attrset(int \fIattrs\fP); +\fBint wattrset(WINDOW *\fIwin\fP, int \fIattrs\fP); +.PP +\fBint chgat(int \fIn\fP, attr_t \fIattr\fP, short \fIpair\fP,\fR \fPconst void *\fIopts\fP); +\fBint wchgat(WINDOW *\fIwin\fP, \fBint \fIn\fB, attr_t \fIattr\fB,\fR \fBshort \fIpair\fB, const void *\fIopts\fB);\fR -.br \fBint mvchgat(int \fIy\fB, int \fIx\fB,\fR - \fBint \fIn\fB, attr_t \fIattr\fB,\fR \fBshort \fIpair\fB, const void *\fIopts\fB);\fR -.br -\fBint mvwchgat(WINDOW *\fIwin, int \fIy, int \fIx\fB,\fR - \fBint \fIn,\fR \fBattr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR -.sp + \fBint \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR +\fBint mvwchgat(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB,\fR + \fBint \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR +.PP \fBint color_set(short \fIpair\fB, void* \fIopts\fB);\fR -.br -\fBint wcolor_set(WINDOW *\fIwin\fB, short \fIpair\fB,\fR \fBvoid* \fIopts);\fR -.sp +\fBint wcolor_set(WINDOW *\fIwin\fB, short \fIpair\fB,\fR \fBvoid* \fIopts\fP);\fR +.PP \fBint standend(void);\fP -.br \fBint wstandend(WINDOW *\fIwin\fB);\fR -.br \fBint standout(void);\fP -.br \fBint wstandout(WINDOW *\fIwin\fB);\fR +.fi .\" --------------------------------------------------------------------------- .SH DESCRIPTION -.PP These routines manipulate the current attributes of the named window, which then apply to all characters that are written into the window with \fBwaddch\fP, \fBwaddstr\fP and \fBwprintw\fP. @@ -159,13 +126,8 @@ These routines do not affect the attributes used when erasing portions of the window. See \fBcurs_bkgd\fP(3X) for functions which modify the attributes used for erasing and clearing. -.PP -Routines which do not have a \fBWINDOW*\fP parameter apply to \fBstdscr\fP. -For example, -\fBattr_set\fP is the \fBstdscr\fP variant of \fBwattr_set\fP. .\" --------------------------------------------------------------------------- -.SS Window attributes -.PP +.SS "Window Attributes" There are two sets of functions: .bP functions for manipulating the window attributes and color: @@ -186,7 +148,7 @@ Use \fBattr_off\fP and \fBwattr_off\fP to turn off window attributes, again values OR'd together in \fIattr\fP, without affecting other attributes. .\" --------------------------------------------------------------------------- -.SS Legacy window attributes +.SS "Legacy Window Attributes" The X/Open window attribute routines which \fIset\fP or \fIget\fP, turn \fIon\fP or \fIoff\fP are extensions of older routines @@ -204,14 +166,18 @@ the attribute parameter. For example, as long as that value fits into the \fBA_COLOR\fP mask, then these calls produce similar results: -.NS +.PP +.RS 4 +.EX attrset(A_BOLD | COLOR_PAIR(\fIpair\fP)); attr_set(A_BOLD, \fIpair\fP, NULL); -.NE +.EE +.RE .PP However, if the value does not fit, then the \fBCOLOR_PAIR\fP macro uses only the bits that fit. -For example, because in ncurses \fBA_COLOR\fP has eight (8) bits, +For example, +because in \fI\%ncurses\fP \fBA_COLOR\fP has eight (8) bits, then \fBCOLOR_PAIR(\fI259\fB)\fR is 4 (i.e., 259 is 4 more than the limit 255). .PP @@ -219,10 +185,13 @@ The \fBPAIR_NUMBER\fP macro extracts a pair number from an \fBint\fP (or \fBchtype\fP). For example, the \fIinput\fP and \fIoutput\fP values in these statements would be the same: -.NS +.PP +.RS 4 +.EX int value = A_BOLD | COLOR_PAIR(\fIinput\fP); int \fIoutput\fP = PAIR_NUMBER(value); -.NE +.EE +.RE .PP The \fBattrset\fP routine is a legacy feature predating SVr4 curses but kept in X/Open Curses for the same reason that SVr4 curses kept it: @@ -232,11 +201,12 @@ The remaining \fBattr\fP* functions operate exactly like the corresponding \fBattr_\fP* functions, except that they take arguments of type \fBint\fP rather than \fBattr_t\fP. .PP -There is no corresponding \fBattrget\fP function as such in X/Open Curses, -although ncurses provides \fBgetattrs\fP (see curs_legacy(3X)). +There is no corresponding \fB\%attrget\fP function as such +in X/Open Curses, +although \fI\%ncurses\fP provides \fB\%getattrs\fP +(see \fB\%curs_legacy\fP(3X)). .\" --------------------------------------------------------------------------- -.SS Change character rendition -.PP +.SS "Change Character Rendition" The routine \fBchgat\fP changes the attributes of a given number of characters starting at the current cursor location of \fBstdscr\fP. It does not update @@ -248,69 +218,74 @@ The \fBwchgat\fP function generalizes this to any window; the \fBmvwchgat\fP function does a cursor move before acting. .PP In these functions, -the color \fIpair\fP argument is a color-pair index +the color \fIpair\fP argument is a color pair index (as in the first argument of \fBinit_pair\fP, see \fBcurs_color\fP(3X)). .\" --------------------------------------------------------------------------- -.SS Change window color +.SS "Change Window Color" The routine \fBcolor_set\fP sets the current color of the given window to the foreground/background combination described by the color \fIpair\fP parameter. .\" --------------------------------------------------------------------------- .SS Standout -.PP The routine \fBstandout\fP is the same as \fBattron(A_STANDOUT)\fP. The routine \fBstandend\fP is the same as \fBattrset(A_NORMAL)\fP or \fBattrset(0)\fP, that is, it turns off all attributes. .PP -X/Open does not mark these \*(``restricted\*('', because +X/Open Curses does not mark these \*(``restricted\*('', because .bP they have well established legacy use, and .bP there is no ambiguity about the way the attributes might be combined with a color pair. .\" --------------------------------------------------------------------------- -.SH VIDEO ATTRIBUTES +.SS "Video Attributes" The following video attributes, defined in \fB<curses.h>\fP, can be passed to the routines \fBattron\fP, \fBattroff\fP, and \fBattrset\fP, or OR'd with the characters passed to \fBaddch\fP (see \fBcurs_addch\fP(3X)). .PP +.ne 15 .RS .TS -l l -_ _ _ -l l . -\fBName\fP \fBDescription\fP -\fBA_NORMAL\fP Normal display (no highlight) -\fBA_STANDOUT\fP Best highlighting mode of the terminal. -\fBA_UNDERLINE\fP Underlining -\fBA_REVERSE\fP Reverse video -\fBA_BLINK\fP Blinking -\fBA_DIM\fP Half bright -\fBA_BOLD\fP Extra bright or bold -\fBA_PROTECT\fP Protected mode -\fBA_INVIS\fP Invisible or blank mode -\fBA_ALTCHARSET\fP Alternate character set -\fBA_ITALIC\fP Italics (non-X/Open extension) -\fBA_CHARTEXT\fP Bit-mask to extract a character -\fBA_COLOR\fP Bit-mask to extract a color (legacy routines) +Lb Lb +Lb Lx. +Name Description +_ +A_NORMAL Normal display (no highlight) +A_STANDOUT T{ +Best highlighting mode of the terminal +T} +A_UNDERLINE Underlining +A_REVERSE Reverse video +A_BLINK Blinking +A_DIM Half bright +A_BOLD Extra bright or bold +A_PROTECT Protected mode +A_INVIS Invisible or blank mode +A_ALTCHARSET Alternate character set +A_ITALIC Italics (non-X/Open extension) +A_CHARTEXT Bit-mask to extract a character +A_COLOR T{ +Bit-mask to extract a color (legacy routines) +T} .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.): +.PP .RS .TS -l l -_ _ _ -l l . -\fBName\fP \fBDescription\fP -\fBWA_HORIZONTAL\fP Horizontal highlight -\fBWA_LEFT\fP Left highlight -\fBWA_LOW\fP Low highlight -\fBWA_RIGHT\fP Right highlight -\fBWA_TOP\fP Top highlight -\fBWA_VERTICAL\fP Vertical highlight +Lb Lb +Lb Lx. +Name Description +_ +WA_HORIZONTAL Horizontal highlight +WA_LEFT Left highlight +WA_LOW Low highlight +WA_RIGHT Right highlight +WA_TOP Top highlight +WA_VERTICAL Vertical highlight .TE .RE .PP @@ -318,6 +293,27 @@ 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\fP. .\" --------------------------------------------------------------------------- +.SH RETURN VALUE +All routines return the integer \fBOK\fP on success, or \fBERR\fP on failure. +.PP +X/Open Curses does not specify any error conditions. +.PP +This implementation +.bP +returns an error if the window pointer is null. +.bP +returns an error if the color pair parameter +for \fBwcolor_set\fP is outside the range 0..COLOR_PAIRS\-1. +.bP +does not return an error if either of the parameters of \fBwattr_get\fP +used for retrieving attribute or color pair values is \fBNULL\fP. +.PP +Functions prefixed with \*(``mv\*('' first perform cursor movement and +fail if the position +.RI ( y , +.IR x ) +is outside the window boundaries. +.\" --------------------------------------------------------------------------- .SH NOTES These functions may be macros: .sp @@ -330,9 +326,133 @@ Color pair 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 +However, \fI\%ncurses\fP 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. +You must use \fI\%ncurses\fP ABI 6 to support more than 256 color pairs. +.\" --------------------------------------------------------------------------- +.SH EXTENSIONS +This implementation provides the \fBA_ITALIC\fP attribute for terminals +which have the \fBenter_italics_mode\fP (\fBsitm\fP) +and \fBexit_italics_mode\fP (\fBritm\fP) capabilities. +Italics are not mentioned in X/Open Curses. +Unlike the other video attributes, \fBA_ITALIC\fP is unrelated +to the \fBset_attributes\fP capabilities. +This implementation makes the assumption that +\fBexit_attribute_mode\fP may also reset italics. +.PP +Each of the functions added by XSI Curses has a parameter \fIopts\fP, +which X/Open Curses still (after more than twenty years) documents +as reserved for future use, saying that it should be \fBNULL\fP. +This implementation uses that parameter in ABI 6 for the functions which +have a color pair parameter to support \fIextended color pairs\fP: +.bP +For functions which modify the color, e.g., +\fBwattr_set\fP and \fBwattr_on\fP, +if \fIopts\fP is set it is treated as a pointer to \fBint\fP, +and used to set the color pair instead of the \fBshort\fP \fIpair\fP parameter. +.bP +For functions which retrieve the color, e.g., +\fBwattr_get\fP, +if \fIopts\fP is set it is treated as a pointer to \fBint\fP, +and used to retrieve the color pair as an \fBint\fP value, +in addition to +retrieving it via the standard pointer to \fBshort\fP parameter. +.bP +For functions which turn attributes off, e.g., +\fBwattr_off\fP, +the \fIopts\fP parameter is ignored except +except to check that it is \fBNULL\fP. +.\" --------------------------------------------------------------------------- +.SH PORTABILITY +These functions are described in X/Open Curses, Issue 4. +The standard defined the dedicated type for highlights, +\fBattr_t\fP, which was not defined in SVr4 curses. +The functions taking \fBattr_t\fP arguments were not supported under SVr4. +.PP +Very old versions of this library did not force an update of the screen +when changing the attributes. +Use \fBtouchwin\fP to force the screen to match the updated attributes. +.PP +X/Open Curses states that whether the traditional functions +\fBattron\fP/\fBattroff\fP/\fBattrset\fP can manipulate attributes other than +\fBA_BLINK\fP, \fBA_BOLD\fP, \fBA_DIM\fP, \fBA_REVERSE\fP, \fBA_STANDOUT\fP, or +\fBA_UNDERLINE\fP is \*(``unspecified\*(''. +Under this implementation as well as +SVr4 curses, these functions correctly manipulate all other highlights +(specifically, \fBA_ALTCHARSET\fP, \fBA_PROTECT\fP, and \fBA_INVIS\fP). +.PP +X/Open Curses added these entry points: +.sp +.RS +\fBattr_get\fP, \fBattr_on\fP, +\fBattr_off\fP, \fBattr_set\fP, \fBwattr_on\fP, \fBwattr_off\fP, +\fBwattr_get\fP, \fBwattr_set\fP +.RE +.PP +The new functions are intended to work with +a new series of highlight macros prefixed with \fBWA_\fP. +The older macros have direct counterparts in the newer set of names: +.PP +.RS +.ne 9 +.TS +Lb Lb +Lb Lx. +Name Description +_ +WA_NORMAL Normal display (no highlight) +WA_STANDOUT T{ +Best highlighting mode of the terminal +T} +WA_UNDERLINE Underlining +WA_REVERSE Reverse video +WA_BLINK Blinking +WA_DIM Half bright +WA_BOLD Extra bright or bold +WA_ALTCHARSET Alternate character set +.TE +.RE +.PP +X/Open Curses does not assign values to these symbols, +nor does it state whether or not they are related to the +similarly-named A_NORMAL, etc.: +.bP +X/Open Curses specifies that each pair of corresponding \fBA_\fP +and \fBWA_\fP-using functions operates on the same current-highlight +information. +.bP +However, in some implementations, those symbols have unrelated values. +.IP +For example, the Solaris \fIxpg4\fP (X/Open) curses declares +\fBattr_t\fP to be an unsigned short integer (16-bits), +while \fBchtype\fP is a unsigned integer (32-bits). +The \fBWA_\fP symbols in this case are different from the \fBA_\fP symbols +because they are used for a smaller datatype which does not +represent \fBA_CHARTEXT\fP or \fBA_COLOR\fP. +.IP +In this implementation (as in many others), the values happen to be +the same because it simplifies copying information between +\fBchtype\fP and \fBcchar_t\fP variables. +.bP +Because \fI\%ncurses\fP's \fBattr_t\fP can hold a color pair +(in the \fBA_COLOR\fP field), +a call to +\fBwattr_on\fP, +\fBwattr_off\fP, or +\fBwattr_set\fP +may alter the window's color. +If the color pair information in the attribute parameter is zero, +no change is made to the window's color. +.IP +This is consistent with SVr4 curses; +X/Open Curses does not specify this. +.PP +The X/Open Curses extended conformance level adds new highlights +\fBA_HORIZONTAL\fP, \fBA_LEFT\fP, \fBA_LOW\fP, \fBA_RIGHT\fP, \fBA_TOP\fP, +\fBA_VERTICAL\fP (and corresponding \fBWA_\fP macros for each). +As of August 2013, +no known terminal provides these highlights +(i.e., via the \fBsgr1\fP capability). .\" --------------------------------------------------------------------------- .SH HISTORY X/Open Curses is largely based on SVr4 curses, @@ -391,25 +511,26 @@ the format and size of the defined constants as well as clues such as the alternate character set implementation. A 32-bit library can be used on a 64-bit system, but not necessarily the reverse. -.RS +.PP .TS -l l l l l l -_ _ _ _ _ _ -l l l l l l . -\fBYear\fP \fBSystem\fP \fBArch\fP \fBColor\fP \fBChar\fP \fBNotes\fP -1992 Solaris 5.2 32 6 17 SVr4 curses -1992 HPUX 9 32 no 8 SVr2 curses -1992 AIX 3.2 32 no 23 SVr2 curses -1994 OSF/1 r3 32 no 23 SVr2 curses -1995 HP-UX 10.00 32 6 16 SVr3 \*(``curses_colr\*('' -1995 HP-UX 10.00 32 6 8 SVr4, X/Open curses -1995 Solaris 5.4 32/64 7 16 X/Open curses -1996 AIX 4.2 32 7 16 X/Open curses -1996 OSF/1 r4 32 6 16 X/Open curses -1997 HP-UX 11.00 32 6 8 X/Open curses -2000 U/Win 32/64 7/31 16 uses \fBchtype\fP +Lb Lb Lb Cb S Lb +Lb2 Lb Lb2 Lb2 Lb2 Lb +L L L L L Lx. +\& \& \& Bits \& +Year System Arch Color Char Notes +_ +1992 Solaris 5.2 32 6 17 SVr4 \fIcurses\fP +1992 HP-UX 9 32 no 8 SVr2 \fIcurses\fP +1992 AIX 3.2 32 no 23 SVr2 \fIcurses\fP +1994 OSF/1 r3 32 no 23 SVr2 \fIcurses\fP +1995 HP-UX 10.00 32 6 16 SVr3 \fIcurses_colr\fP +1995 HP-UX 10.00 32 6 8 SVr4, X/Open \fIcurses\fP +1995 Solaris 5.4 32/64 7 16 X/Open \fIcurses\fP +1996 AIX 4.2 32 7 16 X/Open \fIcurses\fP +1996 OSF/1 r4 32 6 16 X/Open \fIcurses\fP +1997 HP-UX 11.00 32 6 8 X/Open \fIcurses\fP +2000 U/Win 32/64 7/31 16 uses \fIchtype\fP .TE -.RE .PP Notes: .RS 3 @@ -424,8 +545,9 @@ That version of curses was dropped with HP-UX 11.30 in 2006. Regarding OSF/1 (and Tru64), .bP These used 64-bit hardware. -Like ncurses, the OSF/1 curses interface is not customized for 32-bit -and 64-bit versions. +Like \fI\%ncurses\fP, +the OSF/1 curses interface is not customized for 32-bit and 64-bit +versions. .bP Unlike other systems which evolved from AT&T code, OSF/1 provided a new implementation for X/Open curses. @@ -462,157 +584,15 @@ BSD curses was improved slightly in 1993/1994 using Keith Bostic's modification to make the library 8-bit clean for \fBnvi\fP(1). He moved \fIstandout\fP attribute to a structure member. .IP -The resulting 4.4BSD curses was replaced by ncurses over the next ten years. +The resulting 4.4BSD curses was replaced by \fI\%ncurses\fP over the +next ten years. .bP U/Win is rarely used now. .\" --------------------------------------------------------------------------- -.SH EXTENSIONS -.PP -This implementation provides the \fBA_ITALIC\fP attribute for terminals -which have the \fBenter_italics_mode\fP (\fBsitm\fP) -and \fBexit_italics_mode\fP (\fBritm\fP) capabilities. -Italics are not mentioned in X/Open Curses. -Unlike the other video attributes, \fBA_ITALIC\fP is unrelated -to the \fBset_attributes\fP capabilities. -This implementation makes the assumption that -\fBexit_attribute_mode\fP may also reset italics. -.PP -Each of the functions added by XSI Curses has a parameter \fIopts\fP, -which X/Open Curses still (after more than twenty years) documents -as reserved for future use, saying that it should be \fBNULL\fP. -This implementation uses that parameter in ABI 6 for the functions which -have a color-pair parameter to support \fIextended color pairs\fP: -.bP -For functions which modify the color, e.g., -\fBwattr_set\fP and \fBwattr_on\fP, -if \fIopts\fP is set it is treated as a pointer to \fBint\fP, -and used to set the color pair instead of the \fBshort\fP \fIpair\fP parameter. -.bP -For functions which retrieve the color, e.g., -\fBwattr_get\fP, -if \fIopts\fP is set it is treated as a pointer to \fBint\fP, -and used to retrieve the color pair as an \fBint\fP value, -in addition to -retrieving it via the standard pointer to \fBshort\fP parameter. -.bP -For functions which turn attributes off, e.g., -\fBwattr_off\fP, -the \fIopts\fP parameter is ignored except -except to check that it is \fBNULL\fP. -.\" --------------------------------------------------------------------------- -.SH PORTABILITY -These functions are supported in the XSI Curses standard, Issue 4. -The standard defined the dedicated type for highlights, -\fBattr_t\fP, which was not defined in SVr4 curses. -The functions taking \fBattr_t\fP arguments were not supported under SVr4. -.PP -Very old versions of this library did not force an update of the screen -when changing the attributes. -Use \fBtouchwin\fP to force the screen to match the updated attributes. -.PP -The XSI Curses standard states that whether the traditional functions -\fBattron\fP/\fBattroff\fP/\fBattrset\fP can manipulate attributes other than -\fBA_BLINK\fP, \fBA_BOLD\fP, \fBA_DIM\fP, \fBA_REVERSE\fP, \fBA_STANDOUT\fP, or -\fBA_UNDERLINE\fP is \*(``unspecified\*(''. -Under this implementation as well as -SVr4 curses, these functions correctly manipulate all other highlights -(specifically, \fBA_ALTCHARSET\fP, \fBA_PROTECT\fP, and \fBA_INVIS\fP). -.PP -XSI Curses added these entry points: -.sp -.RS -\fBattr_get\fP, \fBattr_on\fP, -\fBattr_off\fP, \fBattr_set\fP, \fBwattr_on\fP, \fBwattr_off\fP, -\fBwattr_get\fP, \fBwattr_set\fP -.RE -.PP -The new functions are intended to work with -a new series of highlight macros prefixed with \fBWA_\fP. -The older macros have direct counterparts in the newer set of names: -.PP -.RS -.ne 9 -.TS -l l -_ _ _ -l l . -\fBName\fP \fBDescription\fP -\fBWA_NORMAL\fP Normal display (no highlight) -\fBWA_STANDOUT\fP Best highlighting mode of the terminal. -\fBWA_UNDERLINE\fP Underlining -\fBWA_REVERSE\fP Reverse video -\fBWA_BLINK\fP Blinking -\fBWA_DIM\fP Half bright -\fBWA_BOLD\fP Extra bright or bold -\fBWA_ALTCHARSET\fP Alternate character set -.TE -.RE -.PP -XSI curses does not assign values to these symbols, -nor does it state whether or not they are related to the -similarly-named A_NORMAL, etc.: -.bP -The XSI curses standard specifies that each pair of corresponding \fBA_\fP -and \fBWA_\fP-using functions operates on the same current-highlight -information. -.bP -However, in some implementations, those symbols have unrelated values. -.IP -For example, the Solaris \fIxpg4\fP (X/Open) curses declares -\fBattr_t\fP to be an unsigned short integer (16-bits), -while \fBchtype\fP is a unsigned integer (32-bits). -The \fBWA_\fP symbols in this case are different from the \fBA_\fP symbols -because they are used for a smaller datatype which does not -represent \fBA_CHARTEXT\fP or \fBA_COLOR\fP. -.IP -In this implementation (as in many others), the values happen to be -the same because it simplifies copying information between -\fBchtype\fP and \fBcchar_t\fP variables. -.bP -Because ncurses's \fBattr_t\fP can hold a color pair -(in the \fBA_COLOR\fP field), -a call to -\fBwattr_on\fP, -\fBwattr_off\fP, or -\fBwattr_set\fP -may alter the window's color. -If the color pair information in the attribute parameter is zero, -no change is made to the window's color. -.IP -This is consistent with SVr4 curses; -X/Open Curses does not specify this. -.PP -The XSI standard extended conformance level adds new highlights -\fBA_HORIZONTAL\fP, \fBA_LEFT\fP, \fBA_LOW\fP, \fBA_RIGHT\fP, \fBA_TOP\fP, -\fBA_VERTICAL\fP (and corresponding \fBWA_\fP 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\fP on success, or \fBERR\fP on failure. -.PP -X/Open does not define any error conditions. -.PP -This implementation -.bP -returns an error if the window pointer is null. -.bP -returns an error if the color pair parameter -for \fBwcolor_set\fP is outside the range 0..COLOR_PAIRS\-1. -.bP -does not return an error if either of the parameters of \fBwattr_get\fP -used for retrieving attribute or color-pair values is \fBNULL\fP. -.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\fP(3X), -\fBcurs_addch\fP(3X), -\fBcurs_addstr\fP(3X), -\fBcurs_bkgd\fP(3X), -\fBcurs_printw\fP(3X), -\fBcurs_variables\fP(3X) +\fB\%curses\fP(3X), +\fB\%curs_addch\fP(3X), +\fB\%curs_addstr\fP(3X), +\fB\%curs_bkgd\fP(3X), +\fB\%curs_printw\fP(3X), +\fB\%curs_variables\fP(3X) |