+'\" t
.\"***************************************************************************
-.\" Copyright 2019-2020,2021 Thomas E. Dickey *
+.\" Copyright 2019-2021,2023 Thomas E. Dickey *
.\" Copyright 2001-2015,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wch.3x,v 1.31 2021/12/25 21:37:49 tom Exp $
-.TH curs_add_wch 3X ""
-.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
+.nf
+\fB#include <curses.h>
.PP
-\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 );"
-.br
+\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
-.PP
The
\fBadd_wch\fP,
\fBwadd_wch\fP,
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,
the window is updated and the cursor moves as if \fBaddch\fP were called.
.SS echo_wchar
-.PP
The \fBecho_wchar\fP
function is functionally equivalent to a call to
\fBadd_wch\fP
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
.bP
U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
.SH RETURN VALUE
-.PP
All routines return the integer \fBERR\fP upon failure and \fBOK\fP on success.
.PP
X/Open does not define any error conditions.
.PP
The latter may be due to different causes:
.bP
-If \fBscrollok\fP is not enabled,
+If \fBscrollok\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
\fBwmove\fP, and return an error if the position is outside the window,
or if the window pointer is null.
.SH NOTES
-.PP
Note that
\fBadd_wch\fP,
\fBmvadd_wch\fP,
\fBecho_wchar\fP
may be macros.
.SH PORTABILITY
-.PP
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).
-.SH SEE ALSO
-.na
+.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
-\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)
+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
+\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