+ waddch writes the curses character ch to the window win, then advances
+ the cursor position, analogously to the standard C library's
+ putchar(3). ncurses(3x) describes the variants of this function.
+
+ If advancement occurs at the right margin,
+
+ o the cursor automatically wraps to the beginning of the next line,
+ then,
+
+ o if it was at the bottom of the scrolling region, and if
+ scrollok(3x) is enabled for win, the scrolling region scrolls up
+ one line.
+
+ If ch is a backspace, carriage return, line feed, or tab, the cursor
+ moves appropriately within the window.
+
+ o Backspace moves the cursor one character left; at the left margin
+ of a window, it does nothing.
+
+ o Carriage return moves the cursor to the left margin on the current
+ line of the window.
+
+ o Line feed does a clrtoeol(3x), then advances as if from the right
+ margin.
+
+ o Tab advances the cursor to the next tab stop (possibly on the next
+ line); these are placed at every eighth column by default. Alter
+ the tab interval with the TABSIZE extension; see
+ curs_variables(3x).
+
+ If ch is any other nonprintable character, it is drawn in printable
+ form using the same convention as unctrl(3x). Calling winch(3x) on the
+ location of a nonprintable character does not return the character
+ itself, but its unctrl(3x) representation.
+
+ The object or expression ch may contain attributes and/or a color pair
+ identifier. (A chtype can be copied from place to place using
+ winch(3x) and waddch.) See curs_attr(3x) for values of predefined
+ constants that can be usefully "or"ed with characters.
+
+
+
+ echochar and wechochar are equivalent to calling (w)addch followed by
+ (w)refresh. curses interprets these functions as a hint that only a
+ single character is being output; for non-control characters, a
+ considerable performance gain may be enjoyed by employing them.
+
+
+ curses defines macros starting with ACS_ that can be used with waddch
+ to write line-drawing and other special characters to the screen.
+ ncurses terms these forms-drawingcharacters. The ACS default listed
+ below is used if the acs_chars (acsc) terminfo capability does not
+ define a terminal-specific replacement for it, or if the terminal and
+ locale configuration requires Unicode to access these characters but
+ the library is unable to use Unicode. The "acsc char" column
+ corresponds to how the characters are specified in the acs_chars (acsc)
+ string capability, and the characters in it may appear on the screen if
+ the terminal type's database entry incorrectly advertises ACS support.
+ The name "ACS" originates in the Alternate Character Set feature of the
+ DEC VT100 terminal.
-
-
DESCRIPTION
- 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 in stdio(3). If the advance is at the right mar-
- gin:
-
- 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 enabled, the scrolling region is scrolled
- up one line.
-
- 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, or backspace, the cursor is moved
- appropriately within the window:
-
- o Backspace moves the cursor one character left; at the
- left edge of a window it does nothing.
-
- 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.
-
- If ch is any control character other than tab, newline, or
- backspace, it is drawn in ^X notation. Calling winch
- after adding a control character does not return the char-
- acter itself, but instead returns the ^-representation of
- the control character.
-
- Video attributes can be combined with a character argument
- passed to 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 and
- addch.) See the curs_attr(3x) page for values of prede-
- fined 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, 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.
-
- LineGraphics
- The following variables may be used to add line drawing
- characters to the screen with routines of the addch fam-
- ily. The default character listed below is used if the
- acsc capability does not define a terminal-specific
- replacement for it. The names are taken from VT100 nomen-
- clature.
-
- NameDefaultDescription
- --------------------------------------------------
- ACS_BLOCK # solid square block
- ACS_BOARD # board of squares
- ACS_BTEE + bottom tee
- ACS_BULLET o bullet
- ACS_CKBOARD : checker board (stipple)
- ACS_DARROW v arrow pointing down
- ACS_DEGREE ' degree symbol
- ACS_DIAMOND + diamond
- ACS_GEQUAL > greater-than-or-equal-to
- ACS_HLINE - horizontal line
- ACS_LANTERN # lantern symbol
- ACS_LARROW < arrow pointing left
- ACS_LEQUAL < less-than-or-equal-to
- ACS_LLCORNER + lower left-hand corner
- ACS_LRCORNER + lower right-hand corner
- ACS_LTEE + left tee
- ACS_NEQUAL ! not-equal
- ACS_PI * greek pi
- ACS_PLMINUS # plus/minus
- ACS_PLUS + plus
- ACS_RARROW > arrow pointing right
- ACS_RTEE + right tee
- ACS_S1 - scan line 1
- ACS_S3 - scan line 3
- ACS_S7 - scan line 7
- ACS_S9 _ scan line 9
- ACS_STERLING f pound-sterling symbol
- ACS_TTEE + top tee
- ACS_UARROW ^ arrow pointing up
- ACS_ULCORNER + upper left-hand corner
- ACS_URCORNER + upper right-hand corner
- ACS_VLINE | vertical line
+ ACSacsc
+ SymbolDefaultcharGlyphName
+ ------------------------------------------------------------------------
+ ACS_BLOCK # 0 solid square block
+ ACS_BOARD # h board of squares
+ ACS_BTEE + v bottom tee
+ ACS_BULLET o ~ bullet
+ ACS_CKBOARD : a checker board (stipple)
+ ACS_DARROW v . arrow pointing down
+ ACS_DEGREE ' f degree symbol
+ ACS_DIAMOND + ` diamond
+ ACS_GEQUAL > > greater-than-or-equal-to
+ ACS_HLINE - q horizontal line
+ ACS_LANTERN # i lantern symbol
+ ACS_LARROW < , arrow pointing left
+ ACS_LEQUAL < y less-than-or-equal-to
+ ACS_LLCORNER + m lower left-hand corner
+ ACS_LRCORNER + j lower right-hand corner
+ ACS_LTEE + t left tee
+ ACS_NEQUAL ! | not-equal
+ ACS_PI * { greek pi
+ ACS_PLMINUS # g plus/minus
+ ACS_PLUS + n plus
+ ACS_RARROW > + arrow pointing right
+ ACS_RTEE + u right tee
+ ACS_S1 - o scan line 1
+ ACS_S3 - p scan line 3
+ ACS_S7 - r scan line 7
+ ACS_S9 _ s scan line 9
+ ACS_STERLING f } pound-sterling symbol
+ ACS_TTEE + w top tee
+ ACS_UARROW ^ - arrow pointing up
+ ACS_ULCORNER + l upper left-hand corner
+ ACS_URCORNER + k upper right-hand corner
+ ACS_VLINE | x vertical line
+
+
+
+ These functions return OK on success and ERR on failure.
+
+ In ncurses, waddch returns ERR if
+
+ owin is NULL,
+
+ o wrapping to a new line is impossible because scrollok(3x) has not
+ been called on win when a write to its bottom right location is
+ attempted, or
+
+ o it is not possible to add a complete character at the cursor
+ position.
+
+ The last may be due to different causes:
+
+ o conversion of a wide character to a multibyte character sequence
+ can fail, or
+
+ o at least one of the bytes resulting from wide character conversion
+ to a multibyte character sequence cannot be added to the window.
+ See section "PORTABILITY" below regarding the use of waddch with
+ wide characters.
+
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (y, x) is outside the window boundaries.
+
+
+
+ X/Open Curses, Issue 4 describes these functions. It specifies no
+ error conditions for them.
+
+ SVr4 curses describes a successful return value only as "an integer
+ value other than ERR".
+
+ The defaults specified for forms-drawing characters apply in the POSIX
+ locale.
+
+
+
+ X/Open Curses states that the ACS_ definitions are char constants.
+ Some implementations are problematic.
+
+ o Solaris curses, for example, defines the ACS symbols as constants;
+ others define them as elements of an array.
+
+ This implementation uses an array, acs_map, as did SVr4 curses.
+ NetBSD also uses an array, actually named _acs_char, with a #define
+ for compatibility.
+ o HP-UX curses equates some of the ACS_ symbols to the analogous
+ WACS_ symbols as if the ACS_ symbols were wide characters (see
+ curs_add_wch(3x)). The misdefined symbols are the arrows and
+ others that are not used for line drawing.
-
-
RETURN VALUE
- 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 other-
- wise noted in the preceding routine descriptions.
+ 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 other
+ implementations use "i" (small i).
- Functions with a "mv" prefix first perform a cursor move-
- ment using wmove, and return an error if the position is
- outside the window, or if the window pointer is null.
+ None of the terminal descriptions on Unix platforms use uppercase
+ I, except for Solaris (in its terminfo entry for screen(1),
+ apparently based on the X/Open documentation around 1995). On the
+ other hand, its gs6300 (AT&T PC6300 with EMOTS Terminal Emulator)
+ description uses lowercase i.
+ Some ACS symbols (ACS_S3, ACS_S7, ACS_LEQUAL, ACS_GEQUAL, ACS_PI,
+ ACS_NEQUAL, and ACS_STERLING) were not documented in any publicly
+ released System V. However, many publicly available terminfo entries
+ include acsc capabilities in which their key characters (pryz{|}) are
+ embedded, and a second-hand list of their character descriptions has
+ come to light. The ncurses developers invented ACS-prefixed names for
+ them.
-
-
NOTES
- Note that addch, mvaddch, mvwaddch, and echochar may be
- macros.
+ The displayed values of ACS_ constants depend on
+ o the ncurses ABI--for example, wide-character versus non-wide-
+ character configurations (the former is capable of displaying
+ Unicode while the latter is not), and
-
-
PORTABILITY
- All these functions are described in the XSI Curses stan-
- dard, Issue 4. The defaults specified for forms-drawing
- characters apply in the POSIX locale.
+ o whether the locale uses UTF-8 encoding.
- 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.
+ In certain cases, the terminal is unable to display forms-drawing
+ characters except by using UTF-8; see the discussion of the
+ NCURSES_NO_UTF8_ACS environment variable in ncurses(3x).
- 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 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. That character may have been more than eight bits
+ wide in an SVr3 or SVr4 implementation, but X/Open Curses leaves the
+ width of a non-wide character code unspecified. The standard further
+ does not specify the internal structure of a chtype, though the use of
+ bit operations to combine the character code with attributes and a
+ color pair identifier into a chtype for passage to waddch is common. A
+ portable application uses only the macros discussed in curs_attr(3x) to
+ manipulate a chtype.
- 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.
+ In ncurses, chtype holds an eight-bit character, but the library allows
+ a multibyte character sequence to be passed via a succession of calls
+ to waddch. Other implementations do not; a waddch call transmits
+ exactly one character, which may be rendered in one or more screen
+ locations depending on whether it is printable (see unctrl(3x)).
+ Depending on the locale, ncurses inspects the byte passed in each
+ waddch call and checks whether the latest call continues a multibyte
+ character. When a character is complete, ncurses displays the
+ character and advances the cursor. If the calling application
+ interrupts the succession of bytes in a multibyte character sequence by
+ changing the current location--for example, with wmove(3x)--ncurses
+ discards the incomplete character.
+ For portability to other implementations, do not rely upon the
+ foregoing behavior. Check whether a character can be represented as a
+ single byte in the current locale.
-