man/curs_addch.3x

   1 '\" t
   2 .\"***************************************************************************
   3 .\" Copyright 2018-2023,2024 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.81 2024/03/23 20:38:57 tom Exp $
  32 .TH curs_addch 3X 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
  33 .ie \n(.g \{\
  34 .ds `` \(lq
  35 .ds '' \(rq
  36 .ds '  \(aq
  37 .ds ^  \(ha
  38 .ds ~  \(ti
  39 .\}
  40 .el \{\
  41 .ie t .ds `` ``
  42 .el   .ds `` ""
  43 .ie t .ds '' ''
  44 .el   .ds '' ""
  45 .ds       '  '
  46 .ds       ^  ^
  47 .ds       ~  ~
  48 .\}
  49 .
  50 .de bP
  51 .ie n  .IP \(bu 4
  52 .el    .IP \(bu 2
  53 ..
  54 .SH NAME
  55 \fB\%addch\fP,
  56 \fB\%waddch\fP,
  57 \fB\%mvaddch\fP,
  58 \fB\%mvwaddch\fP,
  59 \fB\%echochar\fP,
  60 \fB\%wechochar\fP \-
  61 add a \fIcurses\fR character to a window and advance the cursor
  62 .SH SYNOPSIS
  63 .nf
  64 \fB#include <curses.h>
  65 .PP
  66 \fBint addch(const chtype \fIch\fP);
  67 \fBint waddch(WINDOW *\fIwin\fP, const chtype \fIch\fP);
  68 \fBint mvaddch(int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
  69 \fBint mvwaddch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype \fIch\fP);
  70 .PP
  71 \fBint echochar(const chtype \fIch\fP);
  72 \fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP);
  73 .fi
  74 .SH DESCRIPTION
  75 .SS "Adding Characters"
  76 .B \%waddch
  77 puts the character
  78 .I ch
  79 at the cursor position of window
  80 .IR win ,
  81 then advances the cursor position,
  82 analogously to the standard C library's \fI\%putchar\fP(3).
  83 \fB\%ncurses\fP(3X) describes the variants of this function.
  84 .PP
  85 If advancement occurs at the right margin,
  86 .bP
  87 the cursor automatically wraps to the beginning of the next line;
  88 and
  89 .bP
  90 at the bottom of the current scrolling region,
  91 and if \fB\%scrollok\fP(3X) is enabled for
  92 .IR win ,
  93 the scrolling region scrolls up one line.
  94 .PP
  95 If
  96 .I ch
  97 is a
  98 backspace,
  99 carriage return,
 100 line feed,
 101 or
 102 tab,
 103 the cursor moves appropriately within the window.
 104 .bP
 105 Backspace moves the cursor one character left;
 106 at the left margin of a window,
 107 it does nothing.
 108 .bP
 109 Carriage return moves the cursor to the left margin on the current line
 110 of the window.
 111 .bP
 112 Line feed does a \fB\%clrtoeol\fP(3X),
 113 then moves the cursor to the left margin on the next line of the window,
 114 scrolling the window if the cursor was already on the last line.
 115 .bP
 116 Tab advances the cursor to the next tab stop
 117 (possibly on the next line);
 118 these are placed at every eighth column by default.
 119 Alter the tab interval with the
 120 .B \%TABSIZE
 121 extension;
 122 see \fB\%curs_variables\fP(3X).
 123 .PP
 124 If
 125 .I ch
 126 is any other nonprintable character,
 127 it is drawn in printable form,
 128 using the same convention as \fB\%unctrl\fP(3X).
 129 .bP
 130 .B \%waddch
 131 displays control characters in
 132 .BI \*^ X
 133 notation.
 134 .bP
 135 Character codes above 127 are either meta characters
 136 (if the screen has not been initialized,
 137 or if \fB\%meta\fP(3X) has been called with a
 138 .B TRUE
 139 .I bf
 140 parameter)
 141 that render in
 142 .BI M\- X
 143 notation,
 144 or they display as themselves.
 145 In the latter case,
 146 the values may not be printable;
 147 .\" XXX: The following claim could be clearer.
 148 this follows the X/Open specification.
 149 .PP
 150 Calling \fB\%winch\fP(3X) on the location of a nonprintable character
 151 does not return the character itself,
 152 but its \fB\%unctrl\fP(3X) representation.
 153 .PP
 154 Video attributes can be combined with a character argument passed to
 155 .B \%waddch
 156 by logical-ORing them into the character.
 157 (Thus,
 158 text,
 159 including attributes,
 160 can be copied from one place to another using \fB\%winch\fP(3X) and
 161 .BR \%waddch .)
 162 See \fB\%curs_attr\fP(3X) for values of predefined video attribute
 163 constants that can be usefully OR'ed with characters.
 164 .SS "Echoing Characters"
 165 .B \%echochar
 166 and
 167 .B \%wechochar
 168 are equivalent to calling
 169 .RB \%( w ) addch
 170 followed by
 171 .RB \%( w ) refresh .
 172 .I curses
 173 interprets these functions as a hint that only a single character is
 174 being output;
 175 for non-control characters,
 176 a considerable performance gain may be enjoyed by employing them.
 177 .\" TODO: Combine the following with the "Line Drawing" subsection of
 178 .\" terminfo(5) and replace this with a cross reference there.
 179 .SS "Forms-Drawing Characters"
 180 .I curses
 181 defines macros starting with
 182 .B \%ACS_
 183 that can be used with
 184 .B \%waddch
 185 to write line-drawing and other special characters to the screen.
 186 .I \%ncurses
 187 terms these
 188 .I "forms-drawing characters."
 189 The ACS default listed below is used if the
 190 .B \%acs_chars
 191 .RB ( \%acsc )
 192 .I \%term\%info
 193 capability does not define a terminal-specific replacement for it,
 194 or if the terminal and locale configuration requires Unicode to access
 195 these characters but the library is unable to use Unicode.
 196 The \*(``acsc char\*('' column corresponds to how the characters are
 197 specified in the
 198 .B \%acs_chars
 199 string capability,
 200 and the characters in it may appear on the screen if the terminal's
 201 database entry incorrectly advertises ACS support.
 202 The name \*(``ACS\*('' originates in the Alternate Character Set feature
 203 of the DEC VT100 terminal.
 204 .PP
 205 .TS
 206 Lb Lb Lb Lb
 207 Lb Lb Lb Lb
 208 Lb L  L  Lx.
 209 \&      ACS     acsc    \&
 210 Symbol  Default char    Glyph Name
 211 _
 212 ACS_BLOCK       #       0       solid square block
 213 ACS_BOARD       #       h       board of squares
 214 ACS_BTEE        +       v       bottom tee
 215 ACS_BULLET      o       \*~     bullet
 216 ACS_CKBOARD     :       a       checker board (stipple)
 217 ACS_DARROW      v       .       arrow pointing down
 218 ACS_DEGREE      \*'     f       degree symbol
 219 ACS_DIAMOND     +       \(ga    diamond
 220 ACS_GEQUAL      >       >       greater-than-or-equal-to
 221 ACS_HLINE       \-      q       horizontal line
 222 ACS_LANTERN     #       i       lantern symbol
 223 ACS_LARROW      <       ,       arrow pointing left
 224 ACS_LEQUAL      <       y       less-than-or-equal-to
 225 ACS_LLCORNER    +       m       lower left-hand corner
 226 ACS_LRCORNER    +       j       lower right-hand corner
 227 ACS_LTEE        +       t       left tee
 228 ACS_NEQUAL      !       |       not-equal
 229 ACS_PI  *       {       greek pi
 230 ACS_PLMINUS     #       g       plus/minus
 231 ACS_PLUS        +       n       plus
 232 ACS_RARROW      >       +       arrow pointing right
 233 ACS_RTEE        +       u       right tee
 234 ACS_S1  \-      o       scan line 1
 235 ACS_S3  \-      p       scan line 3
 236 ACS_S7  \-      r       scan line 7
 237 ACS_S9  \&_     s       scan line 9
 238 ACS_STERLING    f       }       pound-sterling symbol
 239 ACS_TTEE        +       w       top tee
 240 ACS_UARROW      \*^     \-      arrow pointing up
 241 ACS_ULCORNER    +       l       upper left-hand corner
 242 ACS_URCORNER    +       k       upper right-hand corner
 243 ACS_VLINE       |       x       vertical line
 244 .TE
 245 .SH RETURN VALUE
 246 These functions return
 247 .B OK
 248 on success and
 249 .B ERR
 250 on failure.
 251 .PP
 252 In
 253 .IR \%ncurses ,
 254 .B \%waddch
 255 returns
 256 .B ERR
 257 if it is not possible to add a complete character at the cursor
 258 position,
 259 as when conversion of a multibyte character to a byte sequence fails,
 260 or at least one of the resulting bytes cannot be added to the window.
 261 See section \*(``PORTABILITY\*('' below regarding the use of
 262 .B \%waddch
 263 with multibyte characters.
 264 .PP
 265 If \fB\%scrollok\fP(3X) is not enabled,
 266 .B \%waddch
 267 can successfully write a character at the bottom right location of the
 268 window.
 269 However,
 270 .I \%ncurses
 271 returns
 272 .B ERR
 273 because it is not possible to wrap to a new line.
 274 .PP
 275 Functions with a \*(``mv\*('' prefix first perform cursor movement using
 276 \fB\%wmove\fP(3X) and fail if the position is outside the window,
 277 or
 278 (for \*(``mvw\*('' functions)
 279 if the
 280 .I \%WINDOW
 281 pointer is null.
 282 .SH NOTES
 283 .BR \%addch ,
 284 .BR \%mvaddch ,
 285 .BR \%mvwaddch ,
 286 and
 287 .B \%echochar
 288 may be implemented as macros.
 289 .SH PORTABILITY
 290 X/Open Curses,
 291 Issue 4 describes these functions.
 292 It specifies no error conditions for them.
 293 The defaults specified for forms-drawing characters apply in the POSIX
 294 locale.
 295 .SS "ACS Symbols"
 296 X/Open Curses states that the
 297 .B \%ACS_
 298 definitions are
 299 .I char
 300 constants.
 301 .PP
 302 Some implementations are problematic.
 303 .bP
 304 Solaris
 305 .IR curses ,
 306 for example,
 307 define the ACS symbols as constants;
 308 others define them as elements of an array.
 309 .IP
 310 This implementation uses an array,
 311 .BR \%acs_map ,
 312 as did SVr4
 313 .IR curses .
 314 NetBSD also uses an array,
 315 actually named
 316 .BR \%_acs_char ,
 317 with a
 318 .B \%#define
 319 for compatibility.
 320 .bP
 321 HP-UX
 322 .I curses
 323 equates some of the
 324 .B \%ACS_
 325 symbols to the analogous
 326 .B \%WACS_
 327 symbols as if the
 328 .B \%ACS_
 329 symbols were wide characters
 330 (see \fB\%curs_add_wch\fP(3X)).
 331 The misdefined symbols are the arrows and others that are not used for
 332 line drawing.
 333 .bP
 334 X/Open Curses
 335 (Issues 2 through 7)
 336 has a typographical error
 337 for the
 338 .B \%ACS_LANTERN
 339 symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
 340 (capital I),
 341 while the header files for SVr4
 342 .I curses
 343 and other implementations use \*(``i\*(''
 344 (small i).
 345 .IP
 346 None of the terminal descriptions on Unix platforms use uppercase I,
 347 except for Solaris
 348 (in its
 349 .I \%term\%info
 350 entry for \fI\%screen\fP(1),
 351 apparently based on the X/Open documentation around 1995).
 352 On the other hand,
 353 its
 354 .B \%gs6300
 355 (AT&T PC6300 with EMOTS Terminal Emulator)
 356 description uses lowercase i.
 357 .PP
 358 Some ACS symbols
 359 .RB ( \%ACS_S3 ,
 360 .BR \%ACS_S7 ,
 361 .BR \%ACS_LEQUAL ,
 362 .BR \%ACS_GEQUAL ,
 363 .BR \%ACS_PI ,
 364 .BR \%ACS_NEQUAL ,
 365 and
 366 .BR \%ACS_STERLING )
 367 were not documented in any publicly released System\ V.
 368 However,
 369 many publicly available
 370 .I \%term\%info
 371 entries include
 372 .B \%acsc
 373 strings in which their key characters (pryz{|}) are embedded,
 374 and a second-hand list of their character descriptions has come to
 375 light.
 376 The
 377 .I \%ncurses
 378 developers invented ACS-prefixed names for them.
 379 .PP
 380 The
 381 .I displayed
 382 values of
 383 .B \%ACS_
 384 constants depend on
 385 .bP
 386 the
 387 .I \%ncurses
 388 ABI\(emfor example,
 389 wide-character versus non-wide-character configurations
 390 (the former is capable of displaying Unicode while the latter is not),
 391 and
 392 .bP
 393 whether the locale uses UTF-8 encoding.
 394 .PP
 395 In certain cases,
 396 the terminal is unable to display forms-drawing characters
 397 .I except
 398 by using UTF-8;
 399 see the discussion of the
 400 .I \%NCURSES_NO_UTF8_ACS
 401 environment variable in \fB\%ncurses\fP(3X)).
 402 .SS "Character Set"
 403 X/Open Curses assumes that the parameter passed to
 404 .B \%waddch
 405 contains a single character.
 406 As discussed in \fB\%curs_attr\fP(3X),
 407 that character may have been more than eight bits wide in an SVr3 or
 408 SVr4 implementation,
 409 but in the X/Open Curses model,
 410 the details are not given.
 411 The important distinction between SVr4
 412 .I curses
 413 and X/Open Curses is that the latter separates non-character information
 414 (attributes and color)
 415 from the character code,
 416 which SVr4 packs into a
 417 .I \%chtype
 418 for passage to
 419 .BR \%waddch .
 420 .PP
 421 In
 422 .IR \%ncurses ,
 423 .I \%chtype
 424 holds an eight-bit character.
 425 But
 426 .I \%ncurses
 427 allows a multibyte character to be passed in a succession of calls to
 428 .BR \%waddch .
 429 Other implementations do not;
 430 a
 431 .B \%waddch
 432 call transmits exactly one character,
 433 which may be rendered in one or more screen locations depending on
 434 whether it is printable.
 435 .PP
 436 Depending on the locale settings,
 437 .I \%ncurses
 438 inspects the byte passed in each
 439 .B \%waddch
 440 call,
 441 and checks whether the latest call continues a multibyte sequence.
 442 When a character is
 443 .IR complete ,
 444 .I \%ncurses
 445 displays the character and advances the window's current location.
 446 .PP
 447 If the calling application interrupts the succession of bytes in
 448 a multibyte character sequence by moving the current location
 449 (for example,
 450 with \fB\%wmove\fP(3X)),
 451 .I \%ncurses
 452 discards the incomplete character.
 453 .PP
 454 For portability to other implementations,
 455 do not rely upon this behavior.
 456 Check whether a character can be represented as a single byte in the
 457 current locale.
 458 .bP
 459 If it can,
 460 call either
 461 .B \%waddch
 462 or \fB\%wadd_wch\fP(3X).
 463 .bP
 464 If it cannot,
 465 use only
 466 \fB\%wadd_wch\fP(3X).
 467 .SS TABSIZE
 468 SVr4 and other versions of
 469 .I curses
 470 implement the
 471 .B \%TABSIZE
 472 variable,
 473 but X/Open Curses does not specify it
 474 (see \fB\%curs_variables\fP(3X)).
 475 .SH SEE ALSO
 476 \fB\%curses\fP(3X),
 477 \fB\%curs_addchstr\fP(3X),
 478 \fB\%curs_addstr\fP(3X),
 479 \fB\%curs_attr\fP(3X),
 480 \fB\%curs_clear\fP(3X),
 481 \fB\%curs_inch\fP(3X),
 482 \fB\%curs_outopts\fP(3X),
 483 \fB\%curs_refresh\fP(3X),
 484 \fB\%curs_variables\fP(3X),
 485 \fB\%putchar\fP(3)
 486 .PP
 487 \fB\%curs_add_wch\fP(3X) describes comparable functions of the
 488 .I \%ncurses
 489 library in its wide-character configuration
 490 .RI ( \%ncursesw ).