aboutsummaryrefslogtreecommitdiff
path: root/man/curs_addch.3x
diff options
context:
space:
mode:
authorRong-En Fan <rafan@FreeBSD.org>2008-11-09 09:06:04 +0000
committerRong-En Fan <rafan@FreeBSD.org>2008-11-09 09:06:04 +0000
commita388f199193767bacbb38b172ab89cb84369736c (patch)
treea1816f5667d2280b970ca44e407bac8cc4496c0a /man/curs_addch.3x
parentaa59d4d4c5dda7e1c6f9dc0cc6edc58992a525c7 (diff)
downloadsrc-a388f199193767bacbb38b172ab89cb84369736c.tar.gz
src-a388f199193767bacbb38b172ab89cb84369736c.zip
- Flatten the vendor area
Notes
Notes: svn path=/vendor/ncurses/dist/; revision=184786
Diffstat (limited to 'man/curs_addch.3x')
-rw-r--r--man/curs_addch.3x181
1 files changed, 181 insertions, 0 deletions
diff --git a/man/curs_addch.3x b/man/curs_addch.3x
new file mode 100644
index 000000000000..73918b88b954
--- /dev/null
+++ b/man/curs_addch.3x
@@ -0,0 +1,181 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright (c) 1998-2006,2007 Free Software Foundation, Inc. *
+.\" *
+.\" Permission is hereby granted, free of charge, to any person obtaining a *
+.\" copy of this software and associated documentation files (the *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" $Id: curs_addch.3x,v 1.27 2007/06/02 20:40:07 tom Exp $
+.TH curs_addch 3X ""
+.SH NAME
+\fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR,
+\fBechochar\fR,
+\fBwechochar\fR - add a character (with attributes) to a \fBcurses\fR window, then advance the cursor
+.SH SYNOPSIS
+\fB#include <curses.h>\fR
+.PP
+\fBint addch(const chtype ch);\fR
+.br
+\fBint waddch(WINDOW *win, const chtype ch);\fR
+.br
+\fBint mvaddch(int y, int x, const chtype ch);\fR
+.br
+\fBint mvwaddch(WINDOW *win, int y, int x, const chtype ch);\fR
+.br
+\fBint echochar(const chtype ch);\fR
+.br
+\fBint wechochar(WINDOW *win, const chtype ch);\fR
+.br
+.SH DESCRIPTION
+The \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR and \fBmvwaddch\fR routines put
+the character \fIch\fR into the given window at its current window position,
+which is then advanced. They are analogous to \fBputchar\fR in \fBstdio\fR(3).
+If the advance is at the right margin, the cursor automatically wraps to the
+beginning of the next line. At the bottom of the current scrolling region, if
+\fBscrollok\fR is enabled, the scrolling region is scrolled up one line.
+.PP
+If \fIch\fR is a tab, newline, or backspace,
+the cursor is moved appropriately within the window.
+Backspace moves the cursor one character left; at the left
+edge of a window it does nothing.
+Newline does a \fBclrtoeol\fR,
+then moves the cursor to the window left margin on the next line,
+scrolling the window if on the last line.
+Tabs are considered to be at every eighth column.
+The tab interval may be altered by setting the \fBTABSIZE\fR variable.
+.PP
+If \fIch\fR is any control character other than tab, newline, or backspace, it
+is drawn in \fB^\fR\fIX\fR notation. Calling \fBwinch\fR after adding a
+control character does not return the character itself, but instead returns
+the ^-representation of the control character.
+.PP
+Video attributes can be combined with a character argument passed to
+\fBaddch\fR or related functions by logical-ORing them into the character.
+(Thus, text, including attributes, can be copied from one place to another
+using \fBinch\fR and \fBaddch\fR.) See the \fBcurs_attr\fR(3X) page for
+values of predefined video attribute constants that can be usefully OR'ed
+into characters.
+.PP
+The \fBechochar\fR and \fBwechochar\fR routines are equivalent to a call to
+\fBaddch\fR followed by a call to \fBrefresh\fR, or a call to \fBwaddch\fR
+followed by a call to \fBwrefresh\fR. The knowledge that only a single
+character is being output is used and, for non-control characters, a
+considerable performance gain may be seen by using these routines instead of
+their equivalents.
+.SS Line Graphics
+The following variables may be used to add line drawing characters to the
+screen with routines of the \fBaddch\fR family. The default character listed
+below is used if the \fBacsc\fR capability does not define a terminal-specific
+replacement for it.
+The names are taken from VT100 nomenclature.
+.PP
+.TS
+l l l
+_ _ _
+l l l.
+\fIName\fR \fIDefault\fR \fIDescription\fR
+ACS_BLOCK # solid square block
+ACS_BOARD # board of squares
+ACS_BTEE + bottom tee
+ACS_BULLET o bullet
+ACS_CKBOARD : checker board (stipple)
+ACS_DARROW v arrow pointing down
+ACS_DEGREE ' degree symbol
+ACS_DIAMOND + diamond
+ACS_GEQUAL > greater-than-or-equal-to
+ACS_HLINE - horizontal line
+ACS_LANTERN # lantern symbol
+ACS_LARROW < arrow pointing left
+ACS_LEQUAL < less-than-or-equal-to
+ACS_LLCORNER + lower left-hand corner
+ACS_LRCORNER + lower right-hand corner
+ACS_LTEE + left tee
+ACS_NEQUAL ! not-equal
+ACS_PI * greek pi
+ACS_PLMINUS # plus/minus
+ACS_PLUS + plus
+ACS_RARROW > arrow pointing right
+ACS_RTEE + right tee
+ACS_S1 - scan line 1
+ACS_S3 - scan line 3
+ACS_S7 - scan line 7
+ACS_S9 \&_ scan line 9
+ACS_STERLING f pound-sterling symbol
+ACS_TTEE + top tee
+ACS_UARROW ^ arrow pointing up
+ACS_ULCORNER + upper left-hand corner
+ACS_URCORNER + upper right-hand corner
+ACS_VLINE | vertical line
+.TE
+.SH RETURN VALUE
+All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success
+(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon
+successful completion, unless otherwise noted in the preceding routine
+descriptions.
+.SH NOTES
+Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and
+\fBechochar\fR may be macros.
+.SH PORTABILITY
+All these functions are described in the XSI Curses standard, Issue 4.
+The defaults specified for forms-drawing characters apply in the POSIX locale.
+.LP
+Some ACS symbols
+(ACS_S3,
+ACS_S7,
+ACS_LEQUAL,
+ACS_GEQUAL,
+ACS_PI,
+ACS_NEQUAL,
+ACS_STERLING)
+were not documented in
+any publicly released System V. However, many publicly available terminfos
+include \fBacsc\fR strings in which their key characters (pryz{|}) are
+embedded, and a second-hand list of their character descriptions has come
+to light. The ACS-prefixed names for them were invented for \fBncurses\fR(3X).
+.LP
+The \fBTABSIZE\fR variable is implemented in some versions of curses,
+but is not part of X/Open curses.
+.LP
+If \fIch\fR is a carriage return,
+the cursor is moved to the beginning of the current row of the window.
+This is true of other implementations, but is not documented.
+.SH SEE ALSO
+\fBcurses\fR(3X),
+\fBcurs_attr\fR(3X),
+\fBcurs_clear\fR(3X),
+\fBcurs_inch\fR(3X),
+\fBcurs_outopts\fR(3X),
+\fBcurs_refresh\fR(3X),
+\fBputc\fR(3).
+.PP
+Comparable functions in the wide-character (ncursesw) library are
+described in
+\fBcurs_add_wch\fR(3X).
+.\"#
+.\"# The following sets edit modes for GNU EMACS
+.\"# Local Variables:
+.\"# mode:nroff
+.\"# fill-column:79
+.\"# End: