ncurses 6.0 - patch 20171118
[ncurses.git] / doc / html / man / curs_addch.3x.html
index c0af2f68e20bdb7db782cd268595c743b5d5b517..fbacde1ef9ad190d2b5ae3207f69dcdd7d3e1a3c 100644 (file)
@@ -27,7 +27,7 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_addch.3x,v 1.41 2017/05/05 18:15:29 tom Exp @
+  * @Id: curs_addch.3x,v 1.43 2017/11/19 01:54:00 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
        The defaults specified for forms-drawing characters apply in the  POSIX
        locale.
 
+
+</PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE>
        X/Open Curses states that the <EM>ACS</EM><STRONG>_</STRONG> definitions are <STRONG>char</STRONG> constants.  For
        the wide-character implementation (see <STRONG>curs_add_wch</STRONG>), there are  analo-
        gous <EM>WACS</EM><STRONG>_</STRONG> definitions which are <STRONG>cchar_t</STRONG> constants.
        acters except by using UTF-8 (see the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG>
        in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>).
 
-       The <STRONG>TABSIZE</STRONG> variable is implemented in some versions of curses, but  is
+
+</PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
+       X/Open Curses assumes that the parameter passed to  <STRONG>waddch</STRONG>  contains  a
+       single  character.   As  discussed in <STRONG>curs_attr(3x)</STRONG>, that character may
+       have been more than eight bits in an SVr3 or SVr4  implementation,  but
+       in  the  X/Open Curses model, the details are not given.  The important
+       distinction between SVr4 curses and X/Open Curses is that the non-char-
+       acter information (attributes and color) was separated from the charac-
+       ter information which is packed in a <STRONG>chtype</STRONG> to pass to <STRONG>waddch</STRONG>.
+
+       In this implementation, <STRONG>chtype</STRONG> holds eight bits.   But  ncurses  allows
+       multibyte  characters  to be passed in a succession of calls to <STRONG>waddch</STRONG>.
+       The other implementations do not do  this;  a  call  to  <STRONG>waddch</STRONG>  passes
+       exactly one character which may be rendered as one or more cells on the
+       screen depending on whether it is printable.
+
+       Depending on the locale settings, ncurses will inspect the byte  passed
+       in  each  call  to <STRONG>waddch</STRONG>, and check if the latest call will continue a
+       multibyte sequence.  When a character is <EM>complete</EM>, ncurses displays the
+       character and moves to the next position in the screen.
+
+       If  the  calling  application  interrupts  the succession of bytes in a
+       multibyte character by moving the current location (e.g., using <STRONG>wmove</STRONG>),
+       ncurses discards the partially built character, starting over again.
+
+       For  portability to other implementations, do not rely upon this behav-
+       ior:
+
+       <STRONG>o</STRONG>   check if a character can be represented as a  single  byte  in  the
+           current locale before attempting call <STRONG>waddch</STRONG>, and
+
+       <STRONG>o</STRONG>   call <STRONG>wadd_wch</STRONG> for characters which cannot be handled by <STRONG>waddch</STRONG>.
+
+
+</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
+       The  <STRONG>TABSIZE</STRONG> variable is implemented in some versions of curses, but is
        not part of X/Open curses.
 
        If <EM>ch</EM> is a carriage return, the cursor is moved to the beginning of the
-       current row of the window.  This is true of other implementations,  but
+       current  row of the window.  This is true of other implementations, but
        is not documented.
 
 
        <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>
        <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>.
 
-       Comparable functions  in  the  wide-character  (ncursesw)  library  are
+       Comparable  functions  in  the  wide-character  (ncursesw)  library are
        described in <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>.
 
 
 </li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 <li><a href="#h2-NOTES">NOTES</a></li>
-<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a>
+<ul>
+<li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
+<li><a href="#h3-Character-Set">Character Set</a></li>
+<li><a href="#h3-TABSIZE">TABSIZE</a></li>
+</ul>
+</li>
 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 </ul>
 </div>