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.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"
  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 .PP
 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.
 158 .SS wecho_wchar
 159 .B \%echo_wchar
 160 and
 161 .B \%wecho_wchar
 162 are equivalent to calling
 163 .RB \%( w ) add_wch
 164 followed by
 165 .RB \%( w ) refresh .
 166 .I curses
 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"
 174 .I curses
 175 defines macros starting with
 176 .B \%WACS_
 177 that can be used with
 178 .B \%wadd_wch
 179 to write line-drawing and other special characters to the screen.
 180 .I \%ncurses
 181 terms these
 182 .I "forms-drawing characters."
 183 The ACS default listed below is used if the
 184 .B \%acs_chars
 185 .RB ( \%acsc )
 186 .I \%term\%info
 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
 191 specified in the
 192 .B \%acs_chars
 193 .RB ( \%acsc )
 194 string capability,
 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.
 199 .PP
 200 .TS
 201 Lb Lb Lb Lb Lb
 202 Lb Lb Lb Lb Lb
 203 Lb L  L  L  Lx.
 204 \&      Unicode ACS     acsc    \&
 205 Symbol  Default Default char    Glyph Name
 206 _
 207 WACS_BLOCK      0x25ae  #       0       T{
 208 solid square block
 209 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)
 215 T}
 216 WACS_DARROW     0x2193  v       .       T{
 217 arrow pointing down
 218 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
 223 T}
 224 WACS_HLINE      0x2500  \-      q       horizontal line
 225 WACS_LANTERN    0x2603  #       i       lantern symbol
 226 WACS_LARROW     0x2190  <       ,       T{
 227 arrow pointing left
 228 T}
 229 WACS_LEQUAL     0x2264  <       y       T{
 230 less-than-or-equal-to
 231 T}
 232 WACS_LLCORNER   0x2514  +       m       T{
 233 lower left-hand corner
 234 T}
 235 WACS_LRCORNER   0x2518  +       j       T{
 236 lower right-hand corner
 237 T}
 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{
 244 arrow pointing right
 245 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
 253 T}
 254 WACS_TTEE       0x252c  +       w       top tee
 255 WACS_UARROW     0x2191  ^       \-      T{
 256 arrow pointing up
 257 T}
 258 WACS_ULCORNER   0x250c  +       l       T{
 259 upper left-hand corner
 260 T}
 261 WACS_URCORNER   0x2510  +       k       T{
 262 upper right-hand corner
 263 T}
 264 WACS_VLINE      0x2502  |       x       vertical line
 265 .TE
 266 .PP
 267 The wide-character configuration of \fI\%ncurses\fP also defines symbols
 268 for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''):
 269 .PP
 270 .TS
 271 Lb Lb Lb Lb Lb
 272 Lb Lb Lb Lb Lb
 273 Lb L  L  L  Lx.
 274 \&      Unicode ASCII   acsc    \&
 275 ACS Name        Default Default Char    Glyph Name
 276 _
 277 WACS_T_BTEE     0x253b  +       V       T{
 278 thick tee pointing up
 279 T}
 280 WACS_T_HLINE    0x2501  -       Q       T{
 281 thick horizontal line
 282 T}
 283 WACS_T_LLCORNER 0x2517  +       M       T{
 284 thick lower left corner
 285 T}
 286 WACS_T_LRCORNER 0x251b  +       J       T{
 287 thick lower right corner
 288 T}
 289 WACS_T_LTEE     0x252b  +       T       T{
 290 thick tee pointing right
 291 T}
 292 WACS_T_PLUS     0x254b  +       N       T{
 293 thick large plus
 294 T}
 295 WACS_T_RTEE     0x2523  +       U       T{
 296 thick tee pointing left
 297 T}
 298 WACS_T_TTEE     0x2533  +       W       T{
 299 thick tee pointing down
 300 T}
 301 WACS_T_ULCORNER 0x250f  +       L       T{
 302 thick upper left corner
 303 T}
 304 WACS_T_URCORNER 0x2513  +       K       T{
 305 thick upper right corner
 306 T}
 307 WACS_T_VLINE    0x2503  |       X       T{
 308 thick vertical line
 309 T}
 310 .TE
 311 .PP
 312 and for double-lines (\fBacsc\fP \*(``A\*('' to \*(``I\*(''):
 313 .PP
 314 .TS
 315 Lb Lb Lb Lb Lb
 316 Lb Lb Lb Lb Lb
 317 Lb L  L  L  Lx.
 318 \&      Unicode ASCII   acsc    \&
 319 ACS Name        Default Default Char    Glyph Name
 320 _
 321 WACS_D_BTEE     0x2569  +       H       T{
 322 double tee pointing up
 323 T}
 324 WACS_D_HLINE    0x2550  -       R       T{
 325 double horizontal line
 326 T}
 327 WACS_D_LLCORNER 0x255a  +       D       T{
 328 double lower left corner
 329 T}
 330 WACS_D_LRCORNER 0x255d  +       A       T{
 331 double lower right corner
 332 T}
 333 WACS_D_LTEE     0x2560  +       F       T{
 334 double tee pointing right
 335 T}
 336 WACS_D_PLUS     0x256c  +       E       T{
 337 double large plus
 338 T}
 339 WACS_D_RTEE     0x2563  +       G       T{
 340 double tee pointing left
 341 T}
 342 WACS_D_TTEE     0x2566  +       I       T{
 343 double tee pointing down
 344 T}
 345 WACS_D_ULCORNER 0x2554  +       C       T{
 346 double upper left corner
 347 T}
 348 WACS_D_URCORNER 0x2557  +       B       T{
 349 double upper right corner
 350 T}
 351 WACS_D_VLINE    0x2551  |       Y       T{
 352 double vertical line
 353 T}
 354 .TE
 355 .PP
 356 Unicode's descriptions for these characters differs slightly from
 357 \fI\%ncurses\fP,
 358 by introducing the term \*(``light\*('' (along with less important details).
 359 Here are its descriptions for the normal, thick, and double horizontal lines:
 360 .bP
 361 U+2500 BOX DRAWINGS LIGHT HORIZONTAL
 362 .bP
 363 U+2501 BOX DRAWINGS HEAVY HORIZONTAL
 364 .bP
 365 U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
 366 .SH RETURN VALUE
 367 These functions return
 368 .B OK
 369 on success and
 370 .B ERR
 371 on failure.
 372 In
 373 .IR \%ncurses ,
 374 .B \%wadd_wch
 375 returns
 376 .B ERR
 377 if
 378 .bP
 379 .I win
 380 is
 381 .BR NULL ","
 382 .bP
 383 wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
 384 not been called on
 385 .I win
 386 when writing to its bottom right location is attempted,
 387 or
 388 .bP
 389 it is not possible to add a complete character at the cursor position.
 390 .PP
 391 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 392 fail if the position
 393 .RI ( y ,
 394 .IR x )
 395 is outside the window boundaries.
 396 .SH NOTES
 397 .BR add_wch ","
 398 .BR mvadd_wch ","
 399 .BR mvwadd_wch ","
 400 and
 401 .B echo_wchar
 402 may be implemented as macros.
 403 .SH EXTENSIONS
 404 .SS TABSIZE
 405 The
 406 .B TABSIZE
 407 variable is implemented in SVr4 and other versions of
 408 .IR curses ,
 409 but is not specified by X/Open Curses
 410 (see \fBcurs_variables\fP(3X)).
 411 .SH PORTABILITY
 412 These functions are described in X/Open Curses, Issue 4.
 413 It specifies no error conditions for them.
 414 .PP
 415 SVr4
 416 .I curses
 417 describes a successful return value only as
 418 \*(``an integer value other than
 419 .BR ERR \*(''.
 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 SEE ALSO
 528 \fB\%curs_addch\fP(3X) describes comparable functions of the
 529 .I \%ncurses
 530 library in its non-wide-character configuration.
 531 .PP
 532 \fB\%curses\fP(3X),
 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),
 541 \fB\%putwc\fP(3)