X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_addch.3x.html;h=8bdcec1cdfbff6857c214874cbd9063a8fab3ebb;hp=74834b36d5ff0c214ef7e518f829954378650506;hb=9f479192e3ca3413d235c66bf058f8cc63764898;hpb=17c5992a16be94247b83f2bbb9accdd9b7e7bb72 diff --git a/doc/html/man/curs_addch.3x.html b/doc/html/man/curs_addch.3x.html index 74834b36..8bdcec1c 100644 --- a/doc/html/man/curs_addch.3x.html +++ b/doc/html/man/curs_addch.3x.html @@ -1,7 +1,8 @@ -
--curs_addch(3x) curs_addch(3x) +curs_addch(3X) curs_addch(3X)
- addch, waddch, mvaddch, mvwaddch, echochar, wechochar - add a character - (with attributes) to a curses window, then advance the cursor + addch, waddch, mvaddch, mvwaddch, echochar, wechochar - add a character + (with attributes) to a curses window, then advance the cursor
- #include <curses.h> + #include <curses.h> - int addch(const chtype ch); - 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); + int addch(const chtype ch); + 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);
- The addch, waddch, mvaddch and mvwaddch routines put the character ch + The addch, waddch, mvaddch and mvwaddch routines put the character ch into the given window at its current window position, which is then - advanced. They are analogous to putchar(3) in stdio(3). If the + advanced. They are analogous to putchar(3) in stdio(3). If the advance is at the right margin: - o The cursor automatically wraps to the beginning of the next line. + o The cursor automatically wraps to the beginning of the next line. - o At the bottom of the current scrolling region, and if scrollok is + o At the bottom of the current scrolling region, and if scrollok is enabled, the scrolling region is scrolled up one line. - o If scrollok is not enabled, writing a character at the lower right + 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 - If ch is a tab, newline, carriage return or backspace, the cursor is + If ch is a tab, newline, carriage return or backspace, the cursor is moved appropriately within the window: - o Backspace moves the cursor one character left; at the left edge of + o Backspace moves the cursor one character left; at the left edge of a window it does nothing. - o Carriage return moves the cursor to the window left margin on the + o Carriage return moves the cursor to the window left margin on the current line. - o Newline does a clrtoeol, then moves the cursor to the window left + o Newline does a clrtoeol, then moves the cursor to the window left margin on the next line, scrolling the window if on the last line. - o Tabs are considered to be at every eighth column. The tab interval - may be altered by setting the TABSIZE variable. + 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. + addch or related functions by logical-ORing them into the character. (Thus, text, including attributes, can be copied from one place to - another using inch(3x) and addch.) See the curs_attr(3x) page for val- - ues of predefined video attribute constants that can be usefully OR'ed - into characters. + another using inch(3X) and addch.) See the curs_attr(3X) page for + values of predefined video attribute constants that can be usefully + OR'ed into characters.
- The echochar and wechochar routines are equivalent to a call to addch - followed by a call to refresh(3x), or a call to waddch followed by a - call to wrefresh. 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. + The echochar and wechochar routines are equivalent to a call to addch + followed by a call to refresh(3X), or a call to waddch followed by a + call to wrefresh. The knowledge that only a single character is being + output is used and, for non-control characters, a considerable + performance gain may be seen by using these routines instead of their + equivalents.
The following variables may be used to add line drawing characters to - the screen with routines of the addch family. The default character - listed below is used if the acsc 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. + the screen with routines of the addch family. The default character + listed below is used if the acsc capability does not define a terminal- + 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. - ACS ACS acsc Glyph - Name Default char Name + ACS ACS acsc Glyph + Name Default char Name --------------------------------------------------------- ACS_BLOCK # 0 solid square block ACS_BOARD # h board of squares @@ -163,18 +166,29 @@
- All routines return the integer ERR upon failure and OK on success (the - SVr4 manuals specify only "an integer value other than ERR") upon suc- - cessful completion, unless otherwise noted in the preceding routine + All routines return the integer ERR upon failure and OK on success (the + SVr4 manuals specify only "an integer value other than ERR") upon + successful completion, unless otherwise noted in the preceding routine descriptions. - Functions with a "mv" prefix first perform a cursor movement using - wmove, and return an error if the position is outside the window, or if + Functions with a "mv" prefix first perform a cursor movement using + 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. + Note that addch, mvaddch, mvwaddch, and echochar may be macros.
@@ -184,82 +198,107 @@
- 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. + X/Open Curses states that the ACS_ definitions are char constants. For + the wide-character implementation (see curs_add_wch), there are + analogous WACS_ definitions which are cchar_t constants. Some + implementations are problematic: + + 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. + 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 + misdefined 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 + the ACS_LANTERN symbol, equating its "VT100+ Character" to I + (capital 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, + apparently based on the X/Open documentation around 1995). On the + other hand, the terminal description gs6300 (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 - System V. However, many publicly available terminfos include acsc + 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 ACS-prefixed names for them were invented for ncurses(3X). - The displayed values for the ACS_ and WACS_ constants depend on + The displayed values for the ACS_ and WACS_ constants depend on - o the library configuration, i.e., ncurses versus ncursesw, where the + o the library configuration, i.e., ncurses versus ncursesw, where the latter is capable of displaying Unicode while the former is not, and - o whether the locale uses UTF-8 encoding. + o whether the locale 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 NCURSES_NO_UTF8_ACS - in ncurses(3x)). + In certain cases, the terminal is unable to display line-drawing + characters 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 + 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. + 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 chtype to pass to waddch. - In this implementation, chtype holds eight bits. 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. + 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 - multibyte sequence. When a character is complete, ncurses displays the + 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 - multibyte character by moving the current location (e.g., using wmove), + 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- - ior: + For portability to other implementations, do not rely upon this + behavior: - o check if a character can be represented as a single byte in the - current locale before attempting call waddch, and + 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. + o call wadd_wch for characters which cannot be handled by waddch.
- The TABSIZE variable is implemented in some versions of curses, but is - not part of X/Open curses. + 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 + 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 is not documented.
- curses(3x), curs_attr(3x), curs_clear(3x), curs_inch(3x), curs_out- - opts(3x), curs_refresh(3x), curs_variables(3x), putc(3). + curses(3X), curs_attr(3X), curs_clear(3X), curs_inch(3X), + curs_outopts(3X), curs_refresh(3X), curs_variables(3X), putc(3). - Comparable functions in the wide-character (ncursesw) library are - described in curs_add_wch(3x). + Comparable functions in the wide-character (ncursesw) library are + described in curs_add_wch(3X). - curs_addch(3x) + curs_addch(3X)