ncurses 6.1 - patch 20181208
[ncurses.git] / man / curs_addch.3x
index 903da7564b1ddc39034419c48e2b6abf2f7c7707..d502faabdb03521d40697f15450adbf7f45c77ac 100644 (file)
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2017,2018 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_addch.3x,v 1.29 2010/08/14 23:29:16 tom Exp $
+.\" $Id: curs_addch.3x,v 1.46 2018/07/28 21:02:35 tom Exp $
 .TH curs_addch 3X ""
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
 .SH NAME
 \fBaddch\fR,
 \fBwaddch\fR,
 \fBint wechochar(WINDOW *win, const chtype ch);\fR
 .br
 .SH DESCRIPTION
+.SS Adding characters
 The \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR and \fBmvwaddch\fR routines put
 the character \fIch\fR into the given window at its current window position,
-which is then advanced.  They are analogous to \fBputchar\fR in \fBstdio\fR(3).
-If the advance is at the right margin, the cursor automatically wraps to the
-beginning of the next line.  At the bottom of the current scrolling region, if
-\fBscrollok\fR is enabled, the scrolling region is scrolled up one line.
+which is then advanced.
+They are analogous to \fBputchar\fR(3) in \fBstdio\fR(3).
+If the advance is at the right margin:
+.bP
+The cursor automatically wraps to the beginning of the next line.
+.bP
+At the bottom of the current scrolling region,
+and if \fBscrollok\fR is enabled,
+the scrolling region is scrolled up one line.
+.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
 .PP
-If \fIch\fR is a tab, newline, or backspace,
-the cursor is moved appropriately within the window.
+If \fIch\fR is a tab, newline, carriage return or backspace,
+the cursor is moved appropriately within the window:
+.bP
 Backspace moves the cursor one character left; at the left
 edge of a window it does nothing.
+.bP
+Carriage return moves the cursor to the window left margin on the current line.
+.bP
 Newline does a \fBclrtoeol\fR,
 then moves the cursor to the window left margin on the next line,
 scrolling the window if on the last line.
+.bP
 Tabs are considered to be at every eighth column.
 The tab interval may be altered by setting the \fBTABSIZE\fR variable.
 .PP
-If \fIch\fR is any control character other than tab, newline, or backspace, it
-is drawn in \fB^\fR\fIX\fR notation.  Calling \fBwinch\fR after adding a
+If \fIch\fR is any other control character, it
+is drawn in \fB^\fR\fIX\fR notation.
+Calling \fBwinch\fR after adding a
 control character does not return the character itself, but instead returns
 the ^-representation of the control character.
 .PP
 Video attributes can be combined with a character argument passed to
 \fBaddch\fR or related functions by logical-ORing them into the character.
 (Thus, text, including attributes, can be copied from one place to another
-using \fBinch\fR and \fBaddch\fR.)  See the \fBcurs_attr\fR(3X) page for
+using \fBinch\fR(3X) and \fBaddch\fR.)  See the \fBcurs_attr\fR(3X) page for
 values of predefined video attribute constants that can be usefully OR'ed
 into characters.
+.SS Echoing characters
 .PP
 The \fBechochar\fR and \fBwechochar\fR routines are equivalent to a call to
-\fBaddch\fR followed by a call to \fBrefresh\fR, or a call to \fBwaddch\fR
-followed by a call to \fBwrefresh\fR.  The knowledge that only a single
+\fBaddch\fR followed by a call to \fBrefresh\fR(3X), or a call to \fBwaddch\fR
+followed by a call to \fBwrefresh\fR.
+The knowledge that only a single
 character is being output is used and, for non-control characters, a
 considerable performance gain may be seen by using these routines instead of
 their equivalents.
 .SS Line Graphics
 The following variables may be used to add line drawing characters to the
-screen with routines of the \fBaddch\fR family.  The default character listed
+screen with routines of the \fBaddch\fR family.
+The default character listed
 below is used if the \fBacsc\fR capability does not define a terminal-specific
