.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addch.3x,v 1.85 2024/04/20 19:03:47 tom Exp $
-.TH curs_addch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_addch.3x,v 1.86 2024/05/11 20:39:53 tom Exp $
+.TH curs_addch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\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,
-and if \fB\%scrollok\fP(3X) is enabled for
-.IR win ,
-scrolls 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).
+it is drawn in printable form using the same convention as
+\fB\%unctrl\fP(3X).
.PP
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 rendering and/or color attributes,
-and others can be combined with the parameter
-by logically \*(``or\*(''ing with it.
+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 "Echoing Characters"
+.SS wechochar
.B \%echochar
and
.B \%wechochar
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.
.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.
+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
+The last may be due to different causes:
+.bP
+conversion of a multibyte character to a byte sequence can fail,
+or
+.bP
+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
-.B \%waddch
-can successfully write a character at the bottom right location of the
-window.
-However,
-.I \%ncurses
-returns
-.B ERR
-if \fB\%scrollok\fP(3X) is not enabled in that event,
-because it is not possible to wrap to a new line.
-.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
-.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.
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,
.I \%term\%info
entries include
.B \%acsc
-strings in which their key characters
-.BR ( pryz{|} )
+capabilities in which their key characters
+.RB ( pryz{|} )
are embedded,
and a second-hand list of their character descriptions has come to
light.
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 the library allows a multibyte character to be passed in a
+holds an eight-bit character,
+but the library allows a multibyte character to be passed in a
succession of calls to
-.BR \%waddch .
+.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 sequence.
When a character is
-.IR complete ,
+.IR complete ","
.I \%ncurses
displays the character and advances the cursor.
-.PP
If the calling application interrupts the succession of bytes in
a multibyte character sequence by changing the current location\(emfor
example,
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
-.I curses
-implement the
-.B \%TABSIZE
-variable,
-but X/Open Curses does not specify it
-(see \fB\%curs_variables\fP(3X)).
.SH SEE ALSO
\fB\%curs_add_wch\fP(3X) describes comparable functions of the
.I \%ncurses
projects / ncurses.git / blobdiff