X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_addch.3x.html;h=a7fd7e5749fa66ca3f3305b11f2b100a0f315544;hb=e5d1530ca229aef94a3c84ad33f8ae89f35c4045;hp=c0af2f68e20bdb7db782cd268595c743b5d5b517;hpb=ed646e3f683083e787c6ba773364401dc9fa9d40;p=ncurses.git
diff --git a/doc/html/man/curs_addch.3x.html b/doc/html/man/curs_addch.3x.html
index c0af2f68..a7fd7e57 100644
--- a/doc/html/man/curs_addch.3x.html
+++ b/doc/html/man/curs_addch.3x.html
@@ -1,7 +1,8 @@
-
+
curs_addch 3x
-
+
@@ -58,6 +59,7 @@
intwaddch(WINDOW*win,constchtypech);intmvaddch(inty,intx,constchtypech);intmvwaddch(WINDOW*win,inty,intx,constchtypech);
+
intechochar(constchtypech);intwechochar(WINDOW*win,constchtypech);
@@ -94,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.
@@ -172,44 +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.
+
- 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 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 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
+ 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 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
+ the ACS_LANTERN symbol, equating its "VT100+ Character" to I (capi-
+ 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-
+ ently based on the X/Open documentation around 1995). On the other
+ 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.
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)).
- The TABSIZE variable is implemented in some versions of curses, but is
- not part of X/Open curses.
+
+
+ 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
+ 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
+ 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),
+ ncurses discards the partially built character, starting over again.
+
+ 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
+ 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
+ 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.
@@ -217,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).
@@ -237,7 +312,13 @@