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.83 2024/04/13 22:23:35 tom Exp $
  32 .TH curs_addch 3X 2024-04-13 "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 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 with a \*(``mv\*('' prefix first perform cursor movement using
 257 \fB\%wmove\fP(3X) and fail if the position is outside the window,
 258 or
 259 (for \*(``mvw\*('' functions)
 260 if the
 261 .I \%WINDOW
 262 pointer is null.
 263 .SH NOTES
 264 .BR \%addch ,
 265 .BR \%mvaddch ,
 266 .BR \%mvwaddch ,
 267 and
 268 .B \%echochar
 269 may be implemented as macros.
 270 .SH PORTABILITY
 271 X/Open Curses,
 272 Issue 4 describes these functions.
 273 It specifies no error conditions for them.
 274 The defaults specified for forms-drawing characters apply in the POSIX
 275 locale.
 276 .SS "ACS Symbols"
 277 X/Open Curses states that the
 278 .B \%ACS_
 279 definitions are
 280 .I char
 281 constants.
 282 .PP
 283 Some implementations are problematic.
 284 .bP
 285 Solaris
 286 .IR curses ,
 287 for example,
 288 define the ACS symbols as constants;
 289 others define them as elements of an array.
 290 .IP
 291 This implementation uses an array,
 292 .BR \%acs_map ,
 293 as did SVr4
 294 .IR curses .
 295 NetBSD also uses an array,
 296 actually named
 297 .BR \%_acs_char ,
 298 with a
 299 .B \%#define
 300 for compatibility.
 301 .bP
 302 HP-UX
 303 .I curses
 304 equates some of the
 305 .B \%ACS_
 306 symbols to the analogous
 307 .B \%WACS_
 308 symbols as if the
 309 .B \%ACS_
 310 symbols were wide characters
 311 (see \fB\%curs_add_wch\fP(3X)).
 312 The misdefined symbols are the arrows and others that are not used for
 313 line drawing.
 314 .bP
 315 X/Open Curses
 316 (Issues 2 through 7)
 317 has a typographical error
 318 for the
 319 .B \%ACS_LANTERN
 320 symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
 321 (capital I),
 322 while the header files for SVr4
 323 .I curses
 324 and other implementations use \*(``i\*(''
 325 (small i).
 326 .IP
 327 None of the terminal descriptions on Unix platforms use uppercase I,
 328 except for Solaris
 329 (in its
 330 .I \%term\%info
 331 entry for \fI\%screen\fP(1),
 332 apparently based on the X/Open documentation around 1995).
 333 On the other hand,
 334 its
 335 .B \%gs6300
 336 (AT&T PC6300 with EMOTS Terminal Emulator)
 337 description uses lowercase i.
 338 .PP
 339 Some ACS symbols
 340 .RB ( \%ACS_S3 ,
 341 .BR \%ACS_S7 ,
 342 .BR \%ACS_LEQUAL ,
 343 .BR \%ACS_GEQUAL ,
 344 .BR \%ACS_PI ,
 345 .BR \%ACS_NEQUAL ,
 346 and
 347 .BR \%ACS_STERLING )
 348 were not documented in any publicly released System\ V.
 349 However,
 350 many publicly available
 351 .I \%term\%info
 352 entries include
 353 .B \%acsc
 354 strings in which their key characters
 355 .BR ( pryz{|} )
 356 are embedded,
 357 and a second-hand list of their character descriptions has come to
 358 light.
 359 The
 360 .I \%ncurses
 361 developers invented ACS-prefixed names for them.
 362 .PP
 363 The
 364 .I displayed
 365 values of
 366 .B \%ACS_
 367 constants depend on
 368 .bP
 369 the
 370 .I \%ncurses
 371 ABI\(emfor example,
 372 wide-character versus non-wide-character configurations
 373 (the former is capable of displaying Unicode while the latter is not),
 374 and
 375 .bP
 376 whether the locale uses UTF-8 encoding.
 377 .PP
 378 In certain cases,
 379 the terminal is unable to display forms-drawing characters
 380 .I except
 381 by using UTF-8;
 382 see the discussion of the
 383 .I \%NCURSES_NO_UTF8_ACS
 384 environment variable in \fB\%ncurses\fP(3X)).
 385 .SS "Character Set"
 386 X/Open Curses assumes that the parameter passed to
 387 .B \%waddch
 388 contains a single character.
 389 As discussed in \fB\%curs_attr\fP(3X),
 390 that character may have been more than eight bits wide in an SVr3 or
 391 SVr4 implementation,
 392 but in the X/Open Curses model,
 393 the details are not given.
 394 The important distinction between SVr4
 395 .I curses
 396 and X/Open Curses is that the latter separates non-character information
 397 (attributes and color)
 398 from the character code,
 399 which SVr4 packs into a
 400 .I \%chtype
 401 for passage to
 402 .BR \%waddch .
 403 .PP
 404 In
 405 .IR \%ncurses ,
 406 .I \%chtype
 407 holds an eight-bit character.
 408 But the library allows a multibyte character to be passed in a
 409 succession of calls to
 410 .BR \%waddch .
 411 Other implementations do not;
 412 a
 413 .B \%waddch
 414 call transmits exactly one character,
 415 which may be rendered in one or more screen locations depending on
 416 whether it is printable.
 417 .PP
 418 Depending on the locale settings,
 419 .I \%ncurses
 420 inspects the byte passed in each
 421 .B \%waddch
 422 call,
 423 and checks whether the latest call continues a multibyte sequence.
 424 When a character is
 425 .IR complete ,
 426 .I \%ncurses
 427 displays the character and advances the cursor.
 428 .PP
 429 If the calling application interrupts the succession of bytes in
 430 a multibyte character sequence by changing the current location\(emfor
 431 example,
 432 with \fB\%wmove\fP(3X)\(em\c
 433 .I \%ncurses
 434 discards the incomplete character.
 435 .PP
 436 For portability to other implementations,
 437 do not rely upon this behavior.
 438 Check whether a character can be represented as a single byte in the
 439 current locale.
 440 .bP
 441 If it can,
 442 call either
 443 .B \%waddch
 444 or \fB\%wadd_wch\fP(3X).
 445 .bP
 446 If it cannot,
 447 use only
 448 \fB\%wadd_wch\fP(3X).
 449 .SS TABSIZE
 450 SVr4 and other versions of
 451 .I curses
 452 implement the
 453 .B \%TABSIZE
 454 variable,
 455 but X/Open Curses does not specify it
 456 (see \fB\%curs_variables\fP(3X)).
 457 .SH SEE ALSO
 458 \fB\%curs_add_wch\fP(3X) describes comparable functions of the
 459 .I \%ncurses
 460 library in its wide-character configuration
 461 .RI ( \%ncursesw ).
 462 .PP
 463 \fB\%curses\fP(3X),
 464 \fB\%curs_addchstr\fP(3X),
 465 \fB\%curs_addstr\fP(3X),
 466 \fB\%curs_attr\fP(3X),
 467 \fB\%curs_clear\fP(3X),
 468 \fB\%curs_inch\fP(3X),
 469 \fB\%curs_outopts\fP(3X),
 470 \fB\%curs_refresh\fP(3X),
 471 \fB\%curs_variables\fP(3X),
 472 \fB\%putchar\fP(3)