'\" t
.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addch.3x,v 1.75 2023/12/16 21:19:37 tom Exp $
-.TH curs_addch 3X 2023-12-16 "ncurses 6.4" "Library calls"
+.\" $Id: curs_addch.3x,v 1.88 2024/05/25 21:13:32 tom Exp $
+.TH curs_addch 3X 2024-05-25 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
+.ds ' \(aq
+.ds ^ \(ha
+.ds ~ \(ti
.\}
.el \{\
.ie t .ds `` ``
.el .ds `` ""
.ie t .ds '' ''
.el .ds '' ""
+.ds ' '
+.ds ^ ^
+.ds ~ ~
.\}
.
.de bP
\fB\%mvwaddch\fP,
\fB\%echochar\fP,
\fB\%wechochar\fP \-
-add a \fIcurses\fR character to a window and advance the cursor
+add a \fIcurses\fP character to a window and advance the cursor
.SH SYNOPSIS
.nf
\fB#include <curses.h>
\fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP);
.fi
.SH DESCRIPTION
-.SS Adding characters
-The \fBaddch\fP, \fBwaddch\fP, \fBmvaddch\fP and \fBmvwaddch\fP routines put
-the character \fIch\fP into the given window at its current window position,
-which is then advanced.
-They are analogous to \fBputchar\fP(3) in \fBstdio\fP(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 \fB\%scrollok\fP(3X) is enabled,
-the scrolling region is scrolled up one line.
-.bP
-If \fB\%scrollok\fP(3X) 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.
+.SS waddch
+.B \%waddch
+writes the
+.I curses
+character
+.I ch
+to the window
+.IR win ","
+then advances the cursor position,
+analogously to the standard C library's \fI\%putchar\fP(3).
+\fB\%ncurses\fP(3X) describes the variants of this function.
.PP
-If \fIch\fP is a tab, newline, carriage return or backspace,
-the cursor is moved appropriately within the window:
+If advancement occurs at the right margin,
.bP
-Backspace moves the cursor one character left; at the left
-edge of a window it does nothing.
+the cursor automatically wraps to the beginning of the next line,
+then,
.bP
-Carriage return moves the cursor to the window left margin on the current line.
+if it was at the bottom of the scrolling region,
+and if \fB\%scrollok\fP(3X) is enabled for
+.IR win ,
+the scrolling region scrolls up one line.
+.PP
+If
+.I ch
+is a
+backspace,
+carriage return,
+line feed,
+or
+tab,
+the cursor moves appropriately within the window.
.bP
-Newline does a \fBclrtoeol\fP,
-then moves the cursor to the window left margin on the next line,
-scrolling the window if on the last line.
+Backspace moves the cursor one character left;
+at the left margin of a window,
+it does nothing.
.bP
-Tabs are considered to be at every eighth column.
-The tab interval may be altered by setting the \fBTABSIZE\fP variable.
-.PP
-If \fIch\fP is any other nonprintable character,
-it is drawn in printable form,
-using the same convention as \fB\%unctrl\fP(3X):
+Carriage return moves the cursor to the left margin on the current line
+of the window.
.bP
-Control characters are displayed in the \fB^\fIX\fR notation.
+Line feed does a \fB\%clrtoeol\fP(3X),
+then advances as if from the right margin.
.bP
-Values above 128 are either meta characters
-(if the screen has not been initialized,
-or if \fB\%meta\fP(3X) has been called with a \fBTRUE\fP E parameter),
-shown in the \fBM\-\fIX\fR notation, or are displayed as themselves.
-In the latter case, the values may not be printable;
-this follows the X/Open specification.
+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
+.B \%TABSIZE
+extension;
+see \fB\%curs_variables\fP(3X).
.PP
-Calling \fBwinch\fP after adding a
-nonprintable character does not return the character itself,
-but instead returns the printable representation of the character.
+If
+.I ch
+is any other nonprintable character,
+it is drawn in printable form using the same convention as
+\fB\%unctrl\fP(3X).
.PP
-Video attributes can be combined with a character argument passed to
-\fBaddch\fP or related functions by logical-ORing them into the character.
-(Thus, text, including attributes, can be copied from one place to another
-using \fB\%inch\fP(3X) and \fBaddch\fP.)
-See the \fB\%curs_attr\fP(3X) page for values of predefined video
-attribute constants that can be usefully OR'ed into characters.
-.SS Echoing characters
-The \fBechochar\fP and \fBwechochar\fP routines are equivalent to a call to
-\fBaddch\fP followed by a call to \fB\%refresh\fP(3X), or a call to \fBwaddch\fP
-followed by a call to \fBwrefresh\fP.
-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\fP family.
-The default character listed
-below is used if the \fBacsc\fP 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.
+Calling \fB\%winch\fP(3X) on the location of a nonprintable character
+does not return the character itself,
+but its \fB\%unctrl\fP(3X) representation.
.PP
+The object or expression
+.I ch
+may contain attributes and/or a color pair identifier.
+(A character with its attributes can be copied from place to place
+using \fB\%winch\fP(3X) and
+.BR \%waddch .)
+See \fB\%curs_attr\fP(3X) for values of predefined video attribute
+constants that can be usefully \*(``or\*(''ed with characters.
+.SS wechochar
+.B \%echochar
+and
+.B \%wechochar
+are equivalent to calling
+.RB \%( w ) addch
+followed by
+.RB \%( w ) refresh .
+.I 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.
+.\" TODO: Combine the following with the "Line Drawing" subsection of
+.\" terminfo(5) and replace this with a cross reference there.
+.SS "Forms-Drawing Characters"
+.I curses
+defines macros starting with
+.B \%ACS_
+that can be used with
+.B \%waddch
+to write line-drawing and other special characters to the screen.
+.I \%ncurses
+terms these
+.I "forms-drawing characters."
+The ACS default listed below is used if the
+.B \%acs_chars
+.RB \%( acsc )
+.I \%term\%info
+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
+.B \%acs_chars
+.RB \%( 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.
+.br
+.ie t .ne 4v
+.el .ne 5v
.TS
-l l l l
-l l l l
-_ _ _ _
-l l l l.
-\fBACS\fP \fBACS\fP \fBacsc\fP \fBGlyph\fP
-\fBName\fP \fBDefault\fP \fBchar\fP \fBName\fP
+Lb Lb Lb Lb
+Lb Lb Lb Lb
+Lb L L Lx.
+\& ACS acsc \&
+Symbol Default char Glyph Name
+_
ACS_BLOCK # 0 solid square block
ACS_BOARD # h board of squares
ACS_BTEE + v bottom tee
-ACS_BULLET o ~ bullet
+ACS_BULLET o \*~ bullet
ACS_CKBOARD : a checker board (stipple)
ACS_DARROW v . arrow pointing down
-ACS_DEGREE ' f degree symbol
+ACS_DEGREE \*' f degree symbol
ACS_DIAMOND + \(ga diamond
ACS_GEQUAL > > greater-than-or-equal-to
ACS_HLINE \- q horizontal line
ACS_S9 \&_ s scan line 9
ACS_STERLING f } pound-sterling symbol
ACS_TTEE + w top tee
-ACS_UARROW ^ \- arrow pointing up
+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\fP upon failure and \fBOK\fP on success
-(the SVr4 manuals specify only
-\*(``an integer value other than \fBERR\fP\*('') upon successful completion,
-unless otherwise noted in the preceding routine descriptions.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
.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.
+In
+.IR \%ncurses ,
+.B \%waddch
+returns
+.B ERR
+if
+.bP
+.I win
+is
+.BR NULL ","
+.bP
+wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
+not been called on
+.I win
+when a write to its bottom right location is attempted,
+or
+.bP
+it is not possible to add a complete character at the cursor position.
.PP
-If it is not possible to add a complete character,
-an error is returned:
+The last may be due to different causes:
.bP
-If \fB\%scrollok\fP(3X) 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.
+conversion of a multibyte character to a byte sequence can fail,
+or
.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.
+at least one of the bytes resulting from conversion from a multibyte
+sequence cannot be added to the window.
+See section \*(``PORTABILITY\*('' below regarding the use of
+.B \%waddch
+with multibyte characters.
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-Note that \fBaddch\fP, \fBmvaddch\fP, \fBmvwaddch\fP, and
-\fBechochar\fP may be macros.
+.BR \%addch ","
+.BR \%mvaddch ","
+.BR \%mvwaddch ","
+and
+.B \%echochar
+may be implemented as macros.
+.SH EXTENSIONS
+.SS TABSIZE
+SVr4 and other versions of
+.I curses
+implement the
+.B \%TABSIZE
+variable,
+but X/Open Curses does not specify it;
+see \fB\%curs_variables\fP(3X).
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-The defaults specified for forms-drawing characters apply in the POSIX locale.
-.SS ACS Symbols
-X/Open Curses states that the \fBACS_\fP definitions are \fBchar\fP constants.
-For the wide-character implementation (see \fBcurs_add_wch\fP),
-there are analogous \fBWACS_\fP definitions which are \fBcchar_t\fP constants.
-Some implementations are problematic:
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+SVr4
+.I curses
+describes a successful return value only as
+\*(``an integer value other than
+.BR ERR \*(''.
+.PP
+The defaults specified for forms-drawing characters apply in the POSIX
+locale.
+.SS "ACS Symbols"
+X/Open Curses states that the
+.B \%ACS_
+definitions are
+.I char
+constants.
+.PP
+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.
+Solaris
+.IR curses ,
+for example,
+defines the ACS symbols as constants;
+others define them as elements of 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
+This implementation uses an array,
+.BR \%acs_map ,
+as did SVr4
+.IR curses .
+NetBSD also uses an array,
+actually named
+.BR \%_acs_char ,
+with a
+.B \%#define
for compatibility.
.bP
-HP-UX curses equates some of the \fBACS_\fP symbols
-to the analogous \fBWACS_\fP symbols as if the \fBACS_\fP symbols were
-wide characters.
-The misdefined symbols are the arrows
-and other symbols which are not used for line-drawing.
+HP-UX
+.I curses
+equates some of the
+.B \%ACS_
+symbols to the analogous
+.B \%WACS_
+symbols as if the
+.B \%ACS_
+symbols were wide characters
+(see \fB\%curs_add_wch\fP(3X)).
+The misdefined symbols are the arrows and others that 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).
+X/Open Curses
+(Issues 2 through 7)
+has a typographical error
+for the
+.B \%ACS_LANTERN
+symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
+(capital I),
+while the header files for SVr4
+.I curses
+and other implementations use \*(``i\*(''
+(small i).
.IP
-None of the terminal descriptions on Unix platforms use uppercase-I,
-except for Solaris (i.e., \fBscreen\fP's terminal description,
+None of the terminal descriptions on Unix platforms use uppercase I,
+except for Solaris
+(in its
+.I \%term\%info
+entry for \fI\%screen\fP(1),
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
+On the other hand,
+its
+.B \%gs6300
+(AT&T PC6300 with EMOTS Terminal Emulator)
+description uses lowercase i.
+.PP
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\fP 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 \fB\%ncurses\fP(3X).
-.LP
-The \fIdisplayed\fP values for the \fBACS_\fP and \fBWACS_\fP constants
-depend on
+.RB ( \%ACS_S3 ,
+.BR \%ACS_S7 ,
+.BR \%ACS_LEQUAL ,
+.BR \%ACS_GEQUAL ,
+.BR \%ACS_PI ,
+.BR \%ACS_NEQUAL ,
+and
+.BR \%ACS_STERLING )
+were not documented in any publicly released System\ V.
+However,
+many publicly available
+.I \%term\%info
+entries include
+.B \%acsc
+capabilities in which their key characters
+.RB ( pryz{|} )
+are embedded,
+and a second-hand list of their character descriptions has come to
+light.
+The
+.I \%ncurses
+developers invented ACS-prefixed names for them.
+.PP
+The
+.I displayed
+values of
+.B \%ACS_
+constants depend on
.bP
-the library configuration,
-i.e.,
-\fI\%ncurses\fP versus \fI\%ncursesw\fP,
-where the latter is capable of displaying Unicode while the former is not, and
+the
+.I \%ncurses
+ABI\(emfor example,
+wide-character versus non-wide-character configurations
+(the former is capable of displaying Unicode while the latter 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 \fB\%NCURSES_NO_UTF8_ACS\fP in
-\fB\%ncurses\fP(3X)).
-.SS Character Set
-X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
-a single character.
-As discussed in \fB\%curs_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 \fI\%ncurses\fP 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.
+whether the locale uses UTF-8 encoding.
.PP
-Depending on the locale settings,
-\fI\%ncurses\fP 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,
-\fI\%ncurses\fP displays the character and moves to the next position in the screen.
+In certain cases,
+the terminal is unable to display forms-drawing characters
+.I except
+by using UTF-8;
+see the discussion of the
+.I \%NCURSES_NO_UTF8_ACS
+environment variable in \fB\%ncurses\fP(3X).
+.SS "Character Set"
+X/Open Curses assumes that the parameter passed to
+.B \%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
+.IR chtype ","
+though the use of bit operations to combine the character code with
+attributes and a color pair identifier into a
+.I \%chtype
+for passage to
+.B \%waddch
+is common.
+A portable application uses only the macros discussed in
+\fB\%curs_attr\fP(3X) to manipulate a
+.IR \%chtype "."
.PP
+In
+.IR \%ncurses ,
+.I \%chtype
+holds an eight-bit character,
+but the library allows a multibyte character to be passed in a
+succession of calls to
+.BR \%waddch "."
+Other implementations do not;
+a
+.B \%waddch
+call transmits exactly one character,
+which may be rendered in one or more screen locations depending on
+whether it is printable
+(see \fB\%unctrl\fP(3X)).
+Depending on the locale,
+.I \%ncurses
+inspects the byte passed in each
+.B \%waddch
+call and checks whether the latest call continues a multibyte sequence.
+When a character is
+.IR complete ","
+.I \%ncurses
+displays the character and advances the cursor.
If the calling application interrupts the succession of bytes in
-a multibyte character by moving the current location (e.g., using \fBwmove\fP),
-\fI\%ncurses\fP discards the partially built character,
-starting over again.
+a multibyte character sequence by changing the current location\(emfor
+example,
+with \fB\%wmove\fP(3X)\(em\c
+.I \%ncurses
+discards the incomplete character.
.PP
For portability to other implementations,
-do not rely upon this behavior:
+do not rely upon the foregoing behavior.
+Check whether a character can be represented as a single byte in the
+current locale.
.bP
-check if a character can be represented as a single byte in the current locale
-before attempting call \fBwaddch\fP, and
+If it can,
+call either
+.B \%waddch
+or \fB\%wadd_wch\fP(3X).
.bP
-call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP.
-.SS TABSIZE
-The \fBTABSIZE\fP variable is implemented in SVr4 and other versions of curses,
-but is not part of X/Open curses
-(see \fBcurs_variables\fP(3X) for more details).
-.LP
-If \fIch\fP 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.
+If it cannot,
+use only
+\fB\%wadd_wch\fP(3X).
.SH SEE ALSO
+\fB\%curs_add_wch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP
\fB\%curses\fP(3X),
+\fB\%curs_addchstr\fP(3X),
+\fB\%curs_addstr\fP(3X),
\fB\%curs_attr\fP(3X),
\fB\%curs_clear\fP(3X),
\fB\%curs_inch\fP(3X),
\fB\%curs_outopts\fP(3X),
\fB\%curs_refresh\fP(3X),
\fB\%curs_variables\fP(3X),
-\fB\%putc\fP(3)
-.PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fB\%curs_add_wch\fP(3X).
+\fB\%putchar\fP(3)
projects / ncurses.git / blobdiff