man/curs_addch.3x

   1 '\" t
   2 .\"***************************************************************************
   3 .\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
   4 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
   5 .\"                                                                          *
   6 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   7 .\" copy of this software and associated documentation files (the            *
   8 .\" "Software"), to deal in the Software without restriction, including      *
   9 .\" without limitation the rights to use, copy, modify, merge, publish,      *
  10 .\" distribute, distribute with modifications, sublicense, and/or sell       *
  11 .\" copies of the Software, and to permit persons to whom the Software is    *
  12 .\" furnished to do so, subject to the following conditions:                 *
  13 .\"                                                                          *
  14 .\" The above copyright notice and this permission notice shall be included  *
  15 .\" in all copies or substantial portions of the Software.                   *
  16 .\"                                                                          *
  17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24 .\"                                                                          *
  25 .\" Except as contained in this notice, the name(s) of the above copyright   *
  26 .\" holders shall not be used in advertising or otherwise to promote the     *
  27 .\" sale, use or other dealings in this Software without prior written       *
  28 .\" authorization.                                                           *
  29 .\"***************************************************************************
  30 .\"
  31 .\" $Id: curs_addch.3x,v 1.76 2023/12/23 16:27:51 tom Exp $
  32 .TH curs_addch 3X 2023-12-23 "ncurses 6.4" "Library calls"
  33 .ie \n(.g \{\
  34 .ds `` \(lq
  35 .ds '' \(rq
  36 .\}
  37 .el \{\
  38 .ie t .ds `` ``
  39 .el   .ds `` ""
  40 .ie t .ds '' ''
  41 .el   .ds '' ""
  42 .\}
  43 .
  44 .de bP
  45 .ie n  .IP \(bu 4
  46 .el    .IP \(bu 2
  47 ..
  48 .SH NAME
  49 \fB\%addch\fP,
  50 \fB\%waddch\fP,
  51 \fB\%mvaddch\fP,
  52 \fB\%mvwaddch\fP,
  53 \fB\%echochar\fP,
  54 \fB\%wechochar\fP \-
  55 add a \fIcurses\fR character to a window and advance the cursor
  56 .SH SYNOPSIS
  57 .nf
  58 \fB#include <curses.h>
  59 .PP
  60 \fBint addch(const chtype \fIch\fP);
  61 \fBint waddch(WINDOW *\fIwin\fP, const chtype \fIch\fP);
  62 \fBint mvaddch(int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
  63 \fBint mvwaddch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
  64 .PP
  65 \fBint echochar(const chtype \fIch\fP);
  66 \fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP);
  67 .fi
  68 .SH DESCRIPTION
  69 .SS "Adding Characters"
  70 The \fBaddch\fP, \fBwaddch\fP, \fBmvaddch\fP and \fBmvwaddch\fP routines put
  71 the character \fIch\fP into the given window at its current window position,
  72 which is then advanced.
  73 They are analogous to the standard C library's \fI\%putchar\fP(3).
  74 If the advance is at the right margin:
  75 .bP
  76 The cursor automatically wraps to the beginning of the next line.
  77 .bP
  78 At the bottom of the current scrolling region,
  79 and if \fB\%scrollok\fP(3X) is enabled,
  80 the scrolling region is scrolled up one line.
  81 .bP
  82 If \fB\%scrollok\fP(3X) is not enabled,
  83 writing a character at the lower right margin succeeds.
  84 However,
  85 an error is returned because it is not possible to wrap to a new line.
  86 .PP
  87 If \fIch\fP is a tab, newline, carriage return or backspace,
  88 the cursor is moved appropriately within the window:
  89 .bP
  90 Backspace moves the cursor one character left; at the left
  91 edge of a window it does nothing.
  92 .bP
  93 Carriage return moves the cursor to the window left margin on the current line.
  94 .bP
  95 Newline does a \fBclrtoeol\fP,
  96 then moves the cursor to the window left margin on the next line,
  97 scrolling the window if on the last line.
  98 .bP
  99 Tabs are considered to be at every eighth column.
 100 The tab interval may be altered by setting the \fBTABSIZE\fP variable.
 101 .PP
 102 If \fIch\fP is any other nonprintable character,
 103 it is drawn in printable form,
 104 using the same convention as \fB\%unctrl\fP(3X):
 105 .bP
 106 Control characters are displayed in the \fB^\fIX\fR notation.
 107 .bP
 108 Values above 128 are either meta characters
 109 (if the screen has not been initialized,
 110 or if \fB\%meta\fP(3X) has been called with a \fBTRUE\fP E parameter),
 111 shown in the \fBM\-\fIX\fR notation, or are displayed as themselves.
 112 In the latter case, the values may not be printable;
 113 this follows the X/Open specification.
 114 .PP
 115 Calling \fBwinch\fP after adding a
 116 nonprintable character does not return the character itself,
 117 but instead returns the printable representation of the character.
 118 .PP
 119 Video attributes can be combined with a character argument passed to
 120 \fBaddch\fP or related functions by logical-ORing them into the character.
 121 (Thus, text, including attributes, can be copied from one place to another
 122 using \fB\%inch\fP(3X) and \fBaddch\fP.)
 123 See the \fB\%curs_attr\fP(3X) page for values of predefined video
 124 attribute constants that can be usefully OR'ed into characters.
 125 .SS "Echoing Characters"
 126 The \fBechochar\fP and \fBwechochar\fP routines are equivalent to a call to
 127 \fBaddch\fP followed by a call to \fB\%refresh\fP(3X), or a call to \fBwaddch\fP
 128 followed by a call to \fBwrefresh\fP.
 129 The knowledge that only a single
 130 character is being output is used and, for non-control characters, a
 131 considerable performance gain may be seen by using these routines instead of
 132 their equivalents.
 133 .SS "Line Graphics"
 134 The following variables may be used to add line drawing characters to the
 135 screen with routines of the \fBaddch\fP family.
 136 The default character listed
 137 below is used if the \fBacsc\fP capability does not define a terminal-specific
 138 replacement for it,
 139 or if the terminal and locale configuration requires Unicode but the
 140 library is unable to use Unicode.
 141 .PP
 142 The names are taken from VT100 nomenclature.
 143 .PP
 144 .TS
 145 l l l l
 146 l l l l
 147 _ _ _ _
 148 l l l l.
 149 \fBACS\fP       \fBACS\fP       \fBacsc\fP      \fBGlyph\fP
 150 \fBName\fP      \fBDefault\fP   \fBchar\fP      \fBName\fP
 151 ACS_BLOCK       #       0       solid square block
 152 ACS_BOARD       #       h       board of squares
 153 ACS_BTEE        +       v       bottom tee
 154 ACS_BULLET      o       ~       bullet
 155 ACS_CKBOARD     :       a       checker board (stipple)
 156 ACS_DARROW      v       .       arrow pointing down
 157 ACS_DEGREE      '       f       degree symbol
 158 ACS_DIAMOND     +       \(ga    diamond
 159 ACS_GEQUAL      >       >       greater-than-or-equal-to
 160 ACS_HLINE       \-      q       horizontal line
 161 ACS_LANTERN     #       i       lantern symbol
 162 ACS_LARROW      <       ,       arrow pointing left
 163 ACS_LEQUAL      <       y       less-than-or-equal-to
 164 ACS_LLCORNER    +       m       lower left-hand corner
 165 ACS_LRCORNER    +       j       lower right-hand corner
 166 ACS_LTEE        +       t       left tee
 167 ACS_NEQUAL      !       |       not-equal
 168 ACS_PI  *       {       greek pi
 169 ACS_PLMINUS     #       g       plus/minus
 170 ACS_PLUS        +       n       plus
 171 ACS_RARROW      >       +       arrow pointing right
 172 ACS_RTEE        +       u       right tee
 173 ACS_S1  \-      o       scan line 1
 174 ACS_S3  \-      p       scan line 3
 175 ACS_S7  \-      r       scan line 7
 176 ACS_S9  \&_     s       scan line 9
 177 ACS_STERLING    f       }       pound-sterling symbol
 178 ACS_TTEE        +       w       top tee
 179 ACS_UARROW      ^       \-      arrow pointing up
 180 ACS_ULCORNER    +       l       upper left-hand corner
 181 ACS_URCORNER    +       k       upper right-hand corner
 182 ACS_VLINE       |       x       vertical line
 183 .TE
 184 .SH RETURN VALUE
 185 All routines return the integer \fBERR\fP upon failure and \fBOK\fP on success
 186 (the SVr4 manuals specify only
 187 \*(``an integer value other than \fBERR\fP\*('') upon successful completion,
 188 unless otherwise noted in the preceding routine descriptions.
 189 .PP
 190 Functions with a \*(``mv\*('' prefix first perform a cursor movement using
 191 \fBwmove\fP, and return an error if the position is outside the window,
 192 or if the window pointer is null.
 193 .PP
 194 If it is not possible to add a complete character,
 195 an error is returned:
 196 .bP
 197 If \fB\%scrollok\fP(3X) is not enabled,
 198 writing a character at the lower right margin succeeds.
 199 However,
 200 an error is returned because it is not possible to wrap to a new line.
 201 .bP
 202 If an error is detected when converting a multibyte character to a sequence
 203 of bytes,
 204 or if it is not possible to add all of the resulting bytes in the window,
 205 an error is returned.
 206 .SH NOTES
 207 Note that \fBaddch\fP, \fBmvaddch\fP, \fBmvwaddch\fP, and
 208 \fBechochar\fP may be macros.
 209 .SH PORTABILITY
 210 These functions are described in the XSI Curses standard, Issue 4.
 211 The defaults specified for forms-drawing characters apply in the POSIX locale.
 212 .SS "ACS Symbols"
 213 X/Open Curses states that the \fBACS_\fP definitions are \fBchar\fP constants.
 214 For the wide-character implementation (see \fBcurs_add_wch\fP),
 215 there are analogous \fBWACS_\fP definitions which are \fBcchar_t\fP constants.
 216 Some implementations are problematic:
 217 .bP
 218 Some implementations define the ACS symbols to a constant
 219 (such as Solaris), while others define those to entries in an array.
 220 .IP
 221 This implementation uses an array \fBacs_map\fP, as done in SVr4 curses.
 222 NetBSD also uses an array, actually named \fB_acs_char\fP, with a \fB#define\fP
 223 for compatibility.
 224 .bP
 225 HP-UX curses equates some of the \fBACS_\fP symbols
 226 to the analogous \fBWACS_\fP symbols as if the \fBACS_\fP symbols were
 227 wide characters.
 228 The misdefined symbols are the arrows
 229 and other symbols which are not used for line-drawing.
 230 .bP
 231 X/Open Curses (issues 2 through 7) has a typographical error
 232 for the ACS_LANTERN symbol, equating its \*(``VT100+ Character\*(''
 233 to \fBI\fP (capital I), while the header files for SVr4 curses
 234 and the various implementations use \fBi\fP (lowercase).
 235 .IP
 236 None of the terminal descriptions on Unix platforms use uppercase-I,
 237 except for Solaris (i.e., \fBscreen\fP's terminal description,
 238 apparently based on the X/Open documentation around 1995).
 239 On the other hand, the terminal description \fIgs6300\fP
 240 (AT&T PC6300 with EMOTS Terminal Emulator) uses lowercase-i.
 241 .LP
 242 Some ACS symbols
 243 (ACS_S3,
 244 ACS_S7,
 245 ACS_LEQUAL,
 246 ACS_GEQUAL,
 247 ACS_PI,
 248 ACS_NEQUAL,
 249 ACS_STERLING)
 250 were not documented in
 251 any publicly released System V.
 252 However, many publicly available terminfos
 253 include \fBacsc\fP strings in which their key characters (pryz{|}) are
 254 embedded, and a second-hand list of their character descriptions has come
 255 to light.
 256 The ACS-prefixed names for them were invented for \fB\%ncurses\fP(3X).
 257 .LP
 258 The \fIdisplayed\fP values for the \fBACS_\fP and \fBWACS_\fP constants
 259 depend on
 260 .bP
 261 the library configuration,
 262 i.e.,
 263 \fI\%ncurses\fP versus \fI\%ncursesw\fP,
 264 where the latter is capable of displaying Unicode while the former is not, and
 265 .bP
 266 whether the \fIlocale\fP uses UTF-8 encoding.
 267 .LP
 268 In certain cases, the terminal is unable to display line-drawing characters
 269 except by using UTF-8
 270 (see the discussion of \fB\%NCURSES_NO_UTF8_ACS\fP in
 271 \fB\%ncurses\fP(3X)).
 272 .SS "Character Set"
 273 X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
 274 a single character.
 275 As discussed in \fB\%curs_attr\fP(3X), that character may have been
 276 more than eight bits in an SVr3 or SVr4 implementation,
 277 but in the X/Open Curses model, the details are not given.
 278 The important distinction between SVr4 curses and X/Open Curses is
 279 that the non-character information (attributes and color) was
 280 separated from the character information which is packed in a \fBchtype\fP
 281 to pass to \fBwaddch\fP.
 282 .PP
 283 In this implementation, \fBchtype\fP holds an eight-bit character.
 284 But \fI\%ncurses\fP allows multibyte characters to be passed in a
 285 succession of calls to \fBwaddch\fP.
 286 The other implementations do not do this;
 287 a call to \fBwaddch\fP passes exactly one character
 288 which may be rendered as one or more cells on the screen
 289 depending on whether it is printable.
 290 .PP
 291 Depending on the locale settings,
 292 \fI\%ncurses\fP will inspect the byte passed in each call to \fBwaddch\fP,
 293 and check if the latest call will continue a multibyte sequence.
 294 When a character is \fIcomplete\fP,
 295 \fI\%ncurses\fP displays the character and moves to the next position in the screen.
 296 .PP
 297 If the calling application interrupts the succession of bytes in
 298 a multibyte character by moving the current location (e.g., using \fBwmove\fP),
 299 \fI\%ncurses\fP discards the partially built character,
 300 starting over again.
 301 .PP
 302 For portability to other implementations,
 303 do not rely upon this behavior:
 304 .bP
 305 check if a character can be represented as a single byte in the current locale
 306 before attempting call \fBwaddch\fP, and
 307 .bP
 308 call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP.
 309 .SS TABSIZE
 310 The \fBTABSIZE\fP variable is implemented in SVr4 and other versions of curses,
 311 but is not part of X/Open curses
 312 (see \fBcurs_variables\fP(3X) for more details).
 313 .LP
 314 If \fIch\fP is a carriage return,
 315 the cursor is moved to the beginning of the current row of the window.
 316 This is true of other implementations, but is not documented.
 317 .SH SEE ALSO
 318 \fB\%curses\fP(3X),
 319 \fB\%curs_attr\fP(3X),
 320 \fB\%curs_clear\fP(3X),
 321 \fB\%curs_inch\fP(3X),
 322 \fB\%curs_outopts\fP(3X),
 323 \fB\%curs_refresh\fP(3X),
 324 \fB\%curs_variables\fP(3X),
 325 \fB\%putc\fP(3)
 326 .PP
 327 Comparable functions in the wide-character (ncursesw) library are
 328 described in
 329 \fB\%curs_add_wch\fP(3X).