ncurses 5.7 - patch 20110115
[ncurses.git] / man / curs_add_wch.3x
index 51ac1a4b5c35e38edbc63163eb38181d3c0b38cc..26319a8ef909457950c8b91d2c133ef8edabe846 100644 (file)
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright (c) 2001-2002,2006 Free Software Foundation, Inc.              *
+.\" Copyright (c) 2001-2010,2011 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.6 2006/12/24 15:22:22 tom Exp $
+.\" $Id: curs_add_wch.3x,v 1.14 2011/01/15 15:27:43 tom Exp $
 .TH curs_add_wch 3X ""
+.de bP
+.IP \(bu 4
+..
 .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
+\fBwecho_wchar\fP \- add a complex character and rendition to a \fBcurses\fR window, then advance the cursor
 .SH SYNOPSIS
 .PP
 \fB#include <curses.h>\fP
@@ -63,23 +66,20 @@ window at its current position,
 which is then advanced.
 These functions perform
 wrapping and special-character processing as follows:
-.TP 5
--
+.bP
 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.
-.TP 5
--
+.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.
-.TP 5
--
+.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.
@@ -99,9 +99,90 @@ The knowledge
 that only a single character is being output is taken into consideration and,
 for non-control characters, a considerable performance gain might be seen
 by using the *\fBecho\fP* functions instead of their equivalents.
+.SS Line Graphics
+Like \fBaddch\fP(3X),
+\fBaddch_wch\fP accepts symbols which make it simple to draw lines and other
+frequently used special characters.
+These symbols correspond to the same VT100 line-drawing set as
+\fBaddch\fP(3X).
+.PP
+.TS
+l l l l
+_ _ _ _
+lw(1.5i) lw7 lw7 lw20.
+\fIName\fR     \fIUnicode\fP   \fIDefault\fR   \fIDescription\fR
+WACS_BLOCK     0x25ae  #       solid square block
+WACS_BOARD     0x2592  #       board of squares
+WACS_BTEE      0x2534  +       bottom tee
+WACS_BULLET    0x00b7  o       bullet
+WACS_CKBOARD   0x2592  :       checker board (stipple)
+WACS_DARROW    0x2193  v       arrow pointing down
+WACS_DEGREE    0x00b0  '       degree symbol
+WACS_DIAMOND   0x25c6  +       diamond
+WACS_GEQUAL    0x2265  >       greater-than-or-equal-to
+WACS_HLINE     0x2500  \-      horizontal line
+WACS_LANTERN   0x2603  #       lantern symbol
+WACS_LARROW    0x2190  <       arrow pointing left
+WACS_LEQUAL    0x2264  <       less-than-or-equal-to
+WACS_LLCORNER  0x2514  +       lower left-hand corner
+WACS_LRCORNER  0x2518  +       lower right-hand corner
+WACS_LTEE      0x2524  +       left tee
+WACS_NEQUAL    0x2260  !       not-equal
+WACS_PI        0x03c0  *       greek pi
+WACS_PLMINUS   0x00b1  #       plus/minus
+WACS_PLUS      0x253c  +       plus
+WACS_RARROW    0x2192  >       arrow pointing right
+WACS_RTEE      0x251c  +       right tee
+WACS_S1        0x23ba  \-      scan line 1
+WACS_S3        0x23bb  \-      scan line 3
+WACS_S7        0x23bc  \-      scan line 7
+WACS_S9        0x23bd  \&_     scan line 9
+WACS_STERLING  0x00a3  f       pound-sterling symbol
+WACS_TTEE      0x252c  +       top tee
+WACS_UARROW    0x2191          ^       arrow pointing up
+WACS_ULCORNER  0x250c  +       upper left-hand corner
+WACS_URCORNER  0x2510  +       upper right-hand corner
+WACS_VLINE     0x2502  |       vertical line
+.TE
+.PP
+The wide-character configuration of ncurses also defines symbols
+for thick- and double-lines:
+.PP
+.TS
+l l l l
+_ _ _ _
+lw(1.5i) lw7 lw7 lw20.
+\fIName\fR     \fIUnicode\fP   \fIDefault\fR   \fIDescription\fR
+WACS_T_ULCORNER        0x250f  +       thick upper left corner
+WACS_T_LLCORNER        0x2517  +       thick lower left corner
+WACS_T_URCORNER        0x2513  +       thick upper right corner
+WACS_T_LRCORNER        0x251b  +       thick lower right corner
+WACS_T_LTEE    0x252b  +       thick tee pointing right
+WACS_T_RTEE    0x2523  +       thick tee pointing left
+WACS_T_BTEE    0x253b  +       thick tee pointing up
+WACS_T_TTEE    0x2533  +       thick tee pointing down
+WACS_T_HLINE   0x2501  -       thick horizontal line
+WACS_T_VLINE   0x2503  |       thick vertical line
+WACS_T_PLUS    0x254b  +       thick large plus or crossover
+WACS_D_ULCORNER        0x2554  +       double upper left corner
+WACS_D_LLCORNER        0x255a  +       double lower left corner
+WACS_D_URCORNER        0x2557  +       double upper right corner
+WACS_D_LRCORNER        0x255d  +       double lower right corner
+WACS_D_RTEE    0x2563  +       double tee pointing left
+WACS_D_LTEE    0x2560  +       double tee pointing right
+WACS_D_BTEE    0x2569  +       double tee pointing up
+WACS_D_TTEE    0x2566  +       double tee pointing down
+WACS_D_HLINE   0x2550  -       double horizontal line
+WACS_D_VLINE   0x2551  |       double vertical line
+WACS_D_PLUS    0x256c  +       double large plus or crossover
+.TE
 .SH RETURN VALUES
 .PP
 All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success.
+.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
@@ -112,12 +193,26 @@ Note that
 may be macros.
 .SH PORTABILITY
 .PP
-All these functions are described in the XSI Curses standard, Issue 4.
-The defaults specified for forms-drawing characters apply in the POSIX locale.
+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 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
+wide characters.
+The misdefined symbols are the arrows
+and other symbols which are not used for line-drawing.
 .PP
-XSI documents constants beginning with \fBWACS_\fP which are used for
-line-drawing.
-Those are not currently implemented in \fBncurses\fP.
+X/Open Curses does not define symbols for thick- or double-lines.
+SVr4 curses implementations defined their line-drawing symbols in
+terms of intermediate symbols.
+This implementation extends those symbols, providing new definitions
+which are not in the SVr4 implementations.
 .SH SEE ALSO
 .PP
 \fBcurses\fR(3X),
@@ -127,9 +222,3 @@ Those are not currently implemented in \fBncurses\fP.
 \fBcurs_outopts\fR(3X),
 \fBcurs_refresh\fR(3X),
 \fBputwc\fR(3)
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End: