X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_add_wch.3x;h=26d82e00b01c9657256fbabfd85a8ab0136f8b84;hb=87c2c84cbd2332d6d94b12a1dcaf12ad1a51a938;hp=1c50b2cd919c3f7930065ff668a5cd9d6b729f09;hpb=06078d3fa68db669ed37178c01873546b4b28745;p=ncurses.git

diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x
index 1c50b2cd..26d82e00 100644
--- a/man/curs_add_wch.3x
+++ b/man/curs_add_wch.3x
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 2001-2015,2017 Free Software Foundation, Inc.              *
+.\" 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  *
 .\" copy of this software and associated documentation files (the            *
@@ -26,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_add_wch.3x,v 1.24 2017/11/18 23:47:37 tom Exp $
+.\" $Id: curs_add_wch.3x,v 1.32 2023/03/11 20:40:45 tom Exp $
 .TH curs_add_wch 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -42,7 +43,7 @@
 \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
+\fBwecho_wchar\fP \- add a complex character and rendition to a \fBcurses\fP window, then advance the cursor
 .SH SYNOPSIS
 .PP
 \fB#include <curses.h>\fP
@@ -54,7 +55,7 @@
 .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
+.sp
 .B "int echo_wchar( const cchar_t *\fIwch\fB );"
 .br
 .B "int wecho_wchar( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );"
@@ -88,7 +89,7 @@ and the rendition specified by \fIwch\fP is ignored.
 .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
@@ -118,8 +119,8 @@ 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_BLOCK	0x25ae 	#	0	solid square block
 WACS_BOARD	0x2592 	#	h	board of squares
 WACS_BTEE	0x2534 	+	v	bottom tee
@@ -155,15 +156,36 @@ WACS_VLINE	0x2502 	|	x	vertical line
 .TE
 .PP
 The wide-character configuration of ncurses also defines symbols
-for double-lines:
+for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''):
+.TS
+l l l l l
+l l l l l
+_ _ _ _ _
+lw(1.5i) lw5 lw5 lw5 lw20.
+\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
+WACS_T_LRCORNER	0x251b	+	J	thick lower right corner
+WACS_T_LTEE	0x252b	+	T	thick tee pointing right
+WACS_T_PLUS	0x254b	+	N	thick large plus
+WACS_T_RTEE	0x2523	+	U	thick tee pointing left
+WACS_T_TTEE	0x2533	+	W	thick tee pointing down
+WACS_T_ULCORNER	0x250f	+	L	thick upper left corner
+WACS_T_URCORNER	0x2513	+	K	thick upper right corner
+WACS_T_VLINE	0x2503	|	X	thick vertical line
+.TE
+.PP
+and for double-lines (\fBacsc\fP \*(``A\*('' to \*(``I\*(''):
 .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_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
@@ -177,29 +199,37 @@ WACS_D_URCORNER	0x2557	+	B	double upper right corner
 WACS_D_VLINE	0x2551	|	Y	double vertical line
 .TE
 .PP
-and for thick lines:
-.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
-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
-WACS_T_LRCORNER	0x251b	+	J	thick lower right corner
-WACS_T_LTEE	0x252b	+	T	thick tee pointing right
-WACS_T_PLUS	0x254b	+	N	thick large plus
-WACS_T_RTEE	0x2523	+	U	thick tee pointing left
-WACS_T_TTEE	0x2533	+	W	thick tee pointing down
-WACS_T_ULCORNER	0x250f	+	L	thick upper left corner
-WACS_T_URCORNER	0x2513	+	K	thick upper right corner
-WACS_T_VLINE	0x2503	|	X	thick vertical line
-.TE
+Unicode's descriptions for these characters differs slightly from ncurses,
+by introducing the term \*(``light\*('' (along with less important details).
+Here are its descriptions for the normal, thick, and double horizontal lines:
+.bP
+U+2500 BOX DRAWINGS LIGHT HORIZONTAL
+.bP
+U+2501 BOX DRAWINGS HEAVY HORIZONTAL
+.bP
+U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
 .SH RETURN VALUE
 .PP
-All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success.
+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
+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,
@@ -218,13 +248,13 @@ 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
 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
+HPUX 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.
@@ -295,10 +325,10 @@ Others have suggested these alternatives:
 .SH SEE ALSO
 .na
 .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)
+\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)