<!--
* t
****************************************************************************
- * Copyright 2018-2022,2023 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 *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_attr.3x,v 1.92 2023/12/16 21:07:24 tom Exp @
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
- * ---------------------------------------------------------------------------
+ * @Id: curs_attr.3x,v 1.105 2024/04/27 17:54:42 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
-<TITLE>curs_attr 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_attr 3x 2024-04-27 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_attr 3x 2023-12-16 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_attr 3x 2024-04-27 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
attributes used for erasing and clearing.
-</PRE><H3><a name="h3-Window-
attributes">Window attributes</a></H3><PRE>
+</PRE><H3><a name="h3-Window-
Attributes">Window Attributes</a></H3><PRE>
There are two sets of functions:
<STRONG>o</STRONG> functions for manipulating the window attributes and color:
together in <EM>attr</EM>, without affecting other attributes.
-</PRE><H3><a name="h3-Legacy-
window-attributes">Legacy window attributes</a></H3><PRE>
+</PRE><H3><a name="h3-Legacy-
Window-Attributes">Legacy Window Attributes</a></H3><PRE>
The X/Open window attribute routines which <EM>set</EM> or <EM>get</EM>, turn <EM>on</EM> or <EM>off</EM>
are extensions of older routines which assume that color pairs are OR'd
into the attribute parameter. These newer routines use similar names,
although <EM>ncurses</EM> provides <STRONG>getattrs</STRONG> (see <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>).
-</PRE><H3><a name="h3-Change-
character-rendition">Change character rendition</a></H3><PRE>
+</PRE><H3><a name="h3-Change-
Character-Rendition">Change Character Rendition</a></H3><PRE>
The routine <STRONG>chgat</STRONG> changes the attributes of a given number of
characters starting at the current cursor location of <STRONG>stdscr</STRONG>. It does
not update the cursor and does not perform wrapping. A character count
in the first argument of <STRONG>init_pair</STRONG>, see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>).
-</PRE><H3><a name="h3-Change-
window-color">Change window color</a></H3><PRE>
+</PRE><H3><a name="h3-Change-
Window-Color">Change Window Color</a></H3><PRE>
The routine <STRONG>color_set</STRONG> sets the current color of the given window to the
foreground/background combination described by the color <EM>pair</EM>
parameter.
<STRONG>standend</STRONG> is the same as <STRONG>attrset(A_NORMAL)</STRONG> or <STRONG>attrset(0)</STRONG>, that is, it
turns off all attributes.
- X/Open does not mark these "restricted", because
+ X/Open Curses does not mark these "restricted", because
<STRONG>o</STRONG> they have well established legacy use, and
<STRONG>Name</STRONG> <STRONG>Description</STRONG>
-----------------------------------------------------------------
<STRONG>A_NORMAL</STRONG> Normal display (no highlight)
- <STRONG>A_STANDOUT</STRONG> Best highlighting mode of the terminal.
+ <STRONG>A_STANDOUT</STRONG> Best highlighting mode of the terminal
<STRONG>A_UNDERLINE</STRONG> Underlining
<STRONG>A_REVERSE</STRONG> Reverse video
<STRONG>A_BLINK</STRONG> Blinking
(which also support the attributes recognized by <STRONG>attron</STRONG>, etc.):
<STRONG>Name</STRONG> <STRONG>Description</STRONG>
- -----------------------------------------
+ -----------------------------------------------------------------
<STRONG>WA_HORIZONTAL</STRONG> Horizontal highlight
<STRONG>WA_LEFT</STRONG> Left highlight
<STRONG>WA_LOW</STRONG> Low highlight
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
All routines return the integer <STRONG>OK</STRONG> on success, or <STRONG>ERR</STRONG> on failure.
- X/Open does not define any error conditions.
+ X/Open Curses does not specify any error conditions.
This implementation
<STRONG>o</STRONG> does not return an error if either of the parameters of <STRONG>wattr_get</STRONG>
used for retrieving attribute or color pair values is <STRONG>NULL</STRONG>.
- Functions with a "mv" prefix first perform a cursor movement using
- <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
- the window pointer is null.
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
These functions may be macros:
- <STRONG>attroff</STRONG>, <STRONG>wattroff</STRONG>, <STRONG>attron</STRONG>, <STRONG>wattron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>, <STRONG>standend</STRONG>
+ <STRONG>attroff</STRONG>, <STRONG>wattroff</STRONG>, <STRONG>attron</STRONG>, <STRONG>wattron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>, <STRONG>standend</STRONG>
and <STRONG>standout</STRONG>.
- Color pair values can only be OR'd with attributes if the pair number
+ Color pair values can only be OR'd with attributes if the pair number
is less than 256. The alternate functions such as <STRONG>color_set</STRONG> can pass a
color pair value directly. However, <EM>ncurses</EM> ABI 4 and 5 simply OR this
- value within the alternate functions. You must use <EM>ncurses</EM> ABI 6 to
+ value within the alternate functions. You must use <EM>ncurses</EM> ABI 6 to
support more than 256 color pairs.
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
This implementation provides the <STRONG>A_ITALIC</STRONG> attribute for terminals which
- have the <STRONG>enter_italics_mode</STRONG> (<STRONG>sitm</STRONG>) and <STRONG>exit_italics_mode</STRONG> (<STRONG>ritm</STRONG>)
- capabilities. Italics are not mentioned in X/Open Curses. Unlike the
- other video attributes, <STRONG>A_ITALIC</STRONG> is unrelated to the <STRONG>set_attributes</STRONG>
- capabilities. This implementation makes the assumption that
+ have the <STRONG>enter_italics_mode</STRONG> (<STRONG>sitm</STRONG>) and <STRONG>exit_italics_mode</STRONG> (<STRONG>ritm</STRONG>)
+ capabilities. Italics are not mentioned in X/Open Curses. Unlike the
+ other video attributes, <STRONG>A_ITALIC</STRONG> is unrelated to the <STRONG>set_attributes</STRONG>
+ capabilities. This implementation makes the assumption that
<STRONG>exit_attribute_mode</STRONG> may also reset italics.
- Each of the functions added by XSI Curses has a parameter <EM>opts</EM>, which
- X/Open Curses still (after more than twenty years) documents as
+ Each of the functions added by XSI Curses has a parameter <EM>opts</EM>, which
+ X/Open Curses still (after more than twenty years) documents as
reserved for future use, saying that it should be <STRONG>NULL</STRONG>. This
- implementation uses that parameter in ABI 6 for the functions which
+ implementation uses that parameter in ABI 6 for the functions which
have a color pair parameter to support <EM>extended</EM> <EM>color</EM> <EM>pairs</EM>:
<STRONG>o</STRONG> For functions which modify the color, e.g., <STRONG>wattr_set</STRONG> and <STRONG>wattr_on</STRONG>,
- if <EM>opts</EM> is set it is treated as a pointer to <STRONG>int</STRONG>, and used to set
+ if <EM>opts</EM> is set it is treated as a pointer to <STRONG>int</STRONG>, and used to set
the color pair instead of the <STRONG>short</STRONG> <EM>pair</EM> parameter.
<STRONG>o</STRONG> For functions which retrieve the color, e.g., <STRONG>wattr_get</STRONG>, if <EM>opts</EM> is
- set it is treated as a pointer to <STRONG>int</STRONG>, and used to retrieve the
- color pair as an <STRONG>int</STRONG> value, in addition to retrieving it via the
+ set it is treated as a pointer to <STRONG>int</STRONG>, and used to retrieve the
+ color pair as an <STRONG>int</STRONG> value, in addition to retrieving it via the
standard pointer to <STRONG>short</STRONG> parameter.
- <STRONG>o</STRONG> For functions which turn attributes off, e.g., <STRONG>wattr_off</STRONG>, the <EM>opts</EM>
+ <STRONG>o</STRONG> For functions which turn attributes off, e.g., <STRONG>wattr_off</STRONG>, the <EM>opts</EM>
parameter is ignored except except to check that it is <STRONG>NULL</STRONG>.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These functions are described in the XSI Curses standard, Issue 4. The
- standard defined the dedicated type for highlights, <STRONG>attr_t</STRONG>, which was
- not defined in SVr4 curses. The functions taking <STRONG>attr_t</STRONG> arguments were
- not supported under SVr4.
+ These functions are described in X/Open Curses, Issue 4. The standard
+ defined the dedicated type for highlights, <STRONG>attr_t</STRONG>, which was not
+ defined in SVr4 curses. The functions taking <STRONG>attr_t</STRONG> arguments were not
+ supported under SVr4.
Very old versions of this library did not force an update of the screen
- when changing the attributes. Use <STRONG>touchwin</STRONG> to force the screen to
+ when changing the attributes. Use <STRONG>touchwin</STRONG> to force the screen to
match the updated attributes.
- The XSI Curses standard states that whether the traditional functions
- <STRONG>attron</STRONG>/<STRONG>attroff</STRONG>/<STRONG>attrset</STRONG> can manipulate attributes other than <STRONG>A_BLINK</STRONG>,
- <STRONG>A_BOLD</STRONG>, <STRONG>A_DIM</STRONG>, <STRONG>A_REVERSE</STRONG>, <STRONG>A_STANDOUT</STRONG>, or <STRONG>A_UNDERLINE</STRONG> is "unspecified".
- Under this implementation as well as SVr4 curses, these functions
- correctly manipulate all other highlights (specifically, <STRONG>A_ALTCHARSET</STRONG>,
+ X/Open Curses states that whether the traditional functions
+ <STRONG>attron</STRONG>/<STRONG>attroff</STRONG>/<STRONG>attrset</STRONG> can manipulate attributes other than <STRONG>A_BLINK</STRONG>,
+ <STRONG>A_BOLD</STRONG>, <STRONG>A_DIM</STRONG>, <STRONG>A_REVERSE</STRONG>, <STRONG>A_STANDOUT</STRONG>, or <STRONG>A_UNDERLINE</STRONG> is "unspecified".
+ Under this implementation as well as SVr4 curses, these functions
+ correctly manipulate all other highlights (specifically, <STRONG>A_ALTCHARSET</STRONG>,
<STRONG>A_PROTECT</STRONG>, and <STRONG>A_INVIS</STRONG>).
- XSI Curses added these entry points:
+ X/Open Curses added these entry points:
<STRONG>attr_get</STRONG>, <STRONG>attr_on</STRONG>, <STRONG>attr_off</STRONG>, <STRONG>attr_set</STRONG>, <STRONG>wattr_on</STRONG>, <STRONG>wattr_off</STRONG>,
<STRONG>wattr_get</STRONG>, <STRONG>wattr_set</STRONG>
- The new functions are intended to work with a new series of highlight
+ The new functions are intended to work with a new series of highlight
macros prefixed with <STRONG>WA_</STRONG>. The older macros have direct counterparts in
the newer set of names:
<STRONG>Name</STRONG> <STRONG>Description</STRONG>
- ------------------------------------------------------------
+ -----------------------------------------------------------------
<STRONG>WA_NORMAL</STRONG> Normal display (no highlight)
- <STRONG>WA_STANDOUT</STRONG> Best highlighting mode of the terminal.
+ <STRONG>WA_STANDOUT</STRONG> Best highlighting mode of the terminal
<STRONG>WA_UNDERLINE</STRONG> Underlining
<STRONG>WA_REVERSE</STRONG> Reverse video
<STRONG>WA_BLINK</STRONG> Blinking
<STRONG>WA_ALTCHARSET</STRONG> Alternate character set
- 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.:
+ 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.:
- <STRONG>o</STRONG> The XSI curses standard specifies that each pair of corresponding
- <STRONG>A_</STRONG> and <STRONG>WA_</STRONG>-using functions operates on the same current-highlight
+ <STRONG>o</STRONG> X/Open Curses specifies that each pair of corresponding <STRONG>A_</STRONG> and
+ <STRONG>WA_</STRONG>-using functions operates on the same current-highlight
information.
<STRONG>o</STRONG> However, in some implementations, those symbols have unrelated
This is consistent with SVr4 curses; X/Open Curses does not specify
this.
- The XSI standard extended conformance level adds new highlights
+ The X/Open Curses extended conformance level adds new highlights
<STRONG>A_HORIZONTAL</STRONG>, <STRONG>A_LEFT</STRONG>, <STRONG>A_LOW</STRONG>, <STRONG>A_RIGHT</STRONG>, <STRONG>A_TOP</STRONG>, <STRONG>A_VERTICAL</STRONG> (and
corresponding <STRONG>WA_</STRONG> macros for each). As of August 2013, no known
terminal provides these highlights (i.e., via the <STRONG>sgr1</STRONG> capability).
alternate character set implementation. A 32-bit library can be used
on a 64-bit system, but not necessarily the reverse.
- <STRONG>Year</STRONG> <STRONG>System</STRONG> <STRONG>Arch</STRONG> <STRONG>Color</STRONG> <STRONG>Char</STRONG> <STRONG>Notes</STRONG>
- ----------------------------------------------------------------
- 1992 Solaris 5.2 32 6 17 SVr4 curses
- 1992 HP-UX 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 <STRONG>chtype</STRONG>
+ <STRONG>Bits</STRONG>
+ <STRONG>Year</STRONG> <STRONG>System</STRONG> <STRONG>Arch</STRONG> <STRONG>Color</STRONG> <STRONG>Char</STRONG> <STRONG>Notes</STRONG>
+ ------------------------------------------------------------------------
+ 1992 Solaris 5.2 32 6 17 SVr4 <EM>curses</EM>
+ 1992 HP-UX 9 32 no 8 SVr2 <EM>curses</EM>
+ 1992 AIX 3.2 32 no 23 SVr2 <EM>curses</EM>
+ 1994 OSF/1 r3 32 no 23 SVr2 <EM>curses</EM>
+ 1995 HP-UX 10.00 32 6 16 SVr3 <EM>curses</EM><STRONG>_</STRONG><EM>colr</EM>
+ 1995 HP-UX 10.00 32 6 8 SVr4, X/Open <EM>curses</EM>
+ 1995 Solaris 5.4 32/64 7 16 X/Open <EM>curses</EM>
+ 1996 AIX 4.2 32 7 16 X/Open <EM>curses</EM>
+ 1996 OSF/1 r4 32 6 16 X/Open <EM>curses</EM>
+ 1997 HP-UX 11.00 32 6 8 X/Open <EM>curses</EM>
+ 2000 U/Win 32/64 7/31 16 uses <EM>chtype</EM>
Notes:
-ncurses 6.
4 2023-12-16 <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
+ncurses 6.
5 2024-04-27 <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
-<li><a href="#h3-Window-attributes">Window attributes</a></li>
-<li><a href="#h3-Legacy-window-attributes">Legacy window attributes</a></li>
-<li><a href="#h3-Change-character-rendition">Change character rendition</a></li>
-<li><a href="#h3-Change-window-color">Change window color</a></li>
+<li><a href="#h3-Window-Attributes">Window Attributes</a></li>
+<li><a href="#h3-Legacy-Window-Attributes">Legacy Window Attributes</a></li>
+<li><a href="#h3-Change-Character-Rendition">Change Character Rendition</a></li>
+<li><a href="#h3-Change-Window-Color">Change Window Color</a></li>
<li><a href="#h3-Standout">Standout</a></li>
<li><a href="#h3-Video-Attributes">Video Attributes</a></li>
</ul>
projects / ncurses.git / blobdiff