diff options
Diffstat (limited to 'upstream/debian-unstable/man3/addch.3ncurses')
| -rw-r--r-- | upstream/debian-unstable/man3/addch.3ncurses | 516 |
1 files changed, 332 insertions, 184 deletions
diff --git a/upstream/debian-unstable/man3/addch.3ncurses b/upstream/debian-unstable/man3/addch.3ncurses index ee1e487d..1b3f8568 100644 --- a/upstream/debian-unstable/man3/addch.3ncurses +++ b/upstream/debian-unstable/man3/addch.3ncurses @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,17 +28,23 @@ .\" 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" +.\" $Id: curs_addch.3x,v 1.85 2024/04/20 19:03:47 tom Exp $ +.TH addch 3NCURSES 2024-04-20 "ncurses 6.5" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq +.ds ' \(aq +.ds ^ \(ha +.ds ~ \(ti .\} .el \{\ .ie t .ds `` `` .el .ds `` "" .ie t .ds '' '' .el .ds '' "" +.ds ' ' +.ds ^ ^ +.ds ~ ~ .\} . .de bP @@ -52,7 +58,7 @@ \fB\%mvwaddch\fP, \fB\%echochar\fP, \fB\%wechochar\fP \- -add a \fIcurses\fR character to a window and advance the cursor +add a \fIcurses\fP character to a window and advance the cursor .SH SYNOPSIS .nf \fB#include <curses.h> @@ -67,94 +73,130 @@ add a \fIcurses\fR character to a window and advance the cursor .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. +.B \%waddch +puts the character +.I ch +at the cursor position of window +.IR win , +then advances the cursor position, +analogously to the standard C library's \fI\%putchar\fP(3). +\fB\%ncurses\fP(3NCURSES) describes the variants of this function. +.PP +If advancement occurs at the right margin, .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. +the cursor automatically wraps to the beginning of the next line; +and .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. +at the bottom of the current scrolling region, +and if \fB\%scrollok\fP(3NCURSES) is enabled for +.IR win , +the scrolling region scrolls up one line. .PP -If \fIch\fP is a tab, newline, carriage return or backspace, -the cursor is moved appropriately within the window: +If +.I ch +is a +backspace, +carriage return, +line feed, +or +tab, +the cursor moves 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 margin of a window, +it does nothing. .bP -Carriage return moves the cursor to the window left margin on the current line. +Carriage return moves the cursor to the left margin on the current line +of the window. .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. +Line feed does a \fB\%clrtoeol\fP(3NCURSES), +then moves the cursor to the left margin on the next line of the window, +and if \fB\%scrollok\fP(3NCURSES) is enabled for +.IR win , +scrolls the window if the cursor was already 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. +Tab advances the cursor to the next tab stop +(possibly on the next line); +these are placed at every eighth column by default. +Alter the tab interval with the +.B \%TABSIZE +extension; +see \fB\%curses_variables\fP(3NCURSES). .PP -If \fIch\fP is any other nonprintable character, +If +.I ch +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. +using the same convention as \fB\%unctrl\fP(3NCURSES). .PP -Calling \fBwinch\fP after adding a -nonprintable character does not return the character itself, -but instead returns the printable representation of the character. +Calling \fB\%winch\fP(3NCURSES) on the location of a nonprintable character +does not return the character itself, +but its \fB\%unctrl\fP(3NCURSES) representation. .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. +.I ch +may contain rendering and/or color attributes, +and others can be combined with the parameter +by logically \*(``or\*(''ing with it. +(A character with its attributes can be copied from place to place +using \fB\%winch\fP(3NCURSES) and +.BR \%waddch .) +See \fB\%attr\fP(3NCURSES) for values of predefined video attribute +constants that can be usefully \*(``or\*(''ed with 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. +.B \%echochar +and +.B \%wechochar +are equivalent to calling +.RB \%( w ) addch +followed by +.RB \%( w ) refresh . +.I curses +interprets these functions as a hint that only a single character is +being output; +for non-control characters, +a considerable performance gain may be enjoyed by employing them. +.\" TODO: Combine the following with the "Line Drawing" subsection of +.\" terminfo(5) and replace this with a cross reference there. +.SS "Forms-Drawing Characters" +.I curses +defines macros starting with +.B \%ACS_ +that can be used with +.B \%waddch +to write line-drawing and other special characters to the screen. +.I \%ncurses +terms these +.I "forms-drawing characters." +The ACS default listed below is used if the +.B \%acs_chars +.RB ( \%acsc ) +.I \%term\%info +capability does not define a terminal-specific replacement for it, +or if the terminal and locale configuration requires Unicode to access +these characters but the library is unable to use Unicode. +The \*(``acsc char\*('' column corresponds to how the characters are +specified in the +.B \%acs_chars +string capability, +and the characters in it may appear on the screen if the terminal's +database entry incorrectly advertises ACS support. +The name \*(``ACS\*('' originates in the Alternate Character Set feature +of the DEC VT100 terminal. .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 +Lb Lb Lb Lb +Lb Lb Lb Lb +Lb L L Lx. +\& ACS acsc \& +Symbol Default char Glyph Name +_ ACS_BLOCK # 0 solid square block ACS_BOARD # h board of squares ACS_BTEE + v bottom tee -ACS_BULLET o ~ bullet +ACS_BULLET o \*~ bullet ACS_CKBOARD : a checker board (stipple) ACS_DARROW v . arrow pointing down -ACS_DEGREE ' f degree symbol +ACS_DEGREE \*' f degree symbol ACS_DIAMOND + \(ga diamond ACS_GEQUAL > > greater-than-or-equal-to ACS_HLINE \- q horizontal line @@ -176,154 +218,260 @@ 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_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. +These functions return +.B OK +on success and +.B ERR +on failure. .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. +In +.IR \%ncurses , +.B \%waddch +returns +.B ERR +if it is not possible to add a complete character at the cursor +position, +as when conversion of a multibyte character to a byte sequence fails, +or at least one of the resulting bytes cannot be added to the window. +See section \*(``PORTABILITY\*('' below regarding the use of +.B \%waddch +with multibyte characters. .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. +.B \%waddch +can successfully write a character at the bottom right location of the +window. 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. +.I \%ncurses +returns +.B ERR +if \fB\%scrollok\fP(3NCURSES) is not enabled in that event, +because it is not possible to wrap to a new line. +.PP +Functions prefixed with \*(``mv\*('' first perform cursor movement and +fail if the position +.RI ( y , +.IR x ) +is outside the window boundaries. .SH NOTES -Note that \fBaddch\fP, \fBmvaddch\fP, \fBmvwaddch\fP, and -\fBechochar\fP may be macros. +.BR \%addch , +.BR \%mvaddch , +.BR \%mvwaddch , +and +.B \%echochar +may be implemented as 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. +X/Open Curses, +Issue 4 describes these functions. +It specifies no error conditions for them. +.PP +SVr4 +.I curses +describes a successful return value only as +\*(``an integer value other than +.BR ERR \*(''. +.PP +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: +X/Open Curses states that the +.B \%ACS_ +definitions are +.I char +constants. +.PP +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. +Solaris +.IR curses , +for example, +define the ACS symbols as constants; +others define them as elements of 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 +This implementation uses an array, +.BR \%acs_map , +as did SVr4 +.IR curses . +NetBSD also uses an array, +actually named +.BR \%_acs_char , +with a +.B \%#define 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. +HP-UX +.I curses +equates some of the +.B \%ACS_ +symbols to the analogous +.B \%WACS_ +symbols as if the +.B \%ACS_ +symbols were wide characters +(see \fB\%add_wch\fP(3NCURSES)). +The misdefined symbols are the arrows and others that 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). +X/Open Curses +(Issues 2 through 7) +has a typographical error +for the +.B \%ACS_LANTERN +symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*('' +(capital I), +while the header files for SVr4 +.I curses +and other implementations use \*(``i\*('' +(small i). .IP -None of the terminal descriptions on Unix platforms use uppercase-I, -except for Solaris (i.e., \fBscreen\fP's terminal description, +None of the terminal descriptions on Unix platforms use uppercase I, +except for Solaris +(in its +.I \%term\%info +entry for \fI\%screen\fP(1), 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 +On the other hand, +its +.B \%gs6300 +(AT&T PC6300 with EMOTS Terminal Emulator) +description uses lowercase i. +.PP 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 +.RB ( \%ACS_S3 , +.BR \%ACS_S7 , +.BR \%ACS_LEQUAL , +.BR \%ACS_GEQUAL , +.BR \%ACS_PI , +.BR \%ACS_NEQUAL , +and +.BR \%ACS_STERLING ) +were not documented in any publicly released System\ V. +However, +many publicly available +.I \%term\%info +entries include +.B \%acsc +strings in which their key characters +.BR ( pryz{|} ) +are embedded, +and a second-hand list of their character descriptions has come to +light. +The +.I \%ncurses +developers invented ACS-prefixed names for them. +.PP +The +.I displayed +values of +.B \%ACS_ +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 +the +.I \%ncurses +ABI\(emfor example, +wide-character versus non-wide-character configurations +(the former is capable of displaying Unicode while the latter 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)). +whether the locale uses UTF-8 encoding. +.PP +In certain cases, +the terminal is unable to display forms-drawing characters +.I except +by using UTF-8; +see the discussion of the +.I \%NCURSES_NO_UTF8_ACS +environment variable 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. +X/Open Curses assumes that the parameter passed to +.B \%waddch +contains a single character. +As discussed in \fB\%attr\fP(3NCURSES), +that character may have been more than eight bits wide in an SVr3 or +SVr4 implementation, +but in the X/Open Curses model, +the details are not given. +The important distinction between SVr4 +.I curses +and X/Open Curses is that the latter separates non-character information +(attributes and color) +from the character code, +which SVr4 packs into a +.I \%chtype +for passage to +.BR \%waddch . .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. +In +.IR \%ncurses , +.I \%chtype +holds an eight-bit character. +But the library allows a multibyte character to be passed in a +succession of calls to +.BR \%waddch . +Other implementations do not; +a +.B \%waddch +call transmits exactly one character, +which may be rendered in one or more screen locations 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. +.I \%ncurses +inspects the byte passed in each +.B \%waddch +call, +and checks whether the latest call continues a multibyte sequence. +When a character is +.IR complete , +.I \%ncurses +displays the character and advances the cursor. .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. +a multibyte character sequence by changing the current location\(emfor +example, +with \fB\%wmove\fP(3NCURSES)\(em\c +.I \%ncurses +discards the incomplete character. .PP For portability to other implementations, -do not rely upon this behavior: +do not rely upon this behavior. +Check whether a character can be represented as a single byte in the +current locale. .bP -check if a character can be represented as a single byte in the current locale -before attempting call \fBwaddch\fP, and +If it can, +call either +.B \%waddch +or \fB\%wadd_wch\fP(3NCURSES). .bP -call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP. +If it cannot, +use only +\fB\%wadd_wch\fP(3NCURSES). .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. +SVr4 and other versions of +.I curses +implement the +.B \%TABSIZE +variable, +but X/Open Curses does not specify it +(see \fB\%curses_variables\fP(3NCURSES)). .SH SEE ALSO +\fB\%add_wch\fP(3NCURSES) describes comparable functions of the +.I \%ncurses +library in its wide-character configuration +.RI ( \%ncursesw ). +.PP \fB\%ncurses\fP(3NCURSES), +\fB\%addchstr\fP(3NCURSES), +\fB\%addstr\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). +\fB\%putchar\fP(3) |