diff options
Diffstat (limited to 'doc/html/man/curs_addch.3x.html')
| -rw-r--r-- | doc/html/man/curs_addch.3x.html | 105 |
1 files changed, 59 insertions, 46 deletions
diff --git a/doc/html/man/curs_addch.3x.html b/doc/html/man/curs_addch.3x.html index fa2f94d..b19e72e 100644 --- a/doc/html/man/curs_addch.3x.html +++ b/doc/html/man/curs_addch.3x.html @@ -1,7 +1,7 @@ -<!-- +<!-- * t **************************************************************************** - * Copyright 2018-2019,2020 Thomas E. Dickey * + * Copyright 2018-2020,2021 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,7 +28,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_addch.3x,v 1.51 2020/02/02 23:34:34 tom Exp @ + * @Id: curs_addch.3x,v 1.56 2021/06/17 21:30:22 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> @@ -55,12 +55,13 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>addch(const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG> - <STRONG>int</STRONG> <STRONG>waddch(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG> - <STRONG>int</STRONG> <STRONG>mvaddch(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwaddch(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG> - <STRONG>int</STRONG> <STRONG>echochar(const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG> - <STRONG>int</STRONG> <STRONG>wechochar(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>ch);</STRONG> + <STRONG>int</STRONG> <STRONG>addch(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> + <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> + <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> + <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> + + <STRONG>int</STRONG> <STRONG>echochar(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> + <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> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> @@ -95,34 +96,35 @@ <STRONG>o</STRONG> Tabs are considered to be at every eighth column. The tab interval may be altered by setting the <STRONG>TABSIZE</STRONG> variable. - If <EM>ch</EM> is any other control character, it is drawn in <STRONG>^</STRONG><EM>X</EM> notation. - Calling <STRONG>winch</STRONG> after adding a control character does not return the - character itself, but instead returns the ^-representation of the con- - trol character. + If <EM>ch</EM> is any other nonprintable character, it is drawn in printable + 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 + adding a nonprintable character does not return the character itself, + but instead returns the printable representation of the character. Video attributes can be combined with a character argument passed to <STRONG>addch</STRONG> or related functions by logical-ORing them into the character. (Thus, text, including attributes, can be copied from one place to - 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- - ues of predefined video attribute constants that can be usefully OR'ed - into characters. + 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 + values of predefined video attribute constants that can be usefully + OR'ed into characters. </PRE><H3><a name="h3-Echoing-characters">Echoing characters</a></H3><PRE> The <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> routines are equivalent to a call to <STRONG>addch</STRONG> 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 call to <STRONG>wrefresh</STRONG>. The knowledge that only a single character is being - output is used and, for non-control characters, a considerable perfor- - mance gain may be seen by using these routines instead of their equiva- - lents. + output is used and, for non-control characters, a considerable + performance gain may be seen by using these routines instead of their + equivalents. </PRE><H3><a name="h3-Line-Graphics">Line Graphics</a></H3><PRE> The following variables may be used to add line drawing characters to the screen with routines of the <STRONG>addch</STRONG> family. The default character listed below is used if the <STRONG>acsc</STRONG> capability does not define a terminal- - specific replacement for it, or if the terminal and locale configura- - tion requires Unicode but the library is unable to use Unicode. + specific replacement for it, or if the terminal and locale + configuration requires Unicode but the library is unable to use + Unicode. The names are taken from VT100 nomenclature. @@ -165,14 +167,25 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> All routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success (the - SVr4 manuals specify only "an integer value other than <STRONG>ERR</STRONG>") upon suc- - cessful completion, unless otherwise noted in the preceding routine + SVr4 manuals specify only "an integer value other than <STRONG>ERR</STRONG>") upon + successful completion, unless otherwise noted in the preceding routine descriptions. - Functions with a "mv" prefix first perform a cursor movement using + Functions with a "mv" prefix first perform a cursor movement using <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if the window pointer is null. + If it is not possible to add a complete character, an error is + returned: + + <STRONG>o</STRONG> If <STRONG>scrollok</STRONG> is not enabled, writing a character at the lower right + margin succeeds. However, an error is returned because it is not + possible to wrap to a new line + + <STRONG>o</STRONG> If an error is detected when converting a multibyte character to a + sequence of bytes, or if it is not possible to add all of the + resulting bytes in the window, an error is returned. + </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> Note that <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be macros. @@ -186,9 +199,9 @@ </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. Some implementa- - tions are problematic: + the wide-character implementation (see <STRONG>curs_add_wch</STRONG>), there are + analogous <EM>WACS</EM><STRONG>_</STRONG> definitions which are <STRONG>cchar_t</STRONG> constants. Some + implementations are problematic: <STRONG>o</STRONG> Some implementations define the ACS symbols to a constant (such as Solaris), while others define those to entries in an array. @@ -198,20 +211,20 @@ for compatibility. <STRONG>o</STRONG> HPUX curses equates some of the <EM>ACS</EM><STRONG>_</STRONG> symbols to the analogous <EM>WACS</EM><STRONG>_</STRONG> - symbols as if the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters. The misde- - fined symbols are the arrows and other symbols which are not used - for line-drawing. + symbols as if the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters. The + misdefined symbols are the arrows and other symbols which are not + used for line-drawing. <STRONG>o</STRONG> X/Open Curses (issues 2 through 7) has a typographical error for - the ACS_LANTERN symbol, equating its "VT100+ Character" to <STRONG>I</STRONG> (capi- - tal I), while the header files for SVr4 curses and the various + the ACS_LANTERN symbol, equating its "VT100+ Character" to <STRONG>I</STRONG> + (capital I), while the header files for SVr4 curses and the various implementations use <STRONG>i</STRONG> (lowercase). None of the terminal descriptions on Unix platforms use uppercase- - I, except for Solaris (i.e., <EM>screen</EM>'s terminal description, appar- - ently based on the X/Open documentation around 1995). On the other - hand, the terminal description <EM>gs6300</EM> (AT&T PC6300 with EMOTS Ter- - minal Emulator) uses lowercase-i. + I, except for Solaris (i.e., <EM>screen</EM>'s terminal description, + apparently based on the X/Open documentation around 1995). On the + other hand, the terminal description <EM>gs6300</EM> (AT&T PC6300 with EMOTS + Terminal Emulator) uses lowercase-i. Some ACS symbols (ACS_S3, ACS_S7, ACS_LEQUAL, ACS_GEQUAL, ACS_PI, ACS_NEQUAL, ACS_STERLING) were not documented in any publicly released @@ -228,9 +241,9 @@ <STRONG>o</STRONG> whether the <EM>locale</EM> uses UTF-8 encoding. - In certain cases, the terminal is unable to display line-drawing char- - 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>). + In certain cases, the terminal is unable to display line-drawing + characters 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>). </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE> @@ -238,9 +251,9 @@ single character. As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></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>. + distinction between SVr4 curses and X/Open Curses is that the non- + character information (attributes and color) was separated from the + character information which is packed in a <STRONG>chtype</STRONG> to pass to <STRONG>waddch</STRONG>. In this implementation, <STRONG>chtype</STRONG> holds an eight-bit character. But ncurses allows multibyte characters to be passed in a succession of @@ -257,8 +270,8 @@ 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: + For portability to other implementations, do not rely upon this + behavior: <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 @@ -277,8 +290,8 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <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>. + <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><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="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>. 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>. |