| '\" 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.51 2020/02/02 23:34:34 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 ch);\fR |
| .br |
| \fBint waddch(WINDOW *win, const chtype ch);\fR |
| .br |
| \fBint mvaddch(int y, int x, const chtype ch);\fR |
| .br |
| \fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR |
| .br |
| \fBint echochar(const chtype ch);\fR |
| .br |
| \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(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 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. |
| .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. |
| .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). |