X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_addch.3x.html;h=a7fd7e5749fa66ca3f3305b11f2b100a0f315544;hb=e5d1530ca229aef94a3c84ad33f8ae89f35c4045;hp=fa2f94df2b372c67e98a8be81ebb4ed7ee798b5a;hpb=47d2fb4537d9ad5bb14f4810561a327930ca4280;p=ncurses.git diff --git a/doc/html/man/curs_addch.3x.html b/doc/html/man/curs_addch.3x.html index fa2f94df..a7fd7e57 100644 --- a/doc/html/man/curs_addch.3x.html +++ b/doc/html/man/curs_addch.3x.html @@ -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.54 2020/10/17 23:02:40 tom Exp @ --> @@ -59,6 +59,7 @@ int waddch(WINDOW *win, const chtype ch); int mvaddch(int y, int x, const chtype ch); int mvwaddch(WINDOW *win, int y, int x, const chtype ch); + int echochar(const chtype ch); int wechochar(WINDOW *win, const chtype ch); @@ -95,10 +96,10 @@ o Tabs are considered to be at every eighth column. The tab interval may be altered by setting the TABSIZE variable. - If ch is any other control character, it is drawn in ^X notation. - Calling winch after adding a control character does not return the - character itself, but instead returns the ^-representation of the con- - trol character. + If ch is any other nonprintable character, it is drawn in printable + form, i.e., the ^X notation used by unctrl(3x). Calling winch 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 addch or related functions by logical-ORing them into the character. @@ -173,106 +174,117 @@ wmove, 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: + + o If scrollok 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 + + o 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. +
Note that addch, mvaddch, mvwaddch, and echochar may be macros.
- All these functions are described in the XSI Curses standard, Issue 4. - The defaults specified for forms-drawing characters apply in the POSIX + All these functions are described in the XSI Curses standard, Issue 4. + The defaults specified for forms-drawing characters apply in the POSIX locale.
X/Open Curses states that the ACS_ definitions are char constants. For - the wide-character implementation (see curs_add_wch), there are analo- - gous WACS_ definitions which are cchar_t constants. Some implementa- + the wide-character implementation (see curs_add_wch), there are analo- + gous WACS_ definitions which are cchar_t constants. Some implementa- tions are problematic: - o Some implementations define the ACS symbols to a constant (such as + o Some implementations define the ACS symbols to a constant (such as Solaris), while others define those to entries in an array. - This implementation uses an array acs_map, as done in SVr4 curses. + This implementation uses an array acs_map, as done in SVr4 curses. NetBSD also uses an array, actually named _acs_char, with a #define for compatibility. o HPUX curses equates some of the ACS_ symbols to the analogous WACS_ - symbols as if the ACS_ symbols were wide characters. The misde- - fined symbols are the arrows and other symbols which are not used + symbols as if the ACS_ symbols were wide characters. The misde- + fined symbols are the arrows and other symbols which are not used for line-drawing. - o X/Open Curses (issues 2 through 7) has a typographical error for + o X/Open Curses (issues 2 through 7) has a typographical error for the ACS_LANTERN symbol, equating its "VT100+ Character" to I (capi- - tal I), while the header files for SVr4 curses and the various + tal I), while the header files for SVr4 curses and the various implementations use i (lowercase). - None of the terminal descriptions on Unix platforms use uppercase- - I, except for Solaris (i.e., screen's terminal description, appar- + None of the terminal descriptions on Unix platforms use uppercase- + I, except for Solaris (i.e., screen's terminal description, appar- ently based on the X/Open documentation around 1995). On the other - hand, the terminal description gs6300 (AT&T PC6300 with EMOTS Ter- + hand, the terminal description gs6300 (AT&T PC6300 with EMOTS Ter- minal 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 - System V. However, many publicly available terminfos include acsc - strings in which their key characters (pryz{|}) are embedded, and a - second-hand list of their character descriptions has come to light. + Some ACS symbols (ACS_S3, ACS_S7, ACS_LEQUAL, ACS_GEQUAL, ACS_PI, + ACS_NEQUAL, ACS_STERLING) were not documented in any publicly released + System V. However, many publicly available terminfos include acsc + strings in which their key characters (pryz{|}) are embedded, and a + second-hand list of their character descriptions has come to light. The ACS-prefixed names for them were invented for ncurses(3x). The displayed values for the ACS_ and WACS_ constants depend on o the library configuration, i.e., ncurses versus ncursesw, where the - latter is capable of displaying Unicode while the former is not, + latter is capable of displaying Unicode while the former is not, and o whether the locale uses UTF-8 encoding. - In certain cases, the terminal is unable to display line-drawing char- + In certain cases, the terminal is unable to display line-drawing char- acters except by using UTF-8 (see the discussion of NCURSES_NO_UTF8_ACS in ncurses(3x)).
- X/Open Curses assumes that the parameter passed to waddch contains a - single character. As discussed in curs_attr(3x), 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 + X/Open Curses assumes that the parameter passed to waddch contains a + single character. As discussed in curs_attr(3x), 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 chtype to pass to waddch. - In this implementation, chtype holds an eight-bit character. But - ncurses allows multibyte characters to be passed in a succession of - calls to waddch. The other implementations do not do this; a call to - waddch passes exactly one character which may be rendered as one or + In this implementation, chtype holds an eight-bit character. But + ncurses allows multibyte characters to be passed in a succession of + calls to waddch. The other implementations do not do this; a call to + waddch 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 waddch, and check if the latest call will continue a + Depending on the locale settings, ncurses will inspect the byte passed + in each call to waddch, and check if the latest call will continue a multibyte sequence. When a character is complete, ncurses displays the character and moves to the next position in the screen. - If the calling application interrupts the succession of bytes in a + If the calling application interrupts the succession of bytes in a multibyte character by moving the current location (e.g., using wmove), ncurses discards the partially built character, starting over again. - For portability to other implementations, do not rely upon this behav- + For portability to other implementations, do not rely upon this behav- ior: - o check if a character can be represented as a single byte in the + o check if a character can be represented as a single byte in the current locale before attempting call waddch, and o call wadd_wch for characters which cannot be handled by waddch.
- The TABSIZE variable is implemented in SVr4 and other versions of - curses, but is not part of X/Open curses (see curs_variables(3x) for + The TABSIZE variable is implemented in SVr4 and other versions of + curses, but is not part of X/Open curses (see curs_variables(3x) for more details). If ch 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. @@ -280,7 +292,7 @@ curses(3x), curs_attr(3x), curs_clear(3x), curs_inch(3x), curs_out- opts(3x), curs_refresh(3x), curs_variables(3x), putc(3). - Comparable functions in the wide-character (ncursesw) library are + Comparable functions in the wide-character (ncursesw) library are described in curs_add_wch(3x).