-replacement for it.
+replacement for it,
+or if the terminal and locale configuration requires Unicode but the
+library is unable to use Unicode.
+.PP
 The names are taken from VT100 nomenclature.
 .PP
 .TS
-l l l
-_ _ _
-l l l.
-\fIName\fR     \fIDefault\fR   \fIDescription\fR
-ACS_BLOCK      #       solid square block
-ACS_BOARD      #       board of squares
-ACS_BTEE       +       bottom tee
-ACS_BULLET     o       bullet
-ACS_CKBOARD    :       checker board (stipple)
-ACS_DARROW     v       arrow pointing down
-ACS_DEGREE     '       degree symbol
-ACS_DIAMOND    +       diamond
-ACS_GEQUAL     >       greater-than-or-equal-to
-ACS_HLINE      \-      horizontal line
-ACS_LANTERN    #       lantern symbol
-ACS_LARROW     <       arrow pointing left
-ACS_LEQUAL     <       less-than-or-equal-to
-ACS_LLCORNER   +       lower left-hand corner
-ACS_LRCORNER   +       lower right-hand corner
-ACS_LTEE       +       left tee
-ACS_NEQUAL     !       not-equal
-ACS_PI *       greek pi
-ACS_PLMINUS    #       plus/minus
-ACS_PLUS       +       plus
-ACS_RARROW     >       arrow pointing right
-ACS_RTEE       +       right tee
-ACS_S1 \-      scan line 1
-ACS_S3 \-      scan line 3
-ACS_S7 \-      scan line 7
-ACS_S9 \&_     scan line 9
-ACS_STERLING   f       pound-sterling symbol
-ACS_TTEE       +       top tee
-ACS_UARROW     ^       arrow pointing up
-ACS_ULCORNER   +       upper left-hand corner
-ACS_URCORNER   +       upper right-hand corner
-ACS_VLINE      |       vertical line
+l l l l
+l l l l
+_ _ _ _
+l l l l.
+\fBACS\fR      \fBACS\fR       \fBacsc\fP      \fBGlyph\fR
+\fBName\fR     \fBDefault\fR   \fBchar\fP      \fBName\fR
+ACS_BLOCK      #       0       solid square block
+ACS_BOARD      #       h       board of squares
+ACS_BTEE       +       v       bottom tee
+ACS_BULLET     o       ~       bullet
+ACS_CKBOARD    :       a       checker board (stipple)
+ACS_DARROW     v       .       arrow pointing down
+ACS_DEGREE     '       f       degree symbol
+ACS_DIAMOND    +       `       diamond
+ACS_GEQUAL     >       >       greater-than-or-equal-to
+ACS_HLINE      \-      q       horizontal line
+ACS_LANTERN    #       i       lantern symbol
+ACS_LARROW     <       ,       arrow pointing left
+ACS_LEQUAL     <       y       less-than-or-equal-to
+ACS_LLCORNER   +       m       lower left-hand corner
+ACS_LRCORNER   +       j       lower right-hand corner
+ACS_LTEE       +       t       left tee
+ACS_NEQUAL     !       |       not-equal
+ACS_PI *       {       greek pi
+ACS_PLMINUS    #       g       plus/minus
+ACS_PLUS       +       n       plus
+ACS_RARROW     >       +       arrow pointing right
+ACS_RTEE       +       u       right tee
+ACS_S1 \-      o       scan line 1
+ACS_S3 \-      p       scan line 3
+ACS_S7 \-      r       scan line 7
+ACS_S9 \&_     s       scan line 9
+ACS_STERLING   f       }       pound-sterling symbol
+ACS_TTEE       +       w       top tee
+ACS_UARROW     ^       \-      arrow pointing up
+ACS_ULCORNER   +       l       upper left-hand corner
+ACS_URCORNER   +       k       upper right-hand corner
+ACS_VLINE      |       x       vertical line
 .TE
 .SH RETURN VALUE
 All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success
-(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon
-successful completion, unless otherwise noted in the preceding routine
-descriptions.
+(the SVr4 manuals specify only
+\*(``an integer value other than \fBERR\fR\*('') upon successful completion,
+unless otherwise noted in the preceding routine descriptions.
 .PP
-Functions with a "mv" prefix first perform a cursor movement using
+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
@@ -147,6 +180,11 @@ Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and
 .SH PORTABILITY
 All these functions are described in the XSI Curses standard, Issue 4.
 The defaults specified for forms-drawing characters apply in the POSIX locale.
+.SS ACS Symbols
+.LP
+X/Open Curses states that the \fIACS_\fP definitions are \fBchar\fP constants.
+For the wide-character implementation (see \fBcurs_add_wch\fP),
+there are analogous \fIWACS_\fP definitions which are \fBcchar_t\fP constants.
 .LP
 Some ACS symbols
 (ACS_S3,
@@ -157,10 +195,62 @@ ACS_PI,
 ACS_NEQUAL,
 ACS_STERLING)
 were not documented in
-any publicly released System V.  However, many publicly available terminfos
+any publicly released System V.
+However, many publicly available terminfos
 include \fBacsc\fR strings in which their key characters (pryz{|}) are
 embedded, and a second-hand list of their character descriptions has come
-to light.  The ACS-prefixed names for them were invented for \fBncurses\fR(3X).
+to light.
+The ACS-prefixed names for them were invented for \fBncurses\fR(3X).
+.LP
+The \fIdisplayed\fP values for the \fIACS_\fP and \fIWACS_\fP constants
+depend on 
+.bP
+the library configuration, i.e., \fBncurses\fP versus \fBncursesw\fP,
+where the latter is capable of displaying Unicode while the former is not, and
+.bP
+whether the \fIlocale\fP uses UTF-8 encoding.
+.LP
+In certain cases, the terminal is unable to display line-drawing characters
+except by using UTF-8 (see the discussion of \fBNCURSES_NO_UTF8_ACS\fP in
+ncurses(3X)).
+.SS Character Set
+X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
+a single character.
+As discussed in \fBcurs_attr\fP(3X), that character may have been
+more than eight bits in an SVr3 or SVr4 implementation,
+but in the X/Open Curses model, the details are not given.
+The important distinction between SVr4 curses and X/Open Curses is
+that the non-character information (attributes and color) was
+separated from the character information which is packed in a \fBchtype\fP
+to pass to \fBwaddch\fP.
+.PP
+In this implementation, \fBchtype\fP holds eight bits.
+But ncurses allows multibyte characters to be passed in a succession
+of calls to \fBwaddch\fP.
+The other implementations do not do this;
+a call to \fBwaddch\fP passes exactly one character
+which may be rendered as one or more cells on the screen
+depending on whether it is printable.
+.PP
+Depending on the locale settings,
+ncurses will inspect the byte passed in each call to \fBwaddch\fP,
+and check if the latest call will continue a multibyte sequence.
+When a character is \fIcomplete\fP,
+ncurses displays the character and moves to the next position in the screen.
+.PP
+If the calling application interrupts the succession of bytes in
+a multibyte character by moving the current location (e.g., using \fBwmove\fP),
+ncurses discards the partially built character,
+starting over again.
+.PP
+For portability to other implementations,
+do not rely upon this behavior:
+.bP
+check if a character can be represented as a single byte in the current locale
+before attempting call \fBwaddch\fP, and
+.bP
+call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP.
+.SS TABSIZE
 .LP
 The \fBTABSIZE\fR variable is implemented in some versions of curses,
 but is not part of X/Open curses.
@@ -175,14 +265,9 @@ This is true of other implementations, but is not documented.
 \fBcurs_inch\fR(3X),
 \fBcurs_outopts\fR(3X),
 \fBcurs_refresh\fR(3X),
+\fBcurs_variables\fR(3X),
 \fBputc\fR(3).
 .PP
 Comparable functions in the wide-character (ncursesw) library are
 described in
 \fBcurs_add_wch\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End: