3 ****************************************************************************
4 * Copyright 2018-2023,2024 Thomas E. Dickey *
5 * Copyright 1998-2015,2017 Free Software Foundation, Inc. *
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: *
15 * The above copyright notice and this permission notice shall be included *
16 * in all copies or substantial portions of the Software. *
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. *
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 *
30 ****************************************************************************
31 * @Id: curs_addch.3x,v 1.94 2024/06/22 21:34:49 tom Exp @
33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
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 2024-06-22 ncurses 6.5 Library calls</TITLE>
39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
43 <H1 class="no-header">curs_addch 3x 2024-06-22 ncurses 6.5 Library calls</H1>
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>
50 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
51 <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, <STRONG>echochar</STRONG>, <STRONG>wechochar</STRONG> - add a <EM>curses</EM>
52 character to a window and advance the cursor
55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
56 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
58 <STRONG>int</STRONG> <STRONG>addch(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
59 <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>
60 <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>
61 <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>
63 <STRONG>int</STRONG> <STRONG>echochar(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
64 <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>
67 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
69 </PRE><H3><a name="h3-waddch">waddch</a></H3><PRE>
70 <STRONG>waddch</STRONG> writes the <EM>curses</EM> character <EM>ch</EM> to the window <EM>win</EM>, then advances
71 the cursor position, analogously to the standard C library's
72 <STRONG>putchar(3)</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function.
74 If advancement occurs at the right margin,
76 <STRONG>o</STRONG> the cursor automatically wraps to the beginning of the next line,
79 <STRONG>o</STRONG> if it was at the bottom of the scrolling region, and if
80 <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is enabled for <EM>win</EM>, the scrolling region scrolls up
83 If <EM>ch</EM> is a backspace, carriage return, line feed, or tab, the cursor
84 moves appropriately within the window.
86 <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin
87 of a window, it does nothing.
89 <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the current
92 <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
95 <STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next
96 line); these are placed at every eighth column by default. Alter
97 the tab interval with the <STRONG>TABSIZE</STRONG> extension; see
98 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
100 If <EM>ch</EM> is any other nonprintable character, it is drawn in printable
101 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
102 location of a nonprintable character does not return the character
103 itself, but its <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> representation.
105 The object or expression <EM>ch</EM> may contain attributes and/or a color pair
106 identifier. (A <EM>chtype</EM> can be copied from place to place using
107 <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> and <STRONG>waddch</STRONG>.) See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> for values of predefined
108 constants that can be usefully "or"ed with characters.
111 </PRE><H3><a name="h3-wechochar">wechochar</a></H3><PRE>
112 <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by
113 (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> interprets these functions as a hint that only a
114 single character is being output; for non-control characters, a
115 considerable performance gain may be enjoyed by employing them.
118 </PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE>
119 <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG>
120 to write line-drawing and other special characters to the screen.
121 <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default listed
122 below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> capability does not
123 define a terminal-specific replacement for it, or if the terminal and
124 locale configuration requires Unicode to access these characters but
125 the library is unable to use Unicode. The "acsc char" column
126 corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>)
127 string capability, and the characters in it may appear on the screen if
128 the terminal type's database entry incorrectly advertises ACS support.
129 The name "ACS" originates in the Alternate Character Set feature of the
132 <STRONG>ACS</STRONG> <STRONG>acsc</STRONG>
133 <STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
134 ------------------------------------------------------------------------
135 <STRONG>ACS_BLOCK</STRONG> # 0 solid square block
136 <STRONG>ACS_BOARD</STRONG> # h board of squares
137 <STRONG>ACS_BTEE</STRONG> + v bottom tee
138 <STRONG>ACS_BULLET</STRONG> o ~ bullet
139 <STRONG>ACS_CKBOARD</STRONG> : a checker board (stipple)
140 <STRONG>ACS_DARROW</STRONG> v . arrow pointing down
141 <STRONG>ACS_DEGREE</STRONG> ' f degree symbol
142 <STRONG>ACS_DIAMOND</STRONG> + ` diamond
143 <STRONG>ACS_GEQUAL</STRONG> > > greater-than-or-equal-to
144 <STRONG>ACS_HLINE</STRONG> - q horizontal line
145 <STRONG>ACS_LANTERN</STRONG> # i lantern symbol
146 <STRONG>ACS_LARROW</STRONG> < , arrow pointing left
147 <STRONG>ACS_LEQUAL</STRONG> < y less-than-or-equal-to
148 <STRONG>ACS_LLCORNER</STRONG> + m lower left-hand corner
149 <STRONG>ACS_LRCORNER</STRONG> + j lower right-hand corner
150 <STRONG>ACS_LTEE</STRONG> + t left tee
151 <STRONG>ACS_NEQUAL</STRONG> ! | not-equal
152 <STRONG>ACS_PI</STRONG> * { greek pi
153 <STRONG>ACS_PLMINUS</STRONG> # g plus/minus
154 <STRONG>ACS_PLUS</STRONG> + n plus
155 <STRONG>ACS_RARROW</STRONG> > + arrow pointing right
156 <STRONG>ACS_RTEE</STRONG> + u right tee
157 <STRONG>ACS_S1</STRONG> - o scan line 1
158 <STRONG>ACS_S3</STRONG> - p scan line 3
159 <STRONG>ACS_S7</STRONG> - r scan line 7
160 <STRONG>ACS_S9</STRONG> _ s scan line 9
161 <STRONG>ACS_STERLING</STRONG> f } pound-sterling symbol
162 <STRONG>ACS_TTEE</STRONG> + w top tee
163 <STRONG>ACS_UARROW</STRONG> ^ - arrow pointing up
164 <STRONG>ACS_ULCORNER</STRONG> + l upper left-hand corner
165 <STRONG>ACS_URCORNER</STRONG> + k upper right-hand corner
166 <STRONG>ACS_VLINE</STRONG> | x vertical line
169 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
170 These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
172 In <EM>ncurses</EM>, <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG> if
174 <STRONG>o</STRONG> <EM>win</EM> is <STRONG>NULL</STRONG>,
176 <STRONG>o</STRONG> wrapping to a new line is impossible because <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> has not
177 been called on <EM>win</EM> when a write to its bottom right location is
180 <STRONG>o</STRONG> it is not possible to add a complete character at the cursor
183 The last may be due to different causes:
185 <STRONG>o</STRONG> conversion of a wide character to a multibyte character sequence
188 <STRONG>o</STRONG> at least one of the bytes resulting from wide character conversion
189 to a multibyte character sequence cannot be added to the window.
190 See section "PORTABILITY" below regarding the use of <STRONG>waddch</STRONG> with
193 Functions prefixed with "mv" first perform cursor movement and fail if
194 the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
197 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
198 <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be implemented as macros.
201 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
203 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
204 SVr4 and other versions of <EM>curses</EM> implement the <STRONG>TABSIZE</STRONG> variable, but
205 X/Open Curses does not specify it; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
208 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
209 Applications employing <EM>ncurses</EM> extensions should condition their use on
210 the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
212 X/Open Curses, Issue 4 describes these functions. It specifies no
213 error conditions for them.
215 SVr4 <EM>curses</EM> describes a successful return value only as "an integer
216 value other than <STRONG>ERR</STRONG>".
218 The defaults specified for forms-drawing characters apply in the POSIX
222 </PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE>
223 X/Open Curses states that the <STRONG>ACS_</STRONG> definitions are <EM>char</EM> constants.
224 Some implementations are problematic.
226 <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, defines the ACS symbols as constants;
227 others define them as elements of an array.
229 This implementation uses an array, <STRONG>acs_map</STRONG>, as did SVr4 <EM>curses</EM>.
230 NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG>
233 <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
234 <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters (see
235 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and
236 others that are not used for line drawing.
238 <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for
239 the <STRONG>ACS_LANTERN</STRONG> symbol, equating its "VT100+ Character" to "I"
240 (capital I), while the header files for SVr4 <EM>curses</EM> and other
241 implementations use "i" (small i).
243 None of the terminal descriptions on Unix platforms use uppercase
244 I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>,
245 apparently based on the X/Open documentation around 1995). On the
246 other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator)
247 description uses lowercase i.
249 Some ACS symbols (<STRONG>ACS_S3</STRONG>, <STRONG>ACS_S7</STRONG>, <STRONG>ACS_LEQUAL</STRONG>, <STRONG>ACS_GEQUAL</STRONG>, <STRONG>ACS_PI</STRONG>,
250 <STRONG>ACS_NEQUAL</STRONG>, and <STRONG>ACS_STERLING</STRONG>) were not documented in any publicly
251 released System V. However, many publicly available <EM>terminfo</EM> entries
252 include <STRONG>acsc</STRONG> capabilities in which their key characters (<STRONG>pryz{|}</STRONG>) are
253 embedded, and a second-hand list of their character descriptions has
254 come to light. The <EM>ncurses</EM> developers invented ACS-prefixed names for
257 The <EM>displayed</EM> values of <STRONG>ACS_</STRONG> constants depend on
259 <STRONG>o</STRONG> the <EM>ncurses</EM> ABI--for example, wide-character versus non-wide-
260 character configurations (the former is capable of displaying
261 Unicode while the latter is not), and
263 <STRONG>o</STRONG> whether the locale uses UTF-8 encoding.
265 In certain cases, the terminal is unable to display forms-drawing
266 characters <EM>except</EM> by using UTF-8; see the discussion of the
267 <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>.
270 </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
271 X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a
272 single character. That character may have been more than eight bits
273 wide in an SVr3 or SVr4 implementation, but X/Open Curses leaves the
274 width of a non-wide character code unspecified. The standard further
275 does not specify the internal structure of a <EM>chtype</EM>, though the use of
276 bit operations to combine the character code with attributes and a
277 color pair identifier into a <EM>chtype</EM> for passage to <STRONG>waddch</STRONG> is common. A
278 portable application uses only the macros discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> to
279 manipulate a <EM>chtype</EM>.
281 In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character, but the library allows
282 a multibyte character sequence to be passed via a succession of calls
283 to <STRONG>waddch</STRONG>. Other implementations do not; a <STRONG>waddch</STRONG> call transmits
284 exactly one character, which may be rendered in one or more screen
285 locations depending on whether it is printable (see <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>).
286 Depending on the locale, <EM>ncurses</EM> inspects the byte passed in each
287 <STRONG>waddch</STRONG> call and checks whether the latest call continues a multibyte
288 character. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the
289 character and advances the cursor. If the calling application
290 interrupts the succession of bytes in a multibyte character sequence by
291 changing the current location--for example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG>--<EM>ncurses</EM>
292 discards the incomplete character.
294 For portability to other implementations, do not rely upon the
295 foregoing behavior. Check whether a character can be represented as a
296 single byte in the current locale.
298 <STRONG>o</STRONG> If it can, call either <STRONG>waddch</STRONG> or <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.
300 <STRONG>o</STRONG> If it cannot, use only <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.
303 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
304 4BSD (1980) <EM>curses</EM> introduced <EM>waddch</EM>.
306 SVr3 (1987) added <EM>wechochar</EM>.
309 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
310 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
311 in its wide-character configuration (<EM>ncursesw</EM>).
313 <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>,
314 <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>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>,
315 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putchar(3)</STRONG>
319 ncurses 6.5 2024-06-22 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
323 <li><a href="#h2-NAME">NAME</a></li>
324 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
325 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
327 <li><a href="#h3-waddch">waddch</a></li>
328 <li><a href="#h3-wechochar">wechochar</a></li>
329 <li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li>
332 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
333 <li><a href="#h2-NOTES">NOTES</a></li>
334 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a>
336 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
339 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
341 <li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
342 <li><a href="#h3-Character-Set">Character Set</a></li>
345 <li><a href="#h2-HISTORY">HISTORY</a></li>
346 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>