From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/opensuse-tumbleweed/man3/addch.3ncurses | 329 +++++++++++++++++++++++ 1 file changed, 329 insertions(+) create mode 100644 upstream/opensuse-tumbleweed/man3/addch.3ncurses (limited to 'upstream/opensuse-tumbleweed/man3/addch.3ncurses') diff --git a/upstream/opensuse-tumbleweed/man3/addch.3ncurses b/upstream/opensuse-tumbleweed/man3/addch.3ncurses new file mode 100644 index 00000000..dcd0078d --- /dev/null +++ b/upstream/opensuse-tumbleweed/man3/addch.3ncurses @@ -0,0 +1,329 @@ +'\" t +.\"*************************************************************************** +.\" 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 * +.\" 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.76 2023/12/23 16:27:51 tom Exp $ +.TH addch 3NCURSES 2023-12-23 "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 +\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 +.nf +\fB#include +.PP +\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 character \fIch\fP into the given window at its current window position, +which is then advanced. +They are analogous to the standard C library's \fI\%putchar\fP(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 \fB\%scrollok\fP(3NCURSES) is enabled, +the scrolling region is scrolled up one line. +.bP +If \fB\%scrollok\fP(3NCURSES) 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 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\fP, +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\fP variable. +.PP +If \fIch\fP is any other nonprintable character, +it is drawn in printable form, +using the same convention as \fB\%unctrl\fP(3NCURSES): +.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 \fB\%meta\fP(3NCURSES) 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. +.PP +Video attributes can be combined with a character argument passed to +\fBaddch\fP or related functions by logical-ORing them into the character. +(Thus, text, including attributes, can be copied from one place to another +using \fB\%inch\fP(3NCURSES) and \fBaddch\fP.) +See the \fB\%attr\fP(3NCURSES) page for values of predefined video +attribute constants that can be usefully OR'ed into characters. +.SS "Echoing Characters" +The \fBechochar\fP and \fBwechochar\fP routines are equivalent to a call to +\fBaddch\fP followed by a call to \fB\%refresh\fP(3NCURSES), or a call to \fBwaddch\fP +followed by a call to \fBwrefresh\fP. +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\fP family. +The default character listed +below is used if the \fBacsc\fP 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\fP \fBACS\fP \fBacsc\fP \fBGlyph\fP +\fBName\fP \fBDefault\fP \fBchar\fP \fBName\fP +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 + \(ga 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\fP upon failure and \fBOK\fP on success +(the SVr4 manuals specify only +\*(``an integer value other than \fBERR\fP\*('') 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 \fB\%scrollok\fP(3NCURSES) 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\fP, \fBmvaddch\fP, \fBmvwaddch\fP, and +\fBechochar\fP may be macros. +.SH PORTABILITY +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" +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. +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 +HP-UX curses equates some of the \fBACS_\fP symbols +to the analogous \fBWACS_\fP symbols as if the \fBACS_\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., \fBscreen\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\fP 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 \fB\%ncurses\fP(3NCURSES). +.LP +The \fIdisplayed\fP values for the \fBACS_\fP and \fBWACS_\fP constants +depend on +.bP +the library configuration, +i.e., +\fI\%ncurses\fP versus \fI\%ncursesw\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 \fB\%NCURSES_NO_UTF8_ACS\fP in +\fB\%ncurses\fP(3NCURSES)). +.SS "Character Set" +X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains +a single character. +As discussed in \fB\%attr\fP(3NCURSES), 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 \fI\%ncurses\fP 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, +\fI\%ncurses\fP 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, +\fI\%ncurses\fP 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), +\fI\%ncurses\fP 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 +The \fBTABSIZE\fP variable is implemented in SVr4 and other versions of curses, +but is not part of X/Open curses +(see \fB\%curses_variables\fP(3NCURSES) for more details). +.LP +If \fIch\fP 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 +\fB\%ncurses\fP(3NCURSES), +\fB\%attr\fP(3NCURSES), +\fB\%clear\fP(3NCURSES), +\fB\%inch\fP(3NCURSES), +\fB\%outopts\fP(3NCURSES), +\fB\%refresh\fP(3NCURSES), +\fB\%curses_variables\fP(3NCURSES), +\fB\%putc\fP(3) +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fB\%add_wch\fP(3NCURSES). -- cgit v1.2.3