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 ACS_S9
  78          _    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>