doc/html/man/curs_addch.3x.html

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright 2018-2019,2020 Thomas E. Dickey                                *
   5   * Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
   6   *                                                                          *
   7   * Permission is hereby granted, free of charge, to any person obtaining a  *
   8   * copy of this software and associated documentation files (the            *
   9   * "Software"), to deal in the Software without restriction, including      *
  10   * without limitation the rights to use, copy, modify, merge, publish,      *
  11   * distribute, distribute with modifications, sublicense, and/or sell       *
  12   * copies of the Software, and to permit persons to whom the Software is    *
  13   * furnished to do so, subject to the following conditions:                 *
  14   *                                                                          *
  15   * The above copyright notice and this permission notice shall be included  *
  16   * in all copies or substantial portions of the Software.                   *
  17   *                                                                          *
  18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  19   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  20   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  21   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  22   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  23   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  24   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  25   *                                                                          *
  26   * Except as contained in this notice, the name(s) of the above copyright   *
  27   * holders shall not be used in advertising or otherwise to promote the     *
  28   * sale, use or other dealings in this Software without prior written       *
  29   * authorization.                                                           *
  30   ****************************************************************************
  31   * @Id: curs_addch.3x,v 1.55 2020/10/24 09:12:31 tom Exp @
  32 -->
  33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  34 <HTML>
  35 <HEAD>
  36 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  37 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  38 <TITLE>curs_addch 3x</TITLE>
  39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  40 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  41 </HEAD>
  42 <BODY>
  43 <H1 class="no-header">curs_addch 3x</H1>
  44 <PRE>
  45 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>                                                  <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
  46
  47
  48
  49
  50 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  51        <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, <STRONG>echochar</STRONG>, <STRONG>wechochar</STRONG> - add a character
  52        (with attributes) to a <STRONG>curses</STRONG> window, then advance the cursor
  53
  54
  55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  56        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  57
  58        <STRONG>int</STRONG> <STRONG>addch(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>waddch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>mvaddch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
  61        <STRONG>int</STRONG> <STRONG>mvwaddch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
  62
  63        <STRONG>int</STRONG> <STRONG>echochar(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
  64        <STRONG>int</STRONG> <STRONG>wechochar(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
  65
  66
  67 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  68
  69 </PRE><H3><a name="h3-Adding-characters">Adding characters</a></H3><PRE>
  70        The <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG> and <STRONG>mvwaddch</STRONG> routines put the  character  <EM>ch</EM>
  71        into  the  given  window  at its current window position, which is then
  72        advanced.  They are  analogous  to  <STRONG>putchar(3)</STRONG>  in  <STRONG>stdio(3)</STRONG>.   If  the
  73        advance is at the right margin:
  74
  75        <STRONG>o</STRONG>   The cursor automatically wraps to the beginning of the next line.
  76
  77        <STRONG>o</STRONG>   At  the  bottom of the current scrolling region, and if <STRONG>scrollok</STRONG> is
  78            enabled, the scrolling region is scrolled up one line.
  79
  80        <STRONG>o</STRONG>   If <STRONG>scrollok</STRONG> is not enabled, writing a character at the lower  right
  81            margin  succeeds.   However, an error is returned because it is not
  82            possible to wrap to a new line
  83
  84        If <EM>ch</EM> is a tab, newline, carriage return or backspace,  the  cursor  is
  85        moved appropriately within the window:
  86
  87        <STRONG>o</STRONG>   Backspace  moves the cursor one character left; at the left edge of
  88            a window it does nothing.
  89
  90        <STRONG>o</STRONG>   Carriage return moves the cursor to the window left margin  on  the
  91            current line.
  92
  93        <STRONG>o</STRONG>   Newline  does  a <STRONG>clrtoeol</STRONG>, then moves the cursor to the window left
  94            margin on the next line, scrolling the window if on the last line.
  95
  96        <STRONG>o</STRONG>   Tabs are considered to be at every eighth column.  The tab interval
  97            may be altered by setting the <STRONG>TABSIZE</STRONG> variable.
  98
  99        If  <EM>ch</EM>  is  any  other nonprintable character, it is drawn in printable
 100        form, i.e., the <STRONG>^</STRONG><EM>X</EM> notation used by <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>.   Calling  <STRONG>winch</STRONG>  after
 101        adding  a  nonprintable character does not return the character itself,
 102        but instead returns the printable representation of the character.
 103
 104        Video attributes can be combined with a character  argument  passed  to
 105        <STRONG>addch</STRONG>  or  related  functions by logical-ORing them into the character.
 106        (Thus, text, including attributes, can be  copied  from  one  place  to
 107        another using <STRONG><A HREF="curs_inch.3x.html">inch(3x)</A></STRONG> and <STRONG>addch</STRONG>.)  See the <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> page for val-
 108        ues of predefined video attribute constants that can be usefully  OR'ed
 109        into characters.
 110
 111
 112 </PRE><H3><a name="h3-Echoing-characters">Echoing characters</a></H3><PRE>
 113        The  <STRONG>echochar</STRONG>  and <STRONG>wechochar</STRONG> routines are equivalent to a call to <STRONG>addch</STRONG>
 114        followed by a call to <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>, or a call to <STRONG>waddch</STRONG>  followed  by  a
 115        call  to <STRONG>wrefresh</STRONG>.  The knowledge that only a single character is being
 116        output is used and, for non-control characters, a considerable  perfor-
 117        mance gain may be seen by using these routines instead of their equiva-
 118        lents.
 119
 120
 121 </PRE><H3><a name="h3-Line-Graphics">Line Graphics</a></H3><PRE>
 122        The following variables may be used to add line drawing  characters  to
 123        the  screen  with  routines of the <STRONG>addch</STRONG> family.  The default character
 124        listed below is used if the <STRONG>acsc</STRONG> capability does not define a terminal-
 125        specific  replacement  for it, or if the terminal and locale configura-
 126        tion requires Unicode but the library is unable to use Unicode.
 127
 128        The names are taken from VT100 nomenclature.
 129
 130        <STRONG>ACS</STRONG>            <STRONG>ACS</STRONG>       <STRONG>acsc</STRONG>   <STRONG>Glyph</STRONG>
 131        <STRONG>Name</STRONG>           <STRONG>Default</STRONG>   <STRONG>char</STRONG>   <STRONG>Name</STRONG>
 132        ---------------------------------------------------------
 133        ACS_BLOCK      #         0      solid square block
 134        ACS_BOARD      #         h      board of squares
 135        ACS_BTEE       +         v      bottom tee
 136        ACS_BULLET     o         ~      bullet
 137        ACS_CKBOARD    :         a      checker board (stipple)
 138        ACS_DARROW     v         .      arrow pointing down
 139        ACS_DEGREE     '         f      degree symbol
 140        ACS_DIAMOND    +         `      diamond
 141        ACS_GEQUAL     &gt;         &gt;      greater-than-or-equal-to
 142        ACS_HLINE      -         q      horizontal line
 143        ACS_LANTERN    #         i      lantern symbol
 144        ACS_LARROW     &lt;         ,      arrow pointing left
 145        ACS_LEQUAL     &lt;         y      less-than-or-equal-to
 146        ACS_LLCORNER   +         m      lower left-hand corner
 147        ACS_LRCORNER   +         j      lower right-hand corner
 148        ACS_LTEE       +         t      left tee
 149        ACS_NEQUAL     !         |      not-equal
 150        ACS_PI         *         {      greek pi
 151        ACS_PLMINUS    #         g      plus/minus
 152        ACS_PLUS       +         n      plus
 153        ACS_RARROW     &gt;         +      arrow pointing right
 154        ACS_RTEE       +         u      right tee
 155        ACS_S1         -         o      scan line 1
 156        ACS_S3         -         p      scan line 3
 157        ACS_S7         -         r      scan line 7
 158        ACS_S9         _         s      scan line 9
 159        ACS_STERLING   f         }      pound-sterling symbol
 160        ACS_TTEE       +         w      top tee
 161        ACS_UARROW     ^         -      arrow pointing up
 162        ACS_ULCORNER   +         l      upper left-hand corner
 163        ACS_URCORNER   +         k      upper right-hand corner
 164        ACS_VLINE      |         x      vertical line
 165
 166
 167 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 168        All routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success (the
 169        SVr4  manuals specify only "an integer value other than <STRONG>ERR</STRONG>") upon suc-
 170        cessful completion, unless otherwise noted  in  the  preceding  routine
 171        descriptions.
 172
 173        Functions  with  a  "mv"  prefix  first perform a cursor movement using
 174        <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
 175        the window pointer is null.
 176
 177        If  it  is  not  possible  to  add  a  complete  character, an error is
 178        returned:
 179
 180        <STRONG>o</STRONG>   If <STRONG>scrollok</STRONG> is not enabled, writing a character at the lower  right
 181            margin  succeeds.   However, an error is returned because it is not
 182            possible to wrap to a new line
 183
 184        <STRONG>o</STRONG>   If an error is detected when converting a multibyte character to  a
 185            sequence  of  bytes,  or  if  it  is not possible to add all of the
 186            resulting bytes in the window, an error is returned.
 187
 188
 189 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 190        Note that <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be macros.
 191
 192
 193 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 194        All these functions are described in the XSI Curses standard, Issue  4.
 195        The  defaults specified for forms-drawing characters apply in the POSIX
 196        locale.
 197
 198
 199 </PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE>
 200        X/Open Curses states that the <EM>ACS</EM><STRONG>_</STRONG> definitions are <STRONG>char</STRONG> constants.  For
 201        the  wide-character implementation (see <STRONG>curs_add_wch</STRONG>), there are analo-
 202        gous <EM>WACS</EM><STRONG>_</STRONG> definitions which are <STRONG>cchar_t</STRONG> constants.   Some  implementa-
 203        tions are problematic:
 204
 205        <STRONG>o</STRONG>   Some  implementations define the ACS symbols to a constant (such as
 206            Solaris), while others define those to entries in an array.
 207
 208            This implementation uses an array <STRONG>acs_map</STRONG>, as done in SVr4  curses.
 209            NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG>
 210            for compatibility.
 211
 212        <STRONG>o</STRONG>   HPUX curses equates some of the <EM>ACS</EM><STRONG>_</STRONG> symbols to the analogous <EM>WACS</EM><STRONG>_</STRONG>
 213            symbols  as  if  the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters.  The misde-
 214            fined symbols are the arrows and other symbols which are  not  used
 215            for line-drawing.
 216
 217        <STRONG>o</STRONG>   X/Open  Curses  (issues  2 through 7) has a typographical error for
 218            the ACS_LANTERN symbol, equating its "VT100+ Character" to <STRONG>I</STRONG> (capi-
 219            tal  I),  while  the  header  files for SVr4 curses and the various
 220            implementations use <STRONG>i</STRONG> (lowercase).
 221
 222            None of the terminal descriptions on Unix platforms use  uppercase-
 223            I,  except for Solaris (i.e., <EM>screen</EM>'s terminal description, appar-
 224            ently based on the X/Open documentation around 1995).  On the other
 225            hand,  the terminal description <EM>gs6300</EM> (AT&amp;T PC6300 with EMOTS Ter-
 226            minal Emulator) uses lowercase-i.
 227
 228        Some ACS  symbols  (ACS_S3,  ACS_S7,  ACS_LEQUAL,  ACS_GEQUAL,  ACS_PI,
 229        ACS_NEQUAL,  ACS_STERLING) were not documented in any publicly released
 230        System V.  However, many  publicly  available  terminfos  include  <STRONG>acsc</STRONG>
 231        strings  in  which  their  key characters (pryz{|}) are embedded, and a
 232        second-hand list of their character descriptions  has  come  to  light.
 233        The ACS-prefixed names for them were invented for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
 234
 235        The <EM>displayed</EM> values for the <EM>ACS</EM><STRONG>_</STRONG> and <EM>WACS</EM><STRONG>_</STRONG> constants depend on
 236
 237        <STRONG>o</STRONG>   the library configuration, i.e., <STRONG>ncurses</STRONG> versus <STRONG>ncursesw</STRONG>, where the
 238            latter is capable of displaying Unicode while the  former  is  not,
 239            and
 240
 241        <STRONG>o</STRONG>   whether the <EM>locale</EM> uses UTF-8 encoding.
 242
 243        In  certain cases, the terminal is unable to display line-drawing char-
 244        acters except by using UTF-8 (see the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG>
 245        in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>).
 246
 247
 248 </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
 249        X/Open  Curses  assumes  that the parameter passed to <STRONG>waddch</STRONG> contains a
 250        single character.  As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,  that  character  may
 251        have  been  more than eight bits in an SVr3 or SVr4 implementation, but
 252        in the X/Open Curses model, the details are not given.   The  important
 253        distinction between SVr4 curses and X/Open Curses is that the non-char-
 254        acter information (attributes and color) was separated from the charac-
 255        ter information which is packed in a <STRONG>chtype</STRONG> to pass to <STRONG>waddch</STRONG>.
 256
 257        In  this  implementation,  <STRONG>chtype</STRONG>  holds  an  eight-bit character.  But
 258        ncurses allows multibyte characters to be passed  in  a  succession  of
 259        calls  to  <STRONG>waddch</STRONG>.  The other implementations do not do this; a call to
 260        <STRONG>waddch</STRONG> passes exactly one character which may be  rendered  as  one  or
 261        more cells on the screen depending on whether it is printable.
 262
 263        Depending  on the locale settings, ncurses will inspect the byte passed
 264        in each call to <STRONG>waddch</STRONG>, and check if the latest call  will  continue  a
 265        multibyte sequence.  When a character is <EM>complete</EM>, ncurses displays the
 266        character and moves to the next position in the screen.
 267
 268        If the calling application interrupts the  succession  of  bytes  in  a
 269        multibyte character by moving the current location (e.g., using <STRONG>wmove</STRONG>),
 270        ncurses discards the partially built character, starting over again.
 271
 272        For portability to other implementations, do not rely upon this  behav-
 273        ior:
 274
 275        <STRONG>o</STRONG>   check  if  a  character  can be represented as a single byte in the
 276            current locale before attempting call <STRONG>waddch</STRONG>, and
 277
 278        <STRONG>o</STRONG>   call <STRONG>wadd_wch</STRONG> for characters which cannot be handled by <STRONG>waddch</STRONG>.
 279
 280
 281 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
 282        The <STRONG>TABSIZE</STRONG> variable is implemented  in  SVr4  and  other  versions  of
 283        curses,  but  is  not part of X/Open curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> for
 284        more details).
 285
 286        If <EM>ch</EM> is a carriage return, the cursor is moved to the beginning of the
 287        current  row of the window.  This is true of other implementations, but
 288        is not documented.
 289
 290
 291 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 292        <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>,  <STRONG>curs_out-</STRONG>
 293        <STRONG><A HREF="curs_outopts.3x.html">opts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>.
 294
 295        Comparable  functions  in  the  wide-character  (ncursesw)  library are
 296        described in <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>.
 297
 298
 299
 300                                                                 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
 301 </PRE>
 302 <div class="nav">
 303 <ul>
 304 <li><a href="#h2-NAME">NAME</a></li>
 305 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 306 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 307 <ul>
 308 <li><a href="#h3-Adding-characters">Adding characters</a></li>
 309 <li><a href="#h3-Echoing-characters">Echoing characters</a></li>
 310 <li><a href="#h3-Line-Graphics">Line Graphics</a></li>
 311 </ul>
 312 </li>
 313 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 314 <li><a href="#h2-NOTES">NOTES</a></li>
 315 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 316 <ul>
 317 <li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
 318 <li><a href="#h3-Character-Set">Character Set</a></li>
 319 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
 320 </ul>
 321 </li>
 322 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 323 </ul>
 324 </div>
 325 </BODY>
 326 </HTML>