'\" t
.\"***************************************************************************
-.\" Copyright 2018-2021,2022 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addch.3x,v 1.59 2022/02/12 20:07:29 tom Exp $
-.TH curs_addch 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_addch.3x,v 1.72 2023/10/07 21:19:07 tom Exp $
+.TH curs_addch 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
.SH NAME
-\fBaddch\fP,
-\fBwaddch\fP,
-\fBmvaddch\fP,
-\fBmvwaddch\fP,
-\fBechochar\fP,
-\fBwechochar\fP \- add a character (with attributes) to a \fBcurses\fP window, then advance the cursor
+\fB\%addch\fP,
+\fB\%waddch\fP,
+\fB\%mvaddch\fP,
+\fB\%mvwaddch\fP,
+\fB\%echochar\fP,
+\fB\%wechochar\fP \-
+add a \fIcurses\fR character to a window and advance the cursor
.SH SYNOPSIS
-\fB#include <curses.h>\fP
+.nf
+\fB#include <curses.h>
.PP
-\fBint addch(const chtype \fIch\fB);\fR
-.br
-\fBint waddch(WINDOW *\fIwin\fB, const chtype \fIch\fB);\fR
-.br
-\fBint mvaddch(int \fIy\fB, int \fIx\fB, const chtype \fIch\fB);\fR
-.br
-\fBint mvwaddch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, const chtype \fIch\fB);\fR
-.sp
-\fBint echochar(const chtype \fIch\fB);\fR
-.br
-\fBint wechochar(WINDOW *\fIwin\fB, const chtype \fIch\fB);\fR
-.br
+\fBint addch(const chtype \fIch\fP);
+\fBint waddch(WINDOW *\fIwin\fP, const chtype \fIch\fP);
+\fBint mvaddch(int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
+\fBint mvwaddch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
+.PP
+\fBint echochar(const chtype \fIch\fP);
+\fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP);
+.fi
.SH DESCRIPTION
.SS Adding characters
The \fBaddch\fP, \fBwaddch\fP, \fBmvaddch\fP and \fBmvwaddch\fP routines put
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
.PP
If \fIch\fP is any other nonprintable character,
it is drawn in printable form,
-i.e., the \fB^\fIX\fR notation used by \fBunctrl\fR(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.
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.
ACS_CKBOARD : a checker board (stipple)
ACS_DARROW v . arrow pointing down
ACS_DEGREE ' f degree symbol
-ACS_DIAMOND + ` diamond
+ACS_DIAMOND + \(ga diamond
ACS_GEQUAL > > greater-than-or-equal-to
ACS_HLINE \- q horizontal line
ACS_LANTERN # i lantern symbol
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
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.
.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).
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\fP(3X),
-\fBcurs_attr\fP(3X),
-\fBcurs_clear\fP(3X),
-\fBcurs_inch\fP(3X),
-\fBcurs_outopts\fP(3X),
-\fBcurs_refresh\fP(3X),
-\fBcurs_variables\fP(3X),
-\fBputc\fP(3).
+\fB\%curses\fP(3X),
+\fB\%curs_attr\fP(3X),
+\fB\%curs_clear\fP(3X),
+\fB\%curs_inch\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%putc\fP(3)
.PP
Comparable functions in the wide-character (ncursesw) library are
described in
-\fBcurs_add_wch\fP(3X).
+\fB\%curs_add_wch\fP(3X).
projects / ncurses.git / blobdiff