usr/src/man/man3xcurses/addnwstr.3xcurses

   1 '\" te
   2 .\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH ADDNWSTR 3XCURSES "Jun 5, 2002"
   7 .SH NAME
   8 addnwstr, addwstr, mvaddnwstr, mvaddwstr, mvwaddnwstr, mvwaddwstr, waddnwstr,
   9 waddwstr \- add a wide-character string to a window
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
  14 \fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]
  15
  16 \fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR ... ]
  17
  18 #include <curses.h>
  19
  20 \fBint\fR \fBaddnwstr\fR(\fBconst wchar_t *\fR\fIwstr\fR, \fBint\fR \fIn\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBaddwstr\fR(\fBconst wchar_t *\fR\fIwstr\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBint\fR \fBmvaddnwstr\fR(\fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBconst wchar_t *\fR\fIwstr\fR, \fBint\fR \fIn\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBint\fR \fBmvaddwstr\fR(\fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBconst wchar_t *\fR\fIwstr\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBint\fR \fBmvwaddnwstr\fR(\fBWINDOW*\fR\fIwin\fR, \fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBconst wchar_t *\fR\fIwstr\fR, \fBint\fR \fIn\fR);
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBint\fR \fBmvwaddwstr\fR(\fBWINDOW*\fR\fIwin\fR, \fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBconst wchar_t *\fR\fIwstr\fR);
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBint\fR \fBwaddnwstr\fR(\fBWINDOW*\fR\fIwin\fR, \fBconst wchar_t *\fR\fIwstr\fR, \fBint\fR \fIn\fR);
  51 .fi
  52
  53 .LP
  54 .nf
  55 \fBint\fR \fBwaddwstr\fR(\fBWINDOW*\fR\fIwin\fR, \fBconst wchar_t *\fR\fIwstr\fR);
  56 .fi
  57
  58 .SH DESCRIPTION
  59 .sp
  60 .LP
  61 The \fBaddwstr()\fR function writes a null-terminated wide-character string  to
  62 the \fBstdscr\fR window at the current cursor position.  The \fBwaddwstr()\fR
  63 function performs an identical action, but writes the  string to the window
  64 specified by \fIwin\fR.  The \fBmvaddwstr()\fR and \fBmvwaddwstr()\fR functions
  65 write the string to  the position indicated by the \fIx\fR (column) and \fIy\fR
  66 (row) parameters  (the former to the \fBstdscr\fR window; the latter to window
  67 \fIwin\fR).
  68 .sp
  69 .LP
  70 The \fBaddnwstr()\fR, \fBwaddnwstr()\fR, \fBmvaddnwstr()\fR, and
  71 \fBmvwaddnwstr()\fR functions write at most \fIn\fR characters to the  window.
  72 If \fIn\fR is less than 0, the entire string is written. The former two
  73 functions place the characters at the current cursor position;  the latter two
  74 commands use the position specified by the \fIx\fR and \fIy\fR parameters.
  75 .sp
  76 .LP
  77 All of these functions advance the cursor after writing the string.
  78 .sp
  79 .LP
  80 These functions are functionally equivalent to building a \fBcchar_t\fR from
  81 the \fBwchar_t\fR and the window rendition (or background character and
  82 rendition)  and calling the \fBwadd_wch\fR(3XCURSES) function once for each
  83 \fBwchar_t\fR in the string. Refer to the  \fBcurses\fR(3XCURSES) man page for
  84 a complete description of  special character handling and of the interaction
  85 between the window rendition (or background character and rendition) and the
  86 character written.
  87 .sp
  88 .LP
  89 Note that these functions differ from the \fBadd_wchnstr\fR(3XCURSES) set of
  90 functions  in that the latter copy the string as is (without combining each
  91 character  with the foreground and background attributes of the window).
  92 .SH PARAMETERS
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fIwstr\fR\fR
  97 .ad
  98 .RS 8n
  99 Is a pointer to the wide-character string that is to be written to the window.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fIn\fR\fR
 106 .ad
 107 .RS 8n
 108 Is the maximum number of characters to be copied from \fIwstr\fR. If \fIn\fR is
 109 less than 0, the entire string is written or as much of it as fits on the line.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fIy\fR\fR
 116 .ad
 117 .RS 8n
 118 Is the y (row) coordinate of the starting position of \fIwstr\fR in the window.
 119 .RE
 120
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fIx\fR\fR
 125 .ad
 126 .RS 8n
 127 Is the x (column) coordinate of the starting position of \fIwstr\fR in  the
 128 window.
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fIwin\fR\fR
 135 .ad
 136 .RS 8n
 137 Is a pointer to the window in which the string is to be written.
 138 .RE
 139
 140 .SH RETURN VALUES
 141 .sp
 142 .LP
 143 On success, these functions return \fBOK\fR. Otherwise, they return \fBERR\fR.
 144 .SH ERRORS
 145 .sp
 146 .LP
 147 None.
 148 .SH ATTRIBUTES
 149 .sp
 150 .LP
 151 See \fBattributes\fR(5) for descriptions of the following attributes:
 152 .sp
 153
 154 .sp
 155 .TS
 156 box;
 157 c | c
 158 l | l .
 159 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 160 _
 161 Interface Stability     Standard
 162 _
 163 MT-Level        Unsafe
 164 .TE
 165
 166 .SH SEE ALSO
 167 .sp
 168 .LP
 169 \fBadd_wch\fR(3XCURSES), \fBadd_wchnstr\fR(3XCURSES), \fBcurses\fR(3XCURSES),
 170 \fBlibcurses\fR(3XCURSES), \fBattributes\fR(5), \fBstandards\fR(5)