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.83 2024/04/13 22:23:35 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-13 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-04-13 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, 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 with a "mv" prefix first perform cursor movement using
187 <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and fail if the position is outside the window, or (for "mvw"
188 functions) if the <EM>WINDOW</EM> pointer is null.
191 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
192 <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be implemented as macros.
195 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
196 X/Open Curses, Issue 4 describes these functions. It specifies no
197 error conditions for them. The defaults specified for forms-drawing
198 characters apply in the POSIX locale.
201 </PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE>
202 X/Open Curses states that the <STRONG>ACS_</STRONG> definitions are <EM>char</EM> constants.
204 Some implementations are problematic.
206 <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, define the ACS symbols as constants;
207 others define them as elements of an array.
209 This implementation uses an array, <STRONG>acs_map</STRONG>, as did SVr4 <EM>curses</EM>.
210 NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG>
213 <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
214 <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters (see
215 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and
216 others that are not used for line drawing.
218 <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for
219 the <STRONG>ACS_LANTERN</STRONG> symbol, equating its "VT100+ Character" to "I"
220 (capital I), while the header files for SVr4 <EM>curses</EM> and other
221 implementations use "i" (small i).
223 None of the terminal descriptions on Unix platforms use uppercase
224 I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>,
225 apparently based on the X/Open documentation around 1995). On the
226 other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator)
227 description uses lowercase i.
229 Some ACS symbols (<STRONG>ACS_S3</STRONG>, <STRONG>ACS_S7</STRONG>, <STRONG>ACS_LEQUAL</STRONG>, <STRONG>ACS_GEQUAL</STRONG>, <STRONG>ACS_PI</STRONG>,
230 <STRONG>ACS_NEQUAL</STRONG>, and <STRONG>ACS_STERLING</STRONG>) were not documented in any publicly
231 released System V. However, many publicly available <EM>terminfo</EM> entries
232 include <STRONG>acsc</STRONG> strings in which their key characters <STRONG>(</STRONG>pryz{|}<STRONG>)</STRONG> are
233 embedded, and a second-hand list of their character descriptions has
234 come to light. The <EM>ncurses</EM> developers invented ACS-prefixed names for
237 The <EM>displayed</EM> values of <STRONG>ACS_</STRONG> constants depend on
239 <STRONG>o</STRONG> the <EM>ncurses</EM> ABI--for example, wide-character versus non-wide-
240 character configurations (the former is capable of displaying
241 Unicode while the latter is not), and
243 <STRONG>o</STRONG> whether the locale uses UTF-8 encoding.
245 In certain cases, the terminal is unable to display forms-drawing
246 characters <EM>except</EM> by using UTF-8; see the discussion of the
247 <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>).
250 </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
251 X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a
252 single character. As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, that character may
253 have been more than eight bits wide in an SVr3 or SVr4 implementation,
254 but in the X/Open Curses model, the details are not given. The
255 important distinction between SVr4 <EM>curses</EM> and X/Open Curses is that the
256 latter separates non-character information (attributes and color) from
257 the character code, which SVr4 packs into a <EM>chtype</EM> for passage to
258 <STRONG>waddch</STRONG>.
260 In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character. But the library
261 allows a multibyte character to be passed in a succession of calls to
262 <STRONG>waddch</STRONG>. Other implementations do not; a <STRONG>waddch</STRONG> call transmits exactly
263 one character, which may be rendered in one or more screen locations
264 depending on whether it is printable.
266 Depending on the locale settings, <EM>ncurses</EM> inspects the byte passed in
267 each <STRONG>waddch</STRONG> call, and checks whether the latest call continues a
268 multibyte sequence. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the
269 character and advances the cursor.
271 If the calling application interrupts the succession of bytes in a
272 multibyte character sequence by changing the current location--for
273 example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG>--<EM>ncurses</EM> discards the incomplete character.
275 For portability to other implementations, do not rely upon this
276 behavior. Check whether a character can be represented as a single
277 byte in the current locale.
279 <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>.
281 <STRONG>o</STRONG> If it cannot, use only <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.
284 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
285 SVr4 and other versions of <EM>curses</EM> implement the <STRONG>TABSIZE</STRONG> variable, but
286 X/Open Curses does not specify it (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).
289 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
290 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
291 in its wide-character configuration (<EM>ncursesw</EM>).
293 <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>,
294 <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>,
295 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putchar(3)</STRONG>
299 ncurses 6.4 2024-04-13 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
303 <li><a href="#h2-NAME">NAME</a></li>
304 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
305 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
307 <li><a href="#h3-Adding-Characters">Adding Characters</a></li>
308 <li><a href="#h3-Echoing-Characters">Echoing Characters</a></li>
309 <li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li>
312 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
313 <li><a href="#h2-NOTES">NOTES</a></li>
314 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
316 <li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
317 <li><a href="#h3-Character-Set">Character Set</a></li>
318 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
321 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
projects / ncurses.git / blob