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

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright 2019-2021,2023 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.38 2023/08/06 00:03:38 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 2023-08-05 ncurses 6.4 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 2023-08-05 ncurses 6.4 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 complex character and rendition to a <STRONG>curses</STRONG> window, then advance  the
  53        cursor
  54
  55
  56 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  57        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  58
  59        <STRONG>int</STRONG> <STRONG>add_wch(</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM> <STRONG>);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>wadd_wch(</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM> <STRONG>);</STRONG>
  61        <STRONG>int</STRONG> <STRONG>mvadd_wch(</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        <STRONG>int</STRONG> <STRONG>mvwadd_wch(</STRONG> <STRONG>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>
  63
  64        <STRONG>int</STRONG> <STRONG>echo_wchar(</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM> <STRONG>);</STRONG>
  65        <STRONG>int</STRONG> <STRONG>wecho_wchar(</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM> <STRONG>);</STRONG>
  66
  67
  68 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  69
  70 </PRE><H3><a name="h3-add_wch">add_wch</a></H3><PRE>
  71        The  <STRONG>add_wch</STRONG>,  <STRONG>wadd_wch</STRONG>,  <STRONG>mvadd_wch</STRONG>,  and  <STRONG>mvwadd_wch</STRONG> functions put the
  72        complex character <EM>wch</EM> into the given window at  its  current  position,
  73        which  is then advanced.  These functions perform wrapping and special-
  74        character processing as follows:
  75
  76        <STRONG>o</STRONG>   If <EM>wch</EM> refers to a spacing character, then any  previous  character
  77            at  that  location is removed.  A new character specified by <EM>wch</EM> is
  78            placed at that location  with  rendition  specified  by  <EM>wch</EM>.   The
  79            cursor  then  advances after this spacing character, to prepare for
  80            writing the next character on the screen.
  81
  82            The newly added spacing character is the base of the active complex
  83            character.   Subsequent non-spacing characters can be combined with
  84            this base until another spacing character is written to the screen,
  85            or the cursor is moved, e.g., using <STRONG>wmove</STRONG>.
  86
  87        <STRONG>o</STRONG>   If  <EM>wch</EM>  refers  to  a non-spacing character, it is appended to the
  88            active complex character, retaining the previous characters at that
  89            location.  The rendition specified by <EM>wch</EM> is ignored.
  90
  91            The  cursor  is  not advanced after adding a non-spacing character.
  92            Subsequent calls to add non-spacing characters will update the same
  93            position.
  94
  95        <STRONG>o</STRONG>   If  the character part of <EM>wch</EM> is a tab, newline, backspace or other
  96            control character, the window is updated and the cursor moves as if
  97            <STRONG>addch</STRONG> were called.
  98
  99
 100 </PRE><H3><a name="h3-echo_wchar">echo_wchar</a></H3><PRE>
 101        The <STRONG>echo_wchar</STRONG> function is functionally equivalent to a call to <STRONG>add_wch</STRONG>
 102        followed by a call  to  <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>.   Similarly,  the  <STRONG>wecho_wchar</STRONG>  is
 103        functionally  equivalent  to  a  call to <STRONG>wadd_wch</STRONG> followed by a call to
 104        <STRONG>wrefresh</STRONG>.  The knowledge that only a single character is  being  output
 105        is   taken  into  consideration  and,  for  non-control  characters,  a
 106        considerable performance  gain  might  be  seen  by  using  the  *<STRONG>echo</STRONG>*
 107        functions instead of their equivalents.
 108
 109
 110 </PRE><H3><a name="h3-Line-Graphics">Line Graphics</a></H3><PRE>
 111        Like  <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>, <STRONG>addch_wch</STRONG> accepts symbols which make it simple to draw
 112        lines and other frequently  used  special  characters.   These  symbols
 113        correspond to the same VT100 line-drawing set as <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>.
 114
 115        <STRONG>ACS</STRONG>               <STRONG>Unicode</STRONG>    <STRONG>ASCII</STRONG>     <STRONG>acsc</STRONG>    <STRONG>Glyph</STRONG>
 116
 117        <STRONG>Name</STRONG>              <STRONG>Default</STRONG>    <STRONG>Default</STRONG>   <STRONG>char</STRONG>    <STRONG>Name</STRONG>
 118        ------------------------------------------------------------------------
 119        WACS_BLOCK        0x25ae     #         0       solid square block
 120        WACS_BOARD        0x2592     #         h       board of squares
 121        WACS_BTEE         0x2534     +         v       bottom tee
 122        WACS_BULLET       0x00b7     o         ~       bullet
 123        WACS_CKBOARD      0x2592     :         a       checker board (stipple)
 124        WACS_DARROW       0x2193     v         .       arrow pointing down
 125        WACS_DEGREE       0x00b0     '         f       degree symbol
 126        WACS_DIAMOND      0x25c6     +         `       diamond
 127        WACS_GEQUAL       0x2265     &gt;         &gt;       greater-than-or-equal-to
 128        WACS_HLINE        0x2500     -         q       horizontal line
 129        WACS_LANTERN      0x2603     #         i       lantern symbol
 130        WACS_LARROW       0x2190     &lt;         ,       arrow pointing left
 131        WACS_LEQUAL       0x2264     &lt;         y       less-than-or-equal-to
 132        WACS_LLCORNER     0x2514     +         m       lower left-hand corner
 133        WACS_LRCORNER     0x2518     +         j       lower right-hand corner
 134        WACS_LTEE         0x2524     +         t       left tee
 135        WACS_NEQUAL       0x2260     !         |       not-equal
 136        WACS_PI           0x03c0     *         {       greek pi
 137        WACS_PLMINUS      0x00b1     #         g       plus/minus
 138        WACS_PLUS         0x253c     +         n       plus
 139        WACS_RARROW       0x2192     &gt;         +       arrow pointing right
 140        WACS_RTEE         0x251c     +         u       right tee
 141        WACS_S1           0x23ba     -         o       scan line 1
 142        WACS_S3           0x23bb     -         p       scan line 3
 143        WACS_S7           0x23bc     -         r       scan line 7
 144        WACS_S9           0x23bd     _         s       scan line 9
 145        WACS_STERLING     0x00a3     f         }       pound-sterling symbol
 146        WACS_TTEE         0x252c     +         w       top tee
 147        WACS_UARROW       0x2191     ^         -       arrow pointing up
 148        WACS_ULCORNER     0x250c     +         l       upper left-hand corner
 149        WACS_URCORNER     0x2510     +         k       upper right-hand corner
 150        WACS_VLINE        0x2502     |         x       vertical line
 151
 152        The  wide-character  configuration  of ncurses also defines symbols for
 153        thick lines (<STRONG>acsc</STRONG> "J" to "V"):
 154
 155        <STRONG>ACS</STRONG>               <STRONG>Unicode</STRONG>   <STRONG>ASCII</STRONG>     <STRONG>acsc</STRONG>    <STRONG>Glyph</STRONG>
 156        <STRONG>Name</STRONG>              <STRONG>Default</STRONG>   <STRONG>Default</STRONG>   <STRONG>char</STRONG>    <STRONG>Name</STRONG>
 157        -----------------------------------------------------------------------
 158        WACS_T_BTEE       0x253b    +         V       thick tee pointing up
 159        WACS_T_HLINE      0x2501    -         Q       thick horizontal line
 160        WACS_T_LLCORNER   0x2517    +         M       thick lower left corner
 161        WACS_T_LRCORNER   0x251b    +         J       thick lower right corner
 162        WACS_T_LTEE       0x252b    +         T       thick tee pointing right
 163        WACS_T_PLUS       0x254b    +         N       thick large plus
 164        WACS_T_RTEE       0x2523    +         U       thick tee pointing left
 165        WACS_T_TTEE       0x2533    +         W       thick tee pointing down
 166        WACS_T_ULCORNER   0x250f    +         L       thick upper left corner
 167        WACS_T_URCORNER   0x2513    +         K       thick upper right corner
 168        WACS_T_VLINE      0x2503    |         X       thick vertical line
 169
 170        and for double-lines (<STRONG>acsc</STRONG> "A" to "I"):
 171
 172        <STRONG>ACS</STRONG>               <STRONG>Unicode</STRONG>   <STRONG>ASCII</STRONG>     <STRONG>acsc</STRONG>    <STRONG>Glyph</STRONG>
 173        <STRONG>Name</STRONG>              <STRONG>Default</STRONG>   <STRONG>Default</STRONG>   <STRONG>char</STRONG>    <STRONG>Name</STRONG>
 174        ------------------------------------------------------------------------
 175        WACS_D_BTEE       0x2569    +         H       double tee pointing up
 176        WACS_D_HLINE      0x2550    -         R       double horizontal line
 177        WACS_D_LLCORNER   0x255a    +         D       double lower left corner
 178        WACS_D_LRCORNER   0x255d    +         A       double lower right corner
 179        WACS_D_LTEE       0x2560    +         F       double tee pointing right
 180        WACS_D_PLUS       0x256c    +         E       double large plus
 181        WACS_D_RTEE       0x2563    +         G       double tee pointing left
 182
 183        WACS_D_TTEE       0x2566    +         I       double tee pointing down
 184        WACS_D_ULCORNER   0x2554    +         C       double upper left corner
 185        WACS_D_URCORNER   0x2557    +         B       double upper right corner
 186        WACS_D_VLINE      0x2551    |         Y       double vertical line
 187
 188        Unicode's descriptions  for  these  characters  differs  slightly  from
 189        ncurses,  by  introducing  the  term "light" (along with less important
 190        details).  Here are its descriptions for the normal, thick, and  double
 191        horizontal lines:
 192
 193        <STRONG>o</STRONG>   U+2500 BOX DRAWINGS LIGHT HORIZONTAL
 194
 195        <STRONG>o</STRONG>   U+2501 BOX DRAWINGS HEAVY HORIZONTAL
 196
 197        <STRONG>o</STRONG>   U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
 198
 199
 200 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 201        All routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success.
 202
 203        X/Open  does  not  define  any  error  conditions.  This implementation
 204        returns an error
 205
 206        <STRONG>o</STRONG>   if the window pointer is null or
 207
 208        <STRONG>o</STRONG>   if it is not possible to add a complete character in the window.
 209
 210        The latter may be due to different causes:
 211
 212        <STRONG>o</STRONG>   If <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not enabled, writing a character  at  the  lower
 213            right margin succeeds.  However, an error is returned because it is
 214            not possible to wrap to a new line
 215
 216        <STRONG>o</STRONG>   If an error is detected when converting a multibyte character to  a
 217            sequence  of  bytes,  or  if  it  is not possible to add all of the
 218            resulting bytes in the window, an error is returned.
 219
 220        Functions with a "mv" prefix first  perform  a  cursor  movement  using
 221        <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
 222        the window pointer is null.
 223
 224
 225 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 226        Note that <STRONG>add_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, and <STRONG>echo_wchar</STRONG> may be macros.
 227
 228
 229 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 230        All of these functions are described in the XSI Curses standard,  Issue
 231        4.   The  defaults  specified  for line-drawing characters apply in the
 232        POSIX locale.
 233
 234
 235 </PRE><H3><a name="h3-WACS-Symbols">WACS Symbols</a></H3><PRE>
 236        X/Open Curses makes it clear that the WACS_ symbols should  be  defined
 237        as a pointer to <STRONG>cchar_t</STRONG> data, e.g., in the discussion of <STRONG>border_set</STRONG>.  A
 238        few implementations are problematic:
 239
 240        <STRONG>o</STRONG>   NetBSD curses defines the symbols as a <STRONG>wchar_t</STRONG> within a <STRONG>cchar_t</STRONG>.
 241
 242        <STRONG>o</STRONG>   HPUX curses equates some of the <STRONG>ACS_</STRONG> symbols to the analogous <STRONG>WACS_</STRONG>
 243            symbols   as  if  the  <STRONG>ACS_</STRONG>  symbols  were  wide  characters.   The
 244            misdefined symbols are the arrows and other symbols which  are  not
 245            used for line-drawing.
 246
 247        X/Open Curses does not define symbols for thick- or double-lines.  SVr4
 248        curses implementations defined their line-drawing symbols in  terms  of
 249        intermediate  symbols.   This  implementation  extends  those  symbols,
 250        providing new definitions which are not in the SVr4 implementations.
 251
 252        Not all  Unicode-capable  terminals  provide  support  for  VT100-style
 253        alternate  character  sets  (i.e.,  the  <STRONG>acsc</STRONG>  capability),  with their
 254        corresponding line-drawing characters.  X/Open Curses did  not  address
 255        the   aspect  of  integrating  Unicode  with  line-drawing  characters.
 256        Existing implementations of Unix curses (AIX, HPUX, Solaris)  use  only
 257        the <STRONG>acsc</STRONG> character-mapping to provide this feature.  As a result, those
 258        implementations  can  only  use  single-byte  line-drawing  characters.
 259        Ncurses  5.3  (2002)  provided a table of Unicode values to solve these
 260        problems.  NetBSD curses incorporated that table in 2010.
 261
 262        In this implementation, the Unicode values  are  used  instead  of  the
 263        terminal description's <STRONG>acsc</STRONG> mapping as discussed in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> for the
 264        environment variable <STRONG>NCURSES_NO_UTF8_ACS</STRONG>.  In contrast,  for  the  same
 265        cases, the line-drawing characters described in <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> will use
 266        only the ASCII default values.
 267
 268        Having Unicode available does not solve all of the problems with  line-
 269        drawing for curses:
 270
 271        <STRONG>o</STRONG>   The  closest  Unicode  equivalents to the VT100 graphics <EM>S1</EM>, <EM>S3</EM>, <EM>S7</EM>
 272            and <EM>S9</EM> frequently are not displayed at the regular intervals  which
 273            the terminal used.
 274
 275        <STRONG>o</STRONG>   The  <EM>lantern</EM>  is  a special case.  It originated with the AT&amp;T 4410
 276            terminal in the early 1980s.  There is no accessible  documentation
 277            depicting the lantern symbol on the AT&amp;T terminal.
 278
 279            Lacking documentation, most readers assume that a <EM>storm</EM> <EM>lantern</EM> was
 280            intended.  But there are several possibilities, all with problems.
 281
 282            Unicode 6.0 (2010) does provide two lantern  symbols:  U+1F383  and
 283            U+1F3EE.   Those  were  not  available  in 2002, and are irrelevant
 284            since they lie outside the BMP and as a result  are  not  generally
 285            available in terminals.  They are not storm lanterns, in any case.
 286
 287            Most <EM>storm</EM> <EM>lanterns</EM> have a tapering glass chimney (to guard against
 288            tipping); some have a wire grid protecting the chimney.
 289
 290            For the tapering appearance,  U+2603 was adequate.   In  use  on  a
 291            terminal, no one can tell what the image represents.  Unicode calls
 292            it a snowman.
 293
 294            Others have suggested these alternatives: &lt;section&gt; U+00A7 (section
 295            mark),  &lt;Theta&gt;  U+0398 (theta), &lt;Phi&gt; U+03A6 (phi), &lt;delta&gt; U+03B4
 296            (delta),  U+2327 (x in a rectangle),  U+256C (forms double vertical
 297            and horizontal), and  U+2612 (ballot box with x).
 298
 299
 300 </PRE><H3><a name="h3-Complex-Characters">Complex Characters</a></H3><PRE>
 301        The  complex  character  type  <STRONG>cchar_t</STRONG>  can  store  more  than one wide
 302        character (<STRONG>wchar_t</STRONG>).  The X/Open Curses description  does  not  mention
 303        this  possibility,  describing  only  the  cases where <EM>wch</EM> is a spacing
 304        character or a non-spacing character.
 305
 306        This implementation assumes that <EM>wch</EM> is constructed using <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG>,
 307        and in turn that the result
 308
 309        <STRONG>o</STRONG>   contains at most one spacing character in the beginning of its list
 310            of wide characters, and zero or more non-spacing characters or
 311
 312        <STRONG>o</STRONG>   may hold one non-spacing character.
 313
 314        In the latter case, ncurses  adds  the  non-spacing  character  to  the
 315        active (base) spacing character.
 316
 317
 318 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 319        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>,
 320        <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>, <STRONG>putwc(3)</STRONG>
 321
 322
 323
 324 ncurses 6.4                       2023-08-05                  <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
 325 </PRE>
 326 <div class="nav">
 327 <ul>
 328 <li><a href="#h2-NAME">NAME</a></li>
 329 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 330 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 331 <ul>
 332 <li><a href="#h3-add_wch">add_wch</a></li>
 333 <li><a href="#h3-echo_wchar">echo_wchar</a></li>
 334 <li><a href="#h3-Line-Graphics">Line Graphics</a></li>
 335 </ul>
 336 </li>
 337 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 338 <li><a href="#h2-NOTES">NOTES</a></li>
 339 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 340 <ul>
 341 <li><a href="#h3-WACS-Symbols">WACS Symbols</a></li>
 342 <li><a href="#h3-Complex-Characters">Complex Characters</a></li>
 343 </ul>
 344 </li>
 345 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 346 </ul>
 347 </div>
 348 </BODY>
 349 </HTML>