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.81 2024/03/23 20:38:57 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-03-23 ncurses 6.4 Library calls</TITLE>
39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
43 <H1 class="no-header">curs_addch 3x 2024-03-23 ncurses 6.4 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-Adding-Characters">Adding Characters</a></H3><PRE>
70 <STRONG>waddch</STRONG> puts the character <EM>ch</EM> at the cursor position of window <EM>win</EM>, then
71 advances 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> at the bottom of the current scrolling region, and if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>
80 is enabled for <EM>win</EM>, the scrolling region scrolls up one line.
82 If <EM>ch</EM> is a backspace, carriage return, line feed, or tab, the cursor
83 moves appropriately within the window.
85 <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin
86 of a window, it does nothing.
88 <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the current
91 <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then moves the cursor to the left
92 margin on the next line of the window, scrolling the window if the
93 cursor was already on the last line.
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>.
103 <STRONG>o</STRONG> <STRONG>waddch</STRONG> displays control characters in <STRONG>^</STRONG><EM>X</EM> notation.
105 <STRONG>o</STRONG> Character codes above 127 are either meta characters (if the screen
106 has not been initialized, or if <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> has been called with a
107 <STRONG>TRUE</STRONG> <EM>bf</EM> parameter) that render in <STRONG>M-</STRONG><EM>X</EM> notation, or they display as
108 themselves. In the latter case, the values may not be printable;
109 this follows the X/Open specification.
111 Calling <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> on the location of a nonprintable character does not
112 return the character itself, but its <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> representation.
114 Video attributes can be combined with a character argument passed to
115 <STRONG>waddch</STRONG> by logical-ORing them into the character. (Thus, text,
116 including attributes, can be copied from one place to another using
117 <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
118 video attribute constants that can be usefully OR'ed with characters.
121 </PRE><H3><a name="h3-Echoing-Characters">Echoing Characters</a></H3><PRE>
122 <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by
123 (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> interprets these functions as a hint that only a
124 single character is being output; for non-control characters, a
125 considerable performance gain may be enjoyed by employing them.
128 </PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE>
129 <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG>
130 to write line-drawing and other special characters to the screen.
131 <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default listed
132 below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> capability does not
133 define a terminal-specific replacement for it, or if the terminal and
134 locale configuration requires Unicode to access these characters but
135 the library is unable to use Unicode. The "acsc char" column
136 corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> string
137 capability, and the characters in it may appear on the screen if the
138 terminal's database entry incorrectly advertises ACS support. The name
139 "ACS" originates in the Alternate Character Set feature of the DEC
142 <STRONG>ACS</STRONG> <STRONG>acsc</STRONG>
143 <STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
144 ------------------------------------------------------------------------
145 <STRONG>ACS_BLOCK</STRONG> # 0 solid square block
146 <STRONG>ACS_BOARD</STRONG> # h board of squares
147 <STRONG>ACS_BTEE</STRONG> + v bottom tee
148 <STRONG>ACS_BULLET</STRONG> o ~ bullet
149 <STRONG>ACS_CKBOARD</STRONG> : a checker board (stipple)
150 <STRONG>ACS_DARROW</STRONG> v . arrow pointing down
151 <STRONG>ACS_DEGREE</STRONG> ' f degree symbol
152 <STRONG>ACS_DIAMOND</STRONG> + ` diamond
153 <STRONG>ACS_GEQUAL</STRONG> > > greater-than-or-equal-to
154 <STRONG>ACS_HLINE</STRONG> - q horizontal line
155 <STRONG>ACS_LANTERN</STRONG> # i lantern symbol
156 <STRONG>ACS_LARROW</STRONG> < , arrow pointing left
157 <STRONG>ACS_LEQUAL</STRONG> < y less-than-or-equal-to
158 <STRONG>ACS_LLCORNER</STRONG> + m lower left-hand corner
159 <STRONG>ACS_LRCORNER</STRONG> + j lower right-hand corner
160 <STRONG>ACS_LTEE</STRONG> + t left tee
161 <STRONG>ACS_NEQUAL</STRONG> ! | not-equal
162 <STRONG>ACS_PI</STRONG> * { greek pi
163 <STRONG>ACS_PLMINUS</STRONG> # g plus/minus
164 <STRONG>ACS_PLUS</STRONG> + n plus
165 <STRONG>ACS_RARROW</STRONG> > + arrow pointing right
166 <STRONG>ACS_RTEE</STRONG> + u right tee
167 <STRONG>ACS_S1</STRONG> - o scan line 1
168 <STRONG>ACS_S3</STRONG> - p scan line 3
169 <STRONG>ACS_S7</STRONG> - r scan line 7
170 <STRONG>ACS_S9</STRONG> _ s scan line 9
171 <STRONG>ACS_STERLING</STRONG> f } pound-sterling symbol
172 <STRONG>ACS_TTEE</STRONG> + w top tee
173 <STRONG>ACS_UARROW</STRONG> ^ - arrow pointing up
174 <STRONG>ACS_ULCORNER</STRONG> + l upper left-hand corner
175 <STRONG>ACS_URCORNER</STRONG> + k upper right-hand corner
176 <STRONG>ACS_VLINE</STRONG> | x vertical line
179 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
180 These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
182 In <EM>ncurses</EM>, <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG> if it is not possible to add a complete
183 character at the cursor position, as when conversion of a multibyte
184 character to a byte sequence fails, or at least one of the resulting
185 bytes cannot be added to the window. See section "PORTABILITY" below
186 regarding the use of <STRONG>waddch</STRONG> with multibyte characters.
188 If <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not enabled, <STRONG>waddch</STRONG> can successfully write a
189 character at the bottom right location of the window. However, <EM>ncurses</EM>
190 returns <STRONG>ERR</STRONG> because it is not possible to wrap to a new line.
192 Functions with a "mv" prefix first perform cursor movement using
193 <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and fail if the position is outside the window, or (for "mvw"
194 functions) if the <EM>WINDOW</EM> pointer is null.
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-PORTABILITY">PORTABILITY</a></H2><PRE>
202 X/Open Curses, Issue 4 describes these functions. It specifies no
203 error conditions for them. The defaults specified for forms-drawing
204 characters apply in the POSIX locale.
207 </PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE>
208 X/Open Curses states that the <STRONG>ACS_</STRONG> definitions are <EM>char</EM> constants.
210 Some implementations are problematic.
212 <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, define the ACS symbols as constants;
213 others define them as elements of an array.
215 This implementation uses an array, <STRONG>acs_map</STRONG>, as did SVr4 <EM>curses</EM>.
216 NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG>
219 <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
220 <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters (see
221 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and
222 others that are not used for line drawing.
224 <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for
225 the <STRONG>ACS_LANTERN</STRONG> symbol, equating its "VT100+ Character" to "I"
226 (capital I), while the header files for SVr4 <EM>curses</EM> and other
227 implementations use "i" (small i).
229 None of the terminal descriptions on Unix platforms use uppercase
230 I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>,
231 apparently based on the X/Open documentation around 1995). On the
232 other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator)
233 description uses lowercase i.
235 Some ACS symbols (<STRONG>ACS_S3</STRONG>, <STRONG>ACS_S7</STRONG>, <STRONG>ACS_LEQUAL</STRONG>, <STRONG>ACS_GEQUAL</STRONG>, <STRONG>ACS_PI</STRONG>,
236 <STRONG>ACS_NEQUAL</STRONG>, and <STRONG>ACS_STERLING</STRONG>) were not documented in any publicly
237 released System V. However, many publicly available <EM>terminfo</EM> entries
238 include <STRONG>acsc</STRONG> strings in which their key characters (pryz{|}) are
239 embedded, and a second-hand list of their character descriptions has
240 come to light. The <EM>ncurses</EM> developers invented ACS-prefixed names for
243 The <EM>displayed</EM> values of <STRONG>ACS_</STRONG> constants depend on
245 <STRONG>o</STRONG> the <EM>ncurses</EM> ABI--for example, wide-character versus non-wide-
246 character configurations (the former is capable of displaying
247 Unicode while the latter is not), and
249 <STRONG>o</STRONG> whether the locale uses UTF-8 encoding.
251 In certain cases, the terminal is unable to display forms-drawing
252 characters <EM>except</EM> by using UTF-8; see the discussion of the
253 <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>).
256 </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
257 X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a
258 single character. As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, that character may
259 have been more than eight bits wide in an SVr3 or SVr4 implementation,
260 but in the X/Open Curses model, the details are not given. The
261 important distinction between SVr4 <EM>curses</EM> and X/Open Curses is that the
262 latter separates non-character information (attributes and color) from
263 the character code, which SVr4 packs into a <EM>chtype</EM> for passage to
264 <STRONG>waddch</STRONG>.
266 In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character. But <EM>ncurses</EM> allows a
267 multibyte character to be passed in a succession of calls to <STRONG>waddch</STRONG>.
268 Other implementations do not; a <STRONG>waddch</STRONG> call transmits exactly one
269 character, which may be rendered in one or more screen locations
270 depending on whether it is printable.
272 Depending on the locale settings, <EM>ncurses</EM> inspects the byte passed in
273 each <STRONG>waddch</STRONG> call, and checks whether the latest call continues a
274 multibyte sequence. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the
275 character and advances the window's current location.
277 If the calling application interrupts the succession of bytes in a
278 multibyte character sequence by moving the current location (for
279 example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG>), <EM>ncurses</EM> discards the incomplete character.
281 For portability to other implementations, do not rely upon this
282 behavior. Check whether a character can be represented as a single
283 byte in the current locale.
285 <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>.
287 <STRONG>o</STRONG> If it cannot, use only <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.
290 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
291 SVr4 and other versions of <EM>curses</EM> implement the <STRONG>TABSIZE</STRONG> variable, but
292 X/Open Curses does not specify it (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).
295 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
296 <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>,
297 <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>,
298 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putchar(3)</STRONG>
300 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
301 in its wide-character configuration (<EM>ncursesw</EM>).
305 ncurses 6.4 2024-03-23 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
309 <li><a href="#h2-NAME">NAME</a></li>
310 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
311 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
313 <li><a href="#h3-Adding-Characters">Adding Characters</a></li>
314 <li><a href="#h3-Echoing-Characters">Echoing Characters</a></li>
315 <li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li>
318 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
319 <li><a href="#h2-NOTES">NOTES</a></li>
320 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
322 <li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
323 <li><a href="#h3-Character-Set">Character Set</a></li>
324 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
327 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>