- These routines insert a wchar_t character string (as many characters as
- will fit on the line) before the character under the cursor. All char-
- acters to the right of the cursor are shifted right, with the possibil-
- ity of the rightmost characters on the line being lost. No wrapping is
- performed. The cursor position does not change (after moving to y, x,
- if specified). The four routines with n as the last argument insert a
- leading substring of at most nwchar_t characters. If n is less than
- 1, the entire string is inserted.
-
- If a character in wstr is a tab, newline, carriage return or backspace,
- the cursor is moved appropriately within the window. A newline also
- does a clrtoeol before moving. Tabs are considered to be at every
- eighth column. If a character in wstr is another control character, it
- is drawn in the ^X notation. Calling win_wch after adding a control
- character (and moving to it, if necessary) does not return the control
- character, but instead returns a character in the ^-representation of
- the control character.
+ wins_wstr inserts a wide-character string wstr before the character at
+ the cursor in window win as if by calling wins_wch(3x) for each wchar_t
+ in wstr. No line wrapping is performed. Characters to the right of
+ the cursor are shifted right; those at the right edge of the window may
+ be lost. wins_wstr stops inserting if it would have to wrap to the
+ next line to write the next wchar_t in wstr. The cursor position does
+ not change (after moving to (y, x), if specified). wins_nwstr does the
+ same, but inserts at most n characters, or as many as possible (up to
+ the end of the line) if n is -1. ncurses(3x) describes the variants of
+ these functions.
+
+
+
+ These functions return OK on success and ERR on failure.
+
+ In ncurses, they return ERR if
+
+ owin is NULL,
+
+ owstr is NULL,
+
+ o the first wide character in wstr is a non-spacing character, or
+
+ o an internal wins_wch(3x) call returns ERR.
+
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (y, x) is outside the window boundaries.
- Note that all but wins_nwstr may be macros.
+ All of these functions except wins_nwstr may be implemented as macros.
- If the first character in the string is a nonspacing character, these
- functions will fail. XSI does not define what will happen if a non-
- spacing character follows a control character.
+
- Upon successful completion, these functions return OK. Otherwise, they
- return ERR.
+ X/Open Curses does not specify what happens if a non-spacing character
+ follows a control character.
+
+ Issue 4 states that the entire string is inserted if n is less than 1.
+ This is probably an error, because it is inconsistent with other
+ functions such as waddwstr(3x), and differs from the SVr4 curses and
+ Solaris xcurses implementations. Nevertheless, Issue 7 retains the
+ language.
- Functions with a "mv" prefix first perform a cursor movement using
- wmove, and return an error if the position is outside the window, or if
- the window pointer is null.
+
+
+ These functions were initially specified by X/Open Curses, Issue 4.
+ The System V Interface Definition, Version 4 (1995), specified
+ functions named winswstr and winsnwstr (and the usual variants). These
+ were later additions to SVr4.x, not appearing in the first SVr4 (1989).
+ They differ from X/Open's later wins_wstr and wins_nwstr in that their
+ wstr parameters are not const-qualified.