diff options
Diffstat (limited to 'upstream/archlinux/man3/curs_addch.3x')
| -rw-r--r-- | upstream/archlinux/man3/curs_addch.3x | 588 |
1 files changed, 371 insertions, 217 deletions
diff --git a/upstream/archlinux/man3/curs_addch.3x b/upstream/archlinux/man3/curs_addch.3x index 875f47f3..add60538 100644 --- a/upstream/archlinux/man3/curs_addch.3x +++ b/upstream/archlinux/man3/curs_addch.3x @@ -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,129 +28,176 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addch.3x,v 1.60 2023/03/11 20:39:26 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.85 2024/04/20 19:03:47 tom Exp $ +.TH curs_addch 3X 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 .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\fP 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 character \fIch\fP into the given window at its current window position, -which is then advanced. -They are analogous to \fBputchar\fP(3) in \fBstdio\fP(3). -If the advance is at the right margin: -.bP -The cursor automatically wraps to the beginning of the next line. +.SS "Adding Characters" +.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(3X) 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 \fBscrollok\fP(3X) is enabled, -the scrolling region is scrolled up one line. +the cursor automatically wraps to the beginning of the next line; +and .bP -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 +at the bottom of the current scrolling region, +and if \fB\%scrollok\fP(3X) 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(3X), +then moves the cursor to the left margin on the next line of the window, +and if \fB\%scrollok\fP(3X) 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\%curs_variables\fP(3X). .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 \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. +using the same convention as \fB\%unctrl\fP(3X). .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 \fBinch\fP(3X) and \fBaddch\fP.) See the \fBcurs_attr\fP(3X) page for -values of predefined video attribute constants that can be usefully OR'ed -into characters. -.SS Echoing characters +Calling \fB\%winch\fP(3X) on the location of a nonprintable character +does not return the character itself, +but its \fB\%unctrl\fP(3X) representation. .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. -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. +.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(3X) and +.BR \%waddch .) +See \fB\%curs_attr\fP(3X) for values of predefined video attribute +constants that can be usefully \*(``or\*(''ed with characters. +.SS "Echoing Characters" +.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_DIAMOND + ` diamond +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 @@ -171,153 +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 \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 -.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. +.B \%waddch +can successfully write a character at the bottom right location of the +window. +However, +.I \%ncurses +returns +.B ERR +if \fB\%scrollok\fP(3X) 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 -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. -Some implementations are problematic: +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 +.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 -HPUX 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\%curs_add_wch\fP(3X)). +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 \fBncurses\fP(3X). -.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., \fBncurses\fP versus \fBncursesw\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 \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. +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(3X)). +.SS "Character Set" +X/Open Curses assumes that the parameter passed to +.B \%waddch +contains a single character. +As discussed in \fB\%curs_attr\fP(3X), +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 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. +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, -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. +.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), -ncurses discards the partially built character, -starting over again. +a multibyte character sequence by changing the current location\(emfor +example, +with \fB\%wmove\fP(3X)\(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(3X). .bP -call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP. +If it cannot, +use only +\fB\%wadd_wch\fP(3X). .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). -.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\%curs_variables\fP(3X)). .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\%curs_add_wch\fP(3X) describes comparable functions of the +.I \%ncurses +library in its wide-character configuration +.RI ( \%ncursesw ). .PP -Comparable functions in the wide-character (ncursesw) library are -described in -\fBcurs_add_wch\fP(3X). +\fB\%curses\fP(3X), +\fB\%curs_addchstr\fP(3X), +\fB\%curs_addstr\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\%putchar\fP(3) |