ncurses 6.2 - patch 20201017

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

diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index 729382d49fcce828c3014db21c49bcd9587cc6fd..68667d9f630e037a866c2ea095361c53232de562 100644 (file)
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -1,6 +1,7 @@
 '\" t
 .\"***************************************************************************
 '\" t
 .\"***************************************************************************

-.\" Copyright (c) 1998-2018,2019 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.47 2019/02/16 23:50:17 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


@@ -93,11 +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.
+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
 Calling \fBwinch\fR after adding a

-control character does not return the character itself, but instead returns
-the ^-representation of the control character.
+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.


@@ -174,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.


@@ -185,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,


@@ -224,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;