.\"***************************************************************************
-.\" Copyright (c) 2001-2015,2017 Free Software Foundation, Inc. *
+.\" Copyright 2019,2020 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wch.3x,v 1.24 2017/11/18 23:47:37 tom Exp $
+.\" $Id: curs_add_wch.3x,v 1.28 2020/10/17 23:10:38 tom Exp $
.TH curs_add_wch 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.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 );"
.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\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
+.PP
+and for double-lines (\fBacsc\fP \*(``A\*('' to \*(``I\*(''):
.PP
.TS
l l l l l
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.
.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\fR 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.