doc/html/man/curs_add_wch.3x.html

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright 2019-2023,2024 Thomas E. Dickey                                *
   5   * Copyright 2001-2015,2017 Free Software Foundation, Inc.                  *
   6   *                                                                          *
   7   * Permission is hereby granted, free of charge, to any person obtaining a  *
   8   * copy of this software and associated documentation files (the            *
   9   * "Software"), to deal in the Software without restriction, including      *
  10   * without limitation the rights to use, copy, modify, merge, publish,      *
  11   * distribute, distribute with modifications, sublicense, and/or sell       *
  12   * copies of the Software, and to permit persons to whom the Software is    *
  13   * furnished to do so, subject to the following conditions:                 *
  14   *                                                                          *
  15   * The above copyright notice and this permission notice shall be included  *
  16   * in all copies or substantial portions of the Software.                   *
  17   *                                                                          *
  18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  19   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  20   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  21   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  22   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  23   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  24   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  25   *                                                                          *
  26   * Except as contained in this notice, the name(s) of the above copyright   *
  27   * holders shall not be used in advertising or otherwise to promote the     *
  28   * sale, use or other dealings in this Software without prior written       *
  29   * authorization.                                                           *
  30   ****************************************************************************
  31   * @Id: curs_add_wch.3x,v 1.67 2024/06/01 22:29:08 tom Exp @
  32 -->
  33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  34 <HTML>
  35 <HEAD>
  36 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  37 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  38 <TITLE>curs_add_wch 3x 2024-06-01 ncurses 6.5 Library calls</TITLE>
  39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  40
  41 </HEAD>
  42 <BODY>
  43 <H1 class="no-header">curs_add_wch 3x 2024-06-01 ncurses 6.5 Library calls</H1>
  44 <PRE>
  45 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>                 Library calls                <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
  46
  47
  48
  49
  50 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  51        <STRONG>add_wch</STRONG>, <STRONG>wadd_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, <STRONG>echo_wchar</STRONG>, <STRONG>wecho_wchar</STRONG> - add
  52        a <EM>curses</EM> complex character to a window, possibly advancing the cursor
  53
  54
  55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  56        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  57
  58        <STRONG>int</STRONG> <STRONG>add_wch(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>wadd_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>mvadd_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
  61        <STRONG>int</STRONG> <STRONG>mvwadd_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
  62
  63        <STRONG>int</STRONG> <STRONG>echo_wchar(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
  64        <STRONG>int</STRONG> <STRONG>wecho_wchar(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
  65
  66
  67 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  68
  69 </PRE><H3><a name="h3-wadd_wch">wadd_wch</a></H3><PRE>
  70        <STRONG>wadd_wch</STRONG> writes the complex character <EM>wch</EM> to the window <EM>win</EM>,  then  may
  71        advance  the  cursor  position, analogously to the standard C library's
  72        <STRONG>putwchar(3)</STRONG>.  <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function.
  73
  74        Much behavior depends on whether the wide characters in <EM>wch</EM> are spacing
  75        or non-spacing; see subsection "Complex Characters" below.
  76
  77        <STRONG>o</STRONG>   If  <EM>wch</EM>  contains  a  spacing  character, then any character at the
  78            cursor is first removed.   The  complex  character  <EM>wch</EM>,  with  its
  79            attributes  and  color  pair  identifier,  becomes  the <EM>base</EM> of the
  80            <EM>active</EM> <EM>complex</EM> <EM>character</EM>.
  81
  82        <STRONG>o</STRONG>   If <EM>wch</EM> contains only non-spacing characters, they are combined with
  83            the  active  complex  character.  <EM>curses</EM> ignores its attributes and
  84            color pair identifier, and does not advance the cursor.
  85
  86        Further non-spacing characters added with <STRONG>wadd_wch</STRONG> are not  written  at
  87        the  new  cursor position but combine with the active complex character
  88        until another spacing character is written to the window or the  cursor
  89        is moved.
  90
  91        If advancement occurs at the right margin,
  92
  93        <STRONG>o</STRONG>   the  cursor  automatically wraps to the beginning of the next line,
  94            then,
  95
  96        <STRONG>o</STRONG>   if  it  was  at  the  bottom  of  the  scrolling  region,  and   if
  97            <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>  is  enabled  for <EM>win</EM>, the scrolling region scrolls up
  98            one line.
  99
 100        If <EM>wch</EM> is a backspace, carriage return, line feed, or tab,  the  cursor
 101        moves appropriately within the window.
 102
 103        <STRONG>o</STRONG>   Backspace  moves  the cursor one character left; at the left margin
 104            of a window, it does nothing.
 105
 106        <STRONG>o</STRONG>   Carriage return moves the cursor to the left margin on the  current
 107            line of the window.
 108
 109        <STRONG>o</STRONG>   Line  feed  does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then advances as if from the right
 110            margin.
 111
 112        <STRONG>o</STRONG>   Tab advances the cursor to the next tab stop (possibly on the  next
 113            line);  these  are placed at every eighth column by default.  Alter
 114            the   tab   interval    with    the    <STRONG>TABSIZE</STRONG>    extension;    see
 115            <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
 116
 117        If  <EM>wch</EM>  is  any other nonprintable character, it is drawn in printable
 118        form using the same convention as <STRONG><A HREF="curs_util.3x.html">wunctrl(3x)</A></STRONG>.  Calling <STRONG><A HREF="curs_in_wch.3x.html">win_wch(3x)</A></STRONG>  on
 119        the  location of a nonprintable character does not return the character
 120        itself, but its <STRONG><A HREF="curs_util.3x.html">wunctrl(3x)</A></STRONG> representation.
 121
 122        A <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> can be copied from  place  to  place  using  <STRONG><A HREF="curs_in_wch.3x.html">win_wch(3x)</A></STRONG>  and
 123        <STRONG>wadd_wch</STRONG>.
 124
 125
 126 </PRE><H3><a name="h3-wecho_wchar">wecho_wchar</a></H3><PRE>
 127        <STRONG>echo_wchar</STRONG>   and  <STRONG>wecho_wchar</STRONG>  are  equivalent  to  calling  (<STRONG>w</STRONG>)<STRONG>add_wch</STRONG>
 128        followed by (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>.  <EM>curses</EM> interprets these functions  as  a  hint
 129        that only a single (complex) character is being output; for non-control
 130        characters, a considerable performance gain may be enjoyed by employing
 131        them.
 132
 133
 134 </PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE>
 135        <EM>curses</EM>  defines  macros  starting  with  <STRONG>WACS_</STRONG>  that  can  be used with
 136        <STRONG>wadd_wch</STRONG> to write line-drawing and  other  special  characters  to  the
 137        screen.  <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM>  The ACS default
 138        listed below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM>  capability  does
 139        not  define  a terminal-specific replacement for it, or if the terminal
 140        and locale configuration requires Unicode to  access  these  characters
 141        but  the  library  is  unable  to  use Unicode.  The "acsc char" column
 142        corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>)
 143        string capability, and the characters in it may appear on the screen if
 144        the terminal type's database entry incorrectly advertises ACS  support.
 145        The name "ACS" originates in the Alternate Character Set feature of the
 146        DEC VT100 terminal.
 147
 148                        <STRONG>Unicode</STRONG>   <STRONG>ACS</STRONG>       <STRONG>acsc</STRONG>
 149        <STRONG>Symbol</STRONG>          <STRONG>Default</STRONG>   <STRONG>Default</STRONG>   <STRONG>char</STRONG>   <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
 150        ------------------------------------------------------------------------
 151        <STRONG>WACS_BLOCK</STRONG>      0x25ae    #         0      solid square block
 152        <STRONG>WACS_BOARD</STRONG>      0x2592    #         h      board of squares
 153        <STRONG>WACS_BTEE</STRONG>       0x2534    +         v      bottom tee
 154        <STRONG>WACS_BULLET</STRONG>     0x00b7    o         ~      bullet
 155        <STRONG>WACS_CKBOARD</STRONG>    0x2592    :         a      checker board (stipple)
 156        <STRONG>WACS_DARROW</STRONG>     0x2193    v         .      arrow pointing down
 157        <STRONG>WACS_DEGREE</STRONG>     0x00b0    '         f      degree symbol
 158        <STRONG>WACS_DIAMOND</STRONG>    0x25c6    +         `      diamond
 159        <STRONG>WACS_GEQUAL</STRONG>     0x2265    &gt;         &gt;      greater-than-or-equal-to
 160        <STRONG>WACS_HLINE</STRONG>      0x2500    -         q      horizontal line
 161        <STRONG>WACS_LANTERN</STRONG>    0x2603    #         i      lantern symbol
 162        <STRONG>WACS_LARROW</STRONG>     0x2190    &lt;         ,      arrow pointing left
 163        <STRONG>WACS_LEQUAL</STRONG>     0x2264    &lt;         y      less-than-or-equal-to
 164        <STRONG>WACS_LLCORNER</STRONG>   0x2514    +         m      lower left-hand corner
 165        <STRONG>WACS_LRCORNER</STRONG>   0x2518    +         j      lower right-hand corner
 166        <STRONG>WACS_LTEE</STRONG>       0x2524    +         t      left tee
 167        <STRONG>WACS_NEQUAL</STRONG>     0x2260    !         |      not-equal
 168        <STRONG>WACS_PI</STRONG>         0x03c0    *         {      greek pi
 169        <STRONG>WACS_PLMINUS</STRONG>    0x00b1    #         g      plus/minus
 170        <STRONG>WACS_PLUS</STRONG>       0x253c    +         n      plus
 171        <STRONG>WACS_RARROW</STRONG>     0x2192    &gt;         +      arrow pointing right
 172        <STRONG>WACS_RTEE</STRONG>       0x251c    +         u      right tee
 173        <STRONG>WACS_S1</STRONG>         0x23ba    -         o      scan line 1
 174        <STRONG>WACS_S3</STRONG>         0x23bb    -         p      scan line 3
 175        <STRONG>WACS_S7</STRONG>         0x23bc    -         r      scan line 7
 176        <STRONG>WACS_S9</STRONG>         0x23bd    _         s      scan line 9
 177        <STRONG>WACS_STERLING</STRONG>   0x00a3    f         }      pound-sterling symbol
 178        <STRONG>WACS_TTEE</STRONG>       0x252c    +         w      top tee
 179        <STRONG>WACS_UARROW</STRONG>     0x2191    ^         -      arrow pointing up
 180        <STRONG>WACS_ULCORNER</STRONG>   0x250c    +         l      upper left-hand corner
 181        <STRONG>WACS_URCORNER</STRONG>   0x2510    +         k      upper right-hand corner
 182
 183        <STRONG>WACS_VLINE</STRONG>      0x2502    |         x      vertical line
 184
 185        The wide-character configuration of <EM>ncurses</EM> also  defines  symbols  for
 186        thick lines (<STRONG>acsc</STRONG> "J" to "V"):
 187
 188                          <STRONG>Unicode</STRONG>   <STRONG>ASCII</STRONG>     <STRONG>acsc</STRONG>
 189        <STRONG>ACS</STRONG> <STRONG>Name</STRONG>          <STRONG>Default</STRONG>   <STRONG>Default</STRONG>   <STRONG>Char</STRONG>   <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
 190        ------------------------------------------------------------------------
 191        <STRONG>WACS_T_BTEE</STRONG>       0x253b    +         V      thick tee pointing up
 192        <STRONG>WACS_T_HLINE</STRONG>      0x2501    -         Q      thick horizontal line
 193        <STRONG>WACS_T_LLCORNER</STRONG>   0x2517    +         M      thick lower left corner
 194        <STRONG>WACS_T_LRCORNER</STRONG>   0x251b    +         J      thick lower right corner
 195        <STRONG>WACS_T_LTEE</STRONG>       0x252b    +         T      thick tee pointing right
 196        <STRONG>WACS_T_PLUS</STRONG>       0x254b    +         N      thick large plus
 197        <STRONG>WACS_T_RTEE</STRONG>       0x2523    +         U      thick tee pointing left
 198        <STRONG>WACS_T_TTEE</STRONG>       0x2533    +         W      thick tee pointing down
 199        <STRONG>WACS_T_ULCORNER</STRONG>   0x250f    +         L      thick upper left corner
 200        <STRONG>WACS_T_URCORNER</STRONG>   0x2513    +         K      thick upper right corner
 201        <STRONG>WACS_T_VLINE</STRONG>      0x2503    |         X      thick vertical line
 202
 203        and for double-lines (<STRONG>acsc</STRONG> "A" to "I"):
 204
 205                          <STRONG>Unicode</STRONG>   <STRONG>ASCII</STRONG>     <STRONG>acsc</STRONG>
 206        <STRONG>ACS</STRONG> <STRONG>Name</STRONG>          <STRONG>Default</STRONG>   <STRONG>Default</STRONG>   <STRONG>Char</STRONG>   <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
 207        ------------------------------------------------------------------------
 208        <STRONG>WACS_D_BTEE</STRONG>       0x2569    +         H      double tee pointing up
 209        <STRONG>WACS_D_HLINE</STRONG>      0x2550    -         R      double horizontal line
 210        <STRONG>WACS_D_LLCORNER</STRONG>   0x255a    +         D      double lower left corner
 211        <STRONG>WACS_D_LRCORNER</STRONG>   0x255d    +         A      double lower right corner
 212        <STRONG>WACS_D_LTEE</STRONG>       0x2560    +         F      double tee pointing right
 213        <STRONG>WACS_D_PLUS</STRONG>       0x256c    +         E      double large plus
 214        <STRONG>WACS_D_RTEE</STRONG>       0x2563    +         G      double tee pointing left
 215        <STRONG>WACS_D_TTEE</STRONG>       0x2566    +         I      double tee pointing down
 216        <STRONG>WACS_D_ULCORNER</STRONG>   0x2554    +         C      double upper left corner
 217        <STRONG>WACS_D_URCORNER</STRONG>   0x2557    +         B      double upper right corner
 218        <STRONG>WACS_D_VLINE</STRONG>      0x2551    |         Y      double vertical line
 219
 220        Unicode's  descriptions  for  these  characters  differs  slightly from
 221        <EM>ncurses</EM>, by introducing the term "light"  (along  with  less  important
 222        details).   Here are its descriptions for the normal, thick, and double
 223        horizontal lines:
 224
 225        <STRONG>o</STRONG>   U+2500 BOX DRAWINGS LIGHT HORIZONTAL
 226
 227        <STRONG>o</STRONG>   U+2501 BOX DRAWINGS HEAVY HORIZONTAL
 228
 229        <STRONG>o</STRONG>   U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
 230
 231
 232 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 233        These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.   In  <EM>ncurses</EM>,
 234        <STRONG>wadd_wch</STRONG> returns <STRONG>ERR</STRONG> if
 235
 236        <STRONG>o</STRONG>   <EM>win</EM> is <STRONG>NULL</STRONG>,
 237
 238        <STRONG>o</STRONG>   wrapping  to  a new line is impossible because <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> has not
 239            been called on <EM>win</EM> when writing to its  bottom  right  location  is
 240            attempted, or
 241
 242        <STRONG>o</STRONG>   it  is  not  possible  to  add  a  complete character at the cursor
 243            position.
 244
 245        Functions prefixed with "mv" first perform cursor movement and fail  if
 246        the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
 247
 248
 249 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 250        <STRONG>add_wch</STRONG>,  <STRONG>mvadd_wch</STRONG>,  <STRONG>mvwadd_wch</STRONG>,  and <STRONG>echo_wchar</STRONG> may be implemented as
 251        macros.
 252
 253
 254 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 255
 256 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
 257        The <STRONG>TABSIZE</STRONG> variable is implemented  in  SVr4  and  other  versions  of
 258        <EM>curses</EM>, but is not specified by X/Open Curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).
 259
 260
 261 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 262        These  functions are described in X/Open Curses, Issue 4.  It specifies
 263        no error conditions for them.
 264
 265        The defaults specified for forms-drawing characters apply in the  POSIX
 266        locale.   X/Open Curses makes it clear that the WACS_ symbols should be
 267        defined as a pointer to  <STRONG>cchar_t</STRONG>  data,  e.g.,  in  the  discussion  of
 268        <STRONG>border_set</STRONG>.  A few implementations are problematic:
 269
 270        <STRONG>o</STRONG>   NetBSD curses defines the symbols as a <STRONG>wchar_t</STRONG> within a <STRONG>cchar_t</STRONG>.
 271
 272        <STRONG>o</STRONG>   HP-UX  curses  equates  some  of  the <STRONG>ACS_</STRONG> symbols to the analogous
 273            <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols  were  wide  characters.   The
 274            misdefined  symbols  are the arrows and other symbols which are not
 275            used for line-drawing.
 276
 277        X/Open Curses does not specify  symbols  for  thick-  or  double-lines.
 278        SVr4 curses implementations defined their line-drawing symbols in terms
 279        of intermediate symbols.  This implementation  extends  those  symbols,
 280        providing new definitions which are not in the SVr4 implementations.
 281
 282        Not  all  Unicode-capable  terminals  provide  support  for VT100-style
 283        alternate character  sets  (i.e.,  the  <STRONG>acsc</STRONG>  capability),  with  their
 284        corresponding  line-drawing  characters.  X/Open Curses did not address
 285        the  aspect  of  integrating  Unicode  with  line-drawing   characters.
 286        Existing  implementations of Unix curses (AIX, HP-UX, Solaris) use only
 287        the <STRONG>acsc</STRONG> character-mapping to provide this feature.  As a result, those
 288        implementations  can  only  use  single-byte  line-drawing  characters.
 289        <EM>ncurses</EM> 5.3 (2002) provided a table of Unicode values  to  solve  these
 290        problems.  NetBSD curses incorporated that table in 2010.
 291
 292        In  this  implementation,  the  Unicode  values are used instead of the
 293        terminal description's <STRONG>acsc</STRONG> mapping as discussed in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> for the
 294        environment  variable  <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM>.   In contrast, for the same
 295        cases, the line-drawing characters described in <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG> will use only
 296        the ASCII default values.
 297
 298        Having  Unicode available does not solve all of the problems with line-
 299        drawing for curses:
 300
 301        <STRONG>o</STRONG>   The closest Unicode equivalents to the VT100 graphics  <EM>S1</EM>,  <EM>S3</EM>,  <EM>S7</EM>
 302            and  <EM>S9</EM> frequently are not displayed at the regular intervals which
 303            the terminal used.
 304
 305        <STRONG>o</STRONG>   The <EM>lantern</EM> is a special case.  It originated with  the  AT&amp;T  4410
 306            terminal  in the early 1980s.  There is no accessible documentation
 307            depicting the lantern symbol on the AT&amp;T terminal.
 308
 309            Lacking documentation, most readers assume that a <EM>storm</EM> <EM>lantern</EM> was
 310            intended.  But there are several possibilities, all with problems.
 311
 312            Unicode  6.0  (2010)  does provide two lantern symbols: U+1F383 and
 313            U+1F3EE.  Those were not available  in  2002,  and  are  irrelevant
 314            since  they  lie  outside the BMP and as a result are not generally
 315            available in terminals.  They are not storm lanterns, in any case.
 316
 317            Most <EM>storm</EM> <EM>lanterns</EM> have a tapering glass chimney (to guard against
 318            tipping); some have a wire grid protecting the chimney.
 319
 320            For  the  tapering  appearance,   U+2603 was adequate.  In use on a
 321            terminal, no one can tell what the image represents.  Unicode calls
 322            it a snowman.
 323
 324            Others have suggested these alternatives: &lt;section&gt; U+00A7 (section
 325            mark), &lt;Theta&gt; U+0398 (theta), &lt;Phi&gt; U+03A6 (phi),  &lt;delta&gt;  U+03B4
 326            (delta),  U+2327 (x in a rectangle),  U+256C (forms double vertical
 327            and horizontal), and  U+2612 (ballot box with x).
 328
 329
 330 </PRE><H3><a name="h3-Complex-Characters">Complex Characters</a></H3><PRE>
 331        The complex character  type  <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>  can  store  more  than  one  wide
 332        character  (<EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>).  X/Open Curses does not mention this possibility,
 333        specifying behavior only  where  <EM>wch</EM>  is  a  single  character,  either
 334        spacing or non-spacing.
 335
 336        <EM>ncurses</EM> assumes that <EM>wch</EM> is constructed using <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG>, and in turn
 337        that the result
 338
 339        <STRONG>o</STRONG>   contains at most one spacing character at the beginning of its list
 340            of wide characters, and zero or more non-spacing characters, or
 341
 342        <STRONG>o</STRONG>   holds one non-spacing character.
 343
 344        In  the  latter  case,  <EM>ncurses</EM>  adds  the non-spacing character to the
 345        active complex character.
 346
 347
 348 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 349        These functions were initially specified by  X/Open  Curses,  Issue  4.
 350        The   System V   Interface  Definition,  Version  4  (1995),  specified
 351        functions named <EM>waddwch</EM> and <EM>wechowchar</EM> (and the usual variants).  These
 352        were later additions to SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989).
 353        They differed from X/Open's <EM>wadd</EM><STRONG>_</STRONG><EM>wch</EM> and <EM>wecho</EM><STRONG>_</STRONG><EM>wchar</EM> in that they  each
 354        took an argument of type <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> instead of <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>.
 355
 356
 357 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 358        <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in
 359        its non-wide-character configuration.
 360
 361        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,   <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>,   <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>,   <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,
 362        <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>,  <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>,
 363        <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putwc(3)</STRONG>
 364
 365
 366
 367 ncurses 6.5                       2024-06-01                  <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
 368 </PRE>
 369 <div class="nav">
 370 <ul>
 371 <li><a href="#h2-NAME">NAME</a></li>
 372 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 373 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 374 <ul>
 375 <li><a href="#h3-wadd_wch">wadd_wch</a></li>
 376 <li><a href="#h3-wecho_wchar">wecho_wchar</a></li>
 377 <li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li>
 378 </ul>
 379 </li>
 380 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 381 <li><a href="#h2-NOTES">NOTES</a></li>
 382 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a>
 383 <ul>
 384 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
 385 </ul>
 386 </li>
 387 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 388 <ul>
 389 <li><a href="#h3-Complex-Characters">Complex Characters</a></li>
 390 </ul>
 391 </li>
 392 <li><a href="#h2-HISTORY">HISTORY</a></li>
 393 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 394 </ul>
 395 </div>
 396 </BODY>
 397 </HTML>