ncurses 6.2 - patch 20201017

[ncurses.git] / man / curs_addch.3x

diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index 69a59d603acf2966029a21656e183aab8c3f20aa..68667d9f630e037a866c2ea095361c53232de562 100644 (file)
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -1,6 +1,7 @@
 '\" t
 .\"***************************************************************************
 '\" 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            *
 .\"                                                                          *
 .\" 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.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_addch.3x,v 1.43 2017/11/19 01:54:00 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 `` ``
 .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
 \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
 \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,
 .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.
 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
 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.
 .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
 .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
 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
 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.
 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.
 .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.
 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,
 .LP
 Some ACS symbols
 (ACS_S3,


@@ -191,10 +235,12 @@ ACS_PI,
 ACS_NEQUAL,
 ACS_STERLING)
 were not documented in
 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
 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 
 .LP
 The \fIdisplayed\fP values for the \fIACS_\fP and \fIWACS_\fP constants
 depend on 


@@ -210,7 +256,7 @@ ncurses(3X)).
 .SS Character Set
 X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
 a single character.
 .SS Character Set
 X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
 a single character.

-As discussed in \fBcurs_attr(3X)\fP, that character may have been
+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
 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


@@ -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
 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;
 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
 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.
 .LP
 If \fIch\fR is a carriage return,
 the cursor is moved to the beginning of the current row of the window.