diff options
Diffstat (limited to 'man/curs_addch.3x')
| -rw-r--r-- | man/curs_addch.3x | 210 |
1 files changed, 154 insertions, 56 deletions
diff --git a/man/curs_addch.3x b/man/curs_addch.3x index e450487..c92d12b 100644 --- a/man/curs_addch.3x +++ b/man/curs_addch.3x @@ -1,6 +1,7 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2011,2014 Free Software Foundation, Inc. * +.\" 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 * @@ -27,10 +28,15 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addch.3x,v 1.33 2014/05/24 19:47:41 tom Exp $ +.\" $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 -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. .SH NAME \fBaddch\fR, @@ -55,9 +61,11 @@ \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 in \fBstdio\fR(3). +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. @@ -71,12 +79,14 @@ 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, or backspace, +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. @@ -84,76 +94,85 @@ scrolling the window if on the last line. 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 control character other than tab, newline, or backspace, it -is drawn in \fB^\fR\fIX\fR notation. Calling \fBwinch\fR after adding a +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 and \fBaddch\fR.) See the \fBcurs_attr\fR(3X) page for +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, or a call to \fBwaddch\fR -followed by a call to \fBwrefresh\fR. The knowledge that only a single +\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 +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. +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. -\fIName\fR \fIDefault\fR \fIDescription\fR -ACS_BLOCK # solid square block -ACS_BOARD # board of squares -ACS_BTEE + bottom tee -ACS_BULLET o bullet -ACS_CKBOARD : checker board (stipple) -ACS_DARROW v arrow pointing down -ACS_DEGREE ' degree symbol -ACS_DIAMOND + diamond -ACS_GEQUAL > greater-than-or-equal-to -ACS_HLINE \- horizontal line -ACS_LANTERN # lantern symbol -ACS_LARROW < arrow pointing left -ACS_LEQUAL < less-than-or-equal-to -ACS_LLCORNER + lower left-hand corner -ACS_LRCORNER + lower right-hand corner -ACS_LTEE + left tee -ACS_NEQUAL ! not-equal -ACS_PI * greek pi -ACS_PLMINUS # plus/minus -ACS_PLUS + plus -ACS_RARROW > arrow pointing right -ACS_RTEE + right tee -ACS_S1 \- scan line 1 -ACS_S3 \- scan line 3 -ACS_S7 \- scan line 7 -ACS_S9 \&_ scan line 9 -ACS_STERLING f pound-sterling symbol -ACS_TTEE + top tee -ACS_UARROW ^ arrow pointing up -ACS_ULCORNER + upper left-hand corner -ACS_URCORNER + upper right-hand corner -ACS_VLINE | vertical line +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. +(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 +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 @@ -162,10 +181,36 @@ Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and .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, @@ -176,13 +221,66 @@ ACS_PI, ACS_NEQUAL, ACS_STERLING) were not documented in -any publicly released System V. However, many publicly available terminfos +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). +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 some versions of curses, -but is not part of X/Open curses. +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. |