usr/src/man/man3curses/curs_addch.3curses

   1 '\" te
   2 .\" Copyright 1989 AT&T
   3 .\" Portions Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH CURS_ADDCH 3CURSES "Dec 31, 1996"
   8 .SH NAME
   9 curs_addch, addch, waddch, mvaddch, mvwaddch, echochar, wechochar \- add a
  10 character (with attributes) to a curses window and advance cursor
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lcurses\fR [ \fIlibrary\fR .. ]
  15 #include <curses.h>
  16
  17 \fBint\fR \fBaddch\fR(\fBchtype\fR \fIch\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBwaddch\fR(\fBWINDOW *\fR\fIwin\fR, \fBchtype\fR \fIch\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBint\fR \fBmvaddch\fR(\fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBchtype\fR \fIch\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBint\fR \fBmvwaddch\fR(\fBWINDOW *\fR\fIwin\fR, \fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBchtype\fR \fIch\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBint\fR \fBechochar\fR(\fBchtype\fR \fIch\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBint\fR \fBwechochar\fR(\fBWINDOW *\fR\fIwin\fR, \fBchtype\fR \fIch\fR);
  43 .fi
  44
  45 .SH DESCRIPTION
  46 .sp
  47 .LP
  48 With the \fBaddch()\fR, \fBwaddch()\fR, \fBmvaddch()\fR, and \fBmvwaddch()\fR
  49 routines, the character \fIch\fR is put into the window at the current cursor
  50 position of the window and the position of the window cursor is advanced. Its
  51 function is similar to that of \fBputchar()\fR. At the right margin, an
  52 automatic newline is performed. At the bottom of the scrolling region, if
  53 \fBscrollok()\fR is enabled, the scrolling region is scrolled up one line.
  54 .sp
  55 .LP
  56 If \fIch\fR is a tab, newline, or backspace, the cursor is moved appropriately
  57 within the window. A newline also does a \fBclrtoeol()\fR before moving. Tabs
  58 are considered to be at every eighth column. If \fIch\fR is another control
  59 character, it is drawn in the \fB^\fR\fIX\fR notation. Calling \fBwinch()\fR
  60 after adding a control character does not return the control character, but
  61 instead returns the representation of the control character. See
  62 \fBcurs_inch\fR(3CURSES).
  63 .sp
  64 .LP
  65 Video attributes can be combined with a character by OR-ing them into the
  66 parameter. This results in these attributes also being set. (The intent here is
  67 that text, including attributes, can be copied from one place to another using
  68 \fBinch()\fR and \fBaddch()\fR.) (see \fBstandout()\fR, predefined video
  69 attribute constants, on the \fBcurs_attr\fR(3CURSES) page).
  70 .sp
  71 .LP
  72 The \fBechochar()\fR and \fBwechochar()\fR routines are functionally equivalent
  73 to a call to \fBaddch()\fR followed by a call to \fBrefresh()\fR, or a call to
  74 \fBwaddch\fR followed by a call to \fBwrefresh()\fR. The knowledge that only a
  75 single character is being output is taken into consideration and, for
  76 non-control characters, a considerable performance gain might be seen by using
  77 these routines instead of their equivalents.
  78 .SS "Line Graphics"
  79 .sp
  80 .LP
  81 The following variables may be used to add line drawing characters to the
  82 screen with routines of the \fBaddch()\fR family.  When variables are defined
  83 for the terminal, the \fBA_ALTCHARSET\fR bit is turned on (see
  84 \fBcurs_attr\fR(3CURSES)). Otherwise, the default character listed below is
  85 stored in the variable. The names chosen are consistent with the VT100
  86 nomenclature.
  87 .sp
  88
  89 .sp
  90 .TS
  91 box;
  92 c | c | c
  93 l | l | l .
  94 Name    Default Glyph Description
  95 _
  96 ACS_ULCORNER    +       upper left-hand corner
  97 _
  98 ACS_LLCORNER    +       lower left-hand corner
  99 _
 100 ACS_URCORNER    +       upper right-hand corner
 101 _
 102 ACS_LRCORNER    +       lower right-hand corner
 103 _
 104 ACS_RTEE        +       right tee
 105 _
 106 ACS_LTEE        +       left tee
 107 _
 108 ACS_BTEE        +       bottom tee
 109 _
 110 ACS_TTEE        +       top tee
 111 _
 112 ACS_HLINE       -       horizontal line
 113 _
 114 ACS_VLINE       |       vertical line
 115 _
 116 ACS_PLUS        +       plus
 117 _
 118 ACS_S1  -       scan line 1
 119 _
 120 ACS_S9  -       scan line 9
 121 _
 122 ACS_DIAMOND     +       diamond
 123 _
 124 ACS_CKBOARD     :       checker board (stipple)
 125 _
 126 ACS_DEGREE      \&'     degree symbol
 127 _
 128 ACS_PLMINUS     #       plus/minus
 129 _
 130 ACS_BULLET      o       bullet
 131 _
 132 ACS_LARROW      <       arrow pointing left
 133 _
 134 ACS_RARROW      >       arrow pointing right
 135 _
 136 ACS_DARROW      v       arrow pointing down
 137 _
 138 ACS_UARROW      ^       arrow pointing up
 139 _
 140 ACS_BOARD       #       board of squares
 141 _
 142 ACS_LANTERN     #       lantern symbol
 143 _
 144 ACS_BLOCK       #       solid square block
 145 .TE
 146
 147 .SH RETURN VALUES
 148 .sp
 149 .LP
 150 All routines return the integer \fBERR\fR upon failure and an integer value
 151 other than \fBERR\fR upon successful completion.
 152 .SH ATTRIBUTES
 153 .sp
 154 .LP
 155 See \fBattributes\fR(5) for descriptions of the following attributes:
 156 .sp
 157
 158 .sp
 159 .TS
 160 box;
 161 c | c
 162 l | l .
 163 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 164 _
 165 MT-Level        Unsafe
 166 .TE
 167
 168 .SH SEE ALSO
 169 .sp
 170 .LP
 171 \fBcurs_attr\fR(3CURSES), \fBcurs_clear\fR(3CURSES), \fBcurs_inch\fR(3CURSES),
 172 \fBcurs_outopts\fR(3CURSES), \fBcurs_refresh\fR(3CURSES),
 173 \fBcurses\fR(3CURSES), \fBputc\fR(3C), \fBattributes\fR(5)
 174 .SH NOTES
 175 .sp
 176 .LP
 177 The header <\fBcurses.h\fR> automatically includes the headers  <\fBstdio.h\fR>
 178 and <\fBunctrl.h\fR>.
 179 .sp
 180 .LP
 181 Note that \fBaddch()\fR, \fBmvaddch()\fR, \fBmvwaddch()\fR, and
 182 \fBechochar()\fR may be macros.