ncurses 6.4 - patch 20230701

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

diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index bf512cb150ebb3086a7ece1a8afb4fb927b080f5..4744ba8ba1d110bbb0ba91639806a53eda21640b 100644 (file)
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey                                *
+.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
@@ -28,8 +28,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_addch.3x,v 1.58 2021/12/25 20:18:06 tom Exp $
-.TH curs_addch 3X ""
+.\" $Id: curs_addch.3x,v 1.64 2023/07/01 14:23:04 tom Exp $
+.TH curs_addch 3X 2023-07-01 "ncurses 6.4" "Library calls"
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
@@ -48,17 +48,17 @@
 .SH SYNOPSIS
 \fB#include <curses.h>\fP
 .PP
-\fBint addch(const chtype \fP\fIch\fP\fB);\fP
+\fBint addch(const chtype \fIch\fB);\fR
 .br
-\fBint waddch(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fP
+\fBint waddch(WINDOW *\fIwin\fB, const chtype \fIch\fB);\fR
 .br
-\fBint mvaddch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\fB);\fP
+\fBint mvaddch(int \fIy\fB, int \fIx\fB, const chtype \fIch\fB);\fR
 .br
-\fBint mvwaddch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\fB);\fP
+\fBint mvwaddch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const chtype \fIch\fB);\fR
 .sp
-\fBint echochar(const chtype \fP\fIch\fP\fB);\fP
+\fBint echochar(const chtype \fIch\fB);\fR
 .br
-\fBint wechochar(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fP
+\fBint wechochar(WINDOW *\fIwin\fB, const chtype \fIch\fB);\fR
 .br
 .SH DESCRIPTION
 .SS Adding characters
@@ -71,10 +71,10 @@ If the advance is at the right margin:
 The cursor automatically wraps to the beginning of the next line.
 .bP
 At the bottom of the current scrolling region,
-and if \fBscrollok\fP is enabled,
+and if \fBscrollok\fP(3X) is enabled,
 the scrolling region is scrolled up one line.
 .bP
-If \fBscrollok\fP is not enabled,
+If \fBscrollok\fP(3X) 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
@@ -96,7 +96,16 @@ The tab interval may be altered by setting the \fBTABSIZE\fP variable.
 .PP
 If \fIch\fP is any other nonprintable character,
 it is drawn in printable form,
-i.e., the \fB^\fP\fIX\fP notation used by \fBunctrl\fP(3X).
+using the same convention as \fBunctrl\fR(3X):
+.bP
+Control characters are displayed in the \fB^\fIX\fR notation.
+.bP
+Values above 128 are either meta characters (if the screen has not
+been initialized, or if \fBmeta\fP(3X) has been called with a \fBTRUE\fP E parameter),
+shown in the \fBM\-\fIX\fR notation, or are displayed as themselves.
+In the latter case, the values may not be printable;
+this follows the X/Open specification.
+.PP
 Calling \fBwinch\fP after adding a
 nonprintable character does not return the character itself,
 but instead returns the printable representation of the character.
@@ -108,7 +117,6 @@ using \fBinch\fP(3X) and \fBaddch\fP.)  See the \fBcurs_attr\fP(3X) page for
 values of predefined video attribute constants that can be usefully OR'ed
 into characters.
 .SS Echoing characters
-.PP
 The \fBechochar\fP and \fBwechochar\fP routines are equivalent to a call to
 \fBaddch\fP followed by a call to \fBrefresh\fP(3X), or a call to \fBwaddch\fP
 followed by a call to \fBwrefresh\fP.
@@ -180,7 +188,7 @@ or if the window pointer is null.
 If it is not possible to add a complete character,
 an error is returned:
 .bP
-If \fBscrollok\fP is not enabled,
+If \fBscrollok\fP(3X) 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
@@ -196,7 +204,6 @@ Note that \fBaddch\fP, \fBmvaddch\fP, \fBmvwaddch\fP, and
 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 \fBACS_\fP definitions are \fBchar\fP constants.
 For the wide-character implementation (see \fBcurs_add_wch\fP),
 there are analogous \fBWACS_\fP definitions which are \fBcchar_t\fP constants.
@@ -291,7 +298,6 @@ 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\fP variable is implemented in SVr4 and other versions of curses,
 but is not part of X/Open curses
 (see \fBcurs_variables\fP(3X) for more details).