'\" t
-.\" $Id: curs_addch.3x,v 1.10 1997/12/13 22:37:23 tom Exp $
+.\"***************************************************************************
+.\" Copyright 2018-2019,2020 Thomas E. Dickey *
+.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
+.\" *
+.\" Permission is hereby granted, free of charge, to any person obtaining a *
+.\" copy of this software and associated documentation files (the *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" $Id: curs_addch.3x,v 1.55 2020/10/24 09:12:31 tom Exp $
.TH curs_addch 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR,
-\fBechochar\fR, \fBwechochar\fR - add a character (with attributes) to a
-\fBcurses\fR window, then advance the cursor
+\fBaddch\fR,
+\fBwaddch\fR,
+\fBmvaddch\fR,
+\fBmvwaddch\fR,
+\fBechochar\fR,
+\fBwechochar\fR \- add a character (with attributes) to a \fBcurses\fR window, then advance the cursor
.SH SYNOPSIS
\fB#include <curses.h>\fR
-
-\fBint addch(chtype ch);\fR
+.PP
+\fBint addch(const chtype \fP\fIch\fP\fB);\fR
.br
-\fBint waddch(WINDOW *win, chtype ch);\fR
+\fBint waddch(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fR
.br
-\fBint mvaddch(int y, int x, chtype ch);\fR
+\fBint mvaddch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\fB);\fR
.br
-\fBint mvwaddch(WINDOW *win, int y, int x, chtype ch);\fR
+\fBint mvwaddch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\fB);\fR
+.sp
+\fBint echochar(const chtype \fP\fIch\fP\fB);\fR
.br
-\fBint echochar(chtype ch);\fR
-.br
-\fBint wechochar(WINDOW *win, chtype ch);\fR
+\fBint wechochar(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fR
.br
.SH DESCRIPTION
+.SS Adding characters
The \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR and \fBmvwaddch\fR routines put
the character \fIch\fR into the given window at its current window position,
-which is then advanced. They are analogous to \fBputchar\fR in \fBstdio\fR(3).
-If the advance is at the right margin, the cursor automatically wraps to the
-beginning of the next line. At the bottom of the current scrolling region, if
-\fBscrollok\fR is enabled, the scrolling region is scrolled up one line.
-
-If \fIch\fR is a tab, newline, or backspace, the cursor is moved appropriately
-within the window. Backspace moves the cursor one character left; at the left
-edge of a window it does nothing. Newline does a \fBclrtoeol\fR, then moves
-the cursor to the window left margin on the next line, scrolling the window if
-on the last line). Tabs are considered to be at every eighth column.
-
-If \fIch\fR is any control character other than tab, newline, or backspace, it
-is drawn in \fB^\fR\fIX\fR notation. Calling \fBwinch\fR after adding a
-control character does not return the character itself, but instead returns
-the ^-representation of the control character. (To emit control characters
-literally, use \fBechochar\fR.)
-
+which is then advanced.
+They are analogous to \fBputchar\fR(3) in \fBstdio\fR(3).
+If the advance is at the right margin:
+.bP
+The cursor automatically wraps to the beginning of the next line.
+.bP
+At the bottom of the current scrolling region,
+and if \fBscrollok\fR is enabled,
+the scrolling region is scrolled up one line.
+.bP
+If \fBscrollok\fR 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
+.PP
+If \fIch\fR is a tab, newline, carriage return or backspace,
+the cursor is moved appropriately within the window:
+.bP
+Backspace moves the cursor one character left; at the left
+edge of a window it does nothing.
+.bP
+Carriage return moves the cursor to the window left margin on the current line.
+.bP
+Newline does a \fBclrtoeol\fR,
+then moves the cursor to the window left margin on the next line,
+scrolling the window if on the last line.
+.bP
+Tabs are considered to be at every eighth column.
+The tab interval may be altered by setting the \fBTABSIZE\fR variable.
+.PP
+If \fIch\fR is any other nonprintable character,
+it is drawn in printable form,
+i.e., the \fB^\fR\fIX\fR notation used by \fBunctrl\fR(3X).
+Calling \fBwinch\fR after adding a
+nonprintable character does not return the character itself,
+but instead returns the printable representation of the character.
+.PP
Video attributes can be combined with a character argument passed to
\fBaddch\fR or related functions by logical-ORing them into the character.
(Thus, text, including attributes, can be copied from one place to another
-using \fBinch\fR and \fBaddch\fR.). See the \fBcurs_attr\fR(3X) page for
+using \fBinch\fR(3X) and \fBaddch\fR.) See the \fBcurs_attr\fR(3X) page for
values of predefined video attribute constants that can be usefully OR'ed
into characters.
-
+.SS Echoing characters
+.PP
The \fBechochar\fR and \fBwechochar\fR routines are equivalent to a call to
-\fBaddch\fR followed by a call to \fBrefresh\fR, or a call to \fBwaddch\fR
-followed by a call to \fBwrefresh\fR. The knowledge that only a single
+\fBaddch\fR followed by a call to \fBrefresh\fR(3X), or a call to \fBwaddch\fR
+followed by a call to \fBwrefresh\fR.
+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.
.SS Line Graphics
The following variables may be used to add line drawing characters to the
-screen with routines of the \fBaddch\fR family. The default character listed
-below is used if the \fBacsc\fR capability doesn't define a terminal-specific
-replacement for it (but see the EXTENSIONS section below). The names are
-taken from VT100 nomenclature.
-
+screen with routines of the \fBaddch\fR family.
+The default character listed
+below is used if the \fBacsc\fR 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.
+.PP
+The names are taken from VT100 nomenclature.
+.PP
.TS
-l l l
-_ _ _
-l l l.
-\fIName\fR \fIDefault\fR \fIDescription\fR
-ACS_ULCORNER + upper left-hand corner
-ACS_LLCORNER + lower left-hand corner
-ACS_URCORNER + upper right-hand corner
-ACS_LRCORNER + lower right-hand corner
-ACS_RTEE + right tee
-ACS_LTEE + left tee
-ACS_BTEE + bottom tee
-ACS_TTEE + top tee
-ACS_HLINE - horizontal line
-ACS_VLINE | vertical line
-ACS_PLUS + plus
-ACS_S1 - scan line 1
-ACS_S9 \&_ scan line 9
-ACS_DIAMOND + diamond
-ACS_CKBOARD : checker board (stipple)
-ACS_DEGREE ' degree symbol
-ACS_PLMINUS # plus/minus
-ACS_BULLET o bullet
-ACS_LARROW < arrow pointing left
-ACS_RARROW > arrow pointing right
-ACS_DARROW v arrow pointing down
-ACS_UARROW ^ arrow pointing up
-ACS_BOARD # board of squares
-ACS_LANTERN # lantern symbol
-ACS_BLOCK # solid square block
-ACS_S3 - scan line 3
-ACS_S7 - scan line 7
-ACS_LEQUAL < less-than-or-equal-to
-ACS_GEQUAL > greater-than-or-equal-to
-ACS_PI * greek pi
-ACS_NEQUAL ! not-equal
-ACS_STERLING f pound-sterling symbol
+l l l l
+l l l l
+_ _ _ _
+l l l l.
+\fBACS\fR \fBACS\fR \fBacsc\fP \fBGlyph\fR
+\fBName\fR \fBDefault\fR \fBchar\fP \fBName\fR
+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
.TE
-
.SH RETURN VALUE
All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success
-(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon
-successful completion, unless otherwise noted in the preceding routine
-descriptions.
+(the SVr4 manuals specify only
+\*(``an integer value other than \fBERR\fR\*('') upon successful completion,
+unless otherwise noted in the preceding routine descriptions.
+.PP
+Functions with a \*(``mv\*('' prefix first perform a cursor movement using
+\fBwmove\fP, and return an error if the position is outside the window,
+or if the window pointer is null.
+.PP
+If it is not possible to add a complete character,
+an error is returned:
+.bP
+If \fBscrollok\fR 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
+.bP
+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.
.SH NOTES
Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and
\fBechochar\fR may be macros.
-.SH EXTENSIONS
-The following extended \fBcurses\fR features are available only on PC-clone
-consoles and compatible terminals obeying the ANSI.SYS de-facto standard for
-terminal control sequences. They are not part of XSI curses.
-
-The attribute A_ALTCHARSET actually forces literal display of PC ROM characters
-including the high-half graphics. Your console driver may still capture or
-translate a few (such as ESC) but this feature should give you access to the
-card-suit characters, up and down-arrow, and most others in the range 0-32.
-(In a terminfo entry designed for use with \fBncurses\fR, the high-half
-characters are obtained using this attribute with an \fBacsc\fR string in
-which the second of each pair is a high-half character.)
-
-Giving \fBwechochar\fR an argument with its high bit set will produce the
-corresponding high-half ASCII graphic (SVr4 curses also has this feature but
-does not document it). A control-character argument, however, will not
-typically produce the corresponding graphic; characters such as CR, NL, FF and
-TAB are typically interpreted by the console driver itself, and ESC will be
-interpreted as the leader of a control sequence.
.SH PORTABILITY
All these functions are described in the XSI Curses standard, Issue 4.
The defaults specified for forms-drawing characters apply in the POSIX locale.
-
-The seven ACS symbols starting with \fBACS_S3\fR were not documented in
-any publicly released System V. However, many publicly available terminfos
-include \fBacsc\fR strings in which their key characters (pryz{|}) are
+.SS ACS Symbols
+.LP
+X/Open Curses states that the \fIACS_\fP definitions are \fBchar\fP constants.
+For the wide-character implementation (see \fBcurs_add_wch\fP),
+there are analogous \fIWACS_\fP definitions which are \fBcchar_t\fP constants.
+Some implementations are problematic:
+.bP
+Some implementations define the ACS symbols to a constant
+(such as Solaris), while others define those to entries in an array.
+.IP
+This implementation uses an array \fBacs_map\fP, as done in SVr4 curses.
+NetBSD also uses an array, actually named \fB_acs_char\fP, with a \fB#define\fP
+for compatibility.
+.bP
+HPUX curses equates some of the \fIACS_\fP symbols
+to the analogous \fIWACS_\fP symbols as if the \fIACS_\fP symbols were
+wide characters.
+The misdefined symbols are the arrows
+and other symbols which are not used for line-drawing.
+.bP
+X/Open Curses (issues 2 through 7) has a typographical error
+for the ACS_LANTERN symbol, equating its \*(``VT100+ Character\*(''
+to \fBI\fP (capital I), while the header files for SVr4 curses
+and the various implementations use \fBi\fP (lowercase).
+.IP
+None of the terminal descriptions on Unix platforms use uppercase-I,
+except for Solaris (i.e., \fIscreen\fP's terminal description,
+apparently based on the X/Open documentation around 1995).
+On the other hand, the terminal description \fIgs6300\fP
+(AT&T PC6300 with EMOTS Terminal Emulator) uses lowercase-i.
+.LP
+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 \fBacsc\fR 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 \fBncurses\fR(3X).
+to light.
+The ACS-prefixed names for them were invented for \fBncurses\fR(3X).
+.LP
+The \fIdisplayed\fP values for the \fIACS_\fP and \fIWACS_\fP constants
+depend on
+.bP
+the library configuration, i.e., \fBncurses\fP versus \fBncursesw\fP,
+where the latter is capable of displaying Unicode while the former is not, and
+.bP
+whether the \fIlocale\fP uses UTF-8 encoding.
+.LP
+In certain cases, the terminal is unable to display line-drawing characters
+except by using UTF-8 (see the discussion of \fBNCURSES_NO_UTF8_ACS\fP in
+ncurses(3X)).
+.SS Character Set
+X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
+a single character.
+As discussed in \fBcurs_attr\fP(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-character information (attributes and color) was
+separated from the character information which is packed in a \fBchtype\fP
+to pass to \fBwaddch\fP.
+.PP
+In this implementation, \fBchtype\fP holds an eight-bit character.
+But ncurses allows multibyte characters to be passed in a succession
+of calls to \fBwaddch\fP.
+The other implementations do not do this;
+a call to \fBwaddch\fP passes exactly one character
+which may be rendered as one or more cells on the screen
+depending on whether it is printable.
+.PP
+Depending on the locale settings,
+ncurses will inspect the byte passed in each call to \fBwaddch\fP,
+and check if the latest call will continue a multibyte sequence.
+When a character is \fIcomplete\fP,
+ncurses displays the character and moves to the next position in the screen.
+.PP
+If the calling application interrupts the succession of bytes in
+a multibyte character by moving the current location (e.g., using \fBwmove\fP),
+ncurses discards the partially built character,
+starting over again.
+.PP
+For portability to other implementations,
+do not rely upon this behavior:
+.bP
+check if a character can be represented as a single byte in the current locale
+before attempting call \fBwaddch\fP, and
+.bP
+call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP.
+.SS TABSIZE
+.LP
+The \fBTABSIZE\fR variable is implemented in SVr4 and other versions of curses,
+but is not part of X/Open curses
+(see \fBcurs_variables\fR(3X) for more details).
+.LP
+If \fIch\fR 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.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_attr\fR(3X), \fBcurs_clear\fR(3X),
-\fBcurs_inch\fR(3X), \fBcurs_outopts\fR(3X), \fBcurs_refresh\fR(3X),
-\fBputc\fR(3S).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fBcurses\fR(3X),
+\fBcurs_attr\fR(3X),
+\fBcurs_clear\fR(3X),
+\fBcurs_inch\fR(3X),
+\fBcurs_outopts\fR(3X),
+\fBcurs_refresh\fR(3X),
+\fBcurs_variables\fR(3X),
+\fBputc\fR(3).
+.PP
+Comparable functions in the wide-character (ncursesw) library are
+described in
+\fBcurs_add_wch\fR(3X).
projects / ncurses.git / blobdiff