+'\" t
.\"***************************************************************************
.\" Copyright 2019-2021,2023 Thomas E. Dickey *
.\" Copyright 2001-2015,2017 Free Software Foundation, Inc. *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wch.3x,v 1.36 2023/07/01 14:23:04 tom Exp $
-.TH curs_add_wch 3X 2023-07-01 "ncurses 6.4" "Library calls"
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_add_wch.3x,v 1.46 2023/10/07 21:19:07 tom Exp $
+.TH curs_add_wch 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
.SH NAME
-\fBadd_wch\fP,
-\fBwadd_wch\fP,
-\fBmvadd_wch\fP,
-\fBmvwadd_wch\fP,
-\fBecho_wchar\fP,
-\fBwecho_wchar\fP \- add a complex character and rendition to a \fBcurses\fP window, then advance the cursor
+\fB\%add_wch\fP,
+\fB\%wadd_wch\fP,
+\fB\%mvadd_wch\fP,
+\fB\%mvwadd_wch\fP,
+\fB\%echo_wchar\fP,
+\fB\%wecho_wchar\fP \-
+add a \fIcurses\fR complex character to a window and advance the cursor
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-.B "int add_wch( const cchar_t *\fIwch\fB );"
-.br
-.B "int wadd_wch( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );"
-.br
-.B "int mvadd_wch( int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );"
-.br
-.B "int mvwadd_wch( WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );"
-.sp
-.B "int echo_wchar( const cchar_t *\fIwch\fB );"
-.br
-.B "int wecho_wchar( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );"
+.nf
+\fB#include <curses.h>
+.PP
+\fBint add_wch(const cchar_t *\fIwch\fP);
+\fBint wadd_wch(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
+\fBint mvadd_wch(int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP);
+\fBint mvwadd_wch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP);
+.PP
+\fBint echo_wchar(const cchar_t *\fIwch\fP);
+\fBint wecho_wchar(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
+.fi
.SH DESCRIPTION
.SS add_wch
The
then any previous character at that location is removed.
A new character specified by \fIwch\fP is
placed at that location with rendition specified by \fIwch\fP.
-The cursor then advances to
-the next spacing character on the screen.
+The cursor then advances after this spacing character,
+to prepare for writing the next character on the screen.
+.IP
+The newly added spacing character is the base of the active complex character.
+Subsequent non-spacing characters can be combined with this base
+until another spacing character is written to the screen,
+or the cursor is moved, e.g., using \fBwmove\fP.
.bP
If \fIwch\fP refers to a non-spacing character,
-all previous characters at that location are preserved.
-The non-spacing characters of \fIwch\fP
-are added to the spacing complex character,
-and the rendition specified by \fIwch\fP is ignored.
+it is appended to the active complex character,
+retaining the previous characters at that location.
+The rendition specified by \fIwch\fP is ignored.
+.IP
+The cursor is not advanced after adding a non-spacing character.
+Subsequent calls to add non-spacing characters will update the same position.
.bP
If the character part of \fIwch\fP is
a tab, newline, backspace or other control character,
WACS_CKBOARD 0x2592 : a checker board (stipple)
WACS_DARROW 0x2193 v . arrow pointing down
WACS_DEGREE 0x00b0 ' f degree symbol
-WACS_DIAMOND 0x25c6 + ` diamond
+WACS_DIAMOND 0x25c6 + \(ga diamond
WACS_GEQUAL 0x2265 > > greater-than-or-equal-to
WACS_HLINE 0x2500 \- q horizontal line
WACS_LANTERN 0x2603 # i lantern symbol
.PP
The wide-character configuration of ncurses also defines symbols
for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''):
+.PP
.TS
l l l l l
l l l l l
.SH PORTABILITY
All of these functions are described in the XSI Curses standard, Issue 4.
The defaults specified for line-drawing characters apply in the POSIX locale.
-.PP
+.SS WACS Symbols
X/Open Curses makes it clear that the WACS_ symbols should be defined as
a pointer to \fBcchar_t\fP data, e.g., in the discussion of \fBborder_set\fP.
A few implementations are problematic:
\[u2327] U+2327 (x in a rectangle),
\[u256C] U+256C (forms double vertical and horizontal), and
\[u2612] U+2612 (ballot box with x).
+.SS Complex Characters
+The complex character type \fBcchar_t\fR
+can store more than one wide character (\fBwchar_t\fR).
+The X/Open Curses description does not mention this possibility,
+describing only the cases where \fIwch\fP is a spacing character
+or a non-spacing character.
+.PP
+This implementation assumes that \fIwch\fP is constructed using
+\fBsetcchar\fP(3X), and in turn that the result
+.bP
+contains at most one spacing character in the beginning of its list of wide
+characters,
+and zero or more non-spacing characters
+or
+.bP
+may hold one non-spacing character.
+.PP
+In the latter case, ncurses adds the non-spacing character to the active
+(base) spacing character.
.SH SEE ALSO
-.na
-\fBcurses\fP(3X),
-\fBcurs_addch\fP(3X),
-\fBcurs_attr\fP(3X),
-\fBcurs_clear\fP(3X),
-\fBcurs_outopts\fP(3X),
-\fBcurs_refresh\fP(3X),
-\fBputwc\fP(3)
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_attr\fP(3X),
+\fB\%curs_clear\fP(3X),
+\fB\%curs_getcchar\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%putwc\fP(3)
projects / ncurses.git / blobdiff