curs_add_wch 3x 2024-06-01 ncurses 6.5 Library calls

curs_add_wch(3x)                 Library calls                curs_add_wch(3x)


       add_wch, wadd_wch, mvadd_wch, mvwadd_wch, echo_wchar, wecho_wchar - add
       a curses complex character to a window, possibly advancing the cursor


       #include <curses.h>

       int add_wch(const cchar_t *wch);
       int wadd_wch(WINDOW *win, const cchar_t *wch);
       int mvadd_wch(int y, int x, const cchar_t *wch);
       int mvwadd_wch(WINDOW *win, int y, int x, const cchar_t *wch);

       int echo_wchar(const cchar_t *wch);
       int wecho_wchar(WINDOW *win, const cchar_t *wch);



       wadd_wch writes the complex character wch to the window win,  then  may
       advance  the  cursor  position, analogously to the standard C library's
       putwchar(3).  ncurses(3x) describes the variants of this function.

       Much behavior depends on whether the wide characters in wch are spacing
       or non-spacing; see subsection "Complex Characters" below.

       o   If  wch  contains  a  spacing  character, then any character at the
           cursor is first removed.   The  complex  character  wch,  with  its
           attributes  and  color  pair  identifier,  becomes  the base of the
           active complex character.

       o   If wch contains only non-spacing characters, they are combined with
           the  active  complex  character.  curses ignores its attributes and
           color pair identifier, and does not advance the cursor.

       Further non-spacing characters added with wadd_wch are not  written  at
       the  new  cursor position but combine with the active complex character
       until another spacing character is written to the window or the  cursor
       is moved.

       If advancement occurs at the right margin,

       o   the  cursor  automatically wraps to the beginning of the next line,

       o   if  it  was  at  the  bottom  of  the  scrolling  region,  and   if
           scrollok(3x)  is  enabled  for win, the scrolling region scrolls up
           one line.

       If wch is a backspace, carriage return, line feed, or tab,  the  cursor
       moves appropriately within the window.

       o   Backspace  moves  the cursor one character left; at the left margin
           of a window, it does nothing.

       o   Carriage return moves the cursor to the left margin on the  current
           line of the window.

       o   Line  feed  does a clrtoeol(3x), then advances as if from the right

       o   Tab advances the cursor to the next tab stop (possibly on the  next
           line);  these  are placed at every eighth column by default.  Alter
           the   tab   interval    with    the    TABSIZE    extension;    see

       If  wch  is  any other nonprintable character, it is drawn in printable
       form using the same convention as wunctrl(3x).  Calling win_wch(3x)  on
       the  location of a nonprintable character does not return the character
       itself, but its wunctrl(3x) representation.

       A cchar_t can be copied from  place  to  place  using  win_wch(3x)  and


       echo_wchar   and  wecho_wchar  are  equivalent  to  calling  (w)add_wch
       followed by (w)refresh.  curses interprets these functions  as  a  hint
       that only a single (complex) character is being output; for non-control
       characters, a considerable performance gain may be enjoyed by employing

