315 lines
12 KiB
Plaintext
315 lines
12 KiB
Plaintext
'\" t
|
|
.\"***************************************************************************
|
|
.\" 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 *
|
|
.\" "Software"), to deal in the Software without restriction, including *
|
|
.\" without limitation the rights to use, copy, modify, merge, publish, *
|
|
.\" distribute, distribute with modifications, sublicense, and/or sell *
|
|
.\" copies of the Software, and to permit persons to whom the Software is *
|
|
.\" furnished to do so, subject to the following conditions: *
|
|
.\" *
|
|
.\" The above copyright notice and this permission notice shall be included *
|
|
.\" in all copies or substantial portions of the Software. *
|
|
.\" *
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|
.\" *
|
|
.\" Except as contained in this notice, the name(s) of the above copyright *
|
|
.\" holders shall not be used in advertising or otherwise to promote the *
|
|
.\" sale, use or other dealings in this Software without prior written *
|
|
.\" authorization. *
|
|
.\"***************************************************************************
|
|
.\"
|
|
.\" $Id: curs_addch.3x,v 1.55 2020/10/24 09:12:31 tom Exp $
|
|
.TH curs_addch 3X ""
|
|
.ie \n(.g .ds `` \(lq
|
|
.el .ds `` ``
|
|
.ie \n(.g .ds '' \(rq
|
|
.el .ds '' ''
|
|
.de bP
|
|
.ie n .IP \(bu 4
|
|
.el .IP \(bu 2
|
|
..
|
|
.SH NAME
|
|
\fBaddch\fR,
|
|
\fBwaddch\fR,
|
|
\fBmvaddch\fR,
|
|
\fBmvwaddch\fR,
|
|
\fBechochar\fR,
|
|
\fBwechochar\fR \- add a character (with attributes) to a \fBcurses\fR window, then advance the cursor
|
|
.SH SYNOPSIS
|
|
\fB#include <curses.h>\fR
|
|
.PP
|
|
\fBint addch(const chtype \fP\fIch\fP\fB);\fR
|
|
.br
|
|
\fBint waddch(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\fR
|
|
.br
|
|
\fBint mvaddch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, const chtype \fP\fIch\fP\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);\fR
|
|
.sp
|
|
\fBint echochar(const chtype \fP\fIch\fP\fB);\fR
|
|
.br
|
|
\fBint wechochar(WINDOW *\fP\fIwin\fP\fB, const chtype \fP\fIch\fP\fB);\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(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.
|
|
.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
|
|
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.
|
|
.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.
|
|
.bP
|
|
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 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.
|
|
(Thus, text, including attributes, can be copied from one place to another
|
|
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.
|
|
.SS Echoing 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
|
|
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
|
|
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
|
|
library is unable to use Unicode.
|
|
.PP
|
|
The names are taken from VT100 nomenclature.
|
|
.PP
|
|
.TS
|
|
l l l l
|
|
l l l l
|
|
_ _ _ _
|
|
l l l l.
|
|
\fBACS\fR \fBACS\fR \fBacsc\fP \fBGlyph\fR
|
|
\fBName\fR \fBDefault\fR \fBchar\fP \fBName\fR
|
|
ACS_BLOCK # 0 solid square block
|
|
ACS_BOARD # h board of squares
|
|
ACS_BTEE + v bottom tee
|
|
ACS_BULLET o ~ bullet
|
|
ACS_CKBOARD : a checker board (stipple)
|
|
ACS_DARROW v . arrow pointing down
|
|
ACS_DEGREE ' f degree symbol
|
|
ACS_DIAMOND + ` diamond
|
|
ACS_GEQUAL > > greater-than-or-equal-to
|
|
ACS_HLINE \- q horizontal line
|
|
ACS_LANTERN # i lantern symbol
|
|
ACS_LARROW < , arrow pointing left
|
|
ACS_LEQUAL < y less-than-or-equal-to
|
|
ACS_LLCORNER + m lower left-hand corner
|
|
ACS_LRCORNER + j lower right-hand corner
|
|
ACS_LTEE + t left tee
|
|
ACS_NEQUAL ! | not-equal
|
|
ACS_PI * { greek pi
|
|
ACS_PLMINUS # g plus/minus
|
|
ACS_PLUS + n plus
|
|
ACS_RARROW > + arrow pointing right
|
|
ACS_RTEE + u right tee
|
|
ACS_S1 \- o scan line 1
|
|
ACS_S3 \- p scan line 3
|
|
ACS_S7 \- r scan line 7
|
|
ACS_S9 \&_ s scan line 9
|
|
ACS_STERLING f } pound-sterling symbol
|
|
ACS_TTEE + w top tee
|
|
ACS_UARROW ^ \- arrow pointing up
|
|
ACS_ULCORNER + l upper left-hand corner
|
|
ACS_URCORNER + k upper right-hand corner
|
|
ACS_VLINE | x vertical line
|
|
.TE
|
|
.SH RETURN VALUE
|
|
All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success
|
|
(the SVr4 manuals specify only
|
|
\*(``an integer value other than \fBERR\fR\*('') upon successful completion,
|
|
unless otherwise noted in the preceding routine descriptions.
|
|
.PP
|
|
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 PORTABILITY
|
|
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 \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,
|
|
ACS_S7,
|
|
ACS_LEQUAL,
|
|
ACS_GEQUAL,
|
|
ACS_PI,
|
|
ACS_NEQUAL,
|
|
ACS_STERLING)
|
|
were not documented in
|
|
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).
|
|
.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)).
|
|
.SS Character Set
|
|
X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
|
|
a single character.
|
|
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
|
|
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 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;
|
|
a call to \fBwaddch\fP passes exactly one character
|
|
which may be rendered as one or more cells on the screen
|
|
depending on whether it is printable.
|
|
.PP
|
|
Depending on the locale settings,
|
|
ncurses will inspect the byte passed in each call to \fBwaddch\fP,
|
|
and check if the latest call will continue a multibyte sequence.
|
|
When a character is \fIcomplete\fP,
|
|
ncurses displays the character and moves to the next position in the screen.
|
|
.PP
|
|
If the calling application interrupts the succession of bytes in
|
|
a multibyte character by moving the current location (e.g., using \fBwmove\fP),
|
|
ncurses discards the partially built character,
|
|
starting over again.
|
|
.PP
|
|
For portability to other implementations,
|
|
do not rely upon this behavior:
|
|
.bP
|
|
check if a character can be represented as a single byte in the current locale
|
|
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\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.
|
|
This is true of other implementations, but is not documented.
|
|
.SH SEE ALSO
|
|
\fBcurses\fR(3X),
|
|
\fBcurs_attr\fR(3X),
|
|
\fBcurs_clear\fR(3X),
|
|
\fBcurs_inch\fR(3X),
|
|
\fBcurs_outopts\fR(3X),
|
|
\fBcurs_refresh\fR(3X),
|
|
\fBcurs_variables\fR(3X),
|
|
\fBputc\fR(3).
|
|
.PP
|
|
Comparable functions in the wide-character (ncursesw) library are
|
|
described in
|
|
\fBcurs_add_wch\fR(3X).
|