| 1 |
'\" t |
| 2 |
.\"*************************************************************************** |
| 3 |
.\" Copyright 2018-2024,2025 Thomas E. Dickey * |
| 4 |
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * |
| 5 |
.\" * |
| 6 |
.\" Permission is hereby granted, free of charge, to any person obtaining a * |
| 7 |
.\" copy of this software and associated documentation files (the * |
| 8 |
.\" "Software"), to deal in the Software without restriction, including * |
| 9 |
.\" without limitation the rights to use, copy, modify, merge, publish, * |
| 10 |
.\" distribute, distribute with modifications, sublicense, and/or sell * |
| 11 |
.\" copies of the Software, and to permit persons to whom the Software is * |
| 12 |
.\" furnished to do so, subject to the following conditions: * |
| 13 |
.\" * |
| 14 |
.\" The above copyright notice and this permission notice shall be included * |
| 15 |
.\" in all copies or substantial portions of the Software. * |
| 16 |
.\" * |
| 17 |
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| 18 |
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| 19 |
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| 20 |
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| 21 |
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| 22 |
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| 23 |
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| 24 |
.\" * |
| 25 |
.\" Except as contained in this notice, the name(s) of the above copyright * |
| 26 |
.\" holders shall not be used in advertising or otherwise to promote the * |
| 27 |
.\" sale, use or other dealings in this Software without prior written * |
| 28 |
.\" authorization. * |
| 29 |
.\"*************************************************************************** |
| 30 |
.\" |
| 31 |
.\" $Id: curs_attr.3x,v 1.142 2025/11/12 01:05:49 tom Exp $ |
| 32 |
.TH attr 3NCURSES 2025-11-11 "ncurses 6.6" "Library calls" |
| 33 |
.ie \n(.g \{\ |
| 34 |
.ds `` \(lq |
| 35 |
.ds '' \(rq |
| 36 |
.\} |
| 37 |
.el \{\ |
| 38 |
.ie t .ds `` `` |
| 39 |
.el .ds `` "" |
| 40 |
.ie t .ds '' '' |
| 41 |
.el .ds '' "" |
| 42 |
.\} |
| 43 |
. |
| 44 |
.de bP |
| 45 |
.ie n .IP \(bu 4 |
| 46 |
.el .IP \(bu 2 |
| 47 |
.. |
| 48 |
.\" --------------------------------------------------------------------------- |
| 49 |
.SH NAME |
| 50 |
\fB\%attr_get\fP, |
| 51 |
\fB\%wattr_get\fP, |
| 52 |
\fB\%attr_set\fP, |
| 53 |
\fB\%wattr_set\fP, |
| 54 |
\fB\%attr_off\fP, |
| 55 |
\fB\%wattr_off\fP, |
| 56 |
\fB\%attr_on\fP, |
| 57 |
\fB\%wattr_on\fP, |
| 58 |
\fB\%attroff\fP, |
| 59 |
\fB\%wattroff\fP, |
| 60 |
\fB\%attron\fP, |
| 61 |
\fB\%wattron\fP, |
| 62 |
\fB\%attrset\fP, |
| 63 |
\fB\%wattrset\fP, |
| 64 |
\fB\%chgat\fP, |
| 65 |
\fB\%wchgat\fP, |
| 66 |
\fB\%mvchgat\fP, |
| 67 |
\fB\%mvwchgat\fP, |
| 68 |
\fB\%color_set\fP, |
| 69 |
\fB\%wcolor_set\fP, |
| 70 |
\fB\%standend\fP, |
| 71 |
\fB\%wstandend\fP, |
| 72 |
\fB\%standout\fP, |
| 73 |
\fB\%wstandout\fP \- |
| 74 |
manipulate attributes of character cells in \fIcurses\fR windows |
| 75 |
.\" --------------------------------------------------------------------------- |
| 76 |
.SH SYNOPSIS |
| 77 |
.nf |
| 78 |
\fB#include <curses.h> |
| 79 |
.PP |
| 80 |
\fBint attr_get(attr_t *\fIattrs\fP, short *\fIpair\fP, void *\fIopts\fP); |
| 81 |
\fBint wattr_get(WINDOW *\fIwin\fP, attr_t *\fIattrs\fP, short *\fIpair\fP,\fR \fPvoid *\fIopts\fP); |
| 82 |
\fBint attr_set(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP); |
| 83 |
\fBint wattr_set(WINDOW *\fIwin\fP, attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP); |
| 84 |
.PP |
| 85 |
\fBint attr_off(attr_t \fIattrs\fP, void *\fIopts\fP); |
| 86 |
\fBint wattr_off(WINDOW *\fIwin\fP, attr_t \fIattrs\fP, void *\fIopts\fP); |
| 87 |
\fBint attr_on(attr_t \fIattrs\fP, void *\fIopts\fP); |
| 88 |
\fBint wattr_on(WINDOW *\fIwin\fP, attr_t \fIattrs\fP, void *\fIopts\fP); |
| 89 |
.PP |
| 90 |
\fBint attroff(int \fIattrs\fP); |
| 91 |
\fBint wattroff(WINDOW *\fIwin\fP, int \fIattrs\fP); |
| 92 |
\fBint attron(int \fIattrs\fP); |
| 93 |
\fBint wattron(WINDOW *\fIwin\fP, int \fIattrs\fP); |
| 94 |
\fBint attrset(int \fIattrs\fP); |
| 95 |
\fBint wattrset(WINDOW *\fIwin\fP, int \fIattrs\fP); |
| 96 |
.PP |
| 97 |
\fBint chgat(int \fIn\fP, attr_t \fIattr\fP, short \fIpair\fP,\fR \fPconst void *\fIopts\fP); |
| 98 |
\fBint wchgat(WINDOW *\fIwin\fP, |
| 99 |
\fBint \fIn\fB, attr_t \fIattr\fB,\fR \fBshort \fIpair\fB, const void *\fIopts\fB);\fR |
| 100 |
\fBint mvchgat(int \fIy\fB, int \fIx\fB,\fR |
| 101 |
\fBint \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR |
| 102 |
\fBint mvwchgat(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB,\fR |
| 103 |
\fBint \fIn\fB, attr_t \fIattr\fB, short \fIpair\fB, const void *\fIopts\fB);\fR |
| 104 |
.PP |
| 105 |
\fBint color_set(short \fIpair\fB, void* \fIopts\fB);\fR |
| 106 |
\fBint wcolor_set(WINDOW *\fIwin\fB, short \fIpair\fB,\fR \fBvoid* \fIopts\fP);\fR |
| 107 |
.PP |
| 108 |
\fBint standend(void);\fP |
| 109 |
\fBint wstandend(WINDOW *\fIwin\fB);\fR |
| 110 |
\fBint standout(void);\fP |
| 111 |
\fBint wstandout(WINDOW *\fIwin\fB);\fR |
| 112 |
.fi |
| 113 |
.\" --------------------------------------------------------------------------- |
| 114 |
.SH DESCRIPTION |
| 115 |
These routines manipulate the current attributes of the named window, |
| 116 |
which then apply to all characters that are written into |
| 117 |
the window with \fBwaddch\fP, \fBwaddstr\fP and \fBwprintw\fP. |
| 118 |
Attributes are |
| 119 |
a property of the character, and move with the character through any scrolling |
| 120 |
and insert/delete line/character operations. |
| 121 |
To the extent possible, they are |
| 122 |
displayed as appropriate modifications to the graphic rendition of characters |
| 123 |
put on the screen. |
| 124 |
.PP |
| 125 |
These routines do not affect the attributes used |
| 126 |
when erasing portions of the window. |
| 127 |
See \fBbkgd\fP(3NCURSES) for functions which modify the attributes used for |
| 128 |
erasing and clearing. |
| 129 |
.\" --------------------------------------------------------------------------- |
| 130 |
.SS "Window Attributes" |
| 131 |
There are two sets of functions: |
| 132 |
.bP |
| 133 |
functions for manipulating the window attributes and color: |
| 134 |
\fBwattr_set\fP and \fBwattr_get\fP. |
| 135 |
.bP |
| 136 |
functions for manipulating only the window attributes (not color): |
| 137 |
\fBwattr_on\fP and \fBwattr_off\fP. |
| 138 |
.PP |
| 139 |
The \fBwattr_set\fP function sets the current attributes |
| 140 |
of the given window to \fIattrs\fP, with color specified by \fIpair\fP. |
| 141 |
.PP |
| 142 |
Use \fBwattr_get\fP to retrieve attributes for the given window. |
| 143 |
.PP |
| 144 |
Use \fBattr_on\fP and \fBwattr_on\fP to turn on window attributes, i.e., |
| 145 |
values logically \*(``or\*(''-ed together in \fIattr\fP, |
| 146 |
without affecting other attributes. |
| 147 |
Use \fBattr_off\fP and \fBwattr_off\fP to turn off window attributes, |
| 148 |
again values logically \*(``or\*(''-ed together in \fIattr\fP, |
| 149 |
without affecting other attributes. |
| 150 |
.\" --------------------------------------------------------------------------- |
| 151 |
.SS "Legacy Window Attributes" |
| 152 |
The X/Open window attribute routines which \fIset\fP or \fIget\fP, |
| 153 |
turn \fIon\fP or \fIoff\fP |
| 154 |
are extensions of older routines |
| 155 |
which assume that color pairs are logically \*(``or\*(''-ed |
| 156 |
into the attribute parameter. |
| 157 |
These newer routines use similar names, because |
| 158 |
X/Open simply added an underscore (\fB_\fP) for the newer names. |
| 159 |
.PP |
| 160 |
The |
| 161 |
.I int |
| 162 |
datatype used in the legacy routines is treated as if |
| 163 |
it is the same size as |
| 164 |
.I \%chtype |
| 165 |
(used by \fBaddch\fP(3NCURSES)). |
| 166 |
It holds the common video attributes (such as bold, reverse), |
| 167 |
as well as a few bits for color. |
| 168 |
Those bits correspond to the \fBA_COLOR\fP symbol. |
| 169 |
The \fBCOLOR_PAIR\fP macro provides a value which can be |
| 170 |
logically \*(``or\*(''-ed into the attribute parameter. |
| 171 |
For example, |
| 172 |
as long as that value fits into the \fBA_COLOR\fP mask, |
| 173 |
then these calls produce similar results: |
| 174 |
.PP |
| 175 |
.RS 4 |
| 176 |
.EX |
| 177 |
.nf |
| 178 |
attrset(A_BOLD | COLOR_PAIR(\fIpair\fP)); |
| 179 |
attr_set(A_BOLD, \fIpair\fP, NULL); |
| 180 |
.fi |
| 181 |
.EE |
| 182 |
.RE |
| 183 |
.PP |
| 184 |
However, if the value does not fit, then the \fBCOLOR_PAIR\fP macro |
| 185 |
uses only the bits that fit. |
| 186 |
For example, |
| 187 |
because in |
| 188 |
.I \%ncurses |
| 189 |
\fBA_COLOR\fP has eight (8) bits, |
| 190 |
then \fBCOLOR_PAIR(\fI259\fB)\fR is 4 |
| 191 |
(i.e., 259 is 4 more than the limit 255). |
| 192 |
.PP |
| 193 |
The \fBPAIR_NUMBER\fP macro extracts a pair number from an |
| 194 |
.I int |
| 195 |
(or |
| 196 |
.IR \%chtype ")." |
| 197 |
For example, the \fIinput\fP and \fIoutput\fP values in these statements |
| 198 |
would be the same: |
| 199 |
.PP |
| 200 |
.RS 4 |
| 201 |
.EX |
| 202 |
.nf |
| 203 |
int value = A_BOLD | COLOR_PAIR(\fIinput\fP); |
| 204 |
int \fIoutput\fP = PAIR_NUMBER(value); |
| 205 |
.fi |
| 206 |
.EE |
| 207 |
.RE |
| 208 |
.PP |
| 209 |
The \fBattrset\fP routine is a legacy feature predating SVr4 |
| 210 |
.I curses |
| 211 |
but kept in X/Open Curses for the same reason that SVr4 |
| 212 |
.I curses |
| 213 |
kept it: |
| 214 |
compatibility. |
| 215 |
.PP |
| 216 |
The remaining \fBattr\fP* functions operate exactly like the corresponding |
| 217 |
\fBattr_\fP* functions, except that they take arguments of type |
| 218 |
.I int |
| 219 |
rather than |
| 220 |
.IR \%attr_t "." |
| 221 |
.PP |
| 222 |
There is no corresponding \fB\%attrget\fP function as such |
| 223 |
in X/Open Curses, |
| 224 |
although |
| 225 |
.I \%ncurses |
| 226 |
provides \fB\%getattrs\fP |
| 227 |
(see \fB\%legacy\fP(3NCURSES)). |
| 228 |
.\" --------------------------------------------------------------------------- |
| 229 |
.SS "Change Character Rendition" |
| 230 |
The routine \fBchgat\fP changes the attributes of a given number of characters |
| 231 |
starting at the current cursor location of \fBstdscr\fP. |
| 232 |
It does not update |
| 233 |
the cursor and does not perform wrapping. |
| 234 |
A character count of \-1 or greater |
| 235 |
than the remaining window width means to change attributes all the way to the |
| 236 |
end of the current line. |
| 237 |
The \fBwchgat\fP function generalizes this to any window; |
| 238 |
the \fBmvwchgat\fP function does a cursor move before acting. |
| 239 |
.PP |
| 240 |
In these functions, |
| 241 |
the color \fIpair\fP argument is a color pair index |
| 242 |
(as in the first argument of \fBinit_pair\fP, see \fBcolor\fP(3NCURSES)). |
| 243 |
.\" --------------------------------------------------------------------------- |
| 244 |
.SS "Change Window Color" |
| 245 |
The routine \fBcolor_set\fP sets the current color of the given window to the |
| 246 |
foreground/background combination described by the color \fIpair\fP parameter. |
| 247 |
.\" --------------------------------------------------------------------------- |
| 248 |
.SS Standout |
| 249 |
The routine \fBstandout\fP is |
| 250 |
the same as \fBattron(A_STANDOUT)\fP. |
| 251 |
The routine \fBstandend\fP is the same |
| 252 |
as \fBattrset(A_NORMAL)\fP or \fBattrset(0)\fP, that is, it turns off all |
| 253 |
attributes. |
| 254 |
.PP |
| 255 |
X/Open Curses does not mark these \*(``restricted\*('', because |
| 256 |
.bP |
| 257 |
they have well established legacy use, and |
| 258 |
.bP |
| 259 |
there is no ambiguity about the way the attributes |
| 260 |
might be combined with a color pair. |
| 261 |
.\" --------------------------------------------------------------------------- |
| 262 |
.SS "Video Attributes" |
| 263 |
The following video attributes, |
| 264 |
defined in |
| 265 |
.IR \%curses.h "," |
| 266 |
can be passed to |
| 267 |
.BR \%attron "," |
| 268 |
.BR \%attroff "," |
| 269 |
.BR \%attrset "," |
| 270 |
and |
| 271 |
logically \*(``or\*(''-ed with characters passed to \fBaddch\fP(3NCURSES). |
| 272 |
.PP |
| 273 |
.if t .ne 15 |
| 274 |
.if n .ne 16 |
| 275 |
.RS |
| 276 |
.TS |
| 277 |
Lb Lb |
| 278 |
Lb Lx. |
| 279 |
Name Description |
| 280 |
_ |
| 281 |
A_NORMAL Normal display (no highlight) |
| 282 |
A_STANDOUT Best highlighting mode available |
| 283 |
A_UNDERLINE Underlining |
| 284 |
A_REVERSE Reverse video |
| 285 |
A_BLINK Blinking |
| 286 |
A_DIM Half bright |
| 287 |
A_BOLD Extra bright or bold |
| 288 |
A_PROTECT Protected mode |
| 289 |
A_INVIS Invisible or blank mode |
| 290 |
A_ALTCHARSET Alternate character set |
| 291 |
A_ITALIC Italics (non-X/Open extension) |
| 292 |
A_ATTRIBUTES Mask to extract character code |
| 293 |
A_CHARTEXT Mask to extract attributes |
| 294 |
A_COLOR Mask to extract color pair identifier |
| 295 |
.TE |
| 296 |
.RE |
| 297 |
.PP |
| 298 |
.BR \%attr_on "," |
| 299 |
.BR \%attr_off "," |
| 300 |
and |
| 301 |
.B \%attr_set |
| 302 |
support the foregoing as well as the following additional attributes. |
| 303 |
.PP |
| 304 |
.if t .ne 7 |
| 305 |
.if n .ne 8 |
| 306 |
.RS |
| 307 |
.TS |
| 308 |
Lb Lb |
| 309 |
Lb Lx. |
| 310 |
Name Description |
| 311 |
_ |
| 312 |
WA_HORIZONTAL Horizontal highlight |
| 313 |
WA_LEFT Left highlight |
| 314 |
WA_LOW Low highlight |
| 315 |
WA_RIGHT Right highlight |
| 316 |
WA_TOP Top highlight |
| 317 |
WA_VERTICAL Vertical highlight |
| 318 |
.TE |
| 319 |
.RE |
| 320 |
.\" --------------------------------------------------------------------------- |
| 321 |
.SH RETURN VALUE |
| 322 |
These functions return |
| 323 |
.B OK |
| 324 |
on success and |
| 325 |
.B ERR |
| 326 |
on failure. |
| 327 |
.PP |
| 328 |
In |
| 329 |
.IR \%ncurses "," |
| 330 |
they return |
| 331 |
.B ERR |
| 332 |
if |
| 333 |
.I win |
| 334 |
is |
| 335 |
.IR NULL "." |
| 336 |
.PP |
| 337 |
.B \%wcolor_set |
| 338 |
returns |
| 339 |
.B ERR |
| 340 |
if |
| 341 |
.I pair |
| 342 |
is outside the range |
| 343 |
.BR 0 .\|. COLOR_PAIRS\-1 . |
| 344 |
.PP |
| 345 |
.B \%wattr_get |
| 346 |
does |
| 347 |
.I not |
| 348 |
fail if its |
| 349 |
.I \%attrs |
| 350 |
or |
| 351 |
.I \%pair |
| 352 |
parameter is |
| 353 |
.IR NULL "." |
| 354 |
.PP |
| 355 |
Functions prefixed with \*(``mv\*('' first perform cursor movement and |
| 356 |
fail if the position |
| 357 |
.RI ( y , |
| 358 |
.IR x ) |
| 359 |
is outside the window boundaries. |
| 360 |
.\" --------------------------------------------------------------------------- |
| 361 |
.SH NOTES |
| 362 |
.BR \%attr_on "," |
| 363 |
.BR \%attr_off "," |
| 364 |
.BR \%attr_set "," |
| 365 |
.BR \%wattr_set "," |
| 366 |
.BR \%chgat "," |
| 367 |
.BR \%mvchgat "," |
| 368 |
.BR \%mvwchgat "," |
| 369 |
.BR \%wchgat "," |
| 370 |
and |
| 371 |
.B \%color_set |
| 372 |
are part of |
| 373 |
.IR \%ncurses "'s" |
| 374 |
wide-character API, |
| 375 |
and are not available in its non-wide-character configuration. |
| 376 |
.PP |
| 377 |
.BR \%attron "," |
| 378 |
.BR \%wattron "," |
| 379 |
.BR \%attroff "," |
| 380 |
.BR \%wattroff "," |
| 381 |
.BR \%attrset "," |
| 382 |
.BR \%wattrset "," |
| 383 |
.BR \%standout "," |
| 384 |
and |
| 385 |
.B \%standend |
| 386 |
may be implemented as macros. |
| 387 |
.PP |
| 388 |
Color pair values may be logically \*(``or\*(''-ed with attributes |
| 389 |
if the pair number is less than 256. |
| 390 |
The alternate functions such as \fBcolor_set\fP can pass a color pair |
| 391 |
value directly. |
| 392 |
However, |
| 393 |
.I \%ncurses |
| 394 |
ABI 4 and 5 simply logically \*(``or\*('' this value |
| 395 |
within the alternate functions. |
| 396 |
You must use |
| 397 |
.I \%ncurses |
| 398 |
ABI 6 to support more than 256 color pairs. |
| 399 |
.\" --------------------------------------------------------------------------- |
| 400 |
.SH EXTENSIONS |
| 401 |
This implementation provides the \fBA_ITALIC\fP attribute for terminals |
| 402 |
which have the \fBenter_italics_mode\fP (\fBsitm\fP) |
| 403 |
and \fBexit_italics_mode\fP (\fBritm\fP) capabilities. |
| 404 |
Italics are not mentioned in X/Open Curses. |
| 405 |
Unlike the other video attributes, \fBA_ITALIC\fP is unrelated |
| 406 |
to the \fBset_attributes\fP capabilities. |
| 407 |
This implementation makes the assumption that |
| 408 |
\fBexit_attribute_mode\fP may also reset italics. |
| 409 |
.PP |
| 410 |
Each of the functions added by XSI Curses has a parameter \fIopts\fP, |
| 411 |
which X/Open Curses still (after more than twenty years) documents |
| 412 |
as reserved for future use, saying that it should be |
| 413 |
.IR NULL "." |
| 414 |
This implementation uses that parameter in ABI 6 for the functions which |
| 415 |
have a color pair parameter to support \fIextended color pairs\fP: |
| 416 |
.bP |
| 417 |
For functions which modify the color, e.g., |
| 418 |
\fBwattr_set\fP and \fBwattr_on\fP, |
| 419 |
if \fIopts\fP is set it is treated as a pointer to |
| 420 |
.IR int "," |
| 421 |
and used to set the color pair instead of the |
| 422 |
.I short |
| 423 |
.I pair |
| 424 |
parameter. |
| 425 |
.bP |
| 426 |
For functions which retrieve the color, e.g., |
| 427 |
\fBwattr_get\fP, |
| 428 |
if \fIopts\fP is set it is treated as a pointer to |
| 429 |
.IR int "," |
| 430 |
and used to retrieve the color pair as an |
| 431 |
.I int |
| 432 |
value, |
| 433 |
in addition to |
| 434 |
retrieving it via the standard pointer to |
| 435 |
.I short |
| 436 |
parameter. |
| 437 |
.bP |
| 438 |
For functions which turn attributes off, e.g., |
| 439 |
\fBwattr_off\fP, |
| 440 |
the \fIopts\fP parameter is ignored except to check that it is |
| 441 |
.IR NULL "." |
| 442 |
.\" --------------------------------------------------------------------------- |
| 443 |
.SH PORTABILITY |
| 444 |
These functions are described in X/Open Curses Issue\ 4. |
| 445 |
It specifies no error conditions for them. |
| 446 |
.PP |
| 447 |
The standard defined the dedicated type for highlights, |
| 448 |
.IR \%attr_t "," |
| 449 |
which was not defined in SVr4 |
| 450 |
.IR curses "." |
| 451 |
The functions taking |
| 452 |
.I \%attr_t |
| 453 |
arguments were not supported under SVr4. |
| 454 |
.PP |
| 455 |
SVr4 describes the functions not taking |
| 456 |
.I \%attr_t |
| 457 |
or |
| 458 |
.I pair |
| 459 |
arguments as always returning |
| 460 |
.BR 1 "." \" Courier roman in source; SVID 4, vol. 3, p. 480 |
| 461 |
.PP |
| 462 |
Very old versions of this library did not force an update of the screen |
| 463 |
when changing the attributes. |
| 464 |
Use \fBtouchwin\fP to force the screen to match the updated attributes. |
| 465 |
.PP |
| 466 |
X/Open Curses states that whether the traditional functions |
| 467 |
\fBattron\fP/\fBattroff\fP/\fBattrset\fP can manipulate attributes other than |
| 468 |
\fBA_BLINK\fP, \fBA_BOLD\fP, \fBA_DIM\fP, \fBA_REVERSE\fP, \fBA_STANDOUT\fP, or |
| 469 |
\fBA_UNDERLINE\fP is \*(``unspecified\*(''. |
| 470 |
Under this implementation as well as |
| 471 |
SVr4 |
| 472 |
.IR curses "," |
| 473 |
these functions correctly manipulate all other highlights |
| 474 |
(specifically, \fBA_ALTCHARSET\fP, \fBA_PROTECT\fP, and \fBA_INVIS\fP). |
| 475 |
.PP |
| 476 |
X/Open Curses added these entry points: |
| 477 |
.sp |
| 478 |
.RS |
| 479 |
\fBattr_get\fP, \fBattr_on\fP, |
| 480 |
\fBattr_off\fP, \fBattr_set\fP, \fBwattr_on\fP, \fBwattr_off\fP, |
| 481 |
\fBwattr_get\fP, \fBwattr_set\fP |
| 482 |
.RE |
| 483 |
.PP |
| 484 |
The new functions are intended to work with |
| 485 |
a new series of highlight macros prefixed with \fBWA_\fP. |
| 486 |
The older macros have direct counterparts in the newer set of names: |
| 487 |
.PP |
| 488 |
.RS |
| 489 |
.ne 9 |
| 490 |
.TS |
| 491 |
Lb Lb |
| 492 |
Lb L . |
| 493 |
Name Description |
| 494 |
_ |
| 495 |
WA_NORMAL Normal display (no highlight) |
| 496 |
WA_STANDOUT Best highlighting mode available |
| 497 |
WA_UNDERLINE Underlining |
| 498 |
WA_REVERSE Reverse video |
| 499 |
WA_BLINK Blinking |
| 500 |
WA_DIM Half bright |
| 501 |
WA_BOLD Extra bright or bold |
| 502 |
WA_ALTCHARSET Alternate character set |
| 503 |
.TE |
| 504 |
.RE |
| 505 |
.PP |
| 506 |
X/Open Curses does not assign values to these symbols, |
| 507 |
nor does it state whether or not they are related to the |
| 508 |
similarly-named A_NORMAL, etc.: |
| 509 |
.bP |
| 510 |
X/Open Curses specifies that each pair of corresponding \fBA_\fP |
| 511 |
and \fBWA_\fP-using functions operates on the same current-highlight |
| 512 |
information. |
| 513 |
.bP |
| 514 |
However, in some implementations, those symbols have unrelated values. |
| 515 |
.IP |
| 516 |
For example, the Solaris \fIxpg4\fP (X/Open) |
| 517 |
.I curses |
| 518 |
declares |
| 519 |
.I \%attr_t |
| 520 |
to be an unsigned short integer (16-bits), |
| 521 |
while |
| 522 |
.I \%chtype |
| 523 |
is a unsigned integer (32-bits). |
| 524 |
The \fBWA_\fP symbols in this case are different from the \fBA_\fP symbols |
| 525 |
because they are used for a smaller datatype which does not |
| 526 |
represent \fBA_CHARTEXT\fP or \fBA_COLOR\fP. |
| 527 |
.IP |
| 528 |
In this implementation (as in many others), the values happen to be |
| 529 |
the same because it simplifies copying information between |
| 530 |
.I \%chtype |
| 531 |
and |
| 532 |
.I \%cchar_t |
| 533 |
variables. |
| 534 |
.bP |
| 535 |
Because |
| 536 |
.IR \%ncurses 's |
| 537 |
.I \%attr_t |
| 538 |
can hold a color pair |
| 539 |
(in the \fBA_COLOR\fP field), |
| 540 |
a call to |
| 541 |
\fBwattr_on\fP, |
| 542 |
\fBwattr_off\fP, or |
| 543 |
\fBwattr_set\fP |
| 544 |
may alter the window's color. |
| 545 |
If the color pair information in the attribute parameter is zero, |
| 546 |
no change is made to the window's color. |
| 547 |
.IP |
| 548 |
This is consistent with SVr4 |
| 549 |
.IR curses ";" |
| 550 |
X/Open Curses does not specify this. |
| 551 |
.PP |
| 552 |
The X/Open Curses extended conformance level adds new highlights |
| 553 |
\fBA_HORIZONTAL\fP, \fBA_LEFT\fP, \fBA_LOW\fP, \fBA_RIGHT\fP, \fBA_TOP\fP, |
| 554 |
\fBA_VERTICAL\fP (and corresponding \fBWA_\fP macros for each). |
| 555 |
As of August 2013, |
| 556 |
no known terminal provides these highlights |
| 557 |
(i.e., via the \fBsgr1\fP capability). |
| 558 |
.\" --------------------------------------------------------------------------- |
| 559 |
.SH HISTORY |
| 560 |
4BSD (1980) |
| 561 |
used a |
| 562 |
.I char |
| 563 |
to represent each cell of the terminal screen. |
| 564 |
It assumed 7-bit character codes, |
| 565 |
employing the eighth bit of a byte to represent a |
| 566 |
.I \%standout |
| 567 |
attribute |
| 568 |
(often implemented as bold and/or reverse video). |
| 569 |
It introduced |
| 570 |
.IR \%standout "," |
| 571 |
.IR \%standend "," |
| 572 |
.IR \%wstandout "," |
| 573 |
and |
| 574 |
.I \%wstandend |
| 575 |
functions to manipulate this bit. |
| 576 |
Despite their inflexibility, |
| 577 |
they carried over into System\ V |
| 578 |
.I curses |
| 579 |
and ultimately X/Open Curses |
| 580 |
due to their pervasive use in legacy applications. |
| 581 |
While some 1980s terminals supported a variety of video attributes, |
| 582 |
BSD |
| 583 |
.I curses |
| 584 |
could do nothing with them. |
| 585 |
.PP |
| 586 |
SVr2 (1984) |
| 587 |
provided an improved |
| 588 |
.I curses |
| 589 |
library, |
| 590 |
introducing |
| 591 |
.I \%chtype |
| 592 |
to create the abstract notion of a |
| 593 |
.I curses |
| 594 |
character; |
| 595 |
this was by default an |
| 596 |
.IR "unsigned short" "," |
| 597 |
with a provision for compile-time redefinition to other integral types |
| 598 |
(a freedom not necessarily available to users of shared libraries, |
| 599 |
and in any event a source license was necessary to exercise it). |
| 600 |
It added the functions |
| 601 |
.IR \%attron "," |
| 602 |
.IR \%attroff "," |
| 603 |
.IR \%attrset "," |
| 604 |
.IR \%wattron "," |
| 605 |
.IR \%wattroff "," |
| 606 |
and |
| 607 |
.IR \%wattrset "," |
| 608 |
and defined the |
| 609 |
.I A_ |
| 610 |
macros listed above |
| 611 |
(except for |
| 612 |
.I \%A_ITALIC |
| 613 |
and |
| 614 |
.IR \%A_COLOR ")" |
| 615 |
for use by applications to manipulate other attributes. |
| 616 |
The values of these macros |
| 617 |
were not necessarily the same in different systems, |
| 618 |
even among those certified as System\ V. |
| 619 |
.PP |
| 620 |
SVr3.2 (1988) |
| 621 |
added the |
| 622 |
.I \%A_COLOR |
| 623 |
macro along with a color system; |
| 624 |
see \fBcolor\fP(3NCURSES). |
| 625 |
.PP |
| 626 |
X/Open Curses Issue\ 4 (1995) is largely based on SVr4 |
| 627 |
.IR curses "," |
| 628 |
but recognized that the |
| 629 |
.I \%wchar_t |
| 630 |
type of ISO C95 was intended to house only a single character code, |
| 631 |
not a sequence of codes combining with a base character, |
| 632 |
let alone could it reliably offer room for a color pair identifier |
| 633 |
and a set of attribute bits with a potential for further growth \(em |
| 634 |
thus the standard invented the |
| 635 |
.I curses |
| 636 |
complex character type |
| 637 |
.I \%cchar_t |
| 638 |
and a separate type |
| 639 |
.I \%attr_t |
| 640 |
for storage of attribute bits. |
| 641 |
The new types brought along several new functions to manipulate them, |
| 642 |
some corresponding to existing |
| 643 |
.IR chtype -based |
| 644 |
functions |
| 645 |
.RI \%( attr_on , |
| 646 |
.IR \%attr_off "," |
| 647 |
.IR \%attr_set "," |
| 648 |
.IR \%wattr_on "," |
| 649 |
.IR \%wattr_off "," |
| 650 |
and |
| 651 |
.IR \%wattr_set ")," |
| 652 |
and some new |
| 653 |
.RI \%( chgat |
| 654 |
and its variants, |
| 655 |
.IR \%color_set "," |
| 656 |
and |
| 657 |
.IR \%wcolor_set ")." |
| 658 |
.PP |
| 659 |
Different Unix systems used differently sized bit fields in |
| 660 |
.I \%chtype |
| 661 |
for the character code and the color pair identifier, |
| 662 |
and took into account platforms' different integer sizes |
| 663 |
(32- versus 64-bit). |
| 664 |
.PP |
| 665 |
The following table showing the number of bits for |
| 666 |
.I \%A_COLOR |
| 667 |
and |
| 668 |
.I \%A_CHARTEXT |
| 669 |
was gleaned from the |
| 670 |
.I curses |
| 671 |
header files for various operating systems and architectures. |
| 672 |
The inferred architecture and notes |
| 673 |
reflect the format and size of the defined constants |
| 674 |
as well as clues such as the alternate character set implementation. |
| 675 |
A 32-bit library can be used on a 64-bit system, |
| 676 |
but not necessarily the converse. |
| 677 |
.PP |
| 678 |
.TS |
| 679 |
Lb Lb Lb Cb S Lb |
| 680 |
Lb2 Lb Lb2 Lb2 Lb2 Lb |
| 681 |
L L L L L Lx. |
| 682 |
\& \& \& Bits \& |
| 683 |
Year System Arch Color Char Notes |
| 684 |
_ |
| 685 |
1992 Solaris 5.2 32 6 17 SVr4 \fIcurses\fP |
| 686 |
1992 HP-UX 9 32 no 8 SVr2 \fIcurses\fP |
| 687 |
1992 AIX 3.2 32 no 23 SVr2 \fIcurses\fP |
| 688 |
1994 OSF/1 r3 32 no 23 SVr2 \fIcurses\fP |
| 689 |
1995 HP-UX 10.00 32 6 16 SVr3 \fIcurses_colr\fP |
| 690 |
1995 HP-UX 10.00 32 6 8 SVr4, X/Open \fIcurses\fP |
| 691 |
1995 Solaris 5.4 32/64 7 16 X/Open \fIcurses\fP |
| 692 |
1996 AIX 4.2 32 7 16 X/Open \fIcurses\fP |
| 693 |
1996 OSF/1 r4 32 6 16 X/Open \fIcurses\fP |
| 694 |
1997 HP-UX 11.00 32 6 8 X/Open \fIcurses\fP |
| 695 |
2000 UWIN 32/64 7/31 16 uses \fIchtype\fP |
| 696 |
.TE |
| 697 |
.PP |
| 698 |
Notes: |
| 699 |
.RS 3 |
| 700 |
.PP |
| 701 |
Regarding HP-UX, |
| 702 |
.bP |
| 703 |
HP-UX 10.20 (1996) added support for 64-bit PA-RISC processors in 1996. |
| 704 |
.bP |
| 705 |
HP-UX 10.30 (1997) marked \*(``curses_colr\*('' obsolete. |
| 706 |
That version of |
| 707 |
.I curses |
| 708 |
was dropped with HP-UX 11.30 in 2006. |
| 709 |
.PP |
| 710 |
Regarding OSF/1 (and Tru64), |
| 711 |
.bP |
| 712 |
These used 64-bit hardware. |
| 713 |
Like |
| 714 |
.IR \%ncurses "," |
| 715 |
the OSF/1 |
| 716 |
.I curses |
| 717 |
interface is not customized for 32-bit and 64-bit |
| 718 |
versions. |
| 719 |
.bP |
| 720 |
Unlike other systems which evolved from AT&T code, |
| 721 |
OSF/1 provided a new implementation for X/Open Curses. |
| 722 |
.PP |
| 723 |
Regarding Solaris, |
| 724 |
.bP |
| 725 |
The initial release of Solaris was in 1992. |
| 726 |
.bP |
| 727 |
Its XPG4 |
| 728 |
(X/Open Curses-conforming) |
| 729 |
.I xcurses |
| 730 |
library was developed by Mortice Kern Systems from 1990 to 1995. |
| 731 |
Sun's copyright began in 1996. |
| 732 |
.bP |
| 733 |
Sun updated the X/Open Curses interface |
| 734 |
after 64-bit support was introduced in 1997, |
| 735 |
but did not modify the SVr4 |
| 736 |
.I curses |
| 737 |
interface. |
| 738 |
.PP |
| 739 |
Regarding UWIN, |
| 740 |
.bP |
| 741 |
Development of the |
| 742 |
.I curses |
| 743 |
library began in 1991, stopped in 2000. |
| 744 |
.bP |
| 745 |
Color support was added in 1998. |
| 746 |
.bP |
| 747 |
The library uses only |
| 748 |
.I \%chtype |
| 749 |
(not |
| 750 |
.IR \%cchar_t ")." |
| 751 |
.RE |
| 752 |
.PP |
| 753 |
Once X/Open Curses was adopted in the mid-1990s, the constraint of |
| 754 |
a 32-bit interface with many colors and wide-characters for |
| 755 |
.I \%chtype |
| 756 |
became a moot point. |
| 757 |
The |
| 758 |
.I \%cchar_t |
| 759 |
structure |
| 760 |
(whose size and members are not specified in X/Open Curses) |
| 761 |
could be extended as needed. |
| 762 |
.PP |
| 763 |
Other interfaces are rarely used now. |
| 764 |
.bP |
| 765 |
BSD |
| 766 |
.I curses |
| 767 |
was improved slightly in 1993/1994 using Keith Bostic's |
| 768 |
modification to make the library 8-bit clean for \fInvi\fP(1). |
| 769 |
He moved the |
| 770 |
.I \%standout |
| 771 |
attribute to a structure member. |
| 772 |
The resulting 4.4BSD |
| 773 |
.I curses |
| 774 |
was replaced by |
| 775 |
.I \%ncurses |
| 776 |
over the next ten years. |
| 777 |
.bP |
| 778 |
UWIN has been defunct since 2012. |
| 779 |
.PP |
| 780 |
.I \%ncurses |
| 781 |
6.0 (2015) |
| 782 |
added the |
| 783 |
.I A_ITALIC |
| 784 |
macro. |
| 785 |
.\" --------------------------------------------------------------------------- |
| 786 |
.SH SEE ALSO |
| 787 |
\fB\%ncurses\fP(3NCURSES), |
| 788 |
\fB\%addch\fP(3NCURSES), |
| 789 |
\fB\%addstr\fP(3NCURSES), |
| 790 |
\fB\%bkgd\fP(3NCURSES), |
| 791 |
\fB\%printw\fP(3NCURSES), |
| 792 |
\fB\%curses_variables\fP(3NCURSES) |