Debian Codegraph @

upstream/debian-unstable/man3/add_wch.3ncurses

raw
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright 2019-2024,2025 Thomas E. Dickey *
4 .\" Copyright 2001-2015,2017 Free Software Foundation, Inc. *
5 .\" *
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: *
13 .\" *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
16 .\" *
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. *
24 .\" *
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 *
28 .\" authorization. *
29 .\"***************************************************************************
30 .\"
31 .\" $Id: curs_add_wch.3x,v 1.125 2025/11/12 01:06:36 tom Exp $
32 .TH add_wch 3NCURSES 2025-11-11 "ncurses 6.6" "Library calls"
33 .ie \n(.g \{\
34 .ds `` \(lq
35 .ds '' \(rq
36 .\}
37 .el \{\
38 .ie t .ds `` ``
39 .el .ds `` ""
40 .ie t .ds '' ''
41 .el .ds '' ""
42 .\}
43 .
44 .de bP
45 .ie n .IP \(bu 4
46 .el .IP \(bu 2
47 ..
48 .SH NAME
49 \fB\%add_wch\fP,
50 \fB\%wadd_wch\fP,
51 \fB\%mvadd_wch\fP,
52 \fB\%mvwadd_wch\fP,
53 \fB\%echo_wchar\fP,
54 \fB\%wecho_wchar\fP \-
55 add a \fIcurses\fR complex character to a window, possibly advancing the cursor
56 .SH SYNOPSIS
57 .nf
58 \fB#include <curses.h>
59 .PP
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);
64 .PP
65 \fBint echo_wchar(const cchar_t * \fIwch\fP);
66 \fBint wecho_wchar(WINDOW * \fIwin\fP, const cchar_t *\fIwch\fP);
67 .PP
68 \fI/* (integer) constants */\fP
69 /*\fI .\|.\|. */ \fBWACS_BLOCK;\fR
70 /*\fI .\|.\|. */ \fBWACS_BOARD;\fR
71 /*\fI .\|.\|. */ \fBWACS_BTEE;\fR
72 /*\fI .\|.\|. */ \fBWACS_BULLET;\fR
73 /*\fI .\|.\|. */ \fBWACS_CKBOARD;\fR
74 /*\fI .\|.\|. */ \fBWACS_DARROW;\fR
75 /*\fI .\|.\|. */ \fBWACS_DEGREE;\fR
76 /*\fI .\|.\|. */ \fBWACS_DIAMOND;\fR
77 /*\fI .\|.\|. */ \fBWACS_HLINE;\fR
78 /*\fI .\|.\|. */ \fBWACS_LANTERN;\fR
79 /*\fI .\|.\|. */ \fBWACS_LARROW;\fR
80 /*\fI .\|.\|. */ \fBWACS_LLCORNER;\fR
81 /*\fI .\|.\|. */ \fBWACS_LRCORNER;\fR
82 /*\fI .\|.\|. */ \fBWACS_LTEE;\fR
83 /*\fI .\|.\|. */ \fBWACS_PLMINUS;\fR
84 /*\fI .\|.\|. */ \fBWACS_PLUS;\fR
85 /*\fI .\|.\|. */ \fBWACS_RARROW;\fR
86 /*\fI .\|.\|. */ \fBWACS_RTEE;\fR
87 /*\fI .\|.\|. */ \fBWACS_S1;\fR
88 /*\fI .\|.\|. */ \fBWACS_S9;\fR
89 /*\fI .\|.\|. */ \fBWACS_TTEE;\fR
90 /*\fI .\|.\|. */ \fBWACS_UARROW;\fR
91 /*\fI .\|.\|. */ \fBWACS_ULCORNER;\fR
92 /*\fI .\|.\|. */ \fBWACS_URCORNER;\fR
93 /*\fI .\|.\|. */ \fBWACS_VLINE;\fR
94 \fI/* extensions */\fP
95 /*\fI .\|.\|. */ \fBWACS_GEQUAL;\fR
96 /*\fI .\|.\|. */ \fBWACS_LEQUAL;\fR
97 /*\fI .\|.\|. */ \fBWACS_NEQUAL;\fR
98 /*\fI .\|.\|. */ \fBWACS_PI;\fR
99 /*\fI .\|.\|. */ \fBWACS_S3;\fR
100 /*\fI .\|.\|. */ \fBWACS_S7;\fR
101 /*\fI .\|.\|. */ \fBWACS_STERLING;\fR
102 \fI/* extensions for thick lines */\fP
103 /*\fI .\|.\|. */ \fBWACS_T_BTEE;\fR
104 /*\fI .\|.\|. */ \fBWACS_T_HLINE;\fR
105 /*\fI .\|.\|. */ \fBWACS_T_LLCORNER;\fR
106 /*\fI .\|.\|. */ \fBWACS_T_LRCORNER;\fR
107 /*\fI .\|.\|. */ \fBWACS_T_LTEE;\fR
108 /*\fI .\|.\|. */ \fBWACS_T_PLUS;\fR
109 /*\fI .\|.\|. */ \fBWACS_T_RTEE;\fR
110 /*\fI .\|.\|. */ \fBWACS_T_TTEE;\fR
111 /*\fI .\|.\|. */ \fBWACS_T_ULCORNER;\fR
112 /*\fI .\|.\|. */ \fBWACS_T_URCORNER;\fR
113 /*\fI .\|.\|. */ \fBWACS_T_VLINE;\fR
114 \fI/* extensions for double lines */\fP
115 /*\fI .\|.\|. */ \fBWACS_D_BTEE;\fR
116 /*\fI .\|.\|. */ \fBWACS_D_HLINE;\fR
117 /*\fI .\|.\|. */ \fBWACS_D_LLCORNER;\fR
118 /*\fI .\|.\|. */ \fBWACS_D_LRCORNER;\fR
119 /*\fI .\|.\|. */ \fBWACS_D_LTEE;\fR
120 /*\fI .\|.\|. */ \fBWACS_D_PLUS;\fR
121 /*\fI .\|.\|. */ \fBWACS_D_RTEE;\fR
122 /*\fI .\|.\|. */ \fBWACS_D_TTEE;\fR
123 /*\fI .\|.\|. */ \fBWACS_D_ULCORNER;\fR
124 /*\fI .\|.\|. */ \fBWACS_D_URCORNER;\fR
125 /*\fI .\|.\|. */ \fBWACS_D_VLINE;\fR
126 .fi
127 .SH DESCRIPTION
128 .SS wadd_wch
129 .B \%wadd_wch
130 writes the
131 .I curses
132 complex character
133 .I wch
134 to the window
135 .IR win ","
136 then may advance the cursor position,
137 analogously to the standard C library's \fI\%putwchar\fP(3).
138 \fB\%ncurses\fP(3NCURSES) describes the variants of this function.
139 .PP
140 Construct a
141 .I curses
142 complex character
143 from a
144 .I wchar_t
145 with \fB\%setcchar\fP(3NCURSES).
146 A
147 .I \%cchar_t
148 can be copied from place to place using \fB\%win_wch\fP(3NCURSES) and
149 .BR \%wadd_wch "."
150 .I curses
151 defines constants to aid the manipulation of character attributes;
152 see \fB\%attr\fP(3NCURSES).
153 A complex character whose only character component is a wide space,
154 and whose only attribute is
155 .BR \%WA_NORMAL ,
156 is a
157 .IR "blank character" ","
158 and therefore combines with the window's background character;
159 see \fB\%bkgrnd\fP(3NCURSES).
160 .PP
161 Much behavior depends on whether the wide characters in
162 .I wch
163 are spacing or non-spacing;
164 see subsection \*(``Complex Characters\*('' below.
165 .bP
166 If
167 .I wch
168 contains a spacing character,
169 then any character at the cursor is first removed.
170 The complex character
171 .IR wch ","
172 with its attributes and color pair identifier,
173 becomes the
174 .I base
175 of the
176 .IR "active complex character" "."
177 .bP
178 If
179 .I wch
180 contains only non-spacing characters,
181 .\" XXX: see wadd_wch_literal (the beginning of the array may be
182 .\" nonspacing)
183 they are combined with the active complex character.
184 .I curses
185 ignores its attributes and color pair identifier,
186 and does not advance the cursor.
187 .PP
188 Further non-spacing characters added with
189 .B \%wadd_wch
190 are not written at the new cursor position but combine with the active
191 complex character until another spacing character is written to the
192 window or the cursor is moved.
193 .PP
194 If
195 .I wch
196 is a
197 backspace,
198 carriage return,
199 line feed,
200 or
201 tab,
202 the cursor moves appropriately within the window.
203 .bP
204 Backspace moves the cursor one character left;
205 at the left margin of a window,
206 it does nothing.
207 .bP
208 Carriage return moves the cursor to the left margin on the same line of
209 the window.
210 .bP
211 Line feed does a \fB\%clrtoeol\fP(3NCURSES),
212 then advances as if from the right margin.
213 .bP
214 Tab advances the cursor to the next tab stop
215 (possibly on the next line);
216 these are placed at every eighth column by default.
217 .IP
218 Alter the tab interval with the
219 .B \%TABSIZE
220 extension;
221 see \fB\%curses_variables\fP(3NCURSES).
222 .PP
223 If
224 .I wch
225 is any other nonprintable character,
226 .I curses
227 draws it in printable form using the same convention as
228 \fB\%wunctrl\fP(3NCURSES).
229 Calling \fB\%win_wch\fP(3NCURSES) on the location of a nonprintable character
230 does not retrieve the character itself,
231 but its \fB\%wunctrl\fP(3NCURSES) representation.
232 .PP
233 Adding spacing characters with \fB\%wadd_wch\fP
234 causes it to wrap at the right margin of the window:
235 .bP
236 If the cursor is not at the bottom of the scrolling region
237 and advancement occurs at the right margin,
238 the cursor automatically wraps to the beginning of the next line.
239 .bP
240 If the cursor is at the bottom of the scrolling region
241 when advancement occurs at the right margin,
242 and \fB\%scrollok\fP(3NCURSES) is enabled for
243 .IR win ,
244 the scrolling region scrolls up one line
245 and the cursor wraps as above.
246 Otherwise,
247 advancement and scrolling do not occur,
248 and
249 .B \%wadd_wch
250 returns
251 .BR ERR "."
252 .PP
253 A window's margins may coincide with the screen boundaries.
254 This may be a problem when
255 .I \%ncurses
256 updates the screen to match the curses window.
257 When their right and bottom margins coincide,
258 .I \%ncurses
259 uses different strategies to handle the variations of scrolling and wrapping
260 at the lower-right corner
261 by depending on the terminal capabilities:
262 .bP
263 If the terminal does not automatically wrap as characters
264 are added at the right margin
265 (i.e., auto right margins),
266 .I \%ncurses
267 writes the character directly.
268 .bP
269 If the terminal has auto right margins,
270 but also has capabilities for turning auto margins off and on,
271 .I \%ncurses
272 turns the auto margin feature off temporarily
273 when writing to the lower-right corner.
274 .bP
275 If the terminal has an insertion mode which can be turned off and on,
276 .I \%ncurses
277 writes the character just before the lower-right corner,
278 and then inserts a character to push the update into the corner.
279 .SS wecho_wchar
280 .B \%echo_wchar
281 and
282 .B \%wecho_wchar
283 are equivalent to calling
284 .RB \%( w ) add_wch
285 followed by
286 .RB \%( w ) refresh
287 on
288 .B \%stdscr
289 or the specified window.
290 .I curses
291 interprets these functions as a hint that only a single (complex)
292 character is being output;
293 for non-control characters,
294 a considerable performance gain may be enjoyed by employing them.
295 .\" TODO: Combine the following with the "Line Drawing" subsection of
296 .\" terminfo(5) and replace this with a cross reference there.
297 .SS "Forms-Drawing Characters"
298 .I curses
299 defines macros starting with
300 .B \%WACS_
301 that can be used with
302 .B \%wadd_wch
303 to write line-drawing and other symbols to the screen.
304 .I \%ncurses
305 terms these
306 .I "forms-drawing characters."
307 .I curses
308 uses the ACS default listed below if the terminal type lacks the
309 .B \%acs_chars
310 .RB \%( acsc )
311 capability;
312 that capability does not define a replacement for the character;
313 or if the terminal type and locale configuration
314 require Unicode to access these characters,
315 but the library is unable to use Unicode.
316 The \*(``acsc char\*('' column corresponds to how the characters are
317 specified in the
318 .B \%acs_chars
319 .RB \%( acsc )
320 string capability,
321 and the characters in it may appear on the screen if the terminal type's
322 database entry incorrectly advertises ACS support.
323 The name \*(``ACS\*('' originates in the Alternate Character Set feature
324 of the DEC VT100 terminal.
325 .PP
326 .ie t .ne 4v
327 .el .ne 5v
328 .TS
329 Lb Lb Lb Lb Lb
330 Lb Lb Lb Lb Lb
331 Lb L L L Lw(15n)x.
332 \& Unicode ACS acsc \&
333 Symbol Default Default char Glyph Name
334 _
335 WACS_BLOCK U+25ae # 0 T{
336 solid square block
337 T}
338 WACS_BOARD U+2592 # h board of squares
339 WACS_BTEE U+2534 + v bottom tee
340 WACS_BULLET U+00b7 o ~ bullet
341 WACS_CKBOARD U+2592 : a T{
342 checker board (stipple)
343 T}
344 WACS_DARROW U+2193 v . T{
345 arrow pointing down
346 T}
347 WACS_DEGREE U+00b0 ' f degree symbol
348 WACS_DIAMOND U+25c6 + \(ga diamond
349 WACS_GEQUAL U+2265 > > T{
350 .if n .na \" avoid adjustment warning from groff
351 greater-than-or-equal-to
352 T}
353 WACS_HLINE U+2500 \- q horizontal line
354 WACS_LANTERN U+2603 # i lantern symbol
355 WACS_LARROW U+2190 < , T{
356 arrow pointing left
357 T}
358 WACS_LEQUAL U+2264 < y T{
359 .if n .na \" avoid adjustment warning from groff
360 less-than-or-equal-to
361 T}
362 WACS_LLCORNER U+2514 + m T{
363 lower left-hand corner
364 T}
365 WACS_LRCORNER U+2518 + j T{
366 lower right-hand corner
367 T}
368 WACS_LTEE U+2524 + t left tee
369 WACS_NEQUAL U+2260 ! | not-equal
370 WACS_PI U+03c0 * { greek pi
371 WACS_PLMINUS U+00b1 # g plus/minus
372 WACS_PLUS U+253c + n plus
373 WACS_RARROW U+2192 > + T{
374 arrow pointing right
375 T}
376 WACS_RTEE U+251c + u right tee
377 WACS_S1 U+23ba \- o scan line 1
378 WACS_S3 U+23bb \- p scan line 3
379 WACS_S7 U+23bc \- r scan line 7
380 WACS_S9 U+23bd \&_ s scan line 9
381 WACS_STERLING U+00a3 f } T{
382 .if n .na \" avoid adjustment warning from groff
383 pound-sterling symbol
384 T}
385 WACS_TTEE U+252c + w top tee
386 WACS_UARROW U+2191 ^ \- T{
387 arrow pointing up
388 T}
389 WACS_ULCORNER U+250c + l T{
390 upper left-hand corner
391 T}
392 WACS_URCORNER U+2510 + k T{
393 upper right-hand corner
394 T}
395 WACS_VLINE U+2502 | x vertical line
396 .TE
397 .PP
398 The
399 .I \%ncurses
400 wide API also defines symbols for thick lines
401 .RB \%( acsc
402 \*(``J\*('' through \*(``N\*('',
403 \*(``T\*('' through \*(``X\*('',
404 and \*(``Q\*(''):
405 .PP
406 .TS
407 Lb Lb Lb Lb Lb
408 Lb Lb Lb Lb Lb
409 Lb L L L Lw(14n)x.
410 \& Unicode ASCII acsc \&
411 ACS Name Default Default Char Glyph Name
412 _
413 WACS_T_BTEE U+253b + V T{
414 thick tee pointing up
415 T}
416 WACS_T_HLINE U+2501 - Q T{
417 thick horizontal line
418 T}
419 WACS_T_LLCORNER U+2517 + M T{
420 thick lower left corner
421 T}
422 WACS_T_LRCORNER U+251b + J T{
423 thick lower right corner
424 T}
425 WACS_T_LTEE U+252b + T T{
426 thick tee pointing right
427 T}
428 WACS_T_PLUS U+254b + N T{
429 thick large plus
430 T}
431 WACS_T_RTEE U+2523 + U T{
432 thick tee pointing left
433 T}
434 WACS_T_TTEE U+2533 + W T{
435 thick tee pointing down
436 T}
437 WACS_T_ULCORNER U+250f + L T{
438 thick upper left corner
439 T}
440 WACS_T_URCORNER U+2513 + K T{
441 thick upper right corner
442 T}
443 WACS_T_VLINE U+2503 | X T{
444 thick vertical line
445 T}
446 .TE
447 .PP
448 and for double lines
449 .RB \%( acsc
450 \*(``A\*('' through \*(``I\*('',
451 plus \*(``R\*('' and \*(``Y\*(''):
452 .PP
453 .TS
454 Lb Lb Lb Lb Lb
455 Lb Lb Lb Lb Lb
456 Lb L L L Lw(14n)x.
457 \& Unicode ASCII acsc \&
458 ACS Name Default Default Char Glyph Name
459 _
460 WACS_D_BTEE U+2569 + H T{
461 double tee pointing up
462 T}
463 WACS_D_HLINE U+2550 - R T{
464 double horizontal line
465 T}
466 WACS_D_LLCORNER U+255a + D T{
467 double lower left corner
468 T}
469 WACS_D_LRCORNER U+255d + A T{
470 double lower right corner
471 T}
472 WACS_D_LTEE U+2560 + F T{
473 double tee pointing right
474 T}
475 WACS_D_PLUS U+256c + E T{
476 double large plus
477 T}
478 WACS_D_RTEE U+2563 + G T{
479 double tee pointing left
480 T}
481 WACS_D_TTEE U+2566 + I T{
482 double tee pointing down
483 T}
484 WACS_D_ULCORNER U+2554 + C T{
485 double upper left corner
486 T}
487 WACS_D_URCORNER U+2557 + B T{
488 double upper right corner
489 T}
490 WACS_D_VLINE U+2551 | Y T{
491 double vertical line
492 T}
493 .TE
494 .PP
495 Unicode's descriptions for these characters differs slightly from
496 \fI\%ncurses\fP,
497 by introducing the term \*(``light\*('' (along with less important details).
498 Here are its descriptions for the normal, thick, and double horizontal lines:
499 .bP
500 U+2500 BOX DRAWINGS LIGHT HORIZONTAL
501 .bP
502 U+2501 BOX DRAWINGS HEAVY HORIZONTAL
503 .bP
504 U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
505 .SH RETURN VALUE
506 These functions return
507 .B OK
508 on success and
509 .B ERR
510 on failure.
511 .PP
512 In
513 .IR \%ncurses ,
514 these functions fail if
515 .bP
516 the
517 .I curses
518 screen has not been initialized,
519 .bP
520 (for functions taking a
521 .I \%WINDOW
522 pointer argument)
523 .I win
524 is a null pointer,
525 .bP
526 wrapping to a new line is impossible because \fB\%scrollok\fP(3NCURSES) has
527 not been called on
528 .I win
529 (or
530 .BR \%stdscr ","
531 as applicable)
532 when writing to its bottom right location is attempted,
533 or
534 .bP
535 it is not possible to add a complete character at the cursor position.
536 .PP
537 Functions prefixed with \*(``mv\*('' first perform cursor movement and
538 fail if the position
539 .RI ( y ,
540 .IR x )
541 is outside the window boundaries.
542 .SH NOTES
543 .BR add_wch ","
544 .BR mvadd_wch ","
545 .BR mvwadd_wch ","
546 and
547 .B echo_wchar
548 may be implemented as macros.
549 .SH EXTENSIONS
550 The symbols
551 .IR \%WACS_S3 ","
552 .IR \%WACS_S7 ","
553 .IR \%WACS_LEQUAL ","
554 .IR \%WACS_GEQUAL ","
555 .IR \%WACS_PI ","
556 .IR \%WACS_NEQUAL ","
557 and
558 .I \%WACS_STERLING
559 are not standard.
560 However,
561 many publicly available
562 .I \%term\%info
563 entries include
564 .B \%acs_chars
565 .RB \%( acsc )
566 capabilities in which their key characters
567 .RB ( pryz{|} )
568 are embedded,
569 and a second-hand list of their character descriptions has come to
570 light.
571 The
572 .I \%ncurses
573 developers invented WACS-prefixed names for them.
574 .\" in v5_2_20020209
575 .SH PORTABILITY
576 Applications employing
577 .I \%ncurses
578 extensions should condition their use on the visibility of the
579 .B \%NCURSES_VERSION
580 preprocessor macro.
581 .PP
582 These functions are described in X/Open Curses Issue\ 4.
583 It specifies no error conditions for them.
584 .PP
585 The defaults specified for forms-drawing characters apply in the POSIX
586 locale.
587 X/Open Curses makes it clear that the WACS_ symbols should be defined as
588 a pointer to
589 .I \%cchar_t
590 data, e.g., in the discussion of
591 .IR \%border_set "."
592 A few implementations are problematic:
593 .bP
594 NetBSD
595 .I curses
596 defines the symbols as a
597 .I \%wchar_t
598 within a
599 .IR \%cchar_t "."
600 .bP
601 HP-UX
602 .I curses
603 equates some of the
604 .I \%ACS_
605 symbols to the analogous
606 .I \%WACS_
607 symbols as if the
608 .I \%ACS_
609 symbols were
610 wide characters.
611 The misdefined symbols are the arrows
612 and other symbols which are not used for line-drawing.
613 .PP
614 X/Open Curses does not specify symbols for thick- or double-lines.
615 SVr4
616 .I curses
617 implementations defined their line-drawing symbols
618 in terms of intermediate symbols.
619 .I \%ncurses
620 extends those symbols,
621 providing new definitions not found in SVr4 implementations.
622 .PP
623 Not all Unicode-capable terminals provide support for VT100-style
624 alternate character sets (i.e., the
625 .I \%acsc_chars
626 .RB ( acsc )
627 capability),
628 with their corresponding line-drawing characters.
629 X/Open Curses did not address the aspect of integrating Unicode with
630 line-drawing characters.
631 Existing implementations of System\ V
632 .I curses
633 (AIX, HP-UX, Solaris)
634 use only the
635 .I \%acsc_chars
636 .RB ( acsc )
637 character-mapping to provide this feature.
638 As a result,
639 those implementations can use only single-byte line-drawing characters.
640 .I \%ncurses
641 5.3 (2002) provided a table of Unicode values to solve
642 these problems.
643 NetBSD
644 .I curses
645 incorporated that table in 2010.
646 .PP
647 .I \%ncurses
648 uses the Unicode values instead of the terminal type description's
649 .I \%acsc_chars
650 .RB ( acsc )
651 mapping as discussed in
652 \fB\%ncurses\fP(3NCURSES) for the environment variable
653 .IR \%NCURSES_NO_UTF8_ACS "."
654 In contrast, for the same cases, the line-drawing characters
655 described in \fB\%addch\fP(3NCURSES) will use only the ASCII default values.
656 .PP
657 Having Unicode available does not solve all of the problems with
658 line-drawing for
659 .IR curses ":"
660 .bP
661 The closest Unicode equivalents to the
662 VT100 graphics
663 .IR S1 ","
664 .IR S3 ","
665 .IR S7 ","
666 and
667 .I S9
668 frequently are not displayed at
669 the regular intervals which the terminal used.
670 .bP
671 The
672 .I lantern
673 is a special case.
674 It originated with the AT&T 4410 terminal in the early 1980s.
675 There is no accessible documentation depicting the lantern symbol
676 on the AT&T terminal.
677 .IP
678 Lacking documentation, most readers assume that a
679 .I "storm lantern"
680 was intended.
681 But there are several possibilities, all with problems.
682 .IP
683 Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and U+1F3EE.
684 Those were not available in 2002,
685 and are irrelevant since they lie outside the Basic Multilingual Plane
686 and as a result are unavailable on many terminals.
687 They are not storm lanterns, in any case.
688 .IP
689 Most
690 .I "storm lanterns"
691 have a tapering glass chimney
692 (to guard against tipping);
693 some have a wire grid protecting the chimney.
694 .IP
695 For the tapering appearance, \[u2603] U+2603 was adequate.
696 In use on a terminal, no one can tell what the image represents.
697 Unicode calls it a snowman.
698 .IP
699 Others have suggested these alternatives:
700 \[sc] U+00A7 (section mark),
701 \[u0398] U+0398 (theta),
702 \[u03A6] U+03A6 (phi),
703 \[u03B4] U+03B4 (delta),
704 \[u2327] U+2327 (x in a rectangle),
705 \[u256C] U+256C (forms double vertical and horizontal), and
706 \[u2612] U+2612 (ballot box with x).
707 .SS "Complex Characters"
708 The complex character type
709 .I \%cchar_t
710 can store more than one wide character
711 .RI \%( wchar_t ).
712 X/Open Curses does not mention this possibility,
713 specifying behavior only where
714 .I wch
715 is a single character,
716 either spacing or non-spacing.
717 .PP
718 .I \%ncurses
719 assumes that
720 .I wch
721 is constructed using \fB\%setcchar\fP(3NCURSES),
722 and in turn that the result
723 .bP
724 contains at most one spacing character at the beginning of its list of
725 wide characters,
726 and zero or more non-spacing characters,
727 or
728 .bP
729 holds one non-spacing character.
730 .PP
731 In the latter case,
732 .I \%ncurses
733 adds the non-spacing character to the active complex character.
734 .SH HISTORY
735 X/Open Curses Issue\ 4 (1995) initially specified these functions.
736 The System\ V Interface Definition (SVID) Version\ 4
737 of the same year
738 specified functions named
739 .I \%waddwch
740 (and the usual variants),
741 .IR \%echowchar ","
742 and
743 .IR \%wechowchar "."
744 .\" SVID 4, vol 3., p. 475
745 These were later additions to
746 .RI SVr4. x ,
747 not appearing in the first SVr4 (1989).
748 They differed from X/Open's later
749 .I \%wadd_wch
750 and
751 .I \%wecho_wchar
752 in that they each took an argument of type
753 .I \%wchar_t
754 instead of
755 .IR \%cchar_t "."
756 SVID defined no
757 .I \% WACS_
758 symbols.
759 .PP
760 X/Open Curses Issue\ 4 also defined many of the
761 .I WACS_
762 constants,
763 excepting
764 .IR \%WACS_GEQUAL ","
765 .IR \%WACS_LEQUAL ","
766 .IR \%WACS_NEQUAL ","
767 .IR \%WACS_PI ","
768 .IR \%WACS_S3 ","
769 .IR \%WACS_S7 ","
770 and
771 .IR \%WACS_STERLING ";"
772 and those for drawing thick and double lines.
773 .PP
774 .I \%ncurses
775 5.3 (2002)
776 furnished the remaining
777 .I WACS_
778 constants.
779 .SH SEE ALSO
780 \fB\%addch\fP(3NCURSES) describes comparable functions of the
781 .I \%ncurses
782 library in its non-wide-character configuration.
783 .PP
784 \fB\%ncurses\fP(3NCURSES),
785 \fB\%addwstr\fP(3NCURSES),
786 \fB\%add_wchstr\fP(3NCURSES),
787 \fB\%attr\fP(3NCURSES),
788 \fB\%bkgrnd\fP(3NCURSES),
789 \fB\%clear\fP(3NCURSES),
790 \fB\%getcchar\fP(3NCURSES),
791 \fB\%outopts\fP(3NCURSES),
792 \fB\%refresh\fP(3NCURSES),
793 \fB\%curses_variables\fP(3NCURSES),
794 \fB\%putwc\fP(3)