ncurses 6.0 - patch 20170304

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

diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index 1ad071a8a8a0e06cabdcd9ad52adbcec9799c1f2..f0439992247fcf77c7f700449cf0932966837d54 100644 (file)
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
 '\" t
 .\"***************************************************************************

-.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc.              *
+.\" Copyright (c) 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,8 +27,11 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_addch.3x,v 1.32 2011/01/15 14:15:10 tom Exp $
+.\" $Id: curs_addch.3x,v 1.38 2017/01/07 19:25:15 tom Exp $

 .TH curs_addch 3X ""
 .TH curs_addch 3X ""

+.de bP
+.IP \(bu 4
+..

 .SH NAME
 \fBaddch\fR,
 \fBwaddch\fR,
 .SH NAME
 \fBaddch\fR,
 \fBwaddch\fR,


@@ -52,24 +55,39 @@
 \fBint wechochar(WINDOW *win, const chtype ch);\fR
 .br
 .SH DESCRIPTION
 \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).
 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.
+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
 .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.
 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.
 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
 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
+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.
 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.


@@ -77,12 +95,13 @@ the ^-representation of the control character.
 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
 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.
 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
 .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
+\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
 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


@@ -91,7 +110,10 @@ their equivalents.
 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
 below is used if the \fBacsc\fR capability does not define a terminal-specific
 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
 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
 The names are taken from VT100 nomenclature.
 .PP
 .TS


@@ -166,6 +188,18 @@ 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).
 .LP
 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).
 .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)).
+.LP

 The \fBTABSIZE\fR variable is implemented in some versions of curses,
 but is not part of X/Open curses.
 .LP
 The \fBTABSIZE\fR variable is implemented in some versions of curses,
 but is not part of X/Open curses.
 .LP