https://invisible-island.net/ncurses/man/

curs_add_wchstr 3x 2024-07-27 ncurses 6.5 Library calls

curs_add_wchstr(3x)              Library calls             curs_add_wchstr(3x)

NAME

       add_wchstr,   wadd_wchstr,  mvadd_wchstr,  mvwadd_wchstr,  add_wchnstr,
       wadd_wchnstr, mvadd_wchnstr, mvwadd_wchnstr  -  add  a  curses  complex
       character string to a window

SYNOPSIS

       #include <curses.h>

       int add_wchstr(const cchar_t * wchstr);
       int wadd_wchstr(WINDOW *  win, const cchar_t * wchstr);
       int mvadd_wchstr(int y, int x, const cchar_t * wchstr);
       int mvwadd_wchstr(WINDOW * win, int y, int x, const cchar_t * wchstr);

       int add_wchnstr(const cchar_t * wchstr, int n);
       int wadd_wchnstr(WINDOW *  win, const cchar_t * wchstr, int n);
       int mvadd_wchnstr(int y, int x, const cchar_t * wchstr, int n);
       int mvwadd_wchnstr(WINDOW * win, int y, int x, const cchar_t * wchstr, int n);

DESCRIPTION

       wadd_wchstr  copies  the  string  of  complex  characters wchstr to the
       window win.  A null complex character  terminates  the  string.   If  a
       complex  character  does  not  completely  fit  at the end of the line,
       curses fills the remaining columns  with  the  window  background;  see
       bkgrnd(3x).    wadd_wchnstr  does  the  same,  but  copies  at  most  n
       characters, or as many as possible if n is -1.   ncurses(3x)  describes
       the variants of these functions.

       Because  these  functions do not call wadd_wch(3x) internally, they are
       faster than waddwstr(3x) and waddnwstr(3x).  On the other hand, they

       o   do  not  treat  the  backspace,  carriage  return,  or  line   feed
           characters specially;

       o   do not represent unprintable characters with wunctrl(3x);

       o   do  not  update  the  cursor  position to follow the last character
           written;

       o   truncate the string at  the  window's  right  margin,  rather  than
           wrapping it to the next line and potentially scrolling.

RETURN VALUE

       These functions return OK on success and ERR on failure.

       In ncurses, they return ERR if

       o   win is NULL or

       o   wchstr is NULL.

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

NOTES

       All of these  functions  except  wadd_wchnstr  may  be  implemented  as
       macros.

PORTABILITY

       X/Open  Curses,  Issue  4  describes  these functions.  It specifies no
       error conditions for them.

HISTORY

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