1<!-- 2 * t 3 **************************************************************************** 4 * Copyright 2018-2023,2024 Thomas E. Dickey * 5 * Copyright 1998-2015,2017 Free Software Foundation, Inc. * 6 * * 7 * Permission is hereby granted, free of charge, to any person obtaining a * 8 * copy of this software and associated documentation files (the * 9 * "Software"), to deal in the Software without restriction, including * 10 * without limitation the rights to use, copy, modify, merge, publish, * 11 * distribute, distribute with modifications, sublicense, and/or sell * 12 * copies of the Software, and to permit persons to whom the Software is * 13 * furnished to do so, subject to the following conditions: * 14 * * 15 * The above copyright notice and this permission notice shall be included * 16 * in all copies or substantial portions of the Software. * 17 * * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * 19 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * 20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * 21 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * 22 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * 23 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * 24 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * 25 * * 26 * Except as contained in this notice, the name(s) of the above copyright * 27 * holders shall not be used in advertising or otherwise to promote the * 28 * sale, use or other dealings in this Software without prior written * 29 * authorization. * 30 **************************************************************************** 31 * @Id: curs_addch.3x,v 1.85 2024/04/20 19:03:47 tom Exp @ 32--> 33<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> 34<HTML> 35<HEAD> 36<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 37<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> 38<TITLE>curs_addch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> 39<link rel="author" href="mailto:bug-ncurses@gnu.org"> 40 41</HEAD> 42<BODY> 43<H1 class="no-header">curs_addch 3x 2024-04-20 ncurses 6.5 Library calls</H1> 44<PRE> 45<STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> 46 47 48 49 50</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> 51 <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, <STRONG>echochar</STRONG>, <STRONG>wechochar</STRONG> - add a <EM>curses</EM> 52 character to a window and advance the cursor 53 54 55</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> 56 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> 57 58 <STRONG>int</STRONG> <STRONG>addch(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> 59 <STRONG>int</STRONG> <STRONG>waddch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> 60 <STRONG>int</STRONG> <STRONG>mvaddch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> 61 <STRONG>int</STRONG> <STRONG>mvwaddch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> 62 63 <STRONG>int</STRONG> <STRONG>echochar(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> 64 <STRONG>int</STRONG> <STRONG>wechochar(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> 65 66 67</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> 68 69</PRE><H3><a name="h3-Adding-Characters">Adding Characters</a></H3><PRE> 70 <STRONG>waddch</STRONG> puts the character <EM>ch</EM> at the cursor position of window <EM>win</EM>, then 71 advances the cursor position, analogously to the standard C library's 72 <STRONG>putchar(3)</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function. 73 74 If advancement occurs at the right margin, 75 76 <STRONG>o</STRONG> the cursor automatically wraps to the beginning of the next line; 77 and 78 79 <STRONG>o</STRONG> at the bottom of the current scrolling region, and if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> 80 is enabled for <EM>win</EM>, the scrolling region scrolls up one line. 81 82 If <EM>ch</EM> is a backspace, carriage return, line feed, or tab, the cursor 83 moves appropriately within the window. 84 85 <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin 86 of a window, it does nothing. 87 88 <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the current 89 line of the window. 90 91 <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then moves the cursor to the left 92 margin on the next line of the window, and if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is 93 enabled for <EM>win</EM>, scrolls the window if the cursor was already on 94 the last line. 95 96 <STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next 97 line); these are placed at every eighth column by default. Alter 98 the tab interval with the <STRONG>TABSIZE</STRONG> extension; see 99 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>. 100 101 If <EM>ch</EM> is any other nonprintable character, it is drawn in printable 102 form, using the same convention as <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>. 103 104 Calling <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> on the location of a nonprintable character does not 105 return the character itself, but its <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> representation. 106 107 <EM>ch</EM> may contain rendering and/or color attributes, and others can be 108 combined with the parameter by logically "or"ing with it. (A character 109 with its attributes can be copied from place to place using <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> 110 and <STRONG>waddch</STRONG>.) See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> for values of predefined video 111 attribute constants that can be usefully "or"ed with characters. 112 113 114</PRE><H3><a name="h3-Echoing-Characters">Echoing Characters</a></H3><PRE> 115 <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by 116 (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> interprets these functions as a hint that only a 117 single character is being output; for non-control characters, a 118 considerable performance gain may be enjoyed by employing them. 119 120 121</PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE> 122 <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG> 123 to write line-drawing and other special characters to the screen. 124 <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default listed 125 below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> capability does not 126 define a terminal-specific replacement for it, or if the terminal and 127 locale configuration requires Unicode to access these characters but 128 the library is unable to use Unicode. The "acsc char" column 129 corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> string 130 capability, and the characters in it may appear on the screen if the 131 terminal's database entry incorrectly advertises ACS support. The name 132 "ACS" originates in the Alternate Character Set feature of the DEC 133 VT100 terminal. 134 135 <STRONG>ACS</STRONG> <STRONG>acsc</STRONG> 136 <STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG> 137 ------------------------------------------------------------------------ 138 <STRONG>ACS_BLOCK</STRONG> # 0 solid square block 139 <STRONG>ACS_BOARD</STRONG> # h board of squares 140 <STRONG>ACS_BTEE</STRONG> + v bottom tee 141 <STRONG>ACS_BULLET</STRONG> o ~ bullet 142 <STRONG>ACS_CKBOARD</STRONG> : a checker board (stipple) 143 <STRONG>ACS_DARROW</STRONG> v . arrow pointing down 144 <STRONG>ACS_DEGREE</STRONG> ' f degree symbol 145 <STRONG>ACS_DIAMOND</STRONG> + ` diamond 146 <STRONG>ACS_GEQUAL</STRONG> > > greater-than-or-equal-to 147 <STRONG>ACS_HLINE</STRONG> - q horizontal line 148 <STRONG>ACS_LANTERN</STRONG> # i lantern symbol 149 <STRONG>ACS_LARROW</STRONG> < , arrow pointing left 150 <STRONG>ACS_LEQUAL</STRONG> < y less-than-or-equal-to 151 <STRONG>ACS_LLCORNER</STRONG> + m lower left-hand corner 152 <STRONG>ACS_LRCORNER</STRONG> + j lower right-hand corner 153 <STRONG>ACS_LTEE</STRONG> + t left tee 154 <STRONG>ACS_NEQUAL</STRONG> ! | not-equal 155 <STRONG>ACS_PI</STRONG> * { greek pi 156 <STRONG>ACS_PLMINUS</STRONG> # g plus/minus 157 <STRONG>ACS_PLUS</STRONG> + n plus 158 <STRONG>ACS_RARROW</STRONG> > + arrow pointing right 159 <STRONG>ACS_RTEE</STRONG> + u right tee 160 <STRONG>ACS_S1</STRONG> - o scan line 1 161 <STRONG>ACS_S3</STRONG> - p scan line 3 162 <STRONG>ACS_S7</STRONG> - r scan line 7 163 <STRONG>ACS_S9</STRONG> _ s scan line 9 164 <STRONG>ACS_STERLING</STRONG> f } pound-sterling symbol 165 <STRONG>ACS_TTEE</STRONG> + w top tee 166 <STRONG>ACS_UARROW</STRONG> ^ - arrow pointing up 167 <STRONG>ACS_ULCORNER</STRONG> + l upper left-hand corner 168 <STRONG>ACS_URCORNER</STRONG> + k upper right-hand corner 169 <STRONG>ACS_VLINE</STRONG> | x vertical line 170 171 172</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> 173 These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. 174 175 In <EM>ncurses</EM>, <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG> if it is not possible to add a complete 176 character at the cursor position, as when conversion of a multibyte 177 character to a byte sequence fails, or at least one of the resulting 178 bytes cannot be added to the window. See section "PORTABILITY" below 179 regarding the use of <STRONG>waddch</STRONG> with multibyte characters. 180 181 <STRONG>waddch</STRONG> can successfully write a character at the bottom right location 182 of the window. However, <EM>ncurses</EM> returns <STRONG>ERR</STRONG> if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not 183 enabled in that event, because it is not possible to wrap to a new 184 line. 185 186 Functions prefixed with "mv" first perform cursor movement and fail if 187 the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. 188 189 190</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> 191 <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be implemented as macros. 192 193 194</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> 195 X/Open Curses, Issue 4 describes these functions. It specifies no 196 error conditions for them. 197 198 SVr4 <EM>curses</EM> describes a successful return value only as "an integer 199 value other than <STRONG>ERR</STRONG>". 200 201 The defaults specified for forms-drawing characters apply in the POSIX 202 locale. 203 204 205</PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE> 206 X/Open Curses states that the <STRONG>ACS_</STRONG> definitions are <EM>char</EM> constants. 207 208 Some implementations are problematic. 209 210 <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, define the ACS symbols as constants; 211 others define them as elements of an array. 212 213 This implementation uses an array, <STRONG>acs_map</STRONG>, as did SVr4 <EM>curses</EM>. 214 NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG> 215 for compatibility. 216 217 <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <STRONG>ACS_</STRONG> symbols to the analogous 218 <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters (see 219 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and 220 others that are not used for line drawing. 221 222 <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for 223 the <STRONG>ACS_LANTERN</STRONG> symbol, equating its "VT100+ Character" to "I" 224 (capital I), while the header files for SVr4 <EM>curses</EM> and other 225 implementations use "i" (small i). 226 227 None of the terminal descriptions on Unix platforms use uppercase 228 I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>, 229 apparently based on the X/Open documentation around 1995). On the 230 other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator) 231 description uses lowercase i. 232 233 Some ACS symbols (<STRONG>ACS_S3</STRONG>, <STRONG>ACS_S7</STRONG>, <STRONG>ACS_LEQUAL</STRONG>, <STRONG>ACS_GEQUAL</STRONG>, <STRONG>ACS_PI</STRONG>, 234 <STRONG>ACS_NEQUAL</STRONG>, and <STRONG>ACS_STERLING</STRONG>) were not documented in any publicly 235 released System V. However, many publicly available <EM>terminfo</EM> entries 236 include <STRONG>acsc</STRONG> strings in which their key characters <STRONG>(</STRONG>pryz{|}<STRONG>)</STRONG> are 237 embedded, and a second-hand list of their character descriptions has 238 come to light. The <EM>ncurses</EM> developers invented ACS-prefixed names for 239 them. 240 241 The <EM>displayed</EM> values of <STRONG>ACS_</STRONG> constants depend on 242 243 <STRONG>o</STRONG> the <EM>ncurses</EM> ABI--for example, wide-character versus non-wide- 244 character configurations (the former is capable of displaying 245 Unicode while the latter is not), and 246 247 <STRONG>o</STRONG> whether the locale uses UTF-8 encoding. 248 249 In certain cases, the terminal is unable to display forms-drawing 250 characters <EM>except</EM> by using UTF-8; see the discussion of the 251 <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM> environment variable in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>). 252 253 254</PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE> 255 X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a 256 single character. As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, that character may 257 have been more than eight bits wide in an SVr3 or SVr4 implementation, 258 but in the X/Open Curses model, the details are not given. The 259 important distinction between SVr4 <EM>curses</EM> and X/Open Curses is that the 260 latter separates non-character information (attributes and color) from 261 the character code, which SVr4 packs into a <EM>chtype</EM> for passage to 262 <STRONG>waddch</STRONG>. 263 264 In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character. But the library 265 allows a multibyte character to be passed in a succession of calls to 266 <STRONG>waddch</STRONG>. Other implementations do not; a <STRONG>waddch</STRONG> call transmits exactly 267 one character, which may be rendered in one or more screen locations 268 depending on whether it is printable. 269 270 Depending on the locale settings, <EM>ncurses</EM> inspects the byte passed in 271 each <STRONG>waddch</STRONG> call, and checks whether the latest call continues a 272 multibyte sequence. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the 273 character and advances the cursor. 274 275 If the calling application interrupts the succession of bytes in a 276 multibyte character sequence by changing the current location--for 277 example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG>--<EM>ncurses</EM> discards the incomplete character. 278 279 For portability to other implementations, do not rely upon this 280 behavior. Check whether a character can be represented as a single 281 byte in the current locale. 282 283 <STRONG>o</STRONG> If it can, call either <STRONG>waddch</STRONG> or <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>. 284 285 <STRONG>o</STRONG> If it cannot, use only <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>. 286 287 288</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE> 289 SVr4 and other versions of <EM>curses</EM> implement the <STRONG>TABSIZE</STRONG> variable, but 290 X/Open Curses does not specify it (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>). 291 292 293</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> 294 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library 295 in its wide-character configuration (<EM>ncursesw</EM>). 296 297 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>, <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, 298 <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, 299 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putchar(3)</STRONG> 300 301 302 303ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> 304</PRE> 305<div class="nav"> 306<ul> 307<li><a href="#h2-NAME">NAME</a></li> 308<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> 309<li><a href="#h2-DESCRIPTION">DESCRIPTION</a> 310<ul> 311<li><a href="#h3-Adding-Characters">Adding Characters</a></li> 312<li><a href="#h3-Echoing-Characters">Echoing Characters</a></li> 313<li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li> 314</ul> 315</li> 316<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> 317<li><a href="#h2-NOTES">NOTES</a></li> 318<li><a href="#h2-PORTABILITY">PORTABILITY</a> 319<ul> 320<li><a href="#h3-ACS-Symbols">ACS Symbols</a></li> 321<li><a href="#h3-Character-Set">Character Set</a></li> 322<li><a href="#h3-TABSIZE">TABSIZE</a></li> 323</ul> 324</li> 325<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> 326</ul> 327</div> 328</BODY> 329</HTML> 330