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.50 2019/11/30 20:07:00 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. Some implementa-
190 tions are problematic:
192 <STRONG>o</STRONG> Some implementations define the ACS symbols to a constant (such as
193 Solaris), while others define those to entries in an array.
195 This implementation uses an array <STRONG>acs_map</STRONG>, as done in SVr4 curses.
196 NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG>
199 <STRONG>o</STRONG> HPUX curses equates some of the <EM>ACS</EM><STRONG>_</STRONG> symbols to the analogous <EM>WACS</EM><STRONG>_</STRONG>
200 symbols as if the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters. The misde-
201 fined symbols are the arrows and other symbols which are not used
204 <STRONG>o</STRONG> X/Open Curses (issues 2 through 7) has a typographical error for
205 the ACS_LANTERN symbol, equating its "VT100+ Character" to <STRONG>I</STRONG> (capi-
206 tal I), while the header files for SVr4 curses and the various
207 implementations use <STRONG>i</STRONG> (lowercase).
209 None of the terminal descriptions on Unix platforms use uppercase-
210 I, except for Solaris (i.e., <EM>screen</EM>'s terminal description, appar-
211 ently based on the X/Open documentation around 1995). On the other
212 hand, the terminal description <EM>gs6300</EM> (AT&T PC6300 with EMOTS Ter-
213 minal Emulator) uses lowercase-i.
215 Some ACS symbols (ACS_S3, ACS_S7, ACS_LEQUAL, ACS_GEQUAL, ACS_PI,
216 ACS_NEQUAL, ACS_STERLING) were not documented in any publicly released
217 System V. However, many publicly available terminfos include <STRONG>acsc</STRONG>
218 strings in which their key characters (pryz{|}) are embedded, and a
219 second-hand list of their character descriptions has come to light.
220 The ACS-prefixed names for them were invented for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
222 The <EM>displayed</EM> values for the <EM>ACS</EM><STRONG>_</STRONG> and <EM>WACS</EM><STRONG>_</STRONG> constants depend on
224 <STRONG>o</STRONG> the library configuration, i.e., <STRONG>ncurses</STRONG> versus <STRONG>ncursesw</STRONG>, where the
225 latter is capable of displaying Unicode while the former is not,
228 <STRONG>o</STRONG> whether the <EM>locale</EM> uses UTF-8 encoding.
230 In certain cases, the terminal is unable to display line-drawing char-
231 acters except by using UTF-8 (see the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG>
232 in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>).
235 </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
236 X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a
237 single character. As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, that character may
238 have been more than eight bits in an SVr3 or SVr4 implementation, but
239 in the X/Open Curses model, the details are not given. The important
240 distinction between SVr4 curses and X/Open Curses is that the non-char-
241 acter information (attributes and color) was separated from the charac-
242 ter information which is packed in a <STRONG>chtype</STRONG> to pass to <STRONG>waddch</STRONG>.
244 In this implementation, <STRONG>chtype</STRONG> holds an eight-bit character. But
245 ncurses allows multibyte characters to be passed in a succession of
246 calls to <STRONG>waddch</STRONG>. The other implementations do not do this; a call to
247 <STRONG>waddch</STRONG> passes exactly one character which may be rendered as one or
248 more cells on the screen depending on whether it is printable.
250 Depending on the locale settings, ncurses will inspect the byte passed
251 in each call to <STRONG>waddch</STRONG>, and check if the latest call will continue a
252 multibyte sequence. When a character is <EM>complete</EM>, ncurses displays the
253 character and moves to the next position in the screen.
255 If the calling application interrupts the succession of bytes in a
256 multibyte character by moving the current location (e.g., using <STRONG>wmove</STRONG>),
257 ncurses discards the partially built character, starting over again.
259 For portability to other implementations, do not rely upon this behav-
262 <STRONG>o</STRONG> check if a character can be represented as a single byte in the
263 current locale before attempting call <STRONG>waddch</STRONG>, and
265 <STRONG>o</STRONG> call <STRONG>wadd_wch</STRONG> for characters which cannot be handled by <STRONG>waddch</STRONG>.
268 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
269 The <STRONG>TABSIZE</STRONG> variable is implemented in SVr4 and other versions of
270 curses, but is not part of X/Open curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> for
273 If <EM>ch</EM> is a carriage return, the cursor is moved to the beginning of the
274 current row of the window. This is true of other implementations, but
278 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
279 <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>
280 <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>.
282 Comparable functions in the wide-character (ncursesw) library are
283 described in <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>.
287 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
291 <li><a href="#h2-NAME">NAME</a></li>
292 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
293 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
295 <li><a href="#h3-Adding-characters">Adding characters</a></li>
296 <li><a href="#h3-Echoing-characters">Echoing characters</a></li>
297 <li><a href="#h3-Line-Graphics">Line Graphics</a></li>
300 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
301 <li><a href="#h2-NOTES">NOTES</a></li>
302 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
304 <li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
305 <li><a href="#h3-Character-Set">Character Set</a></li>
306 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
309 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
projects / ncurses.git / blob