man/curs_add_wch.3x

   1 '\" t
   2 .\"***************************************************************************
   3 .\" Copyright 2019-2023,2024 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.67 2024/06/01 22:29:08 tom Exp $
  32 .TH curs_add_wch 3X 2024-06-01 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "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 .fi
  68 .SH DESCRIPTION
  69 .SS wadd_wch
  70 .B \%wadd_wch
  71 writes the complex character
  72 .I wch
  73 to the window
  74 .IR win ","
  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.
  78 .PP
  79 Much behavior depends on whether the wide characters in
  80 .I wch
  81 are spacing or non-spacing;
  82 see subsection \*(``Complex Characters\*('' below.
  83 .bP
  84 If
  85 .I wch
  86 contains a spacing character,
  87 then any character at the cursor is first removed.
  88 The complex character
  89 .IR wch ","
  90 with its attributes and color pair identifier,
  91 becomes the
  92 .I base
  93 of the
  94 .IR "active complex character" "."
  95 .bP
  96 If
  97 .I wch
  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.
 101 .I curses
 102 ignores its attributes and color pair identifier,
 103 and does not advance the cursor.
 104 .PP
 105 Further non-spacing characters added with
 106 .B \%wadd_wch
 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.
 110 .PP
 111 If advancement occurs at the right margin,
 112 .bP
 113 the cursor automatically wraps to the beginning of the next line,
 114 then,
 115 .bP
 116 if it was at the bottom of the scrolling region,
 117 and if \fB\%scrollok\fP(3X) is enabled for
 118 .IR win ,
 119 the scrolling region scrolls up one line.
 120 .PP
 121 If
 122 .I wch
 123 is a
 124 backspace,
 125 carriage return,
 126 line feed,
 127 or
 128 tab,
 129 the cursor moves appropriately within the window.
 130 .bP
 131 Backspace moves the cursor one character left;
 132 at the left margin of a window,
 133 it does nothing.
 134 .bP
 135 Carriage return moves the cursor to the left margin on the current line
 136 of the window.
 137 .bP
 138 Line feed does a \fB\%clrtoeol\fP(3X),
 139 then advances as if from the right margin.
 140 .bP
 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
 145 .B \%TABSIZE
 146 extension;
 147 see \fB\%curs_variables\fP(3X).
 148 .PP
 149 If
 150 .I wch
 151 is any other nonprintable character,
 152 it is drawn in printable form using the same convention as
 153 \fB\%wunctrl\fP(3X).
 154 Calling \fB\%win_wch\fP(3X) on the location of a nonprintable character
 155 does not return the character itself,
 156 but its \fB\%wunctrl\fP(3X) representation.
 157 .PP
 158 A
 159 .I \%cchar_t
 160 can be copied from place to place using \fB\%win_wch\fP(3X) and
 161 .BR \%wadd_wch "."
 162 .SS wecho_wchar
 163 .B \%echo_wchar
 164 and
 165 .B \%wecho_wchar
 166 are equivalent to calling
 167 .RB \%( w ) add_wch
 168 followed by
 169 .RB \%( w ) refresh .
 170 .I curses
 171 interprets these functions as a hint that only a single (complex)
 172 character is being output;
 173 for non-control characters,
 174 a considerable performance gain may be enjoyed by employing them.
 175 .\" TODO: Combine the following with the "Line Drawing" subsection of
 176 .\" terminfo(5) and replace this with a cross reference there.
 177 .SS "Forms-Drawing Characters"
 178 .I curses
 179 defines macros starting with
 180 .B \%WACS_
 181 that can be used with
 182 .B \%wadd_wch
 183 to write line-drawing and other special characters to the screen.
 184 .I \%ncurses
 185 terms these
 186 .I "forms-drawing characters."
 187 The ACS default listed below is used if the
 188 .B \%acs_chars
 189 .RB \%( acsc )
 190 .I \%term\%info
 191 capability does not define a terminal-specific replacement for it,
 192 or if the terminal and locale configuration requires Unicode to access
 193 these characters but the library is unable to use Unicode.
 194 The \*(``acsc char\*('' column corresponds to how the characters are
 195 specified in the
 196 .B \%acs_chars
 197 .RB \%( acsc )
 198 string capability,
 199 and the characters in it may appear on the screen if the terminal type's
 200 database entry incorrectly advertises ACS support.
 201 The name \*(``ACS\*('' originates in the Alternate Character Set feature
 202 of the DEC VT100 terminal.
 203 .PP
 204 .ie t .ne 4v
 205 .el   .ne 5v
 206 .TS
 207 Lb Lb Lb Lb Lb
 208 Lb Lb Lb Lb Lb
 209 Lb L  L  L  Lx.
 210 \&      Unicode ACS     acsc    \&
 211 Symbol  Default Default char    Glyph Name
 212 _
 213 WACS_BLOCK      0x25ae  #       0       T{
 214 solid square block
 215 T}
 216 WACS_BOARD      0x2592  #       h       board of squares
 217 WACS_BTEE       0x2534  +       v       bottom tee
 218 WACS_BULLET     0x00b7  o       ~       bullet
 219 WACS_CKBOARD    0x2592  :       a       T{
 220 checker board (stipple)
 221 T}
 222 WACS_DARROW     0x2193  v       .       T{
 223 arrow pointing down
 224 T}
 225 WACS_DEGREE     0x00b0  '       f       degree symbol
 226 WACS_DIAMOND    0x25c6  +       \(ga    diamond
 227 WACS_GEQUAL     0x2265  >       >       T{
 228 greater-than-or-equal-to
 229 T}
 230 WACS_HLINE      0x2500  \-      q       horizontal line
 231 WACS_LANTERN    0x2603  #       i       lantern symbol
 232 WACS_LARROW     0x2190  <       ,       T{
 233 arrow pointing left
 234 T}
 235 WACS_LEQUAL     0x2264  <       y       T{
 236 less-than-or-equal-to
 237 T}
 238 WACS_LLCORNER   0x2514  +       m       T{
 239 lower left-hand corner
 240 T}
 241 WACS_LRCORNER   0x2518  +       j       T{
 242 lower right-hand corner
 243 T}
 244 WACS_LTEE       0x2524  +       t       left tee
 245 WACS_NEQUAL     0x2260  !       |       not-equal
 246 WACS_PI 0x03c0  *       {       greek pi
 247 WACS_PLMINUS    0x00b1  #       g       plus/minus
 248 WACS_PLUS       0x253c  +       n       plus
 249 WACS_RARROW     0x2192  >       +       T{
 250 arrow pointing right
 251 T}
 252 WACS_RTEE       0x251c  +       u       right tee
 253 WACS_S1 0x23ba  \-      o       scan line 1
 254 WACS_S3 0x23bb  \-      p       scan line 3
 255 WACS_S7 0x23bc  \-      r       scan line 7
 256 WACS_S9 0x23bd  \&_     s       scan line 9
 257 WACS_STERLING   0x00a3  f       }       T{
 258 pound-sterling symbol
 259 T}
 260 WACS_TTEE       0x252c  +       w       top tee
 261 WACS_UARROW     0x2191  ^       \-      T{
 262 arrow pointing up
 263 T}
 264 WACS_ULCORNER   0x250c  +       l       T{
 265 upper left-hand corner
 266 T}
 267 WACS_URCORNER   0x2510  +       k       T{
 268 upper right-hand corner
 269 T}
 270 WACS_VLINE      0x2502  |       x       vertical line
 271 .TE
 272 .PP
 273 The wide-character configuration of \fI\%ncurses\fP also defines symbols
 274 for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''):
 275 .PP
 276 .TS
 277 Lb Lb Lb Lb Lb
 278 Lb Lb Lb Lb Lb
 279 Lb L  L  L  Lx.
 280 \&      Unicode ASCII   acsc    \&
 281 ACS Name        Default Default Char    Glyph Name
 282 _
 283 WACS_T_BTEE     0x253b  +       V       T{
 284 thick tee pointing up
 285 T}
 286 WACS_T_HLINE    0x2501  -       Q       T{
 287 thick horizontal line
 288 T}
 289 WACS_T_LLCORNER 0x2517  +       M       T{
 290 thick lower left corner
 291 T}
 292 WACS_T_LRCORNER 0x251b  +       J       T{
 293 thick lower right corner
 294 T}
 295 WACS_T_LTEE     0x252b  +       T       T{
 296 thick tee pointing right
 297 T}
 298 WACS_T_PLUS     0x254b  +       N       T{
 299 thick large plus
 300 T}
 301 WACS_T_RTEE     0x2523  +       U       T{
 302 thick tee pointing left
 303 T}
 304 WACS_T_TTEE     0x2533  +       W       T{
 305 thick tee pointing down
 306 T}
 307 WACS_T_ULCORNER 0x250f  +       L       T{
 308 thick upper left corner
 309 T}
 310 WACS_T_URCORNER 0x2513  +       K       T{
 311 thick upper right corner
 312 T}
 313 WACS_T_VLINE    0x2503  |       X       T{
 314 thick vertical line
 315 T}
 316 .TE
 317 .PP
 318 and for double-lines (\fBacsc\fP \*(``A\*('' to \*(``I\*(''):
 319 .PP
 320 .TS
 321 Lb Lb Lb Lb Lb
 322 Lb Lb Lb Lb Lb
 323 Lb L  L  L  Lx.
 324 \&      Unicode ASCII   acsc    \&
 325 ACS Name        Default Default Char    Glyph Name
 326 _
 327 WACS_D_BTEE     0x2569  +       H       T{
 328 double tee pointing up
 329 T}
 330 WACS_D_HLINE    0x2550  -       R       T{
 331 double horizontal line
 332 T}
 333 WACS_D_LLCORNER 0x255a  +       D       T{
 334 double lower left corner
 335 T}
 336 WACS_D_LRCORNER 0x255d  +       A       T{
 337 double lower right corner
 338 T}
 339 WACS_D_LTEE     0x2560  +       F       T{
 340 double tee pointing right
 341 T}
 342 WACS_D_PLUS     0x256c  +       E       T{
 343 double large plus
 344 T}
 345 WACS_D_RTEE     0x2563  +       G       T{
 346 double tee pointing left
 347 T}
 348 WACS_D_TTEE     0x2566  +       I       T{
 349 double tee pointing down
 350 T}
 351 WACS_D_ULCORNER 0x2554  +       C       T{
 352 double upper left corner
 353 T}
 354 WACS_D_URCORNER 0x2557  +       B       T{
 355 double upper right corner
 356 T}
 357 WACS_D_VLINE    0x2551  |       Y       T{
 358 double vertical line
 359 T}
 360 .TE
 361 .PP
 362 Unicode's descriptions for these characters differs slightly from
 363 \fI\%ncurses\fP,
 364 by introducing the term \*(``light\*('' (along with less important details).
 365 Here are its descriptions for the normal, thick, and double horizontal lines:
 366 .bP
 367 U+2500 BOX DRAWINGS LIGHT HORIZONTAL
 368 .bP
 369 U+2501 BOX DRAWINGS HEAVY HORIZONTAL
 370 .bP
 371 U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
 372 .SH RETURN VALUE
 373 These functions return
 374 .B OK
 375 on success and
 376 .B ERR
 377 on failure.
 378 In
 379 .IR \%ncurses ,
 380 .B \%wadd_wch
 381 returns
 382 .B ERR
 383 if
 384 .bP
 385 .I win
 386 is
 387 .BR NULL ","
 388 .bP
 389 wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
 390 not been called on
 391 .I win
 392 when writing to its bottom right location is attempted,
 393 or
 394 .bP
 395 it is not possible to add a complete character at the cursor position.
 396 .PP
 397 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 398 fail if the position
 399 .RI ( y ,
 400 .IR x )
 401 is outside the window boundaries.
 402 .SH NOTES
 403 .BR add_wch ","
 404 .BR mvadd_wch ","
 405 .BR mvwadd_wch ","
 406 and
 407 .B echo_wchar
 408 may be implemented as macros.
 409 .SH EXTENSIONS
 410 .SS TABSIZE
 411 The
 412 .B TABSIZE
 413 variable is implemented in SVr4 and other versions of
 414 .IR curses ,
 415 but is not specified by X/Open Curses
 416 (see \fBcurs_variables\fP(3X)).
 417 .SH PORTABILITY
 418 These functions are described in X/Open Curses, Issue 4.
 419 It specifies no error conditions for them.
 420 .PP
 421 The defaults specified for forms-drawing characters apply in the POSIX
 422 locale.
 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:
 426 .bP
 427 NetBSD curses defines the symbols as a \fBwchar_t\fP within a \fBcchar_t\fP.
 428 .bP
 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
 431 wide characters.
 432 The misdefined symbols are the arrows
 433 and other symbols which are not used for line-drawing.
 434 .PP
 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.
 440 .PP
 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
 449 characters.
 450 \fI\%ncurses\fP 5.3 (2002) provided a table of Unicode values to solve
 451 these problems.
 452 NetBSD curses incorporated that table in 2010.
 453 .PP
 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.
 460 .PP
 461 Having Unicode available does not solve all of the problems with
 462 line-drawing for curses:
 463 .bP
 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.
 468 .bP
 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.
 473 .IP
 474 Lacking documentation, most readers assume that a \fIstorm lantern\fP
 475 was intended.
 476 But there are several possibilities, all with problems.
 477 .IP
 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
 481 in terminals.
 482 They are not storm lanterns, in any case.
 483 .IP
 484 Most \fIstorm lanterns\fP have a tapering glass chimney
 485 (to guard against tipping);
 486 some have a wire grid protecting the chimney.
 487 .IP
 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.
 491 .IP
 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
 502 .I \%cchar_t
 503 can store more than one wide character
 504 .RI \%( wchar_t ).
 505 X/Open Curses does not mention this possibility,
 506 specifying behavior only where
 507 .I wch
 508 is a single character,
 509 either spacing or non-spacing.
 510 .PP
 511 .I \%ncurses
 512 assumes that
 513 .I wch
 514 is constructed using \fB\%setcchar\fP(3X),
 515 and in turn that the result
 516 .bP
 517 contains at most one spacing character at the beginning of its list of
 518 wide characters,
 519 and zero or more non-spacing characters,
 520 or
 521 .bP
 522 holds one non-spacing character.
 523 .PP
 524 In the latter case,
 525 .I \%ncurses
 526 adds the non-spacing character to the active complex character.
 527 .SH HISTORY
 528 These functions were initially specified by X/Open Curses,
 529 Issue 4.
 530 The System\ V Interface Definition,
 531 Version 4 (1995),
 532 specified functions named
 533 .I \%waddwch
 534 and
 535 .I \%wechowchar
 536 (and the usual variants).
 537 These were later additions to
 538 .RI SVr4. x ,
 539 not appearing in the first SVr4 (1989).
 540 They differed from X/Open's
 541 .I \%wadd_wch
 542 and
 543 .I \%wecho_wchar
 544 in that they each took an argument of type
 545 .I \%wchar_t
 546 instead of
 547 .IR \%cchar_t "."
 548 .SH SEE ALSO
 549 \fB\%curs_addch\fP(3X) describes comparable functions of the
 550 .I \%ncurses
 551 library in its non-wide-character configuration.
 552 .PP
 553 \fB\%curses\fP(3X),
 554 \fB\%curs_addwstr\fP(3X),
 555 \fB\%curs_add_wchstr\fP(3X),
 556 \fB\%curs_attr\fP(3X),
 557 \fB\%curs_clear\fP(3X),
 558 \fB\%curs_getcchar\fP(3X),
 559 \fB\%curs_outopts\fP(3X),
 560 \fB\%curs_refresh\fP(3X),
 561 \fB\%curs_variables\fP(3X),
 562 \fB\%putwc\fP(3)