.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addch.3x,v 1.81 2024/03/23 20:38:57 tom Exp $
-.TH curs_addch 3X 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_addch.3x,v 1.92 2024/06/08 20:51:41 tom Exp $
+.TH curs_addch 3X 2024-06-08 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\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"
+.SS waddch
.B \%waddch
-puts the character
+writes the
+.I curses
+character
.I ch
-at the cursor position of window
-.IR win ,
+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 advancement occurs at the right margin,
.bP
-the cursor automatically wraps to the beginning of the next line;
-and
+the cursor automatically wraps to the beginning of the next line,
+then,
.bP
-at the bottom of the current scrolling region,
+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.
of the window.
.bP
Line feed does a \fB\%clrtoeol\fP(3X),
-then moves the cursor to the left margin on the next line of the window,
-scrolling the window if the cursor was already on the last line.
+then advances as if from the right margin.
.bP
Tab advances the cursor to the next tab stop
(possibly on the next line);
If
.I ch
is any other nonprintable character,
-it is drawn in printable form,
-using the same convention as \fB\%unctrl\fP(3X).
-.bP
-.B \%waddch
-displays control characters in
-.BI \*^ X
-notation.
-.bP
-Character codes above 127 are either meta characters
-(if the screen has not been initialized,
-or if \fB\%meta\fP(3X) has been called with a
-.B TRUE
-.I bf
-parameter)
-that render in
-.BI M\- X
-notation,
-or they display as themselves.
-In the latter case,
-the values may not be printable;
-.\" XXX: The following claim could be clearer.
-this follows the X/Open specification.
-.PP
+it is drawn in printable form using the same convention as
+\fB\%unctrl\fP(3X).
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
-Video attributes can be combined with a character argument passed to
-.B \%waddch
-by logical-ORing them into the character.
-(Thus,
-text,
-including attributes,
-can be copied from one place to another using \fB\%winch\fP(3X) and
+The object or expression
+.I ch
+may contain attributes and/or a color pair identifier.
+(A
+.I \%chtype
+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 "Echoing Characters"
+See \fB\%curs_attr\fP(3X) for values of predefined constants that can be
+usefully \*(``or\*(''ed with characters.
+.SS wechochar
.B \%echochar
and
.B \%wechochar
.I "forms-drawing characters."
The ACS default listed below is used if the
.B \%acs_chars
-.RB ( \%acsc )
+.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
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's
+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.
.PP
+.ie t .ne 4v
+.el .ne 5v
.TS
Lb Lb Lb Lb
Lb Lb Lb Lb
.B \%waddch
returns
.B ERR
-if it is not possible to add a complete character at the cursor
-position,
-as when conversion of a multibyte character to a byte sequence fails,
-or at least one of the resulting bytes cannot be added to the window.
-See section \*(``PORTABILITY\*('' below regarding the use of
-.B \%waddch
-with multibyte characters.
+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 \fB\%scrollok\fP(3X) is not enabled,
+The last may be due to different causes:
+.bP
+conversion of a wide character to a multibyte character sequence can
+fail,
+or
+.bP
+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
.B \%waddch
-can successfully write a character at the bottom right location of the
-window.
-However,
-.I \%ncurses
-returns
-.B ERR
-because it is not possible to wrap to a new line.
+with wide characters.
.PP
-Functions with a \*(``mv\*('' prefix first perform cursor movement using
-\fB\%wmove\fP(3X) and fail if the position is outside the window,
-or
-(for \*(``mvw\*('' functions)
-if the
-.I \%WINDOW
-pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
.SH NOTES
-.BR \%addch ,
-.BR \%mvaddch ,
-.BR \%mvwaddch ,
+.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
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"
definitions are
.I char
constants.
-.PP
Some implementations are problematic.
.bP
Solaris
.IR curses ,
for example,
-define the ACS symbols as constants;
+defines the ACS symbols as constants;
others define them as elements of an array.
.IP
This implementation uses an array,
description uses lowercase i.
.PP
Some ACS symbols
-.RB ( \%ACS_S3 ,
+.RB \%( ACS_S3 ,
.BR \%ACS_S7 ,
.BR \%ACS_LEQUAL ,
.BR \%ACS_GEQUAL ,
and
.BR \%ACS_STERLING )
were not documented in any publicly released System\ V.
+.\" And did not exist yet as late as SVr4.
+.\" https://github.com/ryanwoodsmall/oldsysv/blob/master/\
+.\" sysvr4/svr4/lib/xlibcurses/screen/curses.ed
However,
many publicly available
.I \%term\%info
entries include
.B \%acsc
-strings in which their key characters (pryz{|}) are embedded,
+capabilities in which their key characters
+.RB ( pryz{|} )
+are embedded,
and a second-hand list of their character descriptions has come to
light.
The
by using UTF-8;
see the discussion of the
.I \%NCURSES_NO_UTF8_ACS
-environment variable in \fB\%ncurses\fP(3X)).
+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.
-As discussed in \fB\%curs_attr\fP(3X),
-that character may have been more than eight bits wide in an SVr3 or
+That character may have been more than eight bits wide in an SVr3 or
SVr4 implementation,
-but in the X/Open Curses model,
-the details are not given.
-The important distinction between SVr4
-.I curses
-and X/Open Curses is that the latter separates non-character information
-(attributes and color)
-from the character code,
-which SVr4 packs into a
+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
-.BR \%waddch .
+.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
-.I \%ncurses
-allows a multibyte character to be passed in a succession of calls to
-.BR \%waddch .
+holds an eight-bit character,
+but the library allows a multibyte character sequence to be passed via 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.
-.PP
-Depending on the locale settings,
+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.
+call and checks whether the latest call continues a multibyte character.
When a character is
-.IR complete ,
+.IR complete ","
.I \%ncurses
-displays the character and advances the window's current location.
-.PP
+displays the character and advances the cursor.
If the calling application interrupts the succession of bytes in
-a multibyte character sequence by moving the current location
-(for example,
-with \fB\%wmove\fP(3X)),
+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
If it cannot,
use only
\fB\%wadd_wch\fP(3X).
-.SS TABSIZE
-SVr4 and other versions of
+.SH HISTORY
+The original
.I curses
-implement the
-.B \%TABSIZE
-variable,
-but X/Open Curses does not specify it
-(see \fB\%curs_variables\fP(3X)).
+in 4BSD (1980) introduced
+.IR \%waddch "."
+.PP
+SVr3 (1987)
+added
+.IR \%wechochar "."
.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_refresh\fP(3X),
\fB\%curs_variables\fP(3X),
\fB\%putchar\fP(3)
-.PP
-\fB\%curs_add_wch\fP(3X) describes comparable functions of the
-.I \%ncurses
-library in its wide-character configuration
-.RI ( \%ncursesw ).
projects / ncurses.git / blobdiff