Debian Codegraph @

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