* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_add_wch.3x,v 1.62 2024/04/20 21:20:07 tom Exp @
+ * @Id: curs_add_wch.3x,v 1.63 2024/05/11 21:31:45 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_add_wch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_add_wch 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_add_wch 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_add_wch 3x 2024-05-11 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
<STRONG>add_wch</STRONG>, <STRONG>wadd_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, <STRONG>echo_wchar</STRONG>, <STRONG>wecho_wchar</STRONG> - add
- a <EM>curses</EM> complex character to a window and advance the cursor
+ a <EM>curses</EM> complex character to a window, possibly advancing the cursor
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
-</PRE><H3><a name="h3-add_wch">add_wch</a></H3><PRE>
- The <STRONG>add_wch</STRONG>, <STRONG>wadd_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, and <STRONG>mvwadd_wch</STRONG> functions put the
- complex character <EM>wch</EM> into the given window at its current position,
- which is then advanced. These functions perform wrapping and special-
- character processing as follows:
-
- <STRONG>o</STRONG> If <EM>wch</EM> refers to a spacing character, then any previous character
- at that location is removed. A new character specified by <EM>wch</EM> is
- placed at that location with rendition specified by <EM>wch</EM>. The
- cursor then advances after this spacing character, to prepare for
- writing the next character on the screen.
-
- The newly added spacing character is the base of the active complex
- character. Subsequent non-spacing characters can be combined with
- this base until another spacing character is written to the screen,
- or the cursor is moved, e.g., using <STRONG>wmove</STRONG>.
-
- <STRONG>o</STRONG> If <EM>wch</EM> refers to a non-spacing character, it is appended to the
- active complex character, retaining the previous characters at that
- location. The rendition specified by <EM>wch</EM> is ignored.
-
- The cursor is not advanced after adding a non-spacing character.
- Subsequent calls to add non-spacing characters will update the same
- position.
+</PRE><H3><a name="h3-wadd_wch">wadd_wch</a></H3><PRE>
+ <STRONG>wadd_wch</STRONG> writes the complex character <EM>wch</EM> to the window <EM>win</EM>, then may
+ advance the cursor position, analogously to the standard C library's
+ <STRONG>putwchar(3)</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function.
+
+ Much behavior depends on whether the wide characters in <EM>wch</EM> are spacing
+ or non-spacing; see subsection "Complex Characters" below.
+
+ <STRONG>o</STRONG> If <EM>wch</EM> contains a spacing character, then any character at the
+ cursor is first removed. The complex character <EM>wch</EM>, with its
+ attributes and color pair identifier, becomes the <EM>base</EM> of the
+ <EM>active</EM> <EM>complex</EM> <EM>character</EM>.
+
+ <STRONG>o</STRONG> If <EM>wch</EM> contains only non-spacing characters, they are combined with
+ the active complex character. <EM>curses</EM> ignores its attributes and
+ color pair identifier, and does not advance the cursor.
+
+ Further non-spacing characters added with <STRONG>wadd_wch</STRONG> are not written at
+ the new cursor position but combine with the active complex character
+ until another spacing character is written to the window or the cursor
+ is moved.
+
+ If advancement occurs at the right margin,
+
+ <STRONG>o</STRONG> the cursor automatically wraps to the beginning of the next line,
+ then,
+
+ <STRONG>o</STRONG> if it was at the bottom of the scrolling region, and if
+ <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is enabled for <EM>win</EM>, the scrolling region scrolls up
+ one line.
- <STRONG>o</STRONG> If the character part of <EM>wch</EM> is a tab, newline, backspace or other
- control character, the window is updated and the cursor moves as if
- <STRONG>addch</STRONG> were called.
+ If <EM>wch</EM> is a backspace, carriage return, line feed, or tab, the cursor
+ moves appropriately within the window.
+ <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin
+ of a window, it does nothing.
-</PRE><H3><a name="h3-echo_wchar">echo_wchar</a></H3><PRE>
- The <STRONG>echo_wchar</STRONG> function is functionally equivalent to a call to <STRONG>add_wch</STRONG>
- followed by a call to <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>. Similarly, the <STRONG>wecho_wchar</STRONG> is
- functionally equivalent to a call to <STRONG>wadd_wch</STRONG> followed by a call to
- <STRONG>wrefresh</STRONG>. The knowledge that only a single character is being output
- is taken into consideration and, for non-control characters, a
- considerable performance gain might be seen by using the *<STRONG>echo</STRONG>*
- functions instead of their equivalents.
+ <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the current
+ line of the window.
+ <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then advances as if from the right
+ margin.
-</PRE><H3><a name="h3-Line-Graphics">Line Graphics</a></H3><PRE>
- Like <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>, <STRONG>addch_wch</STRONG> accepts symbols which make it simple to draw
- lines and other frequently used special characters. These symbols
- correspond to the same VT100 line-drawing set as <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>.
+ <STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next
+ line); these are placed at every eighth column by default. Alter
+ the tab interval with the <STRONG>TABSIZE</STRONG> extension; see
+ <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
- <STRONG>Unicode</STRONG> <STRONG>ASCII</STRONG> <STRONG>acsc</STRONG>
+ If <EM>wch</EM> is any other nonprintable character, it is drawn in printable
+ form using the same convention as <STRONG><A HREF="curs_util.3x.html">wunctrl(3x)</A></STRONG>.
+ Calling <STRONG><A HREF="curs_in_wch.3x.html">win_wch(3x)</A></STRONG> on the location of a nonprintable character does
+ not return the character itself, but its <STRONG><A HREF="curs_util.3x.html">wunctrl(3x)</A></STRONG> representation.
- <STRONG>ACS</STRONG> <STRONG>Name</STRONG> <STRONG>Default</STRONG> <STRONG>Default</STRONG> <STRONG>Char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
+
+</PRE><H3><a name="h3-wecho_wchar">wecho_wchar</a></H3><PRE>
+ <STRONG>echo_wchar</STRONG> and <STRONG>wecho_wchar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>add_wch</STRONG>
+ followed by (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> interprets these functions as a hint
+ that only a single (complex) character is being output; for non-control
+ characters, a considerable performance gain may be enjoyed by employing
+ them.
+
+
+</PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE>
+ <EM>curses</EM> defines macros starting with <STRONG>WACS_</STRONG> that can be used with
+ <STRONG>wadd_wch</STRONG> to write line-drawing and other special characters to the
+ screen. <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default
+ listed below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> capability does
+ not define a terminal-specific replacement for it, or if the terminal
+ and locale configuration requires Unicode to access these characters
+ but the library is unable to use Unicode. The "acsc char" column
+ corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>)
+ string capability, and the characters in it may appear on the screen if
+ the terminal type's database entry incorrectly advertises ACS support.
+ The name "ACS" originates in the Alternate Character Set feature of the
+ DEC VT100 terminal.
+
+ <STRONG>Unicode</STRONG> <STRONG>ACS</STRONG> <STRONG>acsc</STRONG>
+ <STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
------------------------------------------------------------------------
<STRONG>WACS_BLOCK</STRONG> 0x25ae # 0 solid square block
<STRONG>WACS_BOARD</STRONG> 0x2592 # h board of squares
<STRONG>WACS_D_LTEE</STRONG> 0x2560 + F double tee pointing right
<STRONG>WACS_D_PLUS</STRONG> 0x256c + E double large plus
<STRONG>WACS_D_RTEE</STRONG> 0x2563 + G double tee pointing left
-
<STRONG>WACS_D_TTEE</STRONG> 0x2566 + I double tee pointing down
<STRONG>WACS_D_ULCORNER</STRONG> 0x2554 + C double upper left corner
<STRONG>WACS_D_URCORNER</STRONG> 0x2557 + B double upper right corner
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- All routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success.
+ These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. In <EM>ncurses</EM>,
+ <STRONG>wadd_wch</STRONG> returns <STRONG>ERR</STRONG> if
- X/Open Curses does not specify any error conditions. This
- implementation returns an error
+ <STRONG>o</STRONG> <EM>win</EM> is <STRONG>NULL</STRONG>,
- <STRONG>o</STRONG> if the window pointer is null or
+ <STRONG>o</STRONG> wrapping to a new line is impossible because <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> has not
+ been called on <EM>win</EM> when writing to its bottom right location is
+ attempted, or
- <STRONG>o</STRONG> if it is not possible to add a complete character in the window.
+ <STRONG>o</STRONG> it is not possible to add a complete character at the cursor
+ position.
- The latter may be due to different causes:
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
- <STRONG>o</STRONG> If <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not enabled, writing a character at the lower
- right margin succeeds. However, an error is returned because it is
- not possible to wrap to a new line.
- <STRONG>o</STRONG> If an error is detected when converting a multibyte character to a
- sequence of bytes, or if it is not possible to add all of the
- resulting bytes in the window, an error is returned.
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+ <STRONG>add_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, and <STRONG>echo_wchar</STRONG> may be implemented as
+ macros.
- 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-EXTENSIONS">EXTENSIONS</a></H2><PRE>
-</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- Note that <STRONG>add_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, and <STRONG>echo_wchar</STRONG> may be macros.
+</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
+ The <STRONG>TABSIZE</STRONG> variable is implemented in SVr4 and other versions of
+ <EM>curses</EM>, but is not specified by X/Open Curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These functions are described in X/Open Curses, Issue 4. The defaults
- specified for line-drawing characters apply in the POSIX locale.
+ These functions are described in X/Open Curses, Issue 4. It specifies
+ no error conditions for them.
+ SVr4 <EM>curses</EM> describes a successful return value only as "an integer
+ value other than <STRONG>ERR</STRONG>".
-</PRE><H3><a name="h3-WACS-Symbols">WACS Symbols</a></H3><PRE>
- X/Open Curses makes it clear that the WACS_ symbols should be defined
- as a pointer to <STRONG>cchar_t</STRONG> data, e.g., in the discussion of <STRONG>border_set</STRONG>. A
- few implementations are problematic:
+ The defaults specified for forms-drawing characters apply in the POSIX
+ locale. X/Open Curses makes it clear that the WACS_ symbols should be
+ defined as a pointer to <STRONG>cchar_t</STRONG> data, e.g., in the discussion of
+ <STRONG>border_set</STRONG>. A few implementations are problematic:
<STRONG>o</STRONG> NetBSD curses defines the symbols as a <STRONG>wchar_t</STRONG> within a <STRONG>cchar_t</STRONG>.
- <STRONG>o</STRONG> HP-UX curses equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
- <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters. The
- misdefined symbols are the arrows and other symbols which are not
+ <STRONG>o</STRONG> HP-UX curses equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
+ <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters. The
+ misdefined symbols are the arrows and other symbols which are not
used for line-drawing.
- X/Open Curses does not specify symbols for thick- or double-lines.
+ X/Open Curses does not specify symbols for thick- or double-lines.
SVr4 curses implementations defined their line-drawing symbols in terms
- of intermediate symbols. This implementation extends those symbols,
+ of intermediate symbols. This implementation extends those symbols,
providing new definitions which are not in the SVr4 implementations.
- Not all Unicode-capable terminals provide support for VT100-style
- alternate character sets (i.e., the <STRONG>acsc</STRONG> capability), with their
- corresponding line-drawing characters. X/Open Curses did not address
- the aspect of integrating Unicode with line-drawing characters.
- Existing implementations of Unix curses (AIX, HP-UX, Solaris) use only
+ Not all Unicode-capable terminals provide support for VT100-style
+ alternate character sets (i.e., the <STRONG>acsc</STRONG> capability), with their
+ corresponding line-drawing characters. X/Open Curses did not address
+ the aspect of integrating Unicode with line-drawing characters.
+ Existing implementations of Unix curses (AIX, HP-UX, Solaris) use only
the <STRONG>acsc</STRONG> character-mapping to provide this feature. As a result, those
implementations can only use single-byte line-drawing characters.
- <EM>ncurses</EM> 5.3 (2002) provided a table of Unicode values to solve these
+ <EM>ncurses</EM> 5.3 (2002) provided a table of Unicode values to solve these
problems. NetBSD curses incorporated that table in 2010.
- In this implementation, the Unicode values are used instead of the
+ In this implementation, the Unicode values are used instead of the
terminal description's <STRONG>acsc</STRONG> mapping as discussed in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> for the
- environment variable <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM>. In contrast, for the same
+ environment variable <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM>. In contrast, for the same
cases, the line-drawing characters described in <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG> will use only
the ASCII default values.
- Having Unicode available does not solve all of the problems with line-
+ Having Unicode available does not solve all of the problems with line-
drawing for curses:
- <STRONG>o</STRONG> The closest Unicode equivalents to the VT100 graphics <EM>S1</EM>, <EM>S3</EM>, <EM>S7</EM>
- and <EM>S9</EM> frequently are not displayed at the regular intervals which
+ <STRONG>o</STRONG> The closest Unicode equivalents to the VT100 graphics <EM>S1</EM>, <EM>S3</EM>, <EM>S7</EM>
+ and <EM>S9</EM> frequently are not displayed at the regular intervals which
the terminal used.
- <STRONG>o</STRONG> The <EM>lantern</EM> is a special case. It originated with the AT&T 4410
- terminal in the early 1980s. There is no accessible documentation
+ <STRONG>o</STRONG> The <EM>lantern</EM> is a special case. It originated with the AT&T 4410
+ terminal in the early 1980s. There is no accessible documentation
depicting the lantern symbol on the AT&T terminal.
Lacking documentation, most readers assume that a <EM>storm</EM> <EM>lantern</EM> was
intended. But there are several possibilities, all with problems.
- Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and
- U+1F3EE. Those were not available in 2002, and are irrelevant
- since they lie outside the BMP and as a result are not generally
+ Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and
+ U+1F3EE. Those were not available in 2002, and are irrelevant
+ since they lie outside the BMP and as a result are not generally
available in terminals. They are not storm lanterns, in any case.
Most <EM>storm</EM> <EM>lanterns</EM> have a tapering glass chimney (to guard against
tipping); some have a wire grid protecting the chimney.
- For the tapering appearance, U+2603 was adequate. In use on a
+ For the tapering appearance, U+2603 was adequate. In use on a
terminal, no one can tell what the image represents. Unicode calls
it a snowman.
Others have suggested these alternatives: <section> U+00A7 (section
- mark), <Theta> U+0398 (theta), <Phi> U+03A6 (phi), <delta> U+03B4
+ mark), <Theta> U+0398 (theta), <Phi> U+03A6 (phi), <delta> U+03B4
(delta), U+2327 (x in a rectangle), U+256C (forms double vertical
and horizontal), and U+2612 (ballot box with x).
</PRE><H3><a name="h3-Complex-Characters">Complex Characters</a></H3><PRE>
- The complex character type <STRONG>cchar_t</STRONG> can store more than one wide
- character (<STRONG>wchar_t</STRONG>). The X/Open Curses description does not mention
- this possibility, describing only the cases where <EM>wch</EM> is a spacing
- character or a non-spacing character.
+ The complex character type <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> can store more than one wide
+ character (<EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>). X/Open Curses does not mention this possibility,
+ specifying behavior only where <EM>wch</EM> is a single character, either
+ spacing or non-spacing.
- This implementation assumes that <EM>wch</EM> is constructed using <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG>,
- and in turn that the result
+ <EM>ncurses</EM> assumes that <EM>wch</EM> is constructed using <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG>, and in turn
+ that the result
- <STRONG>o</STRONG> contains at most one spacing character in the beginning of its list
- of wide characters, and zero or more non-spacing characters or
+ <STRONG>o</STRONG> contains at most one spacing character at the beginning of its list
+ of wide characters, and zero or more non-spacing characters, or
- <STRONG>o</STRONG> may hold one non-spacing character.
+ <STRONG>o</STRONG> holds one non-spacing character.
- In the latter case, <EM>ncurses</EM> adds the non-spacing character to the
- active (base) spacing character.
-
-
-</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
- The <STRONG>TABSIZE</STRONG> variable is implemented in SVr4 and other versions of
- <EM>curses</EM>, but is not specified by X/Open Curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).
+ In the latter case, <EM>ncurses</EM> adds the non-spacing character to the
+ active complex character.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(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-add_wch">add_wch</a></li>
-<li><a href="#h3-echo_wchar">echo_wchar</a></li>
-<li><a href="#h3-Line-Graphics">Line Graphics</a></li>
+<li><a href="#h3-wadd_wch">wadd_wch</a></li>
+<li><a href="#h3-wecho_wchar">wecho_wchar</a></li>
+<li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
+<li><a href="#h2-EXTENSIONS">EXTENSIONS</a>
+<ul>
+<li><a href="#h3-TABSIZE">TABSIZE</a></li>
+</ul>
+</li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
-<li><a href="#h3-WACS-Symbols">WACS Symbols</a></li>
<li><a href="#h3-Complex-Characters">Complex Characters</a></li>
-<li><a href="#h3-TABSIZE">TABSIZE</a></li>
</ul>
</li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
projects / ncurses.git / blobdiff