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