+'\" t
.\"***************************************************************************
-.\" Copyright 2019,2020 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.26 2020/02/02 23:34:34 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.48 2023/11/25 14:20:05 tom Exp $
+.TH curs_add_wch 3X 2023-11-25 "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\fR 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 );"
-.br
-.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\fR were called.
+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
l l l l l
_ _ _ _ _
lw(1.5i) lw5 lw5 lw5 lw20.
-\fBACS\fR \fBUnicode\fP \fBASCII\fR \fBacsc\fP \fBGlyph\fR
-\fBName\fR \fBDefault\fP \fBDefault\fR \fBchar\fP \fBName\fR
+\fBACS\fP \fBUnicode\fP \fBASCII\fP \fBacsc\fP \fBGlyph\fP
+\fBName\fP \fBDefault\fP \fBDefault\fP \fBchar\fP \fBName\fP
WACS_BLOCK 0x25ae # 0 solid square block
WACS_BOARD 0x2592 # h board of squares
WACS_BTEE 0x2534 + v bottom tee
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
_ _ _ _ _
lw(1.5i) lw5 lw5 lw5 lw20.
-\fBACS\fR \fBUnicode\fP \fBASCII\fR \fBacsc\fP \fBGlyph\fR
-\fBName\fR \fBDefault\fP \fBDefault\fR \fBchar\fP \fBName\fR
+\fBACS\fP \fBUnicode\fP \fBASCII\fP \fBacsc\fP \fBGlyph\fP
+\fBName\fP \fBDefault\fP \fBDefault\fP \fBchar\fP \fBName\fP
WACS_T_BTEE 0x253b + V thick tee pointing up
WACS_T_HLINE 0x2501 - Q thick horizontal line
WACS_T_LLCORNER 0x2517 + M thick lower left corner
l l l l l
_ _ _ _ _
lw(1.5i) lw5 lw5 lw5 lw20.
-\fBACS\fR \fBUnicode\fP \fBASCII\fR \fBacsc\fP \fBGlyph\fR
-\fBName\fR \fBDefault\fP \fBDefault\fR \fBchar\fP \fBName\fR
+\fBACS\fP \fBUnicode\fP \fBASCII\fP \fBacsc\fP \fBGlyph\fP
+\fBName\fP \fBDefault\fP \fBDefault\fP \fBchar\fP \fBName\fP
WACS_D_BTEE 0x2569 + H double tee pointing up
WACS_D_HLINE 0x2550 - R double horizontal line
WACS_D_LLCORNER 0x255a + D double lower left corner
.bP
U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
.SH RETURN VALUE
+All routines return the integer \fBERR\fP upon failure and \fBOK\fP on success.
+.PP
+X/Open does not define any error conditions.
+This implementation returns an error
+.bP
+if the window pointer is null or
+.bP
+if it is not possible to add a complete character in the window.
.PP
-All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success.
+The latter may be due to different causes:
+.bP
+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
+.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.
.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.
.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.
+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\fR.
+a pointer to \fBcchar_t\fP data, e.g., in the discussion of \fBborder_set\fP.
A few implementations are problematic:
.bP
NetBSD curses defines the symbols as a \fBwchar_t\fP within a \fBcchar_t\fP.
.bP
-HPUX curses equates some of the \fIACS_\fP symbols
-to the analogous \fIWACS_\fP symbols as if the \fIACS_\fP symbols were
+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.
with their corresponding line-drawing characters.
X/Open Curses did not address the aspect of integrating Unicode with
line-drawing characters.
-Existing implementations of Unix curses (AIX, HPUX, Solaris)
+Existing implementations of Unix curses (AIX, HP-UX, Solaris)
use only the \fBacsc\fP character-mapping to provide this feature.
As a result, those implementations can only use single-byte line-drawing
characters.
\[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\fR(3X),
-\fBcurs_addch\fR(3X),
-\fBcurs_attr\fR(3X),
-\fBcurs_clear\fR(3X),
-\fBcurs_outopts\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBputwc\fR(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