1curs_addch(3X)                                                  curs_addch(3X)
2
3
4

NAME

6       addch, waddch, mvaddch, mvwaddch, echochar, wechochar - add a character
7       (with attributes) to a curses window, then advance the cursor
8

SYNOPSIS

10       #include <curses.h>
11
12       int addch(const chtype ch);
13       int waddch(WINDOW *win, const chtype ch);
14       int mvaddch(int y, int x, const chtype ch);
15       int mvwaddch(WINDOW *win, int y, int x, const chtype ch);
16
17       int echochar(const chtype ch);
18       int wechochar(WINDOW *win, const chtype ch);
19

DESCRIPTION

21   Adding characters
22       The addch, waddch, mvaddch and mvwaddch routines put the  character  ch
23       into the given window at its current window position, which is then ad‐
24       vanced.  They are analogous to putchar(3) in stdio(3).  If the  advance
25       is at the right margin:
26
27       •   The cursor automatically wraps to the beginning of the next line.
28
29       •   At  the  bottom of the current scrolling region, and if scrollok is
30           enabled, the scrolling region is scrolled up one line.
31
32       •   If scrollok is not enabled, writing a character at the lower  right
33           margin  succeeds.   However, an error is returned because it is not
34           possible to wrap to a new line
35
36       If ch is a tab, newline, carriage return or backspace,  the  cursor  is
37       moved appropriately within the window:
38
39       •   Backspace  moves the cursor one character left; at the left edge of
40           a window it does nothing.
41
42       •   Carriage return moves the cursor to the window left margin  on  the
43           current line.
44
45       •   Newline  does  a clrtoeol, then moves the cursor to the window left
46           margin on the next line, scrolling the window if on the last line.
47
48       •   Tabs are considered to be at every eighth column.  The tab interval
49           may be altered by setting the TABSIZE variable.
50
51       If  ch  is  any  other nonprintable character, it is drawn in printable
52       form, i.e., the ^X notation used by unctrl(3X).   Calling  winch  after
53       adding  a  nonprintable character does not return the character itself,
54       but instead returns the printable representation of the character.
55
56       Video attributes can be combined with a character  argument  passed  to
57       addch  or  related  functions by logical-ORing them into the character.
58       (Thus, text, including attributes, can be copied from one place to  an‐
59       other using inch(3X) and addch.)  See the curs_attr(3X) page for values
60       of predefined video attribute constants that can be usefully OR'ed into
61       characters.
62
63   Echoing characters
64       The  echochar  and wechochar routines are equivalent to a call to addch
65       followed by a call to refresh(3X), or a call to waddch  followed  by  a
66       call  to wrefresh.  The knowledge that only a single character is being
67       output is used and, for non-control characters, a considerable  perfor‐
68       mance gain may be seen by using these routines instead of their equiva‐
69       lents.
70
71   Line Graphics
72       The following variables may be used to add line drawing  characters  to
73       the  screen  with  routines of the addch family.  The default character
74       listed below is used if the acsc capability does not define a terminal-
75       specific  replacement  for it, or if the terminal and locale configura‐
76       tion requires Unicode but the library is unable to use Unicode.
77
78       The names are taken from VT100 nomenclature.
79
80       ACS            ACS       acsc   Glyph
81       Name           Default   char   Name
82       ─────────────────────────────────────────────────────────
83       ACS_BLOCK      #         0      solid square block
84       ACS_BOARD      #         h      board of squares
85       ACS_BTEE       +         v      bottom tee
86       ACS_BULLET     o         ~      bullet
87       ACS_CKBOARD    :         a      checker board (stipple)
88       ACS_DARROW     v         .      arrow pointing down
89       ACS_DEGREE     '         f      degree symbol
90       ACS_DIAMOND    +         `      diamond
91       ACS_GEQUAL     >         >      greater-than-or-equal-to
92       ACS_HLINE      -         q      horizontal line
93       ACS_LANTERN    #         i      lantern symbol
94       ACS_LARROW     <         ,      arrow pointing left
95       ACS_LEQUAL     <         y      less-than-or-equal-to
96       ACS_LLCORNER   +         m      lower left-hand corner
97       ACS_LRCORNER   +         j      lower right-hand corner
98       ACS_LTEE       +         t      left tee
99       ACS_NEQUAL     !         |      not-equal
100       ACS_PI         *         {      greek pi
101       ACS_PLMINUS    #         g      plus/minus
102       ACS_PLUS       +         n      plus
103       ACS_RARROW     >         +      arrow pointing right
104       ACS_RTEE       +         u      right tee
105       ACS_S1         -         o      scan line 1
106       ACS_S3         -         p      scan line 3
107       ACS_S7         -         r      scan line 7
108       ACS_S9         _         s      scan line 9
109       ACS_STERLING   f         }      pound-sterling symbol
110       ACS_TTEE       +         w      top tee
111       ACS_UARROW     ^         -      arrow pointing up
112       ACS_ULCORNER   +         l      upper left-hand corner
113       ACS_URCORNER   +         k      upper right-hand corner
114       ACS_VLINE      |         x      vertical line
115

RETURN VALUE

117       All routines return the integer ERR upon failure and OK on success (the
118       SVr4  manuals specify only “an integer value other than ERR”) upon suc‐
119       cessful completion, unless otherwise noted in the preceding routine de‐
120       scriptions.
121
122       Functions  with  a  “mv”  prefix  first perform a cursor movement using
123       wmove, and return an error if the position is outside the window, or if
124       the window pointer is null.
125
126       If  it  is  not  possible  to add a complete character, an error is re‐
127       turned:
128
129       •   If scrollok is not enabled, writing a character at the lower  right
130           margin  succeeds.   However, an error is returned because it is not
131           possible to wrap to a new line
132
133       •   If an error is detected when converting a multibyte character to  a
134           sequence  of  bytes, or if it is not possible to add all of the re‐
135           sulting bytes in the window, an error is returned.
136

NOTES

138       Note that addch, mvaddch, mvwaddch, and echochar may be macros.
139

PORTABILITY

141       All these functions are described in the XSI Curses standard, Issue  4.
142       The  defaults specified for forms-drawing characters apply in the POSIX
143       locale.
144
145   ACS Symbols
146       X/Open Curses states that the ACS_ definitions are char constants.  For
147       the  wide-character implementation (see curs_add_wch), there are analo‐
148       gous WACS_ definitions which are cchar_t constants.   Some  implementa‐
149       tions are problematic:
150
151       •   Some  implementations define the ACS symbols to a constant (such as
152           Solaris), while others define those to entries in an array.
153
154           This implementation uses an array acs_map, as done in SVr4  curses.
155           NetBSD also uses an array, actually named _acs_char, with a #define
156           for compatibility.
157
158       •   HPUX curses equates some of the ACS_ symbols to the analogous WACS_
159           symbols  as  if  the ACS_ symbols were wide characters.  The misde‐
160           fined symbols are the arrows and other symbols which are  not  used
161           for line-drawing.
162
163       •   X/Open  Curses  (issues  2 through 7) has a typographical error for
164           the ACS_LANTERN symbol, equating its “VT100+ Character” to I (capi‐
165           tal  I), while the header files for SVr4 curses and the various im‐
166           plementations use i (lowercase).
167
168           None of the terminal descriptions on Unix platforms use  uppercase-
169           I,  except for Solaris (i.e., screen's terminal description, appar‐
170           ently based on the X/Open documentation around 1995).  On the other
171           hand,  the terminal description gs6300 (AT&T PC6300 with EMOTS Ter‐
172           minal Emulator) uses lowercase-i.
173
174       Some ACS  symbols  (ACS_S3,  ACS_S7,  ACS_LEQUAL,  ACS_GEQUAL,  ACS_PI,
175       ACS_NEQUAL,  ACS_STERLING) were not documented in any publicly released
176       System V.  However, many  publicly  available  terminfos  include  acsc
177       strings  in  which  their  key characters (pryz{|}) are embedded, and a
178       second-hand list of their character descriptions  has  come  to  light.
179       The ACS-prefixed names for them were invented for ncurses(3X).
180
181       The displayed values for the ACS_ and WACS_ constants depend on
182
183       •   the library configuration, i.e., ncurses versus ncursesw, where the
184           latter is capable of displaying Unicode while the  former  is  not,
185           and
186
187       •   whether the locale uses UTF-8 encoding.
188
189       In  certain cases, the terminal is unable to display line-drawing char‐
190       acters except by using UTF-8 (see the discussion of NCURSES_NO_UTF8_ACS
191       in ncurses(3X)).
192
193   Character Set
194       X/Open  Curses  assumes  that the parameter passed to waddch contains a
195       single character.  As discussed in curs_attr(3X),  that  character  may
196       have  been  more than eight bits in an SVr3 or SVr4 implementation, but
197       in the X/Open Curses model, the details are not given.   The  important
198       distinction between SVr4 curses and X/Open Curses is that the non-char‐
199       acter information (attributes and color) was separated from the charac‐
200       ter information which is packed in a chtype to pass to waddch.
201
202       In  this  implementation,  chtype  holds  an  eight-bit character.  But
203       ncurses allows multibyte characters to be passed  in  a  succession  of
204       calls  to  waddch.  The other implementations do not do this; a call to
205       waddch passes exactly one character which may be  rendered  as  one  or
206       more cells on the screen depending on whether it is printable.
207
208       Depending  on the locale settings, ncurses will inspect the byte passed
209       in each call to waddch, and check if the latest call  will  continue  a
210       multibyte sequence.  When a character is complete, ncurses displays the
211       character and moves to the next position in the screen.
212
213       If the calling application interrupts the  succession  of  bytes  in  a
214       multibyte character by moving the current location (e.g., using wmove),
215       ncurses discards the partially built character, starting over again.
216
217       For portability to other implementations, do not rely upon this  behav‐
218       ior:
219
220       •   check  if  a  character  can be represented as a single byte in the
221           current locale before attempting call waddch, and
222
223       •   call wadd_wch for characters which cannot be handled by waddch.
224
225   TABSIZE
226       The TABSIZE variable is implemented  in  SVr4  and  other  versions  of
227       curses,  but  is  not part of X/Open curses (see curs_variables(3X) for
228       more details).
229
230       If ch is a carriage return, the cursor is moved to the beginning of the
231       current  row of the window.  This is true of other implementations, but
232       is not documented.
233

SEE ALSO

235       curses(3X),  curs_attr(3X),  curs_clear(3X),  curs_inch(3X),  curs_out‐
236       opts(3X), curs_refresh(3X), curs_variables(3X), putc(3).
237
238       Comparable  functions  in the wide-character (ncursesw) library are de‐
239       scribed in curs_add_wch(3X).
240
241
242
243                                                                curs_addch(3X)
Impressum