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.81 2024/03/23 20:38:57 tom Exp $
32 .TH curs_addch 3X 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
61 add a \fIcurses\fR 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);
75 .SS "Adding Characters"
79 at the cursor position of window
81 then advances the cursor position,
82 analogously to the standard C library's \fI\%putchar\fP(3).
83 \fB\%ncurses\fP(3X) describes the variants of this function.
85 If advancement occurs at the right margin,
87 the cursor automatically wraps to the beginning of the next line;
90 at the bottom of the current scrolling region,
91 and if \fB\%scrollok\fP(3X) is enabled for
93 the scrolling region scrolls up one line.
103 the cursor moves appropriately within the window.
105 Backspace moves the cursor one character left;
106 at the left margin of a window,
109 Carriage return moves the cursor to the left margin on the current line
112 Line feed does a \fB\%clrtoeol\fP(3X),
113 then moves the cursor to the left margin on the next line of the window,
114 scrolling the window if the cursor was already on the last line.
116 Tab advances the cursor to the next tab stop
117 (possibly on the next line);
118 these are placed at every eighth column by default.
119 Alter the tab interval with the
122 see \fB\%curs_variables\fP(3X).
126 is any other nonprintable character,
127 it is drawn in printable form,
128 using the same convention as \fB\%unctrl\fP(3X).
131 displays control characters in
135 Character codes above 127 are either meta characters
136 (if the screen has not been initialized,
137 or if \fB\%meta\fP(3X) has been called with a
144 or they display as themselves.
146 the values may not be printable;
147 .\" XXX: The following claim could be clearer.
148 this follows the X/Open specification.
150 Calling \fB\%winch\fP(3X) on the location of a nonprintable character
151 does not return the character itself,
152 but its \fB\%unctrl\fP(3X) representation.
154 Video attributes can be combined with a character argument passed to
156 by logical-ORing them into the character.
159 including attributes,
160 can be copied from one place to another using \fB\%winch\fP(3X) and
162 See \fB\%curs_attr\fP(3X) for values of predefined video attribute
163 constants that can be usefully OR'ed with characters.
164 .SS "Echoing Characters"
168 are equivalent to calling
171 .RB \%( w ) refresh .
173 interprets these functions as a hint that only a single character is
175 for non-control characters,
176 a considerable performance gain may be enjoyed by employing them.
177 .\" TODO: Combine the following with the "Line Drawing" subsection of
178 .\" terminfo(5) and replace this with a cross reference there.
179 .SS "Forms-Drawing Characters"
181 defines macros starting with
183 that can be used with
185 to write line-drawing and other special characters to the screen.
188 .I "forms-drawing characters."
189 The ACS default listed below is used if the
193 capability does not define a terminal-specific replacement for it,
194 or if the terminal and locale configuration requires Unicode to access
195 these characters but the library is unable to use Unicode.
196 The \*(``acsc char\*('' column corresponds to how the characters are
200 and the characters in it may appear on the screen if the terminal's
201 database entry incorrectly advertises ACS support.
202 The name \*(``ACS\*('' originates in the Alternate Character Set feature
203 of the DEC VT100 terminal.
210 Symbol Default char Glyph Name
212 ACS_BLOCK # 0 solid square block
213 ACS_BOARD # h board of squares
214 ACS_BTEE + v bottom tee
215 ACS_BULLET o \*~ bullet
216 ACS_CKBOARD : a checker board (stipple)
217 ACS_DARROW v . arrow pointing down
218 ACS_DEGREE \*' f degree symbol
219 ACS_DIAMOND + \(ga diamond
220 ACS_GEQUAL > > greater-than-or-equal-to
221 ACS_HLINE \- q horizontal line
222 ACS_LANTERN # i lantern symbol
223 ACS_LARROW < , arrow pointing left
224 ACS_LEQUAL < y less-than-or-equal-to
225 ACS_LLCORNER + m lower left-hand corner
226 ACS_LRCORNER + j lower right-hand corner
227 ACS_LTEE + t left tee
228 ACS_NEQUAL ! | not-equal
230 ACS_PLMINUS # g plus/minus
232 ACS_RARROW > + arrow pointing right
233 ACS_RTEE + u right tee
234 ACS_S1 \- o scan line 1
235 ACS_S3 \- p scan line 3
236 ACS_S7 \- r scan line 7
237 ACS_S9 \&_ s scan line 9
238 ACS_STERLING f } pound-sterling symbol
240 ACS_UARROW \*^ \- arrow pointing up
241 ACS_ULCORNER + l upper left-hand corner
242 ACS_URCORNER + k upper right-hand corner
243 ACS_VLINE | x vertical line
246 These functions return
257 if it is not possible to add a complete character at the cursor
259 as when conversion of a multibyte character to a byte sequence fails,
260 or at least one of the resulting bytes cannot be added to the window.
261 See section \*(``PORTABILITY\*('' below regarding the use of
263 with multibyte characters.
265 If \fB\%scrollok\fP(3X) is not enabled,
267 can successfully write a character at the bottom right location of the
273 because it is not possible to wrap to a new line.
275 Functions with a \*(``mv\*('' prefix first perform cursor movement using
276 \fB\%wmove\fP(3X) and fail if the position is outside the window,
278 (for \*(``mvw\*('' functions)
288 may be implemented as macros.
291 Issue 4 describes these functions.
292 It specifies no error conditions for them.
293 The defaults specified for forms-drawing characters apply in the POSIX
296 X/Open Curses states that the
302 Some implementations are problematic.
307 define the ACS symbols as constants;
308 others define them as elements of an array.
310 This implementation uses an array,
314 NetBSD also uses an array,
325 symbols to the analogous
329 symbols were wide characters
330 (see \fB\%curs_add_wch\fP(3X)).
331 The misdefined symbols are the arrows and others that are not used for
336 has a typographical error
339 symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
341 while the header files for SVr4
343 and other implementations use \*(``i\*(''
346 None of the terminal descriptions on Unix platforms use uppercase I,
350 entry for \fI\%screen\fP(1),
351 apparently based on the X/Open documentation around 1995).
355 (AT&T PC6300 with EMOTS Terminal Emulator)
356 description uses lowercase i.
367 were not documented in any publicly released System\ V.
369 many publicly available
373 strings in which their key characters (pryz{|}) are embedded,
374 and a second-hand list of their character descriptions has come to
378 developers invented ACS-prefixed names for them.
389 wide-character versus non-wide-character configurations
390 (the former is capable of displaying Unicode while the latter is not),
393 whether the locale uses UTF-8 encoding.
396 the terminal is unable to display forms-drawing characters
399 see the discussion of the
400 .I \%NCURSES_NO_UTF8_ACS
401 environment variable in \fB\%ncurses\fP(3X)).
403 X/Open Curses assumes that the parameter passed to
405 contains a single character.
406 As discussed in \fB\%curs_attr\fP(3X),
407 that character may have been more than eight bits wide in an SVr3 or
409 but in the X/Open Curses model,
410 the details are not given.
411 The important distinction between SVr4
413 and X/Open Curses is that the latter separates non-character information
414 (attributes and color)
415 from the character code,
416 which SVr4 packs into a
424 holds an eight-bit character.
427 allows a multibyte character to be passed in a succession of calls to
429 Other implementations do not;
432 call transmits exactly one character,
433 which may be rendered in one or more screen locations depending on
434 whether it is printable.
436 Depending on the locale settings,
438 inspects the byte passed in each
441 and checks whether the latest call continues a multibyte sequence.
445 displays the character and advances the window's current location.
447 If the calling application interrupts the succession of bytes in
448 a multibyte character sequence by moving the current location
450 with \fB\%wmove\fP(3X)),
452 discards the incomplete character.
454 For portability to other implementations,
455 do not rely upon this behavior.
456 Check whether a character can be represented as a single byte in the
462 or \fB\%wadd_wch\fP(3X).
466 \fB\%wadd_wch\fP(3X).
468 SVr4 and other versions of
473 but X/Open Curses does not specify it
474 (see \fB\%curs_variables\fP(3X)).
477 \fB\%curs_addchstr\fP(3X),
478 \fB\%curs_addstr\fP(3X),
479 \fB\%curs_attr\fP(3X),
480 \fB\%curs_clear\fP(3X),
481 \fB\%curs_inch\fP(3X),
482 \fB\%curs_outopts\fP(3X),
483 \fB\%curs_refresh\fP(3X),
484 \fB\%curs_variables\fP(3X),
487 \fB\%curs_add_wch\fP(3X) describes comparable functions of the
489 library in its wide-character configuration