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.94 2024/06/22 21:34:49 tom Exp $
32 .TH curs_addch 3X 2024-06-22 "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
130 Calling \fB\%winch\fP(3X) on the location of a nonprintable character
131 does not return the character itself,
132 but its \fB\%unctrl\fP(3X) representation.
134 The object or expression
136 may contain attributes and/or a color pair identifier.
139 can be copied from place to place using \fB\%winch\fP(3X) and
141 See \fB\%curs_attr\fP(3X) for values of predefined constants that can be
142 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.
192 Symbol Default char Glyph Name
194 ACS_BLOCK # 0 solid square block
195 ACS_BOARD # h board of squares
196 ACS_BTEE + v bottom tee
197 ACS_BULLET o \*~ bullet
198 ACS_CKBOARD : a checker board (stipple)
199 ACS_DARROW v . arrow pointing down
200 ACS_DEGREE \*' f degree symbol
201 ACS_DIAMOND + \(ga diamond
202 ACS_GEQUAL > > greater-than-or-equal-to
203 ACS_HLINE \- q horizontal line
204 ACS_LANTERN # i lantern symbol
205 ACS_LARROW < , arrow pointing left
206 ACS_LEQUAL < y less-than-or-equal-to
207 ACS_LLCORNER + m lower left-hand corner
208 ACS_LRCORNER + j lower right-hand corner
209 ACS_LTEE + t left tee
210 ACS_NEQUAL ! | not-equal
212 ACS_PLMINUS # g plus/minus
214 ACS_RARROW > + arrow pointing right
215 ACS_RTEE + u right tee
216 ACS_S1 \- o scan line 1
217 ACS_S3 \- p scan line 3
218 ACS_S7 \- r scan line 7
219 ACS_S9 \&_ s scan line 9
220 ACS_STERLING f } pound-sterling symbol
222 ACS_UARROW \*^ \- arrow pointing up
223 ACS_ULCORNER + l upper left-hand corner
224 ACS_URCORNER + k upper right-hand corner
225 ACS_VLINE | x vertical line
228 These functions return
245 wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
248 when a write to its bottom right location is attempted,
251 it is not possible to add a complete character at the cursor position.
253 The last may be due to different causes:
255 conversion of a wide character to a multibyte character sequence can
259 at least one of the bytes resulting from wide character conversion to a
260 multibyte character sequence cannot be added to the window.
261 See section \*(``PORTABILITY\*('' below regarding the use of
263 with wide characters.
265 Functions prefixed with \*(``mv\*('' first perform cursor movement and
269 is outside the window boundaries.
276 may be implemented as macros.
279 SVr4 and other versions of
284 but X/Open Curses does not specify it;
285 see \fB\%curs_variables\fP(3X).
287 Applications employing
289 extensions should condition their use on the visibility of the
294 Issue 4 describes these functions.
295 It specifies no error conditions for them.
299 describes a successful return value only as
300 \*(``an integer value other than
303 The defaults specified for forms-drawing characters apply in the POSIX
306 X/Open Curses states that the
311 Some implementations are problematic.
316 defines the ACS symbols as constants;
317 others define them as elements of an array.
319 This implementation uses an array,
323 NetBSD also uses an array,
334 symbols to the analogous
338 symbols were wide characters
339 (see \fB\%curs_add_wch\fP(3X)).
340 The misdefined symbols are the arrows and others that are not used for
345 has a typographical error
348 symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
350 while the header files for SVr4
352 and other implementations use \*(``i\*(''
355 None of the terminal descriptions on Unix platforms use uppercase I,
359 entry for \fI\%screen\fP(1),
360 apparently based on the X/Open documentation around 1995).
364 (AT&T PC6300 with EMOTS Terminal Emulator)
365 description uses lowercase i.
376 were not documented in any publicly released System\ V.
377 .\" And did not exist yet as late as SVr4.
378 .\" https://github.com/ryanwoodsmall/oldsysv/blob/master/\
379 .\" sysvr4/svr4/lib/xlibcurses/screen/curses.ed
381 many publicly available
385 capabilities in which their key characters
388 and a second-hand list of their character descriptions has come to
392 developers invented ACS-prefixed names for them.
403 wide-character versus non-wide-character configurations
404 (the former is capable of displaying Unicode while the latter is not),
407 whether the locale uses UTF-8 encoding.
410 the terminal is unable to display forms-drawing characters
413 see the discussion of the
414 .I \%NCURSES_NO_UTF8_ACS
415 environment variable in \fB\%ncurses\fP(3X).
417 X/Open Curses assumes that the parameter passed to
419 contains a single character.
420 That character may have been more than eight bits wide in an SVr3 or
422 but X/Open Curses leaves the width of a non-wide character code
424 The standard further does not specify the internal structure of a
426 though the use of bit operations to combine the character code with
427 attributes and a color pair identifier into a
432 A portable application uses only the macros discussed in
433 \fB\%curs_attr\fP(3X) to manipulate a
439 holds an eight-bit character,
440 but the library allows a multibyte character sequence to be passed via a
441 succession of calls to
443 Other implementations do not;
446 call transmits exactly one character,
447 which may be rendered in one or more screen locations depending on
448 whether it is printable
449 (see \fB\%unctrl\fP(3X)).
450 Depending on the locale,
452 inspects the byte passed in each
454 call and checks whether the latest call continues a multibyte character.
458 displays the character and advances the cursor.
459 If the calling application interrupts the succession of bytes in
460 a multibyte character sequence by changing the current location\(emfor
462 with \fB\%wmove\fP(3X)\(em\c
464 discards the incomplete character.
466 For portability to other implementations,
467 do not rely upon the foregoing behavior.
468 Check whether a character can be represented as a single byte in the
474 or \fB\%wadd_wch\fP(3X).
478 \fB\%wadd_wch\fP(3X).
489 \fB\%curs_add_wch\fP(3X) describes comparable functions of the
491 library in its wide-character configuration
495 \fB\%curs_addchstr\fP(3X),
496 \fB\%curs_addstr\fP(3X),
497 \fB\%curs_attr\fP(3X),
498 \fB\%curs_clear\fP(3X),
499 \fB\%curs_inch\fP(3X),
500 \fB\%curs_outopts\fP(3X),
501 \fB\%curs_refresh\fP(3X),
502 \fB\%curs_variables\fP(3X),