3 ****************************************************************************
4 * Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
6 * Permission is hereby granted, free of charge, to any person obtaining a *
7 * copy of this software and associated documentation files (the *
8 * "Software"), to deal in the Software without restriction, including *
9 * without limitation the rights to use, copy, modify, merge, publish, *
10 * distribute, distribute with modifications, sublicense, and/or sell *
11 * copies of the Software, and to permit persons to whom the Software is *
12 * furnished to do so, subject to the following conditions: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 * Except as contained in this notice, the name(s) of the above copyright *
26 * holders shall not be used in advertising or otherwise to promote the *
27 * sale, use or other dealings in this Software without prior written *
29 ****************************************************************************
30 * @Id: curs_addch.3x,v 1.47 2019/02/16 23:50:17 tom Exp @
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
37 <TITLE>curs_addch 3x</TITLE>
38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
42 <H1 class="no-header">curs_addch 3x</H1>
44 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
50 <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, <STRONG>echochar</STRONG>, <STRONG>wechochar</STRONG> - add a character
51 (with attributes) to a <STRONG>curses</STRONG> window, then advance the cursor
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
57 <STRONG>int</STRONG> <STRONG>addch(const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG>
58 <STRONG>int</STRONG> <STRONG>waddch(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG>
59 <STRONG>int</STRONG> <STRONG>mvaddch(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG>
60 <STRONG>int</STRONG> <STRONG>mvwaddch(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG>
61 <STRONG>int</STRONG> <STRONG>echochar(const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG>
62 <STRONG>int</STRONG> <STRONG>wechochar(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG>
65 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
67 </PRE><H3><a name="h3-Adding-characters">Adding characters</a></H3><PRE>
68 The <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG> and <STRONG>mvwaddch</STRONG> routines put the character <EM>ch</EM>
69 into the given window at its current window position, which is then
70 advanced. They are analogous to <STRONG>putchar(3)</STRONG> in <STRONG>stdio(3)</STRONG>. If the
71 advance is at the right margin:
73 <STRONG>o</STRONG> The cursor automatically wraps to the beginning of the next line.
75 <STRONG>o</STRONG> At the bottom of the current scrolling region, and if <STRONG>scrollok</STRONG> is
76 enabled, the scrolling region is scrolled up one line.
78 <STRONG>o</STRONG> If <STRONG>scrollok</STRONG> is not enabled, writing a character at the lower right
79 margin succeeds. However, an error is returned because it is not
80 possible to wrap to a new line
82 If <EM>ch</EM> is a tab, newline, carriage return or backspace, the cursor is
83 moved appropriately within the window:
85 <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left edge of
86 a window it does nothing.
88 <STRONG>o</STRONG> Carriage return moves the cursor to the window left margin on the
91 <STRONG>o</STRONG> Newline does a <STRONG>clrtoeol</STRONG>, then moves the cursor to the window left
92 margin on the next line, scrolling the window if on the last line.
94 <STRONG>o</STRONG> Tabs are considered to be at every eighth column. The tab interval
95 may be altered by setting the <STRONG>TABSIZE</STRONG> variable.
97 If <EM>ch</EM> is any other control character, it is drawn in <STRONG>^</STRONG><EM>X</EM> notation.
98 Calling <STRONG>winch</STRONG> after adding a control character does not return the
99 character itself, but instead returns the ^-representation of the con-
102 Video attributes can be combined with a character argument passed to
103 <STRONG>addch</STRONG> or related functions by logical-ORing them into the character.
104 (Thus, text, including attributes, can be copied from one place to
105 another using <STRONG><A HREF="curs_inch.3x.html">inch(3x)</A></STRONG> and <STRONG>addch</STRONG>.) See the <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> page for val-
106 ues of predefined video attribute constants that can be usefully OR'ed
110 </PRE><H3><a name="h3-Echoing-characters">Echoing characters</a></H3><PRE>
111 The <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> routines are equivalent to a call to <STRONG>addch</STRONG>
112 followed by a call to <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>, or a call to <STRONG>waddch</STRONG> followed by a
113 call to <STRONG>wrefresh</STRONG>. The knowledge that only a single character is being
114 output is used and, for non-control characters, a considerable perfor-
115 mance gain may be seen by using these routines instead of their equiva-
119 </PRE><H3><a name="h3-Line-Graphics">Line Graphics</a></H3><PRE>
120 The following variables may be used to add line drawing characters to
121 the screen with routines of the <STRONG>addch</STRONG> family. The default character
122 listed below is used if the <STRONG>acsc</STRONG> capability does not define a terminal-
123 specific replacement for it, or if the terminal and locale configura-
124 tion requires Unicode but the library is unable to use Unicode.
126 The names are taken from VT100 nomenclature.
128 <STRONG>ACS</STRONG> <STRONG>ACS</STRONG> <STRONG>acsc</STRONG> <STRONG>Glyph</STRONG>
129 <STRONG>Name</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Name</STRONG>
130 ---------------------------------------------------------
131 ACS_BLOCK # 0 solid square block
132 ACS_BOARD # h board of squares
133 ACS_BTEE + v bottom tee
134 ACS_BULLET o ~ bullet
135 ACS_CKBOARD : a checker board (stipple)
136 ACS_DARROW v . arrow pointing down
137 ACS_DEGREE ' f degree symbol
138 ACS_DIAMOND + ` diamond
139 ACS_GEQUAL > > greater-than-or-equal-to
140 ACS_HLINE - q horizontal line
141 ACS_LANTERN # i lantern symbol
142 ACS_LARROW < , arrow pointing left
143 ACS_LEQUAL < y less-than-or-equal-to
144 ACS_LLCORNER + m lower left-hand corner
145 ACS_LRCORNER + j lower right-hand corner
146 ACS_LTEE + t left tee
147 ACS_NEQUAL ! | not-equal
149 ACS_PLMINUS # g plus/minus
151 ACS_RARROW > + arrow pointing right
152 ACS_RTEE + u right tee
153 ACS_S1 - o scan line 1
154 ACS_S3 - p scan line 3
155 ACS_S7 - r scan line 7
156 ACS_S9 _ s scan line 9
157 ACS_STERLING f } pound-sterling symbol
159 ACS_UARROW ^ - arrow pointing up
160 ACS_ULCORNER + l upper left-hand corner
161 ACS_URCORNER + k upper right-hand corner
162 ACS_VLINE | x vertical line
165 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
166 All routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success (the
167 SVr4 manuals specify only "an integer value other than <STRONG>ERR</STRONG>") upon suc-
168 cessful completion, unless otherwise noted in the preceding routine
171 Functions with a "mv" prefix first perform a cursor movement using
172 <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
173 the window pointer is null.
176 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
177 Note that <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be macros.
180 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
181 All these functions are described in the XSI Curses standard, Issue 4.
182 The defaults specified for forms-drawing characters apply in the POSIX
186 </PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE>
187 X/Open Curses states that the <EM>ACS</EM><STRONG>_</STRONG> definitions are <STRONG>char</STRONG> constants. For
188 the wide-character implementation (see <STRONG>curs_add_wch</STRONG>), there are analo-
189 gous <EM>WACS</EM><STRONG>_</STRONG> definitions which are <STRONG>cchar_t</STRONG> constants.
191 Some ACS symbols (ACS_S3, ACS_S7, ACS_LEQUAL, ACS_GEQUAL, ACS_PI,
192 ACS_NEQUAL, ACS_STERLING) were not documented in any publicly released
193 System V. However, many publicly available terminfos include <STRONG>acsc</STRONG>
194 strings in which their key characters (pryz{|}) are embedded, and a
195 second-hand list of their character descriptions has come to light.
196 The ACS-prefixed names for them were invented for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
198 The <EM>displayed</EM> values for the <EM>ACS</EM><STRONG>_</STRONG> and <EM>WACS</EM><STRONG>_</STRONG> constants depend on
200 <STRONG>o</STRONG> the library configuration, i.e., <STRONG>ncurses</STRONG> versus <STRONG>ncursesw</STRONG>, where the
201 latter is capable of displaying Unicode while the former is not,
204 <STRONG>o</STRONG> whether the <EM>locale</EM> uses UTF-8 encoding.
206 In certain cases, the terminal is unable to display line-drawing char-
207 acters except by using UTF-8 (see the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG>
208 in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>).
211 </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
212 X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a
213 single character. As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, that character may
214 have been more than eight bits in an SVr3 or SVr4 implementation, but
215 in the X/Open Curses model, the details are not given. The important
216 distinction between SVr4 curses and X/Open Curses is that the non-char-
217 acter information (attributes and color) was separated from the charac-
218 ter information which is packed in a <STRONG>chtype</STRONG> to pass to <STRONG>waddch</STRONG>.
220 In this implementation, <STRONG>chtype</STRONG> holds eight bits. But ncurses allows
221 multibyte characters to be passed in a succession of calls to <STRONG>waddch</STRONG>.
222 The other implementations do not do this; a call to <STRONG>waddch</STRONG> passes
223 exactly one character which may be rendered as one or more cells on the
224 screen depending on whether it is printable.
226 Depending on the locale settings, ncurses will inspect the byte passed
227 in each call to <STRONG>waddch</STRONG>, and check if the latest call will continue a
228 multibyte sequence. When a character is <EM>complete</EM>, ncurses displays the
229 character and moves to the next position in the screen.
231 If the calling application interrupts the succession of bytes in a
232 multibyte character by moving the current location (e.g., using <STRONG>wmove</STRONG>),
233 ncurses discards the partially built character, starting over again.
235 For portability to other implementations, do not rely upon this behav-
238 <STRONG>o</STRONG> check if a character can be represented as a single byte in the
239 current locale before attempting call <STRONG>waddch</STRONG>, and
241 <STRONG>o</STRONG> call <STRONG>wadd_wch</STRONG> for characters which cannot be handled by <STRONG>waddch</STRONG>.
244 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
245 The <STRONG>TABSIZE</STRONG> variable is implemented in SVr4 and other versions of
246 curses, but is not part of X/Open curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> for
249 If <EM>ch</EM> is a carriage return, the cursor is moved to the beginning of the
250 current row of the window. This is true of other implementations, but
254 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
255 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG>curs_out-</STRONG>
256 <STRONG><A HREF="curs_outopts.3x.html">opts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>.
258 Comparable functions in the wide-character (ncursesw) library are
259 described in <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>.
263 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
267 <li><a href="#h2-NAME">NAME</a></li>
268 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
269 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
271 <li><a href="#h3-Adding-characters">Adding characters</a></li>
272 <li><a href="#h3-Echoing-characters">Echoing characters</a></li>
273 <li><a href="#h3-Line-Graphics">Line Graphics</a></li>
276 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
277 <li><a href="#h2-NOTES">NOTES</a></li>
278 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
280 <li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
281 <li><a href="#h3-Character-Set">Character Set</a></li>
282 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
285 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>