2 .\"***************************************************************************
3 .\" Copyright 2019-2023,2024 Thomas E. Dickey *
4 .\" Copyright 2001-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_add_wch.3x,v 1.63 2024/05/11 21:31:45 tom Exp $
32 .TH curs_add_wch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
54 \fB\%wecho_wchar\fP \-
55 add a \fIcurses\fR complex character to a window, possibly advancing the cursor
58 \fB#include <curses.h>
60 \fBint add_wch(const cchar_t *\fIwch\fP);
61 \fBint wadd_wch(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
62 \fBint mvadd_wch(int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP);
63 \fBint mvwadd_wch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP);
65 \fBint echo_wchar(const cchar_t *\fIwch\fP);
66 \fBint wecho_wchar(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
71 writes the complex character
75 then may advance the cursor position,
76 analogously to the standard C library's \fI\%putwchar\fP(3).
77 \fB\%ncurses\fP(3X) describes the variants of this function.
79 Much behavior depends on whether the wide characters in
81 are spacing or non-spacing;
82 see subsection \*(``Complex Characters\*('' below.
86 contains a spacing character,
87 then any character at the cursor is first removed.
90 with its attributes and color pair identifier,
94 .IR "active complex character" "."
98 contains only non-spacing characters,
99 .\" XXX: see wadd_wch_literal (the beginning of the array may be nonspacing)
100 they are combined with the active complex character.
102 ignores its attributes and color pair identifier,
103 and does not advance the cursor.
105 Further non-spacing characters added with
107 are not written at the new cursor position but combine with the active
108 complex character until another spacing character is written to the
109 window or the cursor is moved.
111 If advancement occurs at the right margin,
113 the cursor automatically wraps to the beginning of the next line,
116 if it was at the bottom of the scrolling region,
117 and if \fB\%scrollok\fP(3X) is enabled for
119 the scrolling region scrolls up one line.
129 the cursor moves appropriately within the window.
131 Backspace moves the cursor one character left;
132 at the left margin of a window,
135 Carriage return moves the cursor to the left margin on the current line
138 Line feed does a \fB\%clrtoeol\fP(3X),
139 then advances as if from the right margin.
141 Tab advances the cursor to the next tab stop
142 (possibly on the next line);
143 these are placed at every eighth column by default.
144 Alter the tab interval with the
147 see \fB\%curs_variables\fP(3X).
151 is any other nonprintable character,
152 it is drawn in printable form using the same convention as
155 Calling \fB\%win_wch\fP(3X) on the location of a nonprintable character
156 does not return the character itself,
157 but its \fB\%wunctrl\fP(3X) representation.
162 are equivalent to calling
165 .RB \%( w ) refresh .
167 interprets these functions as a hint that only a single (complex)
168 character is being output;
169 for non-control characters,
170 a considerable performance gain may be enjoyed by employing them.
171 .\" TODO: Combine the following with the "Line Drawing" subsection of
172 .\" terminfo(5) and replace this with a cross reference there.
173 .SS "Forms-Drawing Characters"
175 defines macros starting with
177 that can be used with
179 to write line-drawing and other special characters to the screen.
182 .I "forms-drawing characters."
183 The ACS default listed below is used if the
187 capability does not define a terminal-specific replacement for it,
188 or if the terminal and locale configuration requires Unicode to access
189 these characters but the library is unable to use Unicode.
190 The \*(``acsc char\*('' column corresponds to how the characters are
195 and the characters in it may appear on the screen if the terminal type's
196 database entry incorrectly advertises ACS support.
197 The name \*(``ACS\*('' originates in the Alternate Character Set feature
198 of the DEC VT100 terminal.
204 \& Unicode ACS acsc \&
205 Symbol Default Default char Glyph Name
207 WACS_BLOCK 0x25ae # 0 T{
210 WACS_BOARD 0x2592 # h board of squares
211 WACS_BTEE 0x2534 + v bottom tee
212 WACS_BULLET 0x00b7 o ~ bullet
213 WACS_CKBOARD 0x2592 : a T{
214 checker board (stipple)
216 WACS_DARROW 0x2193 v . T{
219 WACS_DEGREE 0x00b0 ' f degree symbol
220 WACS_DIAMOND 0x25c6 + \(ga diamond
221 WACS_GEQUAL 0x2265 > > T{
222 greater-than-or-equal-to
224 WACS_HLINE 0x2500 \- q horizontal line
225 WACS_LANTERN 0x2603 # i lantern symbol
226 WACS_LARROW 0x2190 < , T{
229 WACS_LEQUAL 0x2264 < y T{
230 less-than-or-equal-to
232 WACS_LLCORNER 0x2514 + m T{
233 lower left-hand corner
235 WACS_LRCORNER 0x2518 + j T{
236 lower right-hand corner
238 WACS_LTEE 0x2524 + t left tee
239 WACS_NEQUAL 0x2260 ! | not-equal
240 WACS_PI 0x03c0 * { greek pi
241 WACS_PLMINUS 0x00b1 # g plus/minus
242 WACS_PLUS 0x253c + n plus
243 WACS_RARROW 0x2192 > + T{
246 WACS_RTEE 0x251c + u right tee
247 WACS_S1 0x23ba \- o scan line 1
248 WACS_S3 0x23bb \- p scan line 3
249 WACS_S7 0x23bc \- r scan line 7
250 WACS_S9 0x23bd \&_ s scan line 9
251 WACS_STERLING 0x00a3 f } T{
252 pound-sterling symbol
254 WACS_TTEE 0x252c + w top tee
255 WACS_UARROW 0x2191 ^ \- T{
258 WACS_ULCORNER 0x250c + l T{
259 upper left-hand corner
261 WACS_URCORNER 0x2510 + k T{
262 upper right-hand corner
264 WACS_VLINE 0x2502 | x vertical line
267 The wide-character configuration of \fI\%ncurses\fP also defines symbols
268 for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''):
274 \& Unicode ASCII acsc \&
275 ACS Name Default Default Char Glyph Name
277 WACS_T_BTEE 0x253b + V T{
278 thick tee pointing up
280 WACS_T_HLINE 0x2501 - Q T{
281 thick horizontal line
283 WACS_T_LLCORNER 0x2517 + M T{
284 thick lower left corner
286 WACS_T_LRCORNER 0x251b + J T{
287 thick lower right corner
289 WACS_T_LTEE 0x252b + T T{
290 thick tee pointing right
292 WACS_T_PLUS 0x254b + N T{
295 WACS_T_RTEE 0x2523 + U T{
296 thick tee pointing left
298 WACS_T_TTEE 0x2533 + W T{
299 thick tee pointing down
301 WACS_T_ULCORNER 0x250f + L T{
302 thick upper left corner
304 WACS_T_URCORNER 0x2513 + K T{
305 thick upper right corner
307 WACS_T_VLINE 0x2503 | X T{
312 and for double-lines (\fBacsc\fP \*(``A\*('' to \*(``I\*(''):
318 \& Unicode ASCII acsc \&
319 ACS Name Default Default Char Glyph Name
321 WACS_D_BTEE 0x2569 + H T{
322 double tee pointing up
324 WACS_D_HLINE 0x2550 - R T{
325 double horizontal line
327 WACS_D_LLCORNER 0x255a + D T{
328 double lower left corner
330 WACS_D_LRCORNER 0x255d + A T{
331 double lower right corner
333 WACS_D_LTEE 0x2560 + F T{
334 double tee pointing right
336 WACS_D_PLUS 0x256c + E T{
339 WACS_D_RTEE 0x2563 + G T{
340 double tee pointing left
342 WACS_D_TTEE 0x2566 + I T{
343 double tee pointing down
345 WACS_D_ULCORNER 0x2554 + C T{
346 double upper left corner
348 WACS_D_URCORNER 0x2557 + B T{
349 double upper right corner
351 WACS_D_VLINE 0x2551 | Y T{
356 Unicode's descriptions for these characters differs slightly from
358 by introducing the term \*(``light\*('' (along with less important details).
359 Here are its descriptions for the normal, thick, and double horizontal lines:
361 U+2500 BOX DRAWINGS LIGHT HORIZONTAL
363 U+2501 BOX DRAWINGS HEAVY HORIZONTAL
365 U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
367 These functions return
383 wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
386 when writing to its bottom right location is attempted,
389 it is not possible to add a complete character at the cursor position.
391 Functions prefixed with \*(``mv\*('' first perform cursor movement and
395 is outside the window boundaries.
402 may be implemented as macros.
407 variable is implemented in SVr4 and other versions of
409 but is not specified by X/Open Curses
410 (see \fBcurs_variables\fP(3X)).
412 These functions are described in X/Open Curses, Issue 4.
413 It specifies no error conditions for them.
417 describes a successful return value only as
418 \*(``an integer value other than
421 The defaults specified for forms-drawing characters apply in the POSIX
423 X/Open Curses makes it clear that the WACS_ symbols should be defined as
424 a pointer to \fBcchar_t\fP data, e.g., in the discussion of \fBborder_set\fP.
425 A few implementations are problematic:
427 NetBSD curses defines the symbols as a \fBwchar_t\fP within a \fBcchar_t\fP.
429 HP-UX curses equates some of the \fBACS_\fP symbols
430 to the analogous \fBWACS_\fP symbols as if the \fBACS_\fP symbols were
432 The misdefined symbols are the arrows
433 and other symbols which are not used for line-drawing.
435 X/Open Curses does not specify symbols for thick- or double-lines.
436 SVr4 curses implementations defined their line-drawing symbols in
437 terms of intermediate symbols.
438 This implementation extends those symbols, providing new definitions
439 which are not in the SVr4 implementations.
441 Not all Unicode-capable terminals provide support for VT100-style
442 alternate character sets (i.e., the \fBacsc\fP capability),
443 with their corresponding line-drawing characters.
444 X/Open Curses did not address the aspect of integrating Unicode with
445 line-drawing characters.
446 Existing implementations of Unix curses (AIX, HP-UX, Solaris)
447 use only the \fBacsc\fP character-mapping to provide this feature.
448 As a result, those implementations can only use single-byte line-drawing
450 \fI\%ncurses\fP 5.3 (2002) provided a table of Unicode values to solve
452 NetBSD curses incorporated that table in 2010.
454 In this implementation, the Unicode values are used instead of the
455 terminal description's \fBacsc\fP mapping as discussed in
456 \fB\%ncurses\fP(3X) for the environment variable
457 \fINCURSES_NO_UTF8_ACS\fP.
458 In contrast, for the same cases, the line-drawing characters
459 described in \fB\%addch\fP(3X) will use only the ASCII default values.
461 Having Unicode available does not solve all of the problems with
462 line-drawing for curses:
464 The closest Unicode equivalents to the
465 VT100 graphics \fIS1\fP, \fIS3\fP, \fIS7\fP and \fIS9\fP
466 frequently are not displayed at
467 the regular intervals which the terminal used.
469 The \fIlantern\fP is a special case.
470 It originated with the AT&T 4410 terminal in the early 1980s.
471 There is no accessible documentation depicting the lantern symbol
472 on the AT&T terminal.
474 Lacking documentation, most readers assume that a \fIstorm lantern\fP
476 But there are several possibilities, all with problems.
478 Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and U+1F3EE.
479 Those were not available in 2002, and are irrelevant since
480 they lie outside the BMP and as a result are not generally available
482 They are not storm lanterns, in any case.
484 Most \fIstorm lanterns\fP have a tapering glass chimney
485 (to guard against tipping);
486 some have a wire grid protecting the chimney.
488 For the tapering appearance, \[u2603] U+2603 was adequate.
489 In use on a terminal, no one can tell what the image represents.
490 Unicode calls it a snowman.
492 Others have suggested these alternatives:
493 \[sc] U+00A7 (section mark),
494 \[u0398] U+0398 (theta),
495 \[u03A6] U+03A6 (phi),
496 \[u03B4] U+03B4 (delta),
497 \[u2327] U+2327 (x in a rectangle),
498 \[u256C] U+256C (forms double vertical and horizontal), and
499 \[u2612] U+2612 (ballot box with x).
500 .SS "Complex Characters"
501 The complex character type
503 can store more than one wide character
505 X/Open Curses does not mention this possibility,
506 specifying behavior only where
508 is a single character,
509 either spacing or non-spacing.
514 is constructed using \fB\%setcchar\fP(3X),
515 and in turn that the result
517 contains at most one spacing character at the beginning of its list of
519 and zero or more non-spacing characters,
522 holds one non-spacing character.
526 adds the non-spacing character to the active complex character.
528 \fB\%curs_addch\fP(3X) describes comparable functions of the
530 library in its non-wide-character configuration.
533 \fB\%curs_addwstr\fP(3X),
534 \fB\%curs_add_wchstr\fP(3X),
535 \fB\%curs_attr\fP(3X),
536 \fB\%curs_clear\fP(3X),
537 \fB\%curs_getcchar\fP(3X),
538 \fB\%curs_outopts\fP(3X),
539 \fB\%curs_refresh\fP(3X),
540 \fB\%curs_variables\fP(3X),