plucky (3) mvadd_wchnstr.3ncurses.gz

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 its remaining cells with the window's background  character;  see  bkgrnd(3NCURSES).   wadd_wchnstr
       does  the  same,  but  copies at most n characters, or as many as possible if n is -1.  ncurses(3NCURSES)
       describes the variants of these functions.

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

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

       •   do not represent unprintable characters with wunctrl(3NCURSES);

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

       •   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

       •   win is NULL or

       •   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

       X/Open  Curses  Issue 4  (1995)  initially  specified these functions.  The System V Interface Definition
       Version 4 of the same year 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.

SEE ALSO

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

       ncurses(3NCURSES), addwstr(3NCURSES), add_wch(3NCURSES)