2 .\"***************************************************************************
3 .\" Copyright 2018-2023,2024 Thomas E. Dickey *
4 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a *
7 .\" copy of this software and associated documentation files (the *
8 .\" "Software"), to deal in the Software without restriction, including *
9 .\" without limitation the rights to use, copy, modify, merge, publish, *
10 .\" distribute, distribute with modifications, sublicense, and/or sell *
11 .\" copies of the Software, and to permit persons to whom the Software is *
12 .\" furnished to do so, subject to the following conditions: *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 .\" Except as contained in this notice, the name(s) of the above copyright *
26 .\" holders shall not be used in advertising or otherwise to promote the *
27 .\" sale, use or other dealings in this Software without prior written *
29 .\"***************************************************************************
31 .\" $Id: curs_addch.3x,v 1.86 2024/05/11 20:39:53 tom Exp $
32 .TH curs_addch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
61 add a \fIcurses\fP character to a window and advance the cursor
64 \fB#include <curses.h>
66 \fBint addch(const chtype \fIch\fP);
67 \fBint waddch(WINDOW *\fIwin\fP, const chtype \fIch\fP);
68 \fBint mvaddch(int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
69 \fBint mvwaddch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
71 \fBint echochar(const chtype \fIch\fP);
72 \fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP);
83 then advances the cursor position,
84 analogously to the standard C library's \fI\%putchar\fP(3).
85 \fB\%ncurses\fP(3X) describes the variants of this function.
87 If advancement occurs at the right margin,
89 the cursor automatically wraps to the beginning of the next line,
92 if it was at the bottom of the scrolling region,
93 and if \fB\%scrollok\fP(3X) is enabled for
95 the scrolling region scrolls up one line.
105 the cursor moves appropriately within the window.
107 Backspace moves the cursor one character left;
108 at the left margin of a window,
111 Carriage return moves the cursor to the left margin on the current line
114 Line feed does a \fB\%clrtoeol\fP(3X),
115 then advances as if from the right margin.
117 Tab advances the cursor to the next tab stop
118 (possibly on the next line);
119 these are placed at every eighth column by default.
120 Alter the tab interval with the
123 see \fB\%curs_variables\fP(3X).
127 is any other nonprintable character,
128 it is drawn in printable form using the same convention as
131 Calling \fB\%winch\fP(3X) on the location of a nonprintable character
132 does not return the character itself,
133 but its \fB\%unctrl\fP(3X) representation.
135 The object or expression
137 may contain attributes and/or a color pair identifier.
138 (A character with its attributes can be copied from place to place
139 using \fB\%winch\fP(3X) and
141 See \fB\%curs_attr\fP(3X) for values of predefined video attribute
142 constants that can be usefully \*(``or\*(''ed with characters.
147 are equivalent to calling
150 .RB \%( w ) refresh .
152 interprets these functions as a hint that only a single character is
154 for non-control characters,
155 a considerable performance gain may be enjoyed by employing them.
156 .\" TODO: Combine the following with the "Line Drawing" subsection of
157 .\" terminfo(5) and replace this with a cross reference there.
158 .SS "Forms-Drawing Characters"
160 defines macros starting with
162 that can be used with
164 to write line-drawing and other special characters to the screen.
167 .I "forms-drawing characters."
168 The ACS default listed below is used if the
172 capability does not define a terminal-specific replacement for it,
173 or if the terminal and locale configuration requires Unicode to access
174 these characters but the library is unable to use Unicode.
175 The \*(``acsc char\*('' column corresponds to how the characters are
180 and the characters in it may appear on the screen if the terminal type's
181 database entry incorrectly advertises ACS support.
182 The name \*(``ACS\*('' originates in the Alternate Character Set feature
183 of the DEC VT100 terminal.
190 Symbol Default char Glyph Name
192 ACS_BLOCK # 0 solid square block
193 ACS_BOARD # h board of squares
194 ACS_BTEE + v bottom tee
195 ACS_BULLET o \*~ bullet
196 ACS_CKBOARD : a checker board (stipple)
197 ACS_DARROW v . arrow pointing down
198 ACS_DEGREE \*' f degree symbol
199 ACS_DIAMOND + \(ga diamond
200 ACS_GEQUAL > > greater-than-or-equal-to
201 ACS_HLINE \- q horizontal line
202 ACS_LANTERN # i lantern symbol
203 ACS_LARROW < , arrow pointing left
204 ACS_LEQUAL < y less-than-or-equal-to
205 ACS_LLCORNER + m lower left-hand corner
206 ACS_LRCORNER + j lower right-hand corner
207 ACS_LTEE + t left tee
208 ACS_NEQUAL ! | not-equal
210 ACS_PLMINUS # g plus/minus
212 ACS_RARROW > + arrow pointing right
213 ACS_RTEE + u right tee
214 ACS_S1 \- o scan line 1
215 ACS_S3 \- p scan line 3
216 ACS_S7 \- r scan line 7
217 ACS_S9 \&_ s scan line 9
218 ACS_STERLING f } pound-sterling symbol
220 ACS_UARROW \*^ \- arrow pointing up
221 ACS_ULCORNER + l upper left-hand corner
222 ACS_URCORNER + k upper right-hand corner
223 ACS_VLINE | x vertical line
226 These functions return
243 wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
246 when a write to its bottom right location is attempted,
249 it is not possible to add a complete character at the cursor position.
251 The last may be due to different causes:
253 conversion of a multibyte character to a byte sequence can fail,
256 at least one of the bytes resulting from conversion from a multibyte
257 sequence cannot be added to the window.
258 See section \*(``PORTABILITY\*('' below regarding the use of
260 with multibyte characters.
262 Functions prefixed with \*(``mv\*('' first perform cursor movement and
266 is outside the window boundaries.
273 may be implemented as macros.
276 SVr4 and other versions of
281 but X/Open Curses does not specify it;
282 see \fB\%curs_variables\fP(3X).
285 Issue 4 describes these functions.
286 It specifies no error conditions for them.
290 describes a successful return value only as
291 \*(``an integer value other than
294 The defaults specified for forms-drawing characters apply in the POSIX
297 X/Open Curses states that the
303 Some implementations are problematic.
308 defines the ACS symbols as constants;
309 others define them as elements of an array.
311 This implementation uses an array,
315 NetBSD also uses an array,
326 symbols to the analogous
330 symbols were wide characters
331 (see \fB\%curs_add_wch\fP(3X)).
332 The misdefined symbols are the arrows and others that are not used for
337 has a typographical error
340 symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
342 while the header files for SVr4
344 and other implementations use \*(``i\*(''
347 None of the terminal descriptions on Unix platforms use uppercase I,
351 entry for \fI\%screen\fP(1),
352 apparently based on the X/Open documentation around 1995).
356 (AT&T PC6300 with EMOTS Terminal Emulator)
357 description uses lowercase i.
368 were not documented in any publicly released System\ V.
370 many publicly available
374 capabilities in which their key characters
377 and a second-hand list of their character descriptions has come to
381 developers invented ACS-prefixed names for them.
392 wide-character versus non-wide-character configurations
393 (the former is capable of displaying Unicode while the latter is not),
396 whether the locale uses UTF-8 encoding.
399 the terminal is unable to display forms-drawing characters
402 see the discussion of the
403 .I \%NCURSES_NO_UTF8_ACS
404 environment variable in \fB\%ncurses\fP(3X).
406 X/Open Curses assumes that the parameter passed to
408 contains a single character.
409 That character may have been more than eight bits wide in an SVr3 or
411 but X/Open Curses leaves the width of a non-wide character code
413 The standard further does not specify the internal structure of a
415 though the use of bit operations to combine the character code with
416 attributes and a color pair identifier into a
421 A portable application uses only the macros discussed in
422 \fB\%curs_attr\fP(3X) to manipulate a
428 holds an eight-bit character,
429 but the library allows a multibyte character to be passed in a
430 succession of calls to
432 Other implementations do not;
435 call transmits exactly one character,
436 which may be rendered in one or more screen locations depending on
437 whether it is printable
438 (see \fB\%unctrl\fP(3X)).
439 Depending on the locale,
441 inspects the byte passed in each
443 call and checks whether the latest call continues a multibyte sequence.
447 displays the character and advances the cursor.
448 If the calling application interrupts the succession of bytes in
449 a multibyte character sequence by changing the current location\(emfor
451 with \fB\%wmove\fP(3X)\(em\c
453 discards the incomplete character.
455 For portability to other implementations,
456 do not rely upon the foregoing behavior.
457 Check whether a character can be represented as a single byte in the
463 or \fB\%wadd_wch\fP(3X).
467 \fB\%wadd_wch\fP(3X).
469 \fB\%curs_add_wch\fP(3X) describes comparable functions of the
471 library in its wide-character configuration
475 \fB\%curs_addchstr\fP(3X),
476 \fB\%curs_addstr\fP(3X),
477 \fB\%curs_attr\fP(3X),
478 \fB\%curs_clear\fP(3X),
479 \fB\%curs_inch\fP(3X),
480 \fB\%curs_outopts\fP(3X),
481 \fB\%curs_refresh\fP(3X),
482 \fB\%curs_variables\fP(3X),