ncurses 4.2
[ncurses.git] / Ada95 / html / curs_addch.3x.html
1 <HTML>
2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
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>&lt;curses.h&gt;</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.  (To emit control characters liter-
45        ally, use <STRONG>echochar</STRONG>.)
46
47        Video attributes can be combined with a character argument
48        passed to <STRONG>addch</STRONG> or related functions by logical-ORing them
49        into  the  character.   (Thus, text, including attributes,
50        can be copied from one place to  another  using  <STRONG>inch</STRONG>  and
51        <STRONG>addch</STRONG>.).   See the <STRONG><A HREF="curs_attr.3x.html">curs_attr(3X)</A></STRONG> page for values of prede-
52        fined video attribute constants that can be usefully OR'ed
53        into characters.
54
55        The  <STRONG>echochar</STRONG>  and  <STRONG>wechochar</STRONG> routines are equivalent to a
56        call to <STRONG>addch</STRONG> followed by a call to <STRONG>refresh</STRONG>, or a call  to
57        <STRONG>waddch</STRONG> followed by a call to <STRONG>wrefresh</STRONG>.  The knowledge that
58        only a single character is being output is used  and,  for
59        non-control  characters,  a  considerable performance gain
60
61    <STRONG>Line</STRONG> <STRONG>Graphics</STRONG>
62        The  following  variables  may be used to add line drawing
63        characters to the screen with routines of the  <STRONG>addch</STRONG>  fam-
64        ily.   The  default  character listed below is used if the
65        <STRONG>acsc</STRONG>  capability  doesn't   define   a   terminal-specific
66        replacement for it (but see the EXTENSIONS section below).
67        The names are taken from VT100 nomenclature.
68
69        l  l  l  _  _  _  l   l   l.    <EM>Name</EM> <EM>Default</EM>   <EM>Description</EM>
70        ACS_ULCORNER   +    upper         left-hand         corner
71        ACS_LLCORNER   +    lower         left-hand         corner
72        ACS_URCORNER   +    upper         right-hand        corner
73        ACS_LRCORNER   +    lower        right-hand         corner
74        ACS_RTEE  +    right     tee    ACS_LTEE  +    left    tee
75        ACS_BTEE  +    bottom    tee    ACS_TTEE  +    top     tee
76        ACS_HLINE -    horizontal   line   ACS_VLINE |    vertical
77        line  ACS_PLUS  +    plus   ACS_S1    -    scan   line   1
78        ACS_S9    _    scan   line  9  ACS_DIAMOND    +    diamond
79        ACS_CKBOARD    :    checker        board         (stipple)
80        ACS_DEGREE     '    degree                          symbol
81        ACS_PLMINUS    #    plus/minus  ACS_BULLET     o    bullet
82        ACS_LARROW     &lt;    arrow           pointing          left
83        ACS_RARROW     &gt;    arrow          pointing          right
84        ACS_DARROW     v    arrow           pointing          down
85        ACS_UARROW     ^    arrow pointing up ACS_BOARD #    board
86        of      squares     ACS_LANTERN    #    lantern     symbol
87        ACS_BLOCK #    solid square block ACS_S3    -    scan line
88        3  ACS_S7    -    scan  line  7  ACS_LEQUAL     &lt;    less-
89        than-or-equal-to      ACS_GEQUAL     &gt;    greater-than-or-
90        equal-to  ACS_PI    *    greek pi ACS_NEQUAL     !    not-
91        equal ACS_STERLING   f    pound-sterling symbol
92
93
94
95 </PRE>
96 <H2>RETURN VALUE</H2><PRE>
97        All routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on
98        success  (the  SVr4 manuals specify only "an integer value
99        other than <STRONG>ERR</STRONG>") upon successful completion, unless other-
100        wise noted in the preceding routine descriptions.
101
102
103 </PRE>
104 <H2>NOTES</H2><PRE>
105        Note  that  <STRONG>addch</STRONG>,  <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be
106        macros.
107
108
109 </PRE>
110 <H2>EXTENSIONS</H2><PRE>
111        The following extended <STRONG>curses</STRONG> features are available  only
112        on  PC-clone consoles and compatible terminals obeying the
113        ANSI.SYS de-facto standard for terminal control sequences.
114        They are not part of XSI curses.
115
116        The attribute A_ALTCHARSET actually forces literal display
117        of PC ROM characters  including  the  high-half  graphics.
118        the card-suit characters, up and down-arrow, and most oth-
119        ers in the range 0-32.  (In a terminfo entry designed  for
120        use  with  <STRONG>ncurses</STRONG>,  the high-half characters are obtained
121        using this attribute with an <STRONG>acsc</STRONG> string in which the sec-
122        ond of each pair is a high-half character.)
123
124        Giving  <STRONG>wechochar</STRONG>  an  argument with its high bit set will
125        produce the corresponding high-half  ASCII  graphic  (SVr4
126        curses also has this feature but does not document it).  A
127        control-character argument, however,  will  not  typically
128        produce  the corresponding graphic; characters such as CR,
129        NL, FF and TAB are typically interpreted  by  the  console
130        driver  itself,  and ESC will be interpreted as the leader
131        of a control sequence.
132
133
134 </PRE>
135 <H2>PORTABILITY</H2><PRE>
136        All these functions are described in the XSI Curses  stan-
137        dard,  Issue  4.  The defaults specified for forms-drawing
138        characters apply in the POSIX locale.
139
140        The seven ACS symbols starting with <STRONG>ACS_S3</STRONG> were not  docu-
141        mented  in  any publicly released System V.  However, many
142        publicly available terminfos include <STRONG>acsc</STRONG> strings in which
143        their key characters (pryz{|}) are embedded, and a second-
144        hand list of their  character  descriptions  has  come  to
145        light.   The ACS-prefixed names for them were invented for
146        <STRONG><A HREF="ncurses.3x.html">ncurses(3X)</A></STRONG>.
147
148
149 </PRE>
150 <H2>SEE ALSO</H2><PRE>
151        <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>,
152        <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>.
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174 </PRE>
175 </BODY>
176 </HTML>