| 1 | '\" t
|
|---|
| 2 | .\"***************************************************************************
|
|---|
| 3 | .\" Copyright (c) 1998-2003,2004 Free Software Foundation, Inc. *
|
|---|
| 4 | .\" *
|
|---|
| 5 | .\" Permission is hereby granted, free of charge, to any person obtaining a *
|
|---|
| 6 | .\" copy of this software and associated documentation files (the *
|
|---|
| 7 | .\" "Software"), to deal in the Software without restriction, including *
|
|---|
| 8 | .\" without limitation the rights to use, copy, modify, merge, publish, *
|
|---|
| 9 | .\" distribute, distribute with modifications, sublicense, and/or sell *
|
|---|
| 10 | .\" copies of the Software, and to permit persons to whom the Software is *
|
|---|
| 11 | .\" furnished to do so, subject to the following conditions: *
|
|---|
| 12 | .\" *
|
|---|
| 13 | .\" The above copyright notice and this permission notice shall be included *
|
|---|
| 14 | .\" in all copies or substantial portions of the Software. *
|
|---|
| 15 | .\" *
|
|---|
| 16 | .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|---|
| 17 | .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|---|
| 18 | .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|---|
| 19 | .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|---|
| 20 | .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|---|
| 21 | .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|---|
| 22 | .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|---|
| 23 | .\" *
|
|---|
| 24 | .\" Except as contained in this notice, the name(s) of the above copyright *
|
|---|
| 25 | .\" holders shall not be used in advertising or otherwise to promote the *
|
|---|
| 26 | .\" sale, use or other dealings in this Software without prior written *
|
|---|
| 27 | .\" authorization. *
|
|---|
| 28 | .\"***************************************************************************
|
|---|
| 29 | .\"
|
|---|
| 30 | .\" $Id: curs_addch.3x,v 1.23 2004/01/31 13:16:21 tom Exp $
|
|---|
| 31 | .TH curs_addch 3X ""
|
|---|
| 32 | .SH NAME
|
|---|
| 33 | \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR,
|
|---|
| 34 | \fBechochar\fR,
|
|---|
| 35 | \fBwechochar\fR - add a character (with attributes) to a \fBcurses\fR window, then advance the cursor
|
|---|
| 36 | .SH SYNOPSIS
|
|---|
| 37 | \fB#include <curses.h>\fR
|
|---|
| 38 | .PP
|
|---|
| 39 | \fBint addch(const chtype ch);\fR
|
|---|
| 40 | .br
|
|---|
| 41 | \fBint waddch(WINDOW *win, const chtype ch);\fR
|
|---|
| 42 | .br
|
|---|
| 43 | \fBint mvaddch(int y, int x, const chtype ch);\fR
|
|---|
| 44 | .br
|
|---|
| 45 | \fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR
|
|---|
| 46 | .br
|
|---|
| 47 | \fBint echochar(const chtype ch);\fR
|
|---|
| 48 | .br
|
|---|
| 49 | \fBint wechochar(WINDOW *win, const chtype ch);\fR
|
|---|
| 50 | .br
|
|---|
| 51 | .SH DESCRIPTION
|
|---|
| 52 | The \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR and \fBmvwaddch\fR routines put
|
|---|
| 53 | the character \fIch\fR into the given window at its current window position,
|
|---|
| 54 | which is then advanced. They are analogous to \fBputchar\fR in \fBstdio\fR(3).
|
|---|
| 55 | If the advance is at the right margin, the cursor automatically wraps to the
|
|---|
| 56 | beginning of the next line. At the bottom of the current scrolling region, if
|
|---|
| 57 | \fBscrollok\fR is enabled, the scrolling region is scrolled up one line.
|
|---|
| 58 | .PP
|
|---|
| 59 | If \fIch\fR is a tab, newline, or backspace,
|
|---|
| 60 | the cursor is moved appropriately within the window.
|
|---|
| 61 | Backspace moves the cursor one character left; at the left
|
|---|
| 62 | edge of a window it does nothing.
|
|---|
| 63 | Newline does a \fBclrtoeol\fR,
|
|---|
| 64 | then moves the cursor to the window left margin on the next line,
|
|---|
| 65 | scrolling the window if on the last line.
|
|---|
| 66 | Tabs are considered to be at every eighth column.
|
|---|
| 67 | The tab interval may be altered by setting the \fBTABSIZE\fR variable.
|
|---|
| 68 | .PP
|
|---|
| 69 | If \fIch\fR is any control character other than tab, newline, or backspace, it
|
|---|
| 70 | is drawn in \fB^\fR\fIX\fR notation. Calling \fBwinch\fR after adding a
|
|---|
| 71 | control character does not return the character itself, but instead returns
|
|---|
| 72 | the ^-representation of the control character.
|
|---|
| 73 | .PP
|
|---|
| 74 | Video attributes can be combined with a character argument passed to
|
|---|
| 75 | \fBaddch\fR or related functions by logical-ORing them into the character.
|
|---|
| 76 | (Thus, text, including attributes, can be copied from one place to another
|
|---|
| 77 | using \fBinch\fR and \fBaddch\fR.) See the \fBcurs_attr\fR(3X) page for
|
|---|
| 78 | values of predefined video attribute constants that can be usefully OR'ed
|
|---|
| 79 | into characters.
|
|---|
| 80 | .PP
|
|---|
| 81 | The \fBechochar\fR and \fBwechochar\fR routines are equivalent to a call to
|
|---|
| 82 | \fBaddch\fR followed by a call to \fBrefresh\fR, or a call to \fBwaddch\fR
|
|---|
| 83 | followed by a call to \fBwrefresh\fR. The knowledge that only a single
|
|---|
| 84 | character is being output is used and, for non-control characters, a
|
|---|
| 85 | considerable performance gain may be seen by using these routines instead of
|
|---|
| 86 | their equivalents.
|
|---|
| 87 | .SS Line Graphics
|
|---|
| 88 | The following variables may be used to add line drawing characters to the
|
|---|
| 89 | screen with routines of the \fBaddch\fR family. The default character listed
|
|---|
| 90 | below is used if the \fBacsc\fR capability doesn't define a terminal-specific
|
|---|
| 91 | replacement for it (but see the EXTENSIONS section below). The names are
|
|---|
| 92 | taken from VT100 nomenclature.
|
|---|
| 93 | .PP
|
|---|
| 94 | .TS
|
|---|
| 95 | l l l
|
|---|
| 96 | _ _ _
|
|---|
| 97 | l l l.
|
|---|
| 98 | \fIName\fR \fIDefault\fR \fIDescription\fR
|
|---|
| 99 | ACS_BLOCK # solid square block
|
|---|
| 100 | ACS_BOARD # board of squares
|
|---|
| 101 | ACS_BTEE + bottom tee
|
|---|
| 102 | ACS_BULLET o bullet
|
|---|
| 103 | ACS_CKBOARD : checker board (stipple)
|
|---|
| 104 | ACS_DARROW v arrow pointing down
|
|---|
| 105 | ACS_DEGREE ' degree symbol
|
|---|
| 106 | ACS_DIAMOND + diamond
|
|---|
| 107 | ACS_GEQUAL > greater-than-or-equal-to
|
|---|
| 108 | ACS_HLINE - horizontal line
|
|---|
| 109 | ACS_LANTERN # lantern symbol
|
|---|
| 110 | ACS_LARROW < arrow pointing left
|
|---|
| 111 | ACS_LEQUAL < less-than-or-equal-to
|
|---|
| 112 | ACS_LLCORNER + lower left-hand corner
|
|---|
| 113 | ACS_LRCORNER + lower right-hand corner
|
|---|
| 114 | ACS_LTEE + left tee
|
|---|
| 115 | ACS_NEQUAL ! not-equal
|
|---|
| 116 | ACS_PI * greek pi
|
|---|
| 117 | ACS_PLMINUS # plus/minus
|
|---|
| 118 | ACS_PLUS + plus
|
|---|
| 119 | ACS_RARROW > arrow pointing right
|
|---|
| 120 | ACS_RTEE + right tee
|
|---|
| 121 | ACS_S1 - scan line 1
|
|---|
| 122 | ACS_S3 - scan line 3
|
|---|
| 123 | ACS_S7 - scan line 7
|
|---|
| 124 | ACS_S9 \&_ scan line 9
|
|---|
| 125 | ACS_STERLING f pound-sterling symbol
|
|---|
| 126 | ACS_TTEE + top tee
|
|---|
| 127 | ACS_UARROW ^ arrow pointing up
|
|---|
| 128 | ACS_ULCORNER + upper left-hand corner
|
|---|
| 129 | ACS_URCORNER + upper right-hand corner
|
|---|
| 130 | ACS_VLINE | vertical line
|
|---|
| 131 | .TE
|
|---|
| 132 | .SH RETURN VALUE
|
|---|
| 133 | All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success
|
|---|
| 134 | (the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon
|
|---|
| 135 | successful completion, unless otherwise noted in the preceding routine
|
|---|
| 136 | descriptions.
|
|---|
| 137 | .SH NOTES
|
|---|
| 138 | Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and
|
|---|
| 139 | \fBechochar\fR may be macros.
|
|---|
| 140 | .SH PORTABILITY
|
|---|
| 141 | All these functions are described in the XSI Curses standard, Issue 4.
|
|---|
| 142 | The defaults specified for forms-drawing characters apply in the POSIX locale.
|
|---|
| 143 | .LP
|
|---|
| 144 | Some ACS symbols
|
|---|
| 145 | (ACS_S3,
|
|---|
| 146 | ACS_S7,
|
|---|
| 147 | ACS_LEQUAL,
|
|---|
| 148 | ACS_GEQUAL,
|
|---|
| 149 | ACS_PI,
|
|---|
| 150 | ACS_NEQUAL,
|
|---|
| 151 | ACS_STERLING)
|
|---|
| 152 | were not documented in
|
|---|
| 153 | any publicly released System V. However, many publicly available terminfos
|
|---|
| 154 | include \fBacsc\fR strings in which their key characters (pryz{|}) are
|
|---|
| 155 | embedded, and a second-hand list of their character descriptions has come
|
|---|
| 156 | to light. The ACS-prefixed names for them were invented for \fBncurses\fR(3X).
|
|---|
| 157 | .LP
|
|---|
| 158 | The \fBTABSIZE\fR variable is implemented in some versions of curses,
|
|---|
| 159 | but is not part of X/Open curses.
|
|---|
| 160 | .LP
|
|---|
| 161 | If \fIch\fR is a carriage return,
|
|---|
| 162 | the cursor is moved to the beginning of the current row of the window.
|
|---|
| 163 | This is true of other implementations, but is not documented.
|
|---|
| 164 | .SH SEE ALSO
|
|---|
| 165 | \fBcurses\fR(3X), \fBcurs_attr\fR(3X), \fBcurs_clear\fR(3X),
|
|---|
| 166 | \fBcurs_inch\fR(3X), \fBcurs_outopts\fR(3X), \fBcurs_refresh\fR(3X),
|
|---|
| 167 | \fBputc\fR(3S).
|
|---|
| 168 | .\"#
|
|---|
| 169 | .\"# The following sets edit modes for GNU EMACS
|
|---|
| 170 | .\"# Local Variables:
|
|---|
| 171 | .\"# mode:nroff
|
|---|
| 172 | .\"# fill-column:79
|
|---|
| 173 | .\"# End:
|
|---|
