man/curs_addwstr.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2019-2023,2024 Thomas E. Dickey                                *
   3 .\" Copyright 2002-2012,2017 Free Software Foundation, Inc.                  *
   4 .\"                                                                          *
   5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   6 .\" copy of this software and associated documentation files (the            *
   7 .\" "Software"), to deal in the Software without restriction, including      *
   8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
   9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
  10 .\" copies of the Software, and to permit persons to whom the Software is    *
  11 .\" furnished to do so, subject to the following conditions:                 *
  12 .\"                                                                          *
  13 .\" The above copyright notice and this permission notice shall be included  *
  14 .\" in all copies or substantial portions of the Software.                   *
  15 .\"                                                                          *
  16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23 .\"                                                                          *
  24 .\" Except as contained in this notice, the name(s) of the above copyright   *
  25 .\" holders shall not be used in advertising or otherwise to promote the     *
  26 .\" sale, use or other dealings in this Software without prior written       *
  27 .\" authorization.                                                           *
  28 .\"***************************************************************************
  29 .\"
  30 .\" $Id: curs_addwstr.3x,v 1.35 2024/04/13 22:14:06 tom Exp $
  31 .TH curs_addwstr 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
  32 .ie \n(.g \{\
  33 .ds `` \(lq
  34 .ds '' \(rq
  35 .\}
  36 .el \{\
  37 .ie t .ds `` ``
  38 .el   .ds `` ""
  39 .ie t .ds '' ''
  40 .el   .ds '' ""
  41 .\}
  42 .
  43 .de bP
  44 .ie n  .IP \(bu 4
  45 .el    .IP \(bu 2
  46 ..
  47 .SH NAME
  48 \fB\%addwstr\fP,
  49 \fB\%addnwstr\fP,
  50 \fB\%waddwstr\fP,
  51 \fB\%waddnwstr\fP,
  52 \fB\%mvaddwstr\fP,
  53 \fB\%mvaddnwstr\fP,
  54 \fB\%mvwaddwstr\fP,
  55 \fB\%mvwaddnwstr\fP \-
  56 add a wide-character string to a \fIcurses\fR window and advance the cursor
  57 .SH SYNOPSIS
  58 .nf
  59 \fB#include <curses.h>
  60 .PP
  61 \fBint addwstr(const wchar_t *\fIwstr\fP);
  62 \fBint mvaddwstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP);
  63 \fBint mvwaddwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP);
  64 \fBint waddwstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP);
  65 .PP
  66 \fBint addnwstr(const wchar_t *\fIwstr\fP, int \fIn\fP);
  67 \fBint mvaddnwstr(int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
  68 \fBint mvwaddnwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
  69 \fBint waddnwstr(WINDOW *\fIwin\fP, const wchar_t *\fIwstr\fP, int \fIn\fP);
  70 .fi
  71 .SH DESCRIPTION
  72 .B waddwstr
  73 writes the characters of the (wide-null-terminated) wide-character
  74 string
  75 .I wstr
  76 to the window
  77 .IR win .
  78 Its process is similar to constructing a
  79 .I cchar_t
  80 for each
  81 .I wchar_t
  82 in
  83 .IR wstr ,
  84 then calling \fB\%wadd_wch\fP(3X) with the resulting
  85 .IR cchar_t .
  86 .bP
  87 Spacing and non-spacing characters in the string
  88 are processed one at a time,
  89 and
  90 .bP
  91 control characters are processed as in \fB\%wadd_wch\fP(3X).
  92 .PP
  93 .B waddnwstr
  94 writes at most
  95 .I n
  96 wide characters,
  97 or until a terminating wide null character occurs in
  98 .IR wstr .
  99 If
 100 .I n
 101 is \-1,
 102 .B
 103 .B waddnwstr
 104 writes the entire wide string.
 105 .PP
 106 \fB\%ncurses\fP(3X) describes the variants of these functions.
 107 .SH RETURN VALUE
 108 These functions return
 109 .B OK
 110 on success and
 111 .B ERR
 112 on failure.
 113 .PP
 114 X/Open Curses does not specify any error conditions.
 115 .I \%ncurses
 116 returns an error
 117 .bP
 118 if the window pointer is
 119 .BR NULL ,
 120 .bP
 121 if the string pointer is
 122 .BR NULL ,
 123 or
 124 .bP
 125 if an internal \fB\%wadd_wch\fP(3X) call returns an error.
 126 .PP
 127 Functions with a \*(``mv\*('' prefix first perform cursor movement using
 128 \fB\%wmove\fP(3X) and fail if the position is outside the window,
 129 or
 130 (for \*(``mvw\*('' functions)
 131 if the
 132 .I \%WINDOW
 133 pointer is null.
 134 .SH NOTES
 135 All of these functions except
 136 .B waddnwstr
 137 may be implemented as macros.
 138 .SH PORTABILITY
 139 X/Open Curses,
 140 Issue 4 describes these functions.
 141 .SH SEE ALSO
 142 \fB\%curs_addstr\fP(3X) describes comparable functions of the
 143 .I \%ncurses
 144 library in its non-wide-character configuration.
 145 .PP
 146 \fB\%curses\fP(3X),
 147 \fB\%curs_add_wch\fP(3X),
 148 \fB\%curs_add_wchstr\fP(3X)