ncurses 6.4 - patch 20230917

[ncurses.git] / man / curs_add_wch.3x

diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x
index 26d82e00b01c9657256fbabfd85a8ab0136f8b84..69c2ed0bafaa23425277e56e731974b544df4033 100644 (file)
--- a/man/curs_add_wch.3x
+++ b/man/curs_add_wch.3x
@@ -1,3 +1,4 @@
+'\" t
 .\"***************************************************************************
 .\" Copyright 2019-2021,2023 Thomas E. Dickey                                *
 .\" Copyright 2001-2015,2017 Free Software Foundation, Inc.                  *
@@ -27,8 +28,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_add_wch.3x,v 1.32 2023/03/11 20:40:45 tom Exp $
-.TH curs_add_wch 3X ""
+.\" $Id: curs_add_wch.3x,v 1.43 2023/09/16 23:34:43 tom Exp $
+.TH curs_add_wch 3X 2023-09-16 "ncurses 6.4" "Library calls"
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
@@ -38,14 +39,14 @@
 .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
-.PP
 \fB#include <curses.h>\fP
 .sp
 .B "int add_wch( const cchar_t *\fIwch\fB );"
@@ -59,10 +60,8 @@
 .B "int echo_wchar( const cchar_t *\fIwch\fB );"
 .br
 .B "int wecho_wchar( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );"
-.br
 .SH DESCRIPTION
 .SS add_wch
-.PP
 The
 \fBadd_wch\fP,
 \fBwadd_wch\fP,
@@ -78,20 +77,26 @@ If \fIwch\fP refers to a spacing character,
 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
@@ -157,6 +162,7 @@ WACS_VLINE  0x2502  |       x       vertical line
 .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
@@ -209,7 +215,6 @@ U+2501 BOX DRAWINGS HEAVY HORIZONTAL
 .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.
@@ -235,7 +240,6 @@ 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,
@@ -243,10 +247,9 @@ Note that
 \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:
@@ -322,13 +325,33 @@ Others have suggested these alternatives:
 \[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
-.PP
+.hy 0
 \fBcurses\fP(3X),
 \fBcurs_addch\fP(3X),
 \fBcurs_attr\fP(3X),
 \fBcurs_clear\fP(3X),
+\fBcurs_getcchar\fP(3X),
 \fBcurs_outopts\fP(3X),
 \fBcurs_refresh\fP(3X),
 \fBputwc\fP(3)