Forms-Drawing Characters

       curses  defines  macros  starting  with  WACS_  that  can  be used with
       wadd_wch to write line-drawing and  other  special  characters  to  the
       screen.  ncurses terms these forms-drawing characters.  The ACS default
       listed below is used if the acs_chars (acsc) terminfo  capability  does
       not  define  a terminal-specific replacement for it, or if the terminal
       and locale configuration requires Unicode to  access  these  characters
       but  the  library  is  unable  to  use Unicode.  The "acsc char" column
       corresponds to how the characters are specified in the acs_chars (acsc)
       string capability, and the characters in it may appear on the screen if
       the terminal type's database entry incorrectly advertises ACS  support.
       The name "ACS" originates in the Alternate Character Set feature of the
       DEC VT100 terminal.

                       Unicode   ACS       acsc
       Symbol          Default   Default   char   Glyph Name
       WACS_BLOCK      0x25ae    #         0      solid square block
       WACS_BOARD      0x2592    #         h      board of squares
       WACS_BTEE       0x2534    +         v      bottom tee
       WACS_BULLET     0x00b7    o         ~      bullet
       WACS_CKBOARD    0x2592    :         a      checker board (stipple)
       WACS_DARROW     0x2193    v         .      arrow pointing down
       WACS_DEGREE     0x00b0    '         f      degree symbol
       WACS_DIAMOND    0x25c6    +         `      diamond
       WACS_GEQUAL     0x2265    >         >      greater-than-or-equal-to
       WACS_HLINE      0x2500    -         q      horizontal line
       WACS_LANTERN    0x2603    #         i      lantern symbol
       WACS_LARROW     0x2190    <         ,      arrow pointing left
       WACS_LEQUAL     0x2264    <         y      less-than-or-equal-to
       WACS_LLCORNER   0x2514    +         m      lower left-hand corner
       WACS_LRCORNER   0x2518    +         j      lower right-hand corner
       WACS_LTEE       0x2524    +         t      left tee
       WACS_NEQUAL     0x2260    !         |      not-equal
       WACS_PI         0x03c0    *         {      greek pi
       WACS_PLMINUS    0x00b1    #         g      plus/minus
       WACS_PLUS       0x253c    +         n      plus
       WACS_RARROW     0x2192    >         +      arrow pointing right
       WACS_RTEE       0x251c    +         u      right tee
       WACS_S1         0x23ba    -         o      scan line 1
       WACS_S3         0x23bb    -         p      scan line 3
       WACS_S7         0x23bc    -         r      scan line 7
       WACS_S9         0x23bd    _         s      scan line 9
       WACS_STERLING   0x00a3    f         }      pound-sterling symbol
       WACS_TTEE       0x252c    +         w      top tee
       WACS_UARROW     0x2191    ^         -      arrow pointing up
       WACS_ULCORNER   0x250c    +         l      upper left-hand corner
       WACS_URCORNER   0x2510    +         k      upper right-hand corner

       WACS_VLINE      0x2502    |         x      vertical line

       The wide-character configuration of ncurses also  defines  symbols  for
       thick lines (acsc "J" to "V"):

                         Unicode   ASCII     acsc
       ACS Name          Default   Default   Char   Glyph Name
       WACS_T_BTEE       0x253b    +         V      thick tee pointing up
       WACS_T_HLINE      0x2501    -         Q      thick horizontal line
       WACS_T_LLCORNER   0x2517    +         M      thick lower left corner
       WACS_T_LRCORNER   0x251b    +         J      thick lower right corner
       WACS_T_LTEE       0x252b    +         T      thick tee pointing right
       WACS_T_PLUS       0x254b    +         N      thick large plus
       WACS_T_RTEE       0x2523    +         U      thick tee pointing left
       WACS_T_TTEE       0x2533    +         W      thick tee pointing down
       WACS_T_ULCORNER   0x250f    +         L      thick upper left corner
       WACS_T_URCORNER   0x2513    +         K      thick upper right corner
       WACS_T_VLINE      0x2503    |         X      thick vertical line

       and for double-lines (acsc "A" to "I"):

                         Unicode   ASCII     acsc
       ACS Name          Default   Default   Char   Glyph Name
       WACS_D_BTEE       0x2569    +         H      double tee pointing up
       WACS_D_HLINE      0x2550    -         R      double horizontal line
       WACS_D_LLCORNER   0x255a    +         D      double lower left corner
       WACS_D_LRCORNER   0x255d    +         A      double lower right corner
       WACS_D_LTEE       0x2560    +         F      double tee pointing right
       WACS_D_PLUS       0x256c    +         E      double large plus
       WACS_D_RTEE       0x2563    +         G      double tee pointing left
       WACS_D_TTEE       0x2566    +         I      double tee pointing down
       WACS_D_ULCORNER   0x2554    +         C      double upper left corner
       WACS_D_URCORNER   0x2557    +         B      double upper right corner
       WACS_D_VLINE      0x2551    |         Y      double vertical line

       Unicode's  descriptions  for  these  characters  differs  slightly from
       ncurses, by introducing the term "light"  (along  with  less  important
       details).   Here are its descriptions for the normal, thick, and double
       horizontal lines:





       These functions return OK on success and ERR on failure.   In  ncurses,
       wadd_wch returns ERR if

       o   win is NULL,

       o   wrapping  to  a new line is impossible because scrollok(3x) has not
           been called on win when writing to its  bottom  right  location  is
           attempted, or

       o   it  is  not  possible  to  add  a  complete character at the cursor

       Functions prefixed with "mv" first perform cursor movement and fail  if
       the position (y, x) is outside the window boundaries.


       add_wch,  mvadd_wch,  mvwadd_wch,  and echo_wchar may be implemented as



       The TABSIZE variable is implemented  in  SVr4  and  other  versions  of
       curses, but is not specified by X/Open Curses (see curs_variables(3x)).


       These  functions are described in X/Open Curses, Issue 4.  It specifies
       no error conditions for them.

       The defaults specified for forms-drawing characters apply in the  POSIX
       locale.   X/Open Curses makes it clear that the WACS_ symbols should be
       defined as a pointer to  cchar_t  data,  e.g.,  in  the  discussion  of
       border_set.  A few implementations are problematic:

       o   NetBSD curses defines the symbols as a wchar_t within a cchar_t.

       o   HP-UX  curses  equates  some  of  the ACS_ symbols to the analogous
           WACS_ symbols as if the ACS_ symbols  were  wide  characters.   The
           misdefined  symbols  are the arrows and other symbols which are not
           used for line-drawing.

       X/Open Curses does not specify  symbols  for  thick-  or  double-lines.
       SVr4 curses implementations defined their line-drawing symbols in terms
       of intermediate symbols.  This implementation  extends  those  symbols,
       providing new definitions which are not in the SVr4 implementations.

       Not  all  Unicode-capable  terminals  provide  support  for VT100-style
       alternate character  sets  (i.e.,  the  acsc  capability),  with  their
       corresponding  line-drawing  characters.  X/Open Curses did not address
       the  aspect  of  integrating  Unicode  with  line-drawing   characters.
       Existing  implementations of Unix curses (AIX, HP-UX, Solaris) use only
       the acsc character-mapping to provide this feature.  As a result, those
       implementations  can  only  use  single-byte  line-drawing  characters.
       ncurses 5.3 (2002) provided a table of Unicode values  to  solve  these
       problems.  NetBSD curses incorporated that table in 2010.

       In  this  implementation,  the  Unicode  values are used instead of the
       terminal description's acsc mapping as discussed in ncurses(3x) for the
       environment  variable  NCURSES_NO_UTF8_ACS.   In contrast, for the same
       cases, the line-drawing characters described in addch(3x) will use only
       the ASCII default values.

       Having  Unicode available does not solve all of the problems with line-
       drawing for curses:

       o   The closest Unicode equivalents to the VT100 graphics  S1,  S3,  S7
           and  S9 frequently are not displayed at the regular intervals which
           the terminal used.

       o   The lantern is a special case.  It originated with  the  AT&T  4410
           terminal  in the early 1980s.  There is no accessible documentation
           depicting the lantern symbol on the AT&T terminal.

           Lacking documentation, most readers assume that a storm lantern was
           intended.  But there are several possibilities, all with problems.

           Unicode  6.0  (2010)  does provide two lantern symbols: U+1F383 and
           U+1F3EE.  Those were not available  in  2002,  and  are  irrelevant
           since  they  lie  outside the BMP and as a result are not generally
           available in terminals.  They are not storm lanterns, in any case.

           Most storm lanterns have a tapering glass chimney (to guard against
           tipping); some have a wire grid protecting the chimney.

           For  the  tapering  appearance,   U+2603 was adequate.  In use on a
           terminal, no one can tell what the image represents.  Unicode calls
           it a snowman.

           Others have suggested these alternatives: <section> U+00A7 (section
           mark), <Theta> U+0398 (theta), <Phi> U+03A6 (phi),  <delta>  U+03B4
           (delta),  U+2327 (x in a rectangle),  U+256C (forms double vertical
           and horizontal), and  U+2612 (ballot box with x).

Complex Characters

       The complex character  type  cchar_t  can  store  more  than  one  wide
       character  (wchar_t).  X/Open Curses does not mention this possibility,
       specifying behavior only  where  wch  is  a  single  character,  either
       spacing or non-spacing.

       ncurses assumes that wch is constructed using setcchar(3x), and in turn
       that the result

       o   contains at most one spacing character at the beginning of its list
           of wide characters, and zero or more non-spacing characters, or

       o   holds one non-spacing character.

       In  the  latter  case,  ncurses  adds  the non-spacing character to the
       active complex character.


       These functions were initially specified by  X/Open  Curses,  Issue  4.
       The   System V   Interface  Definition,  Version  4  (1995),  specified
       functions named waddwch and wechowchar (and the usual variants).  These
       were later additions to SVr4.x, not appearing in the first SVr4 (1989).
       They differed from X/Open's wadd_wch and wecho_wchar in that they  each
       took an argument of type wchar_t instead of cchar_t.


       curs_addch(3x) describes comparable functions of the ncurses library in
       its non-wide-character configuration.

       curses(3x),   curs_addwstr(3x),   curs_add_wchstr(3x),   curs_attr(3x),
       curs_clear(3x),  curs_getcchar(3x), curs_outopts(3x), curs_refresh(3x),
       curs_variables(3x), putwc(3)

ncurses 6.5                       2024-06-01                  curs_add_wch(3x)