ncurses 5.0
[ncurses.git] / Ada95 / html / man / curs_addch.3x.html
1 <HTML>
2 <BODY>
3 <PRE>
4        <STRONG>addch</STRONG>,  <STRONG>waddch</STRONG>,  <STRONG>mvaddch</STRONG>,  <STRONG>mvwaddch</STRONG>, <STRONG>echochar</STRONG>, <STRONG>wechochar</STRONG> -
5        add a character (with attributes) to a <STRONG>curses</STRONG> window, then
6        advance the cursor
7
8
9 </PRE>
10 <H2>SYNOPSIS</H2><PRE>
11        <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
12
13        <STRONG>int</STRONG> <STRONG>addch(chtype</STRONG> <STRONG>ch);</STRONG>
14        <STRONG>int</STRONG> <STRONG>waddch(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG>
15        <STRONG>int</STRONG> <STRONG>mvaddch(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG>
16        <STRONG>int</STRONG> <STRONG>mvwaddch(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG>
17        <STRONG>int</STRONG> <STRONG>echochar(chtype</STRONG> <STRONG>ch);</STRONG>
18        <STRONG>int</STRONG> <STRONG>wechochar(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG>
19
20
21 </PRE>
22 <H2>DESCRIPTION</H2><PRE>
23        The  <STRONG>addch</STRONG>,  <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG> and <STRONG>mvwaddch</STRONG> routines put the
24        character <EM>ch</EM> into the given window at its  current  window
25        position,  which  is then advanced.  They are analogous to
26        <STRONG>putchar</STRONG> in <STRONG><A HREF="stdio.3.html">stdio(3)</A></STRONG>.  If the advance is at the right  mar-
27        gin,  the  cursor  automatically wraps to the beginning of
28        the next line.  At the bottom  of  the  current  scrolling
29        region,  if  <STRONG>scrollok</STRONG>  is enabled, the scrolling region is
30        scrolled up one line.
31
32        If <EM>ch</EM> is a tab, newline, or backspace, the cursor is moved
33        appropriately within the window.  Backspace moves the cur-
34        sor one character left; at the left edge of  a  window  it
35        does  nothing.   Newline  does  a <STRONG>clrtoeol</STRONG>, then moves the
36        cursor to  the  window  left  margin  on  the  next  line,
37        scrolling  the window if on the last line).  Tabs are con-
38        sidered to be at every eighth column.
39
40        If <EM>ch</EM> is any control character other than tab, newline, or
41        backspace,  it  is  drawn  in  <STRONG>^</STRONG><EM>X</EM> notation.  Calling <STRONG>winch</STRONG>
42        after adding a control character does not return the char-
43        acter  itself, but instead returns the ^-representation of
44        the control character.
45
46        Video attributes can be combined with a character argument
47        passed to <STRONG>addch</STRONG> or related functions by logical-ORing them
48        into the character.  (Thus,  text,  including  attributes,
49        can  be  copied  from  one place to another using <STRONG>inch</STRONG> and
50        <STRONG>addch</STRONG>.).  See the <STRONG><A HREF="curs_attr.3x.html">curs_attr(3X)</A></STRONG> page for values of  prede-
51        fined video attribute constants that can be usefully OR'ed
52        into characters.
53
54        The <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> routines are  equivalent  to  a
55        call  to <STRONG>addch</STRONG> followed by a call to <STRONG>refresh</STRONG>, or a call to
56        <STRONG>waddch</STRONG> followed by a call to <STRONG>wrefresh</STRONG>.  The knowledge that
57        only  a  single character is being output is used and, for
58        non-control characters, a  considerable  performance  gain
59        may  be  seen  by  using  these  routines instead of their
60        The following variables may be used to  add  line  drawing
61        characters  to  the screen with routines of the <STRONG>addch</STRONG> fam-
62        ily.  The default character listed below is  used  if  the
63        <STRONG>acsc</STRONG>   capability   doesn't   define  a  terminal-specific
64        replacement for it (but see the EXTENSIONS section below).
65        The names are taken from VT100 nomenclature.
66
67        l   l   l   _  _  _  l  l  l.   <EM>Name</EM> <EM>Default</EM>   <EM>Description</EM>
68        ACS_BLOCK #    solid square block ACS_BOARD #    board  of
69        squares ACS_BTEE  +    bottom tee ACS_BULLET     o    bul-
70        let    ACS_CKBOARD    :    checker     board     (stipple)
71        ACS_DARROW     v    arrow           pointing          down
72        ACS_DEGREE     '    degree symbol ACS_DIAMOND    +    dia-
73        mond          ACS_GEQUAL     >    greater-than-or-equal-to
74        ACS_HLINE -    horizontal line ACS_LANTERN    #    lantern
75        symbol     ACS_LARROW     <    arrow     pointing     left
76        ACS_LEQUAL     <    less-than-or-equal-to
77        ACS_LLCORNER   +    lower         left-hand         corner
78        ACS_LRCORNER   +    lower        right-hand         corner
79        ACS_LTEE  +    left    tee   ACS_NEQUAL     !    not-equal
80        ACS_PI    *    greek   pi   ACS_PLMINUS    #    plus/minus
81        ACS_PLUS  +    plus   ACS_RARROW     >    arrow   pointing
82        right ACS_RTEE  +    right tee ACS_S1    -    scan line  1
83        ACS_S3    -    scan  line  3  ACS_S7    -    scan  line  7
84        ACS_S9    _    scan line 9 ACS_STERLING   f    pound-ster-
85        ling         symbol         ACS_TTEE  +    top         tee
86        ACS_UARROW     ^    arrow           pointing            up
87        ACS_ULCORNER   +    upper         left-hand         corner
88        ACS_URCORNER   +    upper        right-hand         corner
89        ACS_VLINE |    vertical line
90
91
92
93 </PRE>
94 <H2>RETURN VALUE</H2><PRE>
95        All routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on
96        success (the SVr4 manuals specify only "an  integer  value
97        other than <STRONG>ERR</STRONG>") upon successful completion, unless other-
98        wise noted in the preceding routine descriptions.
99
100
101 </PRE>
102 <H2>NOTES</H2><PRE>
103        Note that <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and  <STRONG>echochar</STRONG>  may  be
104        macros.
105
106
107 </PRE>
108 <H2>PORTABILITY</H2><PRE>
109        All  these functions are described in the XSI Curses stan-
110        dard, Issue 4.  The defaults specified  for  forms-drawing
111        characters apply in the POSIX locale.
112
113        Some  ACS symbols (ACS_S3, ACS_S7, ACS_LEQUAL, ACS_GEQUAL,
114        ACS_PI, ACS_NEQUAL, ACS_STERLING) were not  documented  in
115        any  publicly  released  System V.  However, many publicly
116        available terminfos include <STRONG>acsc</STRONG> strings  in  which  their
117        key  characters  (pryz{|}) are embedded, and a second-hand
118        <STRONG><A HREF="ncurses.3x.html">ncurses(3X)</A></STRONG>.
119
120
121 </PRE>
122 <H2>SEE ALSO</H2><PRE>
123        <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>,
124        <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3X)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3X)</A></STRONG>, <STRONG><A HREF="putc.3s.html">putc(3S)</A></STRONG>.
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172 </PRE>
173 </BODY>
174 </HTML>