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.62 2024/04/20 21:20:07 tom Exp $
  32 .TH curs_add_wch 3X 2024-04-20 "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 and advance 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 add_wch
  70 The
  71 \fBadd_wch\fP,
  72 \fBwadd_wch\fP,
  73 \fBmvadd_wch\fP, and
  74 \fBmvwadd_wch\fP
  75 functions put the complex character \fIwch\fP into the given
  76 window at its current position,
  77 which is then advanced.
  78 These functions perform
  79 wrapping and special-character processing as follows:
  80 .bP
  81 If \fIwch\fP refers to a spacing character,
  82 then any previous character at that location is removed.
  83 A new character specified by \fIwch\fP is
  84 placed at that location with rendition specified by \fIwch\fP.
  85 The cursor then advances after this spacing character,
  86 to prepare for writing the next character on the screen.
  87 .IP
  88 The newly added spacing character is the base of the active complex character.
  89 Subsequent non-spacing characters can be combined with this base
  90 until another spacing character is written to the screen,
  91 or the cursor is moved, e.g., using \fBwmove\fP.
  92 .bP
  93 If \fIwch\fP refers to a non-spacing character,
  94 it is appended to the active complex character,
  95 retaining the previous characters at that location.
  96 The rendition specified by \fIwch\fP is ignored.
  97 .IP
  98 The cursor is not advanced after adding a non-spacing character.
  99 Subsequent calls to add non-spacing characters will update the same position.
 100 .bP
 101 If the character part of \fIwch\fP is
 102 a tab, newline, backspace or other control character,
 103 the window is updated and the cursor moves as if \fBaddch\fP were called.
 104 .SS echo_wchar
 105 The \fBecho_wchar\fP
 106 function is functionally equivalent to a call to
 107 \fBadd_wch\fP
 108 followed by a call to
 109 \fB\%refresh\fP(3X).
 110 Similarly, the
 111 \fBwecho_wchar\fP
 112 is functionally equivalent to a call to
 113 \fBwadd_wch\fP
 114 followed by a call to
 115 \fBwrefresh\fP.
 116 The knowledge
 117 that only a single character is being output is taken into consideration and,
 118 for non-control characters, a considerable performance gain might be seen
 119 by using the *\fBecho\fP* functions instead of their equivalents.
 120 .SS "Line Graphics"
 121 Like \fB\%addch\fP(3X),
 122 \fBaddch_wch\fP accepts symbols which make it simple to draw lines and other
 123 frequently used special characters.
 124 These symbols correspond to the same VT100 line-drawing set as
 125 \fB\%addch\fP(3X).
 126 .PP
 127 .TS
 128 Lb Lb Lb Lb Lb
 129 Lb Lb Lb Lb Lb
 130 Lb L  L  L  Lx.
 131 \&      Unicode ASCII   acsc    \&
 132 ACS Name        Default Default Char    Glyph Name
 133 _
 134 WACS_BLOCK      0x25ae  #       0       T{
 135 solid square block
 136 T}
 137 WACS_BOARD      0x2592  #       h       board of squares
 138 WACS_BTEE       0x2534  +       v       bottom tee
 139 WACS_BULLET     0x00b7  o       ~       bullet
 140 WACS_CKBOARD    0x2592  :       a       T{
 141 checker board (stipple)
 142 T}
 143 WACS_DARROW     0x2193  v       .       T{
 144 arrow pointing down
 145 T}
 146 WACS_DEGREE     0x00b0  '       f       degree symbol
 147 WACS_DIAMOND    0x25c6  +       \(ga    diamond
 148 WACS_GEQUAL     0x2265  >       >       T{
 149 greater-than-or-equal-to
 150 T}
 151 WACS_HLINE      0x2500  \-      q       horizontal line
 152 WACS_LANTERN    0x2603  #       i       lantern symbol
 153 WACS_LARROW     0x2190  <       ,       T{
 154 arrow pointing left
 155 T}
 156 WACS_LEQUAL     0x2264  <       y       T{
 157 less-than-or-equal-to
 158 T}
 159 WACS_LLCORNER   0x2514  +       m       T{
 160 lower left-hand corner
 161 T}
 162 WACS_LRCORNER   0x2518  +       j       T{
 163 lower right-hand corner
 164 T}
 165 WACS_LTEE       0x2524  +       t       left tee
 166 WACS_NEQUAL     0x2260  !       |       not-equal
 167 WACS_PI 0x03c0  *       {       greek pi
 168 WACS_PLMINUS    0x00b1  #       g       plus/minus
 169 WACS_PLUS       0x253c  +       n       plus
 170 WACS_RARROW     0x2192  >       +       T{
 171 arrow pointing right
 172 T}
 173 WACS_RTEE       0x251c  +       u       right tee
 174 WACS_S1 0x23ba  \-      o       scan line 1
 175 WACS_S3 0x23bb  \-      p       scan line 3
 176 WACS_S7 0x23bc  \-      r       scan line 7
 177 WACS_S9 0x23bd  \&_     s       scan line 9
 178 WACS_STERLING   0x00a3  f       }       T{
 179 pound-sterling symbol
 180 T}
 181 WACS_TTEE       0x252c  +       w       top tee
 182 WACS_UARROW     0x2191  ^       \-      T{
 183 arrow pointing up
 184 T}
 185 WACS_ULCORNER   0x250c  +       l       T{
 186 upper left-hand corner
 187 T}
 188 WACS_URCORNER   0x2510  +       k       T{
 189 upper right-hand corner
 190 T}
 191 WACS_VLINE      0x2502  |       x       vertical line
 192 .TE
 193 .PP
 194 The wide-character configuration of \fI\%ncurses\fP also defines symbols
 195 for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''):
 196 .PP
 197 .TS
 198 Lb Lb Lb Lb Lb
 199 Lb Lb Lb Lb Lb
 200 Lb L  L  L  Lx.
 201 \&      Unicode ASCII   acsc    \&
 202 ACS Name        Default Default Char    Glyph Name
 203 _
 204 WACS_T_BTEE     0x253b  +       V       T{
 205 thick tee pointing up
 206 T}
 207 WACS_T_HLINE    0x2501  -       Q       T{
 208 thick horizontal line
 209 T}
 210 WACS_T_LLCORNER 0x2517  +       M       T{
 211 thick lower left corner
 212 T}
 213 WACS_T_LRCORNER 0x251b  +       J       T{
 214 thick lower right corner
 215 T}
 216 WACS_T_LTEE     0x252b  +       T       T{
 217 thick tee pointing right
 218 T}
 219 WACS_T_PLUS     0x254b  +       N       T{
 220 thick large plus
 221 T}
 222 WACS_T_RTEE     0x2523  +       U       T{
 223 thick tee pointing left
 224 T}
 225 WACS_T_TTEE     0x2533  +       W       T{
 226 thick tee pointing down
 227 T}
 228 WACS_T_ULCORNER 0x250f  +       L       T{
 229 thick upper left corner
 230 T}
 231 WACS_T_URCORNER 0x2513  +       K       T{
 232 thick upper right corner
 233 T}
 234 WACS_T_VLINE    0x2503  |       X       T{
 235 thick vertical line
 236 T}
 237 .TE
 238 .PP
 239 and for double-lines (\fBacsc\fP \*(``A\*('' to \*(``I\*(''):
 240 .PP
 241 .TS
 242 Lb Lb Lb Lb Lb
 243 Lb Lb Lb Lb Lb
 244 Lb L  L  L  Lx.
 245 \&      Unicode ASCII   acsc    \&
 246 ACS Name        Default Default Char    Glyph Name
 247 _
 248 WACS_D_BTEE     0x2569  +       H       T{
 249 double tee pointing up
 250 T}
 251 WACS_D_HLINE    0x2550  -       R       T{
 252 double horizontal line
 253 T}
 254 WACS_D_LLCORNER 0x255a  +       D       T{
 255 double lower left corner
 256 T}
 257 WACS_D_LRCORNER 0x255d  +       A       T{
 258 double lower right corner
 259 T}
 260 WACS_D_LTEE     0x2560  +       F       T{
 261 double tee pointing right
 262 T}
 263 WACS_D_PLUS     0x256c  +       E       T{
 264 double large plus
 265 T}
 266 WACS_D_RTEE     0x2563  +       G       T{
 267 double tee pointing left
 268 T}
 269 WACS_D_TTEE     0x2566  +       I       T{
 270 double tee pointing down
 271 T}
 272 WACS_D_ULCORNER 0x2554  +       C       T{
 273 double upper left corner
 274 T}
 275 WACS_D_URCORNER 0x2557  +       B       T{
 276 double upper right corner
 277 T}
 278 WACS_D_VLINE    0x2551  |       Y       T{
 279 double vertical line
 280 T}
 281 .TE
 282 .PP
 283 Unicode's descriptions for these characters differs slightly from
 284 \fI\%ncurses\fP,
 285 by introducing the term \*(``light\*('' (along with less important details).
 286 Here are its descriptions for the normal, thick, and double horizontal lines:
 287 .bP
 288 U+2500 BOX DRAWINGS LIGHT HORIZONTAL
 289 .bP
 290 U+2501 BOX DRAWINGS HEAVY HORIZONTAL
 291 .bP
 292 U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
 293 .SH RETURN VALUE
 294 All routines return the integer \fBERR\fP upon failure and \fBOK\fP on success.
 295 .PP
 296 X/Open Curses does not specify any error conditions.
 297 This implementation returns an error
 298 .bP
 299 if the window pointer is null or
 300 .bP
 301 if it is not possible to add a complete character in the window.
 302 .PP
 303 The latter may be due to different causes:
 304 .bP
 305 If \fB\%scrollok\fP(3X) is not enabled,
 306 writing a character at the lower right margin succeeds.
 307 However,
 308 an error is returned because it is not possible to wrap to a new line.
 309 .bP
 310 If an error is detected when converting a multibyte character to a sequence
 311 of bytes,
 312 or if it is not possible to add all of the resulting bytes in the window,
 313 an error is returned.
 314 .PP
 315 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 316 fail if the position
 317 .RI ( y ,
 318 .IR x )
 319 is outside the window boundaries.
 320 .SH NOTES
 321 Note that
 322 \fBadd_wch\fP,
 323 \fBmvadd_wch\fP,
 324 \fBmvwadd_wch\fP, and
 325 \fBecho_wchar\fP
 326 may be macros.
 327 .SH PORTABILITY
 328 These functions are described in X/Open Curses, Issue 4.
 329 The defaults specified for line-drawing characters apply in the POSIX locale.
 330 .SS "WACS Symbols"
 331 X/Open Curses makes it clear that the WACS_ symbols should be defined as
 332 a pointer to \fBcchar_t\fP data, e.g., in the discussion of \fBborder_set\fP.
 333 A few implementations are problematic:
 334 .bP
 335 NetBSD curses defines the symbols as a \fBwchar_t\fP within a \fBcchar_t\fP.
 336 .bP
 337 HP-UX curses equates some of the \fBACS_\fP symbols
 338 to the analogous \fBWACS_\fP symbols as if the \fBACS_\fP symbols were
 339 wide characters.
 340 The misdefined symbols are the arrows
 341 and other symbols which are not used for line-drawing.
 342 .PP
 343 X/Open Curses does not specify symbols for thick- or double-lines.
 344 SVr4 curses implementations defined their line-drawing symbols in
 345 terms of intermediate symbols.
 346 This implementation extends those symbols, providing new definitions
 347 which are not in the SVr4 implementations.
 348 .PP
 349 Not all Unicode-capable terminals provide support for VT100-style
 350 alternate character sets (i.e., the \fBacsc\fP capability),
 351 with their corresponding line-drawing characters.
 352 X/Open Curses did not address the aspect of integrating Unicode with
 353 line-drawing characters.
 354 Existing implementations of Unix curses (AIX, HP-UX, Solaris)
 355 use only the \fBacsc\fP character-mapping to provide this feature.
 356 As a result, those implementations can only use single-byte line-drawing
 357 characters.
 358 \fI\%ncurses\fP 5.3 (2002) provided a table of Unicode values to solve
 359 these problems.
 360 NetBSD curses incorporated that table in 2010.
 361 .PP
 362 In this implementation, the Unicode values are used instead of the
 363 terminal description's \fBacsc\fP mapping as discussed in
 364 \fB\%ncurses\fP(3X) for the environment variable
 365 \fINCURSES_NO_UTF8_ACS\fP.
 366 In contrast, for the same cases, the line-drawing characters
 367 described in \fB\%addch\fP(3X) will use only the ASCII default values.
 368 .PP
 369 Having Unicode available does not solve all of the problems with
 370 line-drawing for curses:
 371 .bP
 372 The closest Unicode equivalents to the
 373 VT100 graphics \fIS1\fP, \fIS3\fP, \fIS7\fP and \fIS9\fP
 374 frequently are not displayed at
 375 the regular intervals which the terminal used.
 376 .bP
 377 The \fIlantern\fP is a special case.
 378 It originated with the AT&T 4410 terminal in the early 1980s.
 379 There is no accessible documentation depicting the lantern symbol
 380 on the AT&T terminal.
 381 .IP
 382 Lacking documentation, most readers assume that a \fIstorm lantern\fP
 383 was intended.
 384 But there are several possibilities, all with problems.
 385 .IP
 386 Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and U+1F3EE.
 387 Those were not available in 2002, and are irrelevant since
 388 they lie outside the BMP and as a result are not generally available
 389 in terminals.
 390 They are not storm lanterns, in any case.
 391 .IP
 392 Most \fIstorm lanterns\fP have a tapering glass chimney
 393 (to guard against tipping);
 394 some have a wire grid protecting the chimney.
 395 .IP
 396 For the tapering appearance, \[u2603] U+2603 was adequate.
 397 In use on a terminal, no one can tell what the image represents.
 398 Unicode calls it a snowman.
 399 .IP
 400 Others have suggested these alternatives:
 401 \[sc] U+00A7 (section mark),
 402 \[u0398] U+0398 (theta),
 403 \[u03A6] U+03A6 (phi),
 404 \[u03B4] U+03B4 (delta),
 405 \[u2327] U+2327 (x in a rectangle),
 406 \[u256C] U+256C (forms double vertical and horizontal), and
 407 \[u2612] U+2612 (ballot box with x).
 408 .SS "Complex Characters"
 409 The complex character type \fBcchar_t\fR
 410 can store more than one wide character (\fBwchar_t\fR).
 411 The X/Open Curses description does not mention this possibility,
 412 describing only the cases where \fIwch\fP is a spacing character
 413 or a non-spacing character.
 414 .PP
 415 This implementation assumes that \fIwch\fP is constructed using
 416 \fB\%setcchar\fP(3X), and in turn that the result
 417 .bP
 418 contains at most one spacing character in the beginning of its list of wide
 419 characters,
 420 and zero or more non-spacing characters
 421 or
 422 .bP
 423 may hold one non-spacing character.
 424 .PP
 425 In the latter case,
 426 \fI\%ncurses\fP adds the non-spacing character to the active
 427 (base) spacing character.
 428 .SS TABSIZE
 429 The
 430 .B TABSIZE
 431 variable is implemented in SVr4 and other versions of
 432 .IR curses ,
 433 but is not specified by X/Open Curses
 434 (see \fBcurs_variables\fP(3X)).
 435 .SH SEE ALSO
 436 \fB\%curs_addch\fP(3X) describes comparable functions of the
 437 .I \%ncurses
 438 library in its non-wide-character configuration.
 439 .PP
 440 \fB\%curses\fP(3X),
 441 \fB\%curs_addwstr\fP(3X),
 442 \fB\%curs_add_wchstr\fP(3X),
 443 \fB\%curs_attr\fP(3X),
 444 \fB\%curs_clear\fP(3X),
 445 \fB\%curs_getcchar\fP(3X),
 446 \fB\%curs_outopts\fP(3X),
 447 \fB\%curs_refresh\fP(3X),
 448 \fB\%curs_variables\fP(3X),
 449 \fB\%putwc\fP(3)