ncurses 6.2 - patch 20210109
[ncurses.git] / doc / html / man / curs_addch.3x.html
1 <!-- 
2   * t
3   ****************************************************************************
4   * Copyright 2018-2019,2020 Thomas E. Dickey                                *
5   * Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
6   *                                                                          *
7   * Permission is hereby granted, free of charge, to any person obtaining a  *
8   * copy of this software and associated documentation files (the            *
9   * "Software"), to deal in the Software without restriction, including      *
10   * without limitation the rights to use, copy, modify, merge, publish,      *
11   * distribute, distribute with modifications, sublicense, and/or sell       *
12   * copies of the Software, and to permit persons to whom the Software is    *
13   * furnished to do so, subject to the following conditions:                 *
14   *                                                                          *
15   * The above copyright notice and this permission notice shall be included  *
16   * in all copies or substantial portions of the Software.                   *
17   *                                                                          *
18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
19   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
20   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
21   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
22   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
23   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
24   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
25   *                                                                          *
26   * Except as contained in this notice, the name(s) of the above copyright   *
27   * holders shall not be used in advertising or otherwise to promote the     *
28   * sale, use or other dealings in this Software without prior written       *
29   * authorization.                                                           *
30   ****************************************************************************
31   * @Id: curs_addch.3x,v 1.55 2020/10/24 09:12:31 tom Exp @
32 -->
33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
34 <HTML>
35 <HEAD>
36 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
37 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
38 <TITLE>curs_addch 3x</TITLE>
39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
40 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
41 </HEAD>
42 <BODY>
43 <H1 class="no-header">curs_addch 3x</H1>
44 <PRE>
45 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>                                                  <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
46
47
48
49
50 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
51        <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, <STRONG>echochar</STRONG>, <STRONG>wechochar</STRONG> - add a character
52        (with attributes) to a <STRONG>curses</STRONG> window, then advance the cursor
53
54
55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
56        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
57
58        <STRONG>int</STRONG> <STRONG>addch(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
59        <STRONG>int</STRONG> <STRONG>waddch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
60        <STRONG>int</STRONG> <STRONG>mvaddch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
61        <STRONG>int</STRONG> <STRONG>mvwaddch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
62
63        <STRONG>int</STRONG> <STRONG>echochar(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
64        <STRONG>int</STRONG> <STRONG>wechochar(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
65
66
67 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
68
69 </PRE><H3><a name="h3-Adding-characters">Adding characters</a></H3><PRE>
70        The <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG> and <STRONG>mvwaddch</STRONG> routines put the  character  <EM>ch</EM>
71        into  the  given  window  at its current window position, which is then
72        advanced.  They are  analogous  to  <STRONG>putchar(3)</STRONG>  in  <STRONG>stdio(3)</STRONG>.   If  the
73        advance is at the right margin:
74
75        <STRONG>o</STRONG>   The cursor automatically wraps to the beginning of the next line.
76
77        <STRONG>o</STRONG>   At  the  bottom of the current scrolling region, and if <STRONG>scrollok</STRONG> is
78            enabled, the scrolling region is scrolled up one line.
79
80        <STRONG>o</STRONG>   If <STRONG>scrollok</STRONG> is not enabled, writing a character at the lower  right
81            margin  succeeds.   However, an error is returned because it is not
82            possible to wrap to a new line
83
84        If <EM>ch</EM> is a tab, newline, carriage return or backspace,  the  cursor  is
85        moved appropriately within the window:
86
87        <STRONG>o</STRONG>   Backspace  moves the cursor one character left; at the left edge of
88            a window it does nothing.
89
90        <STRONG>o</STRONG>   Carriage return moves the cursor to the window left margin  on  the
91            current line.
92
93        <STRONG>o</STRONG>   Newline  does  a <STRONG>clrtoeol</STRONG>, then moves the cursor to the window left
94            margin on the next line, scrolling the window if on the last line.
95
96        <STRONG>o</STRONG>   Tabs are considered to be at every eighth column.  The tab interval
97            may be altered by setting the <STRONG>TABSIZE</STRONG> variable.
98
99        If  <EM>ch</EM>  is  any  other nonprintable character, it is drawn in printable
100        form, i.e., the <STRONG>^</STRONG><EM>X</EM> notation used by <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>.   Calling  <STRONG>winch</STRONG>  after
101        adding  a  nonprintable character does not return the character itself,
102        but instead returns the printable representation of the character.
103
104        Video attributes can be combined with a character  argument  passed  to
105        <STRONG>addch</STRONG>  or  related  functions by logical-ORing them into the character.
106        (Thus, text, including attributes, can be  copied  from  one  place  to
107        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-
108        ues of predefined video attribute constants that can be usefully  OR'ed
109        into characters.
110
111
112 </PRE><H3><a name="h3-Echoing-characters">Echoing characters</a></H3><PRE>
113        The  <STRONG>echochar</STRONG>  and <STRONG>wechochar</STRONG> routines are equivalent to a call to <STRONG>addch</STRONG>
114        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
115        call  to <STRONG>wrefresh</STRONG>.  The knowledge that only a single character is being
116        output is used and, for non-control characters, a considerable  perfor-
117        mance gain may be seen by using these routines instead of their equiva-
118        lents.
119
120
121 </PRE><H3><a name="h3-Line-Graphics">Line Graphics</a></H3><PRE>
122        The following variables may be used to add line drawing  characters  to
123        the  screen  with  routines of the <STRONG>addch</STRONG> family.  The default character
124        listed below is used if the <STRONG>acsc</STRONG> capability does not define a terminal-
125        specific  replacement  for it, or if the terminal and locale configura-
126        tion requires Unicode but the library is unable to use Unicode.
127
128        The names are taken from VT100 nomenclature.
129
130        <STRONG>ACS</STRONG>            <STRONG>ACS</STRONG>       <STRONG>acsc</STRONG>   <STRONG>Glyph</STRONG>
131        <STRONG>Name</STRONG>           <STRONG>Default</STRONG>   <STRONG>char</STRONG>   <STRONG>Name</STRONG>
132        ---------------------------------------------------------
133        ACS_BLOCK      #         0      solid square block
134        ACS_BOARD      #         h      board of squares
135        ACS_BTEE       +         v      bottom tee
136        ACS_BULLET     o         ~      bullet
137        ACS_CKBOARD    :         a      checker board (stipple)
138        ACS_DARROW     v         .      arrow pointing down
139        ACS_DEGREE     '         f      degree symbol
140        ACS_DIAMOND    +         `      diamond
141        ACS_GEQUAL     &gt;         &gt;      greater-than-or-equal-to
142        ACS_HLINE      -         q      horizontal line
143        ACS_LANTERN    #         i      lantern symbol
144        ACS_LARROW     &lt;         ,      arrow pointing left
145        ACS_LEQUAL     &lt;         y      less-than-or-equal-to
146        ACS_LLCORNER   +         m      lower left-hand corner
147        ACS_LRCORNER   +         j      lower right-hand corner
148        ACS_LTEE       +         t      left tee
149        ACS_NEQUAL     !         |      not-equal
150        ACS_PI         *         {      greek pi
151        ACS_PLMINUS    #         g      plus/minus
152        ACS_PLUS       +         n      plus
153        ACS_RARROW     &gt;         +      arrow pointing right
154        ACS_RTEE       +         u      right tee
155        ACS_S1         -         o      scan line 1
156        ACS_S3         -         p      scan line 3
157        ACS_S7         -         r      scan line 7
158        ACS_S9         _         s      scan line 9
159        ACS_STERLING   f         }      pound-sterling symbol
160        ACS_TTEE       +         w      top tee
161        ACS_UARROW     ^         -      arrow pointing up
162        ACS_ULCORNER   +         l      upper left-hand corner
163        ACS_URCORNER   +         k      upper right-hand corner
164        ACS_VLINE      |         x      vertical line
165
166
167 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
168        All routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success (the
169        SVr4  manuals specify only "an integer value other than <STRONG>ERR</STRONG>") upon suc-
170        cessful completion, unless otherwise noted  in  the  preceding  routine
171        descriptions.
172
173        Functions  with  a  "mv"  prefix  first perform a cursor movement using
174        <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
175        the window pointer is null.
176
177        If  it  is  not  possible  to  add  a  complete  character, an error is
178        returned:
179
180        <STRONG>o</STRONG>   If <STRONG>scrollok</STRONG> is not enabled, writing a character at the lower  right
181            margin  succeeds.   However, an error is returned because it is not
182            possible to wrap to a new line
183
184        <STRONG>o</STRONG>   If an error is detected when converting a multibyte character to  a
185            sequence  of  bytes,  or  if  it  is not possible to add all of the
186            resulting bytes in the window, an error is returned.
187
188
189 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
190        Note that <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be macros.
191
192
193 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
194        All these functions are described in the XSI Curses standard, Issue  4.
195        The  defaults specified for forms-drawing characters apply in the POSIX
196        locale.
197
198
199 </PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE>
200        X/Open Curses states that the <EM>ACS</EM><STRONG>_</STRONG> definitions are <STRONG>char</STRONG> constants.  For
201        the  wide-character implementation (see <STRONG>curs_add_wch</STRONG>), there are analo-
202        gous <EM>WACS</EM><STRONG>_</STRONG> definitions which are <STRONG>cchar_t</STRONG> constants.   Some  implementa-
203        tions are problematic:
204
205        <STRONG>o</STRONG>   Some  implementations define the ACS symbols to a constant (such as
206            Solaris), while others define those to entries in an array.
207
208            This implementation uses an array <STRONG>acs_map</STRONG>, as done in SVr4  curses.
209            NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG>
210            for compatibility.
211
212        <STRONG>o</STRONG>   HPUX curses equates some of the <EM>ACS</EM><STRONG>_</STRONG> symbols to the analogous <EM>WACS</EM><STRONG>_</STRONG>
213            symbols  as  if  the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters.  The misde-
214            fined symbols are the arrows and other symbols which are  not  used
215            for line-drawing.
216
217        <STRONG>o</STRONG>   X/Open  Curses  (issues  2 through 7) has a typographical error for
218            the ACS_LANTERN symbol, equating its "VT100+ Character" to <STRONG>I</STRONG> (capi-
219            tal  I),  while  the  header  files for SVr4 curses and the various
220            implementations use <STRONG>i</STRONG> (lowercase).
221
222            None of the terminal descriptions on Unix platforms use  uppercase-
223            I,  except for Solaris (i.e., <EM>screen</EM>'s terminal description, appar-
224            ently based on the X/Open documentation around 1995).  On the other
225            hand,  the terminal description <EM>gs6300</EM> (AT&amp;T PC6300 with EMOTS Ter-
226            minal Emulator) uses lowercase-i.
227
228        Some ACS  symbols  (ACS_S3,  ACS_S7,  ACS_LEQUAL,  ACS_GEQUAL,  ACS_PI,
229        ACS_NEQUAL,  ACS_STERLING) were not documented in any publicly released
230        System V.  However, many  publicly  available  terminfos  include  <STRONG>acsc</STRONG>
231        strings  in  which  their  key characters (pryz{|}) are embedded, and a
232        second-hand list of their character descriptions  has  come  to  light.
233        The ACS-prefixed names for them were invented for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
234
235        The <EM>displayed</EM> values for the <EM>ACS</EM><STRONG>_</STRONG> and <EM>WACS</EM><STRONG>_</STRONG> constants depend on
236
237        <STRONG>o</STRONG>   the library configuration, i.e., <STRONG>ncurses</STRONG> versus <STRONG>ncursesw</STRONG>, where the
238            latter is capable of displaying Unicode while the  former  is  not,
239            and
240
241        <STRONG>o</STRONG>   whether the <EM>locale</EM> uses UTF-8 encoding.
242
243        In  certain cases, the terminal is unable to display line-drawing char-
244        acters except by using UTF-8 (see the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG>
245        in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>).
246
247
248 </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
249        X/Open  Curses  assumes  that the parameter passed to <STRONG>waddch</STRONG> contains a
250        single character.  As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,  that  character  may
251        have  been  more than eight bits in an SVr3 or SVr4 implementation, but
252        in the X/Open Curses model, the details are not given.   The  important
253        distinction between SVr4 curses and X/Open Curses is that the non-char-
254        acter information (attributes and color) was separated from the charac-
255        ter information which is packed in a <STRONG>chtype</STRONG> to pass to <STRONG>waddch</STRONG>.
256
257        In  this  implementation,  <STRONG>chtype</STRONG>  holds  an  eight-bit character.  But
258        ncurses allows multibyte characters to be passed  in  a  succession  of
259        calls  to  <STRONG>waddch</STRONG>.  The other implementations do not do this; a call to
260        <STRONG>waddch</STRONG> passes exactly one character which may be  rendered  as  one  or
261        more cells on the screen depending on whether it is printable.
262
263        Depending  on the locale settings, ncurses will inspect the byte passed
264        in each call to <STRONG>waddch</STRONG>, and check if the latest call  will  continue  a
265        multibyte sequence.  When a character is <EM>complete</EM>, ncurses displays the
266        character and moves to the next position in the screen.
267
268        If the calling application interrupts the  succession  of  bytes  in  a
269        multibyte character by moving the current location (e.g., using <STRONG>wmove</STRONG>),
270        ncurses discards the partially built character, starting over again.
271
272        For portability to other implementations, do not rely upon this  behav-
273        ior:
274
275        <STRONG>o</STRONG>   check  if  a  character  can be represented as a single byte in the
276            current locale before attempting call <STRONG>waddch</STRONG>, and
277
278        <STRONG>o</STRONG>   call <STRONG>wadd_wch</STRONG> for characters which cannot be handled by <STRONG>waddch</STRONG>.
279
280
281 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
282        The <STRONG>TABSIZE</STRONG> variable is implemented  in  SVr4  and  other  versions  of
283        curses,  but  is  not part of X/Open curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> for
284        more details).
285
286        If <EM>ch</EM> is a carriage return, the cursor is moved to the beginning of the
287        current  row of the window.  This is true of other implementations, but
288        is not documented.
289
290
291 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
292        <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>
293        <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>.
294
295        Comparable  functions  in  the  wide-character  (ncursesw)  library are
296        described in <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>.
297
298
299
300                                                                 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
301 </PRE>
302 <div class="nav">
303 <ul>
304 <li><a href="#h2-NAME">NAME</a></li>
305 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
306 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
307 <ul>
308 <li><a href="#h3-Adding-characters">Adding characters</a></li>
309 <li><a href="#h3-Echoing-characters">Echoing characters</a></li>
310 <li><a href="#h3-Line-Graphics">Line Graphics</a></li>
311 </ul>
312 </li>
313 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
314 <li><a href="#h2-NOTES">NOTES</a></li>
315 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
316 <ul>
317 <li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
318 <li><a href="#h3-Character-Set">Character Set</a></li>
319 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
320 </ul>
321 </li>
322 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
323 </ul>
324 </div>
325 </BODY>
326 </HTML>