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       int echochar(const chtype ch);
17       int wechochar(WINDOW *win, const chtype ch);
18

DESCRIPTION

20       The addch, waddch, mvaddch and mvwaddch routines put the  character  ch
21       into  the  given  window  at its current window position, which is then
22       advanced.  They are analogous to putchar in stdio(3).  If  the  advance
23       is at the right margin, the cursor automatically wraps to the beginning
24       of the next line.  At the bottom of the current  scrolling  region,  if
25       scrollok is enabled, the scrolling region is scrolled up one line.
26
27       If  ch  is  a tab, newline, or backspace, the cursor is moved appropri‐
28       ately within the window.  Backspace  moves  the  cursor  one  character
29       left;  at  the  left  edge of a window it does nothing.  Newline does a
30       clrtoeol, then moves the cursor to the window left margin on  the  next
31       line, scrolling the window if on the last line.  Tabs are considered to
32       be at every eighth column.  The tab interval may be altered by  setting
33       the TABSIZE variable.
34
35       If  ch  is any control character other than tab, newline, or backspace,
36       it is drawn in ^X notation.  Calling winch after adding a control char‐
37       acter  does  not  return  the character itself, but instead returns the
38       ^-representation of the control character.
39
40       Video attributes can be combined with a character  argument  passed  to
41       addch  or  related  functions by logical-ORing them into the character.
42       (Thus, text, including attributes, can be  copied  from  one  place  to
43       another  using  inch and addch.)  See the curs_attr(3X) page for values
44       of predefined video attribute constants that can be usefully OR'ed into
45       characters.
46
47       The  echochar  and wechochar routines are equivalent to a call to addch
48       followed by a call to refresh, or a call to waddch followed by  a  call
49       to  wrefresh.  The knowledge that only a single character is being out‐
50       put is used and, for non-control characters, a considerable performance
51       gain may be seen by using these routines instead of their equivalents.
52
53   Line Graphics
54       The  following  variables may be used to add line drawing characters to
55       the screen with routines of the addch family.   The  default  character
56       listed below is used if the acsc capability does not define a terminal-
57       specific replacement for it.  The names are taken from VT100  nomencla‐
58       ture.
59
60       Name           Default   Description
61       ──────────────────────────────────────────────────
62       ACS_BLOCK      #         solid square block
63       ACS_BOARD      #         board of squares
64       ACS_BTEE       +         bottom tee
65       ACS_BULLET     o         bullet
66
67       ACS_CKBOARD    :         checker board (stipple)
68       ACS_DARROW     v         arrow pointing down
69       ACS_DEGREE     '         degree symbol
70       ACS_DIAMOND    +         diamond
71       ACS_GEQUAL     >         greater-than-or-equal-to
72       ACS_HLINE      -         horizontal line
73       ACS_LANTERN    #         lantern symbol
74       ACS_LARROW     <         arrow pointing left
75       ACS_LEQUAL     <         less-than-or-equal-to
76       ACS_LLCORNER   +         lower left-hand corner
77       ACS_LRCORNER   +         lower right-hand corner
78       ACS_LTEE       +         left tee
79       ACS_NEQUAL     !         not-equal
80       ACS_PI         *         greek pi
81       ACS_PLMINUS    #         plus/minus
82       ACS_PLUS       +         plus
83       ACS_RARROW     >         arrow pointing right
84       ACS_RTEE       +         right tee
85       ACS_S1         -         scan line 1
86       ACS_S3         -         scan line 3
87       ACS_S7         -         scan line 7
88       ACS_S9         _         scan line 9
89       ACS_STERLING   f         pound-sterling symbol
90       ACS_TTEE       +         top tee
91       ACS_UARROW     ^         arrow pointing up
92       ACS_ULCORNER   +         upper left-hand corner
93       ACS_URCORNER   +         upper right-hand corner
94       ACS_VLINE      |         vertical line
95

RETURN VALUE

97       All routines return the integer ERR upon failure and OK on success (the
98       SVr4 manuals specify only "an integer value other than ERR") upon  suc‐
99       cessful  completion,  unless  otherwise  noted in the preceding routine
100       descriptions.
101
102       Functions with a "mv" prefix first  perform  a  cursor  movement  using
103       wmove, and return an error if the position is outside the window, or if
104       the window pointer is null.
105

NOTES

107       Note that addch, mvaddch, mvwaddch, and echochar may be macros.
108

PORTABILITY

110       All these functions are described in the XSI Curses standard, Issue  4.
111       The  defaults specified for forms-drawing characters apply in the POSIX
112       locale.
113
114       X/Open Curses states that the ACS_ definitions are char constants.  For
115       the  wide-character implementation (see curs_add_wch), there are analo‐
116       gous WACS_ definitions which are cchar_t constants.
117
118       Some ACS  symbols  (ACS_S3,  ACS_S7,  ACS_LEQUAL,  ACS_GEQUAL,  ACS_PI,
119       ACS_NEQUAL,  ACS_STERLING) were not documented in any publicly released
120       System V.  However, many  publicly  available  terminfos  include  acsc
121       strings  in  which  their  key characters (pryz{|}) are embedded, and a
122       second-hand list of their character descriptions  has  come  to  light.
123       The ACS-prefixed names for them were invented for ncurses(3X).
124
125       The  TABSIZE variable is implemented in some versions of curses, but is
126       not part of X/Open curses.
127
128       If ch is a carriage return, the cursor is moved to the beginning of the
129       current  row of the window.  This is true of other implementations, but
130       is not documented.
131

SEE ALSO

133       curses(3X),  curs_attr(3X),  curs_clear(3X),  curs_inch(3X),  curs_out‐
134       opts(3X), curs_refresh(3X), curs_variables(3X), putc(3).
135
136       Comparable  functions  in  the  wide-character  (ncursesw)  library are
137       described in curs_add_wch(3X).
138
139
140
141                                                                curs_addch(3X)
Impressum