| 1 |
<!-- |
| 2 |
* t |
| 3 |
**************************************************************************** |
| 4 |
* Copyright 2018-2024,2025 Thomas E. Dickey * |
| 5 |
* Copyright 1998-2015,2017 Free Software Foundation, Inc. * |
| 6 |
* * |
| 7 |
* Permission is hereby granted, free of charge, to any person obtaining a * |
| 8 |
* copy of this software and associated documentation files (the * |
| 9 |
* "Software"), to deal in the Software without restriction, including * |
| 10 |
* without limitation the rights to use, copy, modify, merge, publish, * |
| 11 |
* distribute, distribute with modifications, sublicense, and/or sell * |
| 12 |
* copies of the Software, and to permit persons to whom the Software is * |
| 13 |
* furnished to do so, subject to the following conditions: * |
| 14 |
* * |
| 15 |
* The above copyright notice and this permission notice shall be included * |
| 16 |
* in all copies or substantial portions of the Software. * |
| 17 |
* * |
| 18 |
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| 19 |
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| 20 |
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| 21 |
* IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| 22 |
* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| 23 |
* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| 24 |
* THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| 25 |
* * |
| 26 |
* Except as contained in this notice, the name(s) of the above copyright * |
| 27 |
* holders shall not be used in advertising or otherwise to promote the * |
| 28 |
* sale, use or other dealings in this Software without prior written * |
| 29 |
* authorization. * |
| 30 |
**************************************************************************** |
| 31 |
* @Id: curs_addch.3x,v 1.144 2025/11/12 01:04:12 tom Exp @ |
| 32 |
--> |
| 33 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
| 34 |
<HTML> |
| 35 |
<HEAD> |
| 36 |
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
| 37 |
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> |
| 38 |
<TITLE>curs_addch 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> |
| 39 |
<link rel="author" href="mailto:[email protected]"> |
| 40 |
|
| 41 |
</HEAD> |
| 42 |
<BODY> |
| 43 |
<H1 class="no-header">curs_addch 3x 2025-11-11 ncurses 6.6 Library calls</H1> |
| 44 |
<PRE> |
| 45 |
<STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> |
| 46 |
|
| 47 |
|
| 48 |
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> |
| 49 |
<STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, <STRONG>echochar</STRONG>, <STRONG>wechochar</STRONG> - add a <EM>curses</EM> |
| 50 |
character to a window and advance the cursor |
| 51 |
|
| 52 |
|
| 53 |
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> |
| 54 |
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG> |
| 55 |
|
| 56 |
<STRONG>int</STRONG> <STRONG>addch(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> |
| 57 |
<STRONG>int</STRONG> <STRONG>waddch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> |
| 58 |
<STRONG>int</STRONG> <STRONG>mvaddch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> |
| 59 |
<STRONG>int</STRONG> <STRONG>mvwaddch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> |
| 60 |
|
| 61 |
<STRONG>int</STRONG> <STRONG>echochar(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> |
| 62 |
<STRONG>int</STRONG> <STRONG>wechochar(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> |
| 63 |
|
| 64 |
<EM>/*</EM> <EM>(integer)</EM> <EM>constants</EM> <EM>*/</EM> |
| 65 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BLOCK;</STRONG> |
| 66 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BOARD;</STRONG> |
| 67 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BTEE;</STRONG> |
| 68 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BULLET;</STRONG> |
| 69 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_CKBOARD;</STRONG> |
| 70 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_DARROW;</STRONG> |
| 71 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_DEGREE;</STRONG> |
| 72 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_DIAMOND;</STRONG> |
| 73 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_HLINE;</STRONG> |
| 74 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LANTERN;</STRONG> |
| 75 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LARROW;</STRONG> |
| 76 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LLCORNER;</STRONG> |
| 77 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LRCORNER;</STRONG> |
| 78 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LTEE;</STRONG> |
| 79 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_PLMINUS;</STRONG> |
| 80 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_PLUS;</STRONG> |
| 81 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_RARROW;</STRONG> |
| 82 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_RTEE;</STRONG> |
| 83 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S1;</STRONG> |
| 84 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S9;</STRONG> |
| 85 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_TTEE;</STRONG> |
| 86 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_UARROW;</STRONG> |
| 87 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_ULCORNER;</STRONG> |
| 88 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_URCORNER;</STRONG> |
| 89 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_VLINE;</STRONG> |
| 90 |
<EM>/*</EM> <EM>extensions</EM> <EM>*/</EM> |
| 91 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_GEQUAL;</STRONG> |
| 92 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LEQUAL;</STRONG> |
| 93 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_NEQUAL;</STRONG> |
| 94 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_PI;</STRONG> |
| 95 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S3;</STRONG> |
| 96 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S7;</STRONG> |
| 97 |
/* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_STERLING;</STRONG> |
| 98 |
|
| 99 |
|
| 100 |
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> |
| 101 |
|
| 102 |
</PRE><H3><a name="h3-waddch">waddch</a></H3><PRE> |
| 103 |
<STRONG>waddch</STRONG> writes the <EM>curses</EM> character <EM>ch</EM> to the window <EM>win</EM>, then advances |
| 104 |
the cursor position, analogously to the standard C library's |
| 105 |
<STRONG>putchar(3)</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function. |
| 106 |
|
| 107 |
Construct a <EM>curses</EM> character from a <EM>char</EM> by assignment or typecast. |
| 108 |
Subsection "Video Attributes" of <STRONG><A HREF="curs_attr.3x.html">attron(3x)</A></STRONG> describes how to manipulate |
| 109 |
its attributes and color pair. (A color pair selection is not honored |
| 110 |
unless initialized; see <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG>.) |
| 111 |
|
| 112 |
The object or expression <EM>ch</EM> may contain attributes and/or a color pair |
| 113 |
identifier. (A <EM>chtype</EM> can be copied from place to place using |
| 114 |
<STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> and <STRONG>waddch</STRONG>.) <EM>curses</EM> defines constants to aid the |
| 115 |
manipulation of character attributes; see <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>. A <EM>ch</EM> whose |
| 116 |
character component is a space, and whose only attribute is <STRONG>A_NORMAL</STRONG>, |
| 117 |
is a <EM>blank</EM> <EM>character</EM>, and therefore combines with the window's |
| 118 |
background character; see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>. |
| 119 |
|
| 120 |
If <EM>ch</EM> is a backspace, carriage return, line feed, or tab, the cursor |
| 121 |
moves appropriately within the window. |
| 122 |
|
| 123 |
<STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin |
| 124 |
of a window, it does nothing. |
| 125 |
|
| 126 |
<STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the same |
| 127 |
line of the window. |
| 128 |
|
| 129 |
<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 |
| 130 |
margin. |
| 131 |
|
| 132 |
<STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next |
| 133 |
line); these are placed at every eighth column by default. |
| 134 |
|
| 135 |
Alter the tab interval with the <STRONG>TABSIZE</STRONG> extension; see |
| 136 |
<STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>. |
| 137 |
|
| 138 |
If <EM>ch</EM> is any other nonprintable character, <EM>curses</EM> draws it in printable |
| 139 |
form using the same convention as <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>. Calling <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> on the |
| 140 |
location of a nonprintable character does not return the character |
| 141 |
itself, but its <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> representation. |
| 142 |
|
| 143 |
Adding printable characters with <STRONG>waddch</STRONG> causes it to wrap at the right |
| 144 |
margin of the window: |
| 145 |
|
| 146 |
<STRONG>o</STRONG> If the cursor is not at the bottom of the scrolling region and |
| 147 |
advancement occurs at the right margin, the cursor automatically |
| 148 |
wraps to the beginning of the next line. |
| 149 |
|
| 150 |
<STRONG>o</STRONG> If the cursor is at the bottom of the scrolling region when |
| 151 |
advancement occurs at the right margin, and <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is enabled |
| 152 |
for <EM>win</EM>, the scrolling region scrolls up one line and the cursor |
| 153 |
wraps as above. Otherwise, advancement and scrolling do not occur, |
| 154 |
and <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG>. |
| 155 |
|
| 156 |
A window's margins may coincide with the screen boundaries. This may |
| 157 |
be a problem when <EM>ncurses</EM> updates the screen to match the curses |
| 158 |
window. When their right and bottom margins coincide, <EM>ncurses</EM> uses |
| 159 |
different strategies to handle the variations of scrolling and wrapping |
| 160 |
at the lower-right corner by depending on the terminal capabilities: |
| 161 |
|
| 162 |
<STRONG>o</STRONG> If the terminal does not automatically wrap as characters are added |
| 163 |
at the right margin (i.e., auto right margins), <EM>ncurses</EM> writes the |
| 164 |
character directly. |
| 165 |
|
| 166 |
<STRONG>o</STRONG> If the terminal has auto right margins, but also has capabilities |
| 167 |
for turning auto margins off and on, <EM>ncurses</EM> turns the auto margin |
| 168 |
feature off temporarily when writing to the lower-right corner. |
| 169 |
|
| 170 |
<STRONG>o</STRONG> If the terminal has an insertion mode which can be turned off and |
| 171 |
on, <EM>ncurses</EM> writes the character just before the lower-right |
| 172 |
corner, and then inserts a character to push the update into the |
| 173 |
corner. |
| 174 |
|
| 175 |
|
| 176 |
</PRE><H3><a name="h3-wechochar">wechochar</a></H3><PRE> |
| 177 |
<STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by |
| 178 |
(<STRONG>w</STRONG>)<STRONG>refresh</STRONG> on <STRONG>stdscr</STRONG> or the specified window. <EM>curses</EM> interprets these |
| 179 |
functions as a hint to its optimizer that only a single character cell |
| 180 |
in the window is being altered between refreshes; for non-control |
| 181 |
characters, a considerable performance gain may be enjoyed by employing |
| 182 |
them. |
| 183 |
|
| 184 |
|
| 185 |
</PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE> |
| 186 |
<EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG> |
| 187 |
to write line-drawing and other symbols to the screen. <EM>ncurses</EM> terms |
| 188 |
these <EM>forms-drawing</EM> <EM>characters.</EM> <EM>curses</EM> uses the ACS default listed |
| 189 |
below if the terminal type lacks the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) capability; that |
| 190 |
capability does not define a replacement for the character; or if the |
| 191 |
terminal type and locale configuration require Unicode to access these |
| 192 |
characters, but the library is unable to use Unicode. The "acsc char" |
| 193 |
column corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> |
| 194 |
(<STRONG>acsc</STRONG>) string capability, and the characters in it may appear on the |
| 195 |
screen if the terminal type's database entry incorrectly advertises ACS |
| 196 |
support. The name "ACS" originates in the Alternate Character Set |
| 197 |
feature of the DEC VT100 terminal. |
| 198 |
|
| 199 |
<STRONG>ACS</STRONG> <STRONG>acsc</STRONG> |
| 200 |
<STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG> |
| 201 |
------------------------------------------------------------------------ |
| 202 |
<STRONG>ACS_BLOCK</STRONG> # 0 solid square block |
| 203 |
<STRONG>ACS_BOARD</STRONG> # h board of squares |
| 204 |
<STRONG>ACS_BTEE</STRONG> + v bottom tee |
| 205 |
<STRONG>ACS_BULLET</STRONG> o ~ bullet |
| 206 |
<STRONG>ACS_CKBOARD</STRONG> : a checker board (stipple) |
| 207 |
<STRONG>ACS_DARROW</STRONG> v . arrow pointing down |
| 208 |
<STRONG>ACS_DEGREE</STRONG> ' f degree symbol |
| 209 |
<STRONG>ACS_DIAMOND</STRONG> + ` diamond |
| 210 |
<STRONG>ACS_GEQUAL</STRONG> > > greater-than-or-equal-to |
| 211 |
<STRONG>ACS_HLINE</STRONG> - q horizontal line |
| 212 |
<STRONG>ACS_LANTERN</STRONG> # i lantern symbol |
| 213 |
<STRONG>ACS_LARROW</STRONG> < , arrow pointing left |
| 214 |
<STRONG>ACS_LEQUAL</STRONG> < y less-than-or-equal-to |
| 215 |
<STRONG>ACS_LLCORNER</STRONG> + m lower left-hand corner |
| 216 |
<STRONG>ACS_LRCORNER</STRONG> + j lower right-hand corner |
| 217 |
<STRONG>ACS_LTEE</STRONG> + t left tee |
| 218 |
<STRONG>ACS_NEQUAL</STRONG> ! | not-equal |
| 219 |
<STRONG>ACS_PI</STRONG> * { greek pi |
| 220 |
<STRONG>ACS_PLMINUS</STRONG> # g plus/minus |
| 221 |
<STRONG>ACS_PLUS</STRONG> + n plus |
| 222 |
<STRONG>ACS_RARROW</STRONG> > + arrow pointing right |
| 223 |
<STRONG>ACS_RTEE</STRONG> + u right tee |
| 224 |
<STRONG>ACS_S1</STRONG> - o scan line 1 |
| 225 |
<STRONG>ACS_S3</STRONG> - p scan line 3 |
| 226 |
<STRONG>ACS_S7</STRONG> - r scan line 7 |
| 227 |
<STRONG>ACS_S9</STRONG> _ s scan line 9 |
| 228 |
<STRONG>ACS_STERLING</STRONG> f } pound-sterling symbol |
| 229 |
<STRONG>ACS_TTEE</STRONG> + w top tee |
| 230 |
<STRONG>ACS_UARROW</STRONG> ^ - arrow pointing up |
| 231 |
<STRONG>ACS_ULCORNER</STRONG> + l upper left-hand corner |
| 232 |
<STRONG>ACS_URCORNER</STRONG> + k upper right-hand corner |
| 233 |
<STRONG>ACS_VLINE</STRONG> | x vertical line |
| 234 |
|
| 235 |
|
| 236 |
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> |
| 237 |
These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. |
| 238 |
|
| 239 |
In <EM>ncurses</EM>, these functions fail if |
| 240 |
|
| 241 |
<STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, |
| 242 |
|
| 243 |
<STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null |
| 244 |
pointer, |
| 245 |
|
| 246 |
<STRONG>o</STRONG> wrapping to a new line is impossible because <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> has not |
| 247 |
been called on <EM>win</EM> (or <STRONG>stdscr</STRONG>, as applicable) when a write to its |
| 248 |
bottom right location is attempted, or |
| 249 |
|
| 250 |
<STRONG>o</STRONG> it is not possible to add a complete character at the cursor |
| 251 |
position. |
| 252 |
|
| 253 |
The last may be due to different causes: |
| 254 |
|
| 255 |
<STRONG>o</STRONG> conversion of a wide character to a multibyte character sequence |
| 256 |
can fail, or |
| 257 |
|
| 258 |
<STRONG>o</STRONG> at least one of the bytes resulting from wide character conversion |
| 259 |
to a multibyte character sequence cannot be added to the window. |
| 260 |
See section "PORTABILITY" below regarding the use of <STRONG>waddch</STRONG> with |
| 261 |
wide characters. |
| 262 |
|
| 263 |
Functions prefixed with "mv" first perform cursor movement and fail if |
| 264 |
the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. |
| 265 |
|
| 266 |
|
| 267 |
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> |
| 268 |
<STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be implemented as macros. |
| 269 |
|
| 270 |
|
| 271 |
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> |
| 272 |
The symbols <EM>ACS</EM><STRONG>_</STRONG><EM>S3</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>S7</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>LEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>GEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>PI</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>NEQUAL</EM>, |
| 273 |
and <EM>ACS</EM><STRONG>_</STRONG><EM>STERLING</EM> were not documented in any publicly released System V |
| 274 |
and are not standard. However, many publicly available <EM>terminfo</EM> |
| 275 |
entries include <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) capabilities in which their key |
| 276 |
characters (<STRONG>pryz{|}</STRONG>) are embedded, and a second-hand list of their |
| 277 |
character descriptions has come to light, which identifies them as |
| 278 |
VT100 special characters. |
| 279 |
|
| 280 |
The DEC Special Character and Line Drawing Set (VT100) is indexed by an |
| 281 |
ASCII character in the range 96 (`) to 126 (~). That index character |
| 282 |
is part of the definition for the curses <STRONG>ACS_</STRONG> symbols. The VT100 |
| 283 |
special characters can be categorized in three groups: |
| 284 |
|
| 285 |
<STRONG>o</STRONG> useful graphic symbols with a standard <STRONG>ACS_</STRONG> symbol, (e.g., the |
| 286 |
line-drawing symbols), |
| 287 |
|
| 288 |
<STRONG>o</STRONG> possibly useful characters (these non-standard symbols), |
| 289 |
|
| 290 |
<STRONG>o</STRONG> representations of control characters (e.g., newline and vertical |
| 291 |
tabulation). |
| 292 |
|
| 293 |
A few <STRONG>ACS_</STRONG> symbols do not fit into DEC's VT100 scheme. The AT&T |
| 294 |
Teletype 5410v1 arrow symbols and <STRONG>ACS_BLOCK</STRONG> use indices outside the |
| 295 |
range 96 to 126. Two of the Teletype symbols use indices in that |
| 296 |
range, with different meaning versus the VT100: |
| 297 |
|
| 298 |
<STRONG>o</STRONG> <STRONG>ACS_BOARD</STRONG> corresponds to the VT100 symbol for newline |
| 299 |
|
| 300 |
<STRONG>o</STRONG> <STRONG>ACS_LANTERN</STRONG> corresponds to the VT100 symbol for vertical tabulation |
| 301 |
|
| 302 |
AT&T defined <STRONG>ACS_</STRONG> names for the most useful graphic symbols, as well as |
| 303 |
for its own. Its header file commented: |
| 304 |
|
| 305 |
/* |
| 306 |
* Standard alternate character set. The current ACS world is |
| 307 |
* evolving, so we support only a widely available subset: the |
| 308 |
* line drawing characters from the VT100, plus a few from the |
| 309 |
* Teletype 5410v1. Eventually there may be support of more |
| 310 |
* sophisticated ACS line drawing, such as that in the Teletype |
| 311 |
* 5410, the HP line drawing set, and the like. There may be |
| 312 |
* support for some non line oriented characters as well. |
| 313 |
* |
| 314 |
* Line drawing ACS names are of the form ACS_trbl, where t is |
| 315 |
* the top, r is the right, b is the bottom, and l is the left. |
| 316 |
* t, r, b, and l might be B (blank), S (single), D (double), or |
| 317 |
* T (thick). The subset defined here only uses B and S. |
| 318 |
*/ |
| 319 |
|
| 320 |
Although these less-useful graphic symbols were not given names, they |
| 321 |
were used in <EM>terminfo</EM> entries. The <EM>ncurses</EM> developers invented ACS- |
| 322 |
prefixed names for them. |
| 323 |
|
| 324 |
|
| 325 |
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> |
| 326 |
Applications employing <EM>ncurses</EM> extensions should condition their use on |
| 327 |
the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. |
| 328 |
|
| 329 |
X/Open Curses Issue 4 describes these functions. It specifies no error |
| 330 |
conditions for them. |
| 331 |
|
| 332 |
SVr4 describes a successful return value only as "an integer value |
| 333 |
other than <EM>ERR</EM>". |
| 334 |
|
| 335 |
The defaults specified for forms-drawing characters apply in the POSIX |
| 336 |
locale. |
| 337 |
|
| 338 |
|
| 339 |
</PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE> |
| 340 |
X/Open Curses states that the <EM>ACS</EM><STRONG>_</STRONG> definitions are <EM>char</EM> constants. |
| 341 |
Some implementations are problematic. |
| 342 |
|
| 343 |
<STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, defines the ACS symbols as constants; |
| 344 |
others define them as elements of an array. |
| 345 |
|
| 346 |
SVr4 used an array, <EM>acs</EM><STRONG>_</STRONG><EM>map</EM>, as does <EM>ncurses</EM>. NetBSD <EM>curses</EM> also |
| 347 |
uses an array, actually named <STRONG>_</STRONG><EM>acs</EM><STRONG>_</STRONG><EM>char</EM>, with a "#define" for |
| 348 |
compatibility. |
| 349 |
|
| 350 |
<STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <EM>ACS</EM><STRONG>_</STRONG> symbols to the analogous |
| 351 |
<EM>WACS</EM><STRONG>_</STRONG> symbols as if the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters (see |
| 352 |
<STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and |
| 353 |
others that are not used for line drawing. |
| 354 |
|
| 355 |
<STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for |
| 356 |
the <EM>ACS</EM><STRONG>_</STRONG><EM>LANTERN</EM> symbol, equating its "VT100+ Character" to "I" |
| 357 |
(capital I), while the header files for SVr4 <EM>curses</EM> and other |
| 358 |
implementations use "i" (small i). |
| 359 |
|
| 360 |
None of the terminal descriptions on Unix platforms use uppercase |
| 361 |
I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>, |
| 362 |
apparently based on the X/Open documentation around 1995). On the |
| 363 |
other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator) |
| 364 |
description uses lowercase i. |
| 365 |
|
| 366 |
The <EM>displayed</EM> values of <EM>ACS</EM><STRONG>_</STRONG> constants depend on |
| 367 |
|
| 368 |
<STRONG>o</STRONG> the <EM>ncurses</EM> ABI -- for example, wide-character versus non-wide- |
| 369 |
character configurations (the former is capable of displaying |
| 370 |
Unicode while the latter is not), and |
| 371 |
|
| 372 |
<STRONG>o</STRONG> whether the locale uses UTF-8 encoding. |
| 373 |
|
| 374 |
In certain cases, the terminal is unable to display forms-drawing |
| 375 |
characters <EM>except</EM> by using UTF-8; see the discussion of the |
| 376 |
<EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM> environment variable in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. |
| 377 |
|
| 378 |
|
| 379 |
</PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE> |
| 380 |
X/Open Curses assumes that the parameter passed to <EM>waddch</EM> contains a |
| 381 |
single character. That character may have been more than eight bits |
| 382 |
wide in an SVr3 or SVr4 implementation, but X/Open Curses leaves the |
| 383 |
width of a non-wide character code unspecified. The standard further |
| 384 |
does not specify the internal structure of a <EM>chtype</EM>, though the use of |
| 385 |
bitwise operators to combine the character code with attributes and a |
| 386 |
color pair identifier into a <EM>chtype</EM> for passage to <EM>waddch</EM> is common. A |
| 387 |
portable application uses only the macros discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> to |
| 388 |
manipulate a <EM>chtype</EM>. |
| 389 |
|
| 390 |
In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character, but the library allows |
| 391 |
a multibyte character sequence to be passed via a succession of calls |
| 392 |
to <EM>waddch</EM>. Other implementations do not; a <EM>waddch</EM> call transmits |
| 393 |
exactly one character, which may be rendered in one or more screen |
| 394 |
locations depending on whether it is printable (see <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>). |
| 395 |
Depending on the locale, <EM>ncurses</EM> inspects the byte passed in each |
| 396 |
<EM>waddch</EM> call and checks whether the latest call continues a multibyte |
| 397 |
character. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the |
| 398 |
character and advances the cursor. If the calling application |
| 399 |
interrupts the succession of bytes in a multibyte character sequence by |
| 400 |
changing the current location -- for example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> -- <EM>ncurses</EM> |
| 401 |
discards the incomplete character. |
| 402 |
|
| 403 |
For portability to other implementations, do not rely upon the |
| 404 |
foregoing behavior. Check whether a character can be represented as a |
| 405 |
single byte in the current locale. |
| 406 |
|
| 407 |
<STRONG>o</STRONG> If it can, call either <EM>waddch</EM> or <EM>wadd</EM><STRONG>_</STRONG><EM>wch</EM>. |
| 408 |
|
| 409 |
<STRONG>o</STRONG> If it cannot, use only <EM>wadd</EM><STRONG>_</STRONG><EM>wch</EM>. |
| 410 |
|
| 411 |
|
| 412 |
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> |
| 413 |
4BSD (1980) introduced <EM>waddch</EM> and its variants. |
| 414 |
|
| 415 |
SVr3 (1987) added the <EM>echochar</EM> and <EM>wechochar</EM> functions and most of the |
| 416 |
<EM>ACS</EM><STRONG>_</STRONG> constants, except for <EM>ACS</EM><STRONG>_</STRONG><EM>GEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>LEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>NEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>PI</EM>, |
| 417 |
<EM>ACS</EM><STRONG>_</STRONG><EM>S3</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>S7</EM>, and <EM>ACS</EM><STRONG>_</STRONG><EM>STERLING</EM>. |
| 418 |
|
| 419 |
<EM>ncurses</EM> 1.9.6 (1995) furnished the remaining <EM>ACS</EM><STRONG>_</STRONG> constants. |
| 420 |
|
| 421 |
|
| 422 |
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> |
| 423 |
<STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library |
| 424 |
in its wide-character configuration (<EM>ncursesw</EM>). |
| 425 |
|
| 426 |
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>, <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, |
| 427 |
<STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, |
| 428 |
<STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putchar(3)</STRONG> |
| 429 |
|
| 430 |
ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> |
| 431 |
</PRE> |
| 432 |
<div class="nav"> |
| 433 |
<ul> |
| 434 |
<li><a href="#h2-NAME">NAME</a></li> |
| 435 |
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> |
| 436 |
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a> |
| 437 |
<ul> |
| 438 |
<li><a href="#h3-waddch">waddch</a></li> |
| 439 |
<li><a href="#h3-wechochar">wechochar</a></li> |
| 440 |
<li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li> |
| 441 |
</ul> |
| 442 |
</li> |
| 443 |
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> |
| 444 |
<li><a href="#h2-NOTES">NOTES</a></li> |
| 445 |
<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> |
| 446 |
<li><a href="#h2-PORTABILITY">PORTABILITY</a> |
| 447 |
<ul> |
| 448 |
<li><a href="#h3-ACS-Symbols">ACS Symbols</a></li> |
| 449 |
<li><a href="#h3-Character-Set">Character Set</a></li> |
| 450 |
</ul> |
| 451 |
</li> |
| 452 |
<li><a href="#h2-HISTORY">HISTORY</a></li> |
| 453 |
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> |
| 454 |
</ul> |
| 455 |
</div> |
| 456 |
</BODY> |
| 457 |
</HTML> |