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.85 2024/04/20 19:03:47 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-04-20 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-04-20 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-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, and if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is
93 enabled for <EM>win</EM>, scrolls the window if the cursor was already on
96 <STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next
97 line); these are placed at every eighth column by default. Alter
98 the tab interval with the <STRONG>TABSIZE</STRONG> extension; see
99 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
101 If <EM>ch</EM> is any other nonprintable character, it is drawn in printable
102 form, using the same convention as <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>.
104 Calling <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> on the location of a nonprintable character does not
105 return the character itself, but its <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> representation.
107 <EM>ch</EM> may contain rendering and/or color attributes, and others can be
108 combined with the parameter by logically "or"ing with it. (A character
109 with its attributes can be copied from place to place using <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG>
110 and <STRONG>waddch</STRONG>.) See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> for values of predefined video
111 attribute constants that can be usefully "or"ed with characters.
114 </PRE><H3><a name="h3-Echoing-Characters">Echoing Characters</a></H3><PRE>
115 <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by
116 (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> interprets these functions as a hint that only a
117 single character is being output; for non-control characters, a
118 considerable performance gain may be enjoyed by employing them.
121 </PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE>
122 <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG>
123 to write line-drawing and other special characters to the screen.
124 <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default listed
125 below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> capability does not
126 define a terminal-specific replacement for it, or if the terminal and
127 locale configuration requires Unicode to access these characters but
128 the library is unable to use Unicode. The "acsc char" column
129 corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> string
130 capability, and the characters in it may appear on the screen if the
131 terminal's database entry incorrectly advertises ACS support. The name
132 "ACS" originates in the Alternate Character Set feature of the DEC
135 <STRONG>ACS</STRONG> <STRONG>acsc</STRONG>
136 <STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
137 ------------------------------------------------------------------------
138 <STRONG>ACS_BLOCK</STRONG> # 0 solid square block
139 <STRONG>ACS_BOARD</STRONG> # h board of squares
140 <STRONG>ACS_BTEE</STRONG> + v bottom tee
141 <STRONG>ACS_BULLET</STRONG> o ~ bullet
142 <STRONG>ACS_CKBOARD</STRONG> : a checker board (stipple)
143 <STRONG>ACS_DARROW</STRONG> v . arrow pointing down
144 <STRONG>ACS_DEGREE</STRONG> ' f degree symbol
145 <STRONG>ACS_DIAMOND</STRONG> + ` diamond
146 <STRONG>ACS_GEQUAL</STRONG> > > greater-than-or-equal-to
147 <STRONG>ACS_HLINE</STRONG> - q horizontal line
148 <STRONG>ACS_LANTERN</STRONG> # i lantern symbol
149 <STRONG>ACS_LARROW</STRONG> < , arrow pointing left
150 <STRONG>ACS_LEQUAL</STRONG> < y less-than-or-equal-to
151 <STRONG>ACS_LLCORNER</STRONG> + m lower left-hand corner
152 <STRONG>ACS_LRCORNER</STRONG> + j lower right-hand corner
153 <STRONG>ACS_LTEE</STRONG> + t left tee
154 <STRONG>ACS_NEQUAL</STRONG> ! | not-equal
155 <STRONG>ACS_PI</STRONG> * { greek pi
156 <STRONG>ACS_PLMINUS</STRONG> # g plus/minus
157 <STRONG>ACS_PLUS</STRONG> + n plus
158 <STRONG>ACS_RARROW</STRONG> > + arrow pointing right
159 <STRONG>ACS_RTEE</STRONG> + u right tee
160 <STRONG>ACS_S1</STRONG> - o scan line 1
161 <STRONG>ACS_S3</STRONG> - p scan line 3
162 <STRONG>ACS_S7</STRONG> - r scan line 7
163 <STRONG>ACS_S9</STRONG> _ s scan line 9
164 <STRONG>ACS_STERLING</STRONG> f } pound-sterling symbol
165 <STRONG>ACS_TTEE</STRONG> + w top tee
166 <STRONG>ACS_UARROW</STRONG> ^ - arrow pointing up
167 <STRONG>ACS_ULCORNER</STRONG> + l upper left-hand corner
168 <STRONG>ACS_URCORNER</STRONG> + k upper right-hand corner
169 <STRONG>ACS_VLINE</STRONG> | x vertical line
172 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
173 These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
175 In <EM>ncurses</EM>, <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG> if it is not possible to add a complete
176 character at the cursor position, as when conversion of a multibyte
177 character to a byte sequence fails, or at least one of the resulting
178 bytes cannot be added to the window. See section "PORTABILITY" below
179 regarding the use of <STRONG>waddch</STRONG> with multibyte characters.
181 <STRONG>waddch</STRONG> can successfully write a character at the bottom right location
182 of the window. However, <EM>ncurses</EM> returns <STRONG>ERR</STRONG> if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not
183 enabled in that event, because it is not possible to wrap to a new
186 Functions prefixed with "mv" first perform cursor movement and fail if
187 the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
190 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
191 <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be implemented as macros.
194 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
195 X/Open Curses, Issue 4 describes these functions. It specifies no
196 error conditions for them.
198 SVr4 <EM>curses</EM> describes a successful return value only as "an integer
199 value other than <STRONG>ERR</STRONG>".
201 The defaults specified for forms-drawing characters apply in the POSIX
205 </PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE>
206 X/Open Curses states that the <STRONG>ACS_</STRONG> definitions are <EM>char</EM> constants.
208 Some implementations are problematic.
210 <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, define the ACS symbols as constants;
211 others define them as elements of an array.
213 This implementation uses an array, <STRONG>acs_map</STRONG>, as did SVr4 <EM>curses</EM>.
214 NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG>
217 <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
218 <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters (see
219 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and
220 others that are not used for line drawing.
222 <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for
223 the <STRONG>ACS_LANTERN</STRONG> symbol, equating its "VT100+ Character" to "I"
224 (capital I), while the header files for SVr4 <EM>curses</EM> and other
225 implementations use "i" (small i).
227 None of the terminal descriptions on Unix platforms use uppercase
228 I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>,
229 apparently based on the X/Open documentation around 1995). On the
230 other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator)
231 description uses lowercase i.
233 Some ACS symbols (<STRONG>ACS_S3</STRONG>, <STRONG>ACS_S7</STRONG>, <STRONG>ACS_LEQUAL</STRONG>, <STRONG>ACS_GEQUAL</STRONG>, <STRONG>ACS_PI</STRONG>,
234 <STRONG>ACS_NEQUAL</STRONG>, and <STRONG>ACS_STERLING</STRONG>) were not documented in any publicly
235 released System V. However, many publicly available <EM>terminfo</EM> entries
236 include <STRONG>acsc</STRONG> strings in which their key characters <STRONG>(</STRONG>pryz{|}<STRONG>)</STRONG> are
237 embedded, and a second-hand list of their character descriptions has
238 come to light. The <EM>ncurses</EM> developers invented ACS-prefixed names for
241 The <EM>displayed</EM> values of <STRONG>ACS_</STRONG> constants depend on
243 <STRONG>o</STRONG> the <EM>ncurses</EM> ABI--for example, wide-character versus non-wide-
244 character configurations (the former is capable of displaying
245 Unicode while the latter is not), and
247 <STRONG>o</STRONG> whether the locale uses UTF-8 encoding.
249 In certain cases, the terminal is unable to display forms-drawing
250 characters <EM>except</EM> by using UTF-8; see the discussion of the
251 <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>).
254 </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
255 X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a
256 single character. As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, that character may
257 have been more than eight bits wide in an SVr3 or SVr4 implementation,
258 but in the X/Open Curses model, the details are not given. The
259 important distinction between SVr4 <EM>curses</EM> and X/Open Curses is that the
260 latter separates non-character information (attributes and color) from
261 the character code, which SVr4 packs into a <EM>chtype</EM> for passage to
262 <STRONG>waddch</STRONG>.
264 In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character. But the library
265 allows a multibyte character to be passed in a succession of calls to
266 <STRONG>waddch</STRONG>. Other implementations do not; a <STRONG>waddch</STRONG> call transmits exactly
267 one character, which may be rendered in one or more screen locations
268 depending on whether it is printable.
270 Depending on the locale settings, <EM>ncurses</EM> inspects the byte passed in
271 each <STRONG>waddch</STRONG> call, and checks whether the latest call continues a
272 multibyte sequence. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the
273 character and advances the cursor.
275 If the calling application interrupts the succession of bytes in a
276 multibyte character sequence by changing the current location--for
277 example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG>--<EM>ncurses</EM> discards the incomplete character.
279 For portability to other implementations, do not rely upon this
280 behavior. Check whether a character can be represented as a single
281 byte in the current locale.
283 <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>.
285 <STRONG>o</STRONG> If it cannot, use only <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.
288 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
289 SVr4 and other versions of <EM>curses</EM> implement the <STRONG>TABSIZE</STRONG> variable, but
290 X/Open Curses does not specify it (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).
293 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
294 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
295 in its wide-character configuration (<EM>ncursesw</EM>).
297 <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>,
298 <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>,
299 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putchar(3)</STRONG>
303 ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
307 <li><a href="#h2-NAME">NAME</a></li>
308 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
309 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
311 <li><a href="#h3-Adding-Characters">Adding Characters</a></li>
312 <li><a href="#h3-Echoing-Characters">Echoing Characters</a></li>
313 <li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li>
316 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
317 <li><a href="#h2-NOTES">NOTES</a></li>
318 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
320 <li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
321 <li><a href="#h3-Character-Set">Character Set</a></li>
322 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
325 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>