ncurses 6.2 - patch 20201017
[ncurses.git] / man / curs_addch.3x
index cfcb4a267d8a45044fa62e208772c5121f734d24..68667d9f630e037a866c2ea095361c53232de562 100644 (file)
@@ -1,6 +1,7 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2015,2017 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 1998-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            *
@@ -27,7 +28,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_addch.3x,v 1.44 2017/11/20 01:27:20 tom Exp $
+.\" $Id: curs_addch.3x,v 1.54 2020/10/17 23:02:40 tom Exp $
 .TH curs_addch 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -54,7 +55,7 @@
 \fBint mvaddch(int y, int x, const chtype ch);\fR
 .br
 \fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR
-.br
+.sp
 \fBint echochar(const chtype ch);\fR
 .br
 \fBint wechochar(WINDOW *win, const chtype ch);\fR
@@ -63,7 +64,8 @@
 .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(3) in \fBstdio\fR(3).
+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.
@@ -92,10 +94,12 @@ scrolling the window if on the last line.
 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 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.
+If \fIch\fR is any other nonprintable character,
+it is drawn in printable form,
+i.e., the \fB^\fR\fIX\fR notation used by \fBunctrl\fR(3X).
+Calling \fBwinch\fR after adding a
+nonprintable character does not return the character itself,
+but instead returns the printable representation of the 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.
@@ -107,13 +111,15 @@ into characters.
 .PP
 The \fBechochar\fR and \fBwechochar\fR routines are equivalent to a call to
 \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
+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,
 or if the terminal and locale configuration requires Unicode but the
@@ -170,6 +176,19 @@ unless otherwise noted in the preceding routine descriptions.
 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.
+.PP
+If it is not possible to add a complete character,
+an error is returned:
+.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.
 .SH NOTES
 Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and
 \fBechochar\fR may be macros.
@@ -181,6 +200,31 @@ The defaults specified for forms-drawing characters apply in the POSIX locale.
 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.
+Some implementations are problematic:
+.bP
+Some implementations define the ACS symbols to a constant
+(such as Solaris), while others define those to entries in an array.
+.IP
+This implementation uses an array \fBacs_map\fP, as done in SVr4 curses.
+NetBSD also uses an array, actually named \fB_acs_char\fP, with a \fB#define\fP
+for compatibility.
+.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.
+.bP
+X/Open Curses (issues 2 through 7) has a typographical error
+for the ACS_LANTERN symbol, equating its \*(``VT100+ Character\*(''
+to \fBI\fP (capital I), while the header files for SVr4 curses
+and the various implementations use \fBi\fP (lowercase).
+.IP
+None of the terminal descriptions on Unix platforms use uppercase-I,
+except for Solaris (i.e., \fIscreen\fP's terminal description,
+apparently based on the X/Open documentation around 1995).
+On the other hand, the terminal description \fIgs6300\fP
+(AT&T PC6300 with EMOTS Terminal Emulator) uses lowercase-i.
 .LP
 Some ACS symbols
 (ACS_S3,
@@ -191,10 +235,12 @@ 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 
@@ -218,7 +264,7 @@ 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.
+In this implementation, \fBchtype\fP holds an eight-bit character.
 But ncurses allows multibyte characters to be passed in a succession
 of calls to \fBwaddch\fP.
 The other implementations do not do this;
@@ -246,8 +292,9 @@ before attempting call \fBwaddch\fP, and
 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.
+The \fBTABSIZE\fR variable is implemented in SVr4 and other versions of curses,
+but is not part of X/Open curses
+(see \fBcurs_variables\fR(3X) for more details).
 .LP
 If \fIch\fR is a carriage return,
 the cursor is moved to the beginning of the current row of the window.