lib/libcurses/curses_addch.3

   1 .\"     $NetBSD: curses_addch.3,v 1.7 2007/07/13 11:15:33 jdc Exp $
   2 .\"
   3 .\" Copyright (c) 2002
   4 .\"     Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au)
   5 .\"
   6 .\" This code is donated to the NetBSD Foundation by the Author.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. The name of the Author may not be used to endorse or promote
  17 .\"    products derived from this software without specific prior written
  18 .\"    permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"
  33 .Dd July 11, 2007
  34 .Dt CURSES_ADDCH 3
  35 .Os
  36 .Sh NAME
  37 .Nm curses_addch ,
  38 .Nm addch ,
  39 .Nm waddch ,
  40 .Nm mvaddch ,
  41 .Nm mvwaddch
  42 .Nd curses add characters to windows routines
  43 .Sh LIBRARY
  44 .Lb libcurses
  45 .Sh SYNOPSIS
  46 .In curses.h
  47 .Ft int
  48 .Fn addch "chtype ch"
  49 .Ft int
  50 .Fn waddch "WINDOW *win" "chtype ch"
  51 .Ft int
  52 .Fn mvaddch "int y" "int x" "chtype ch"
  53 .Ft int
  54 .Fn mvwaddch "WINDOW *win" "int y" "int x" "chtype ch"
  55 .Sh DESCRIPTION
  56 These functions add characters to
  57 .Dv stdscr
  58 or to the specified window.
  59 .Pp
  60 The
  61 .Fn addch
  62 function adds the character given in
  63 .Fa ch
  64 to
  65 .Dv stdscr
  66 at the current cursor position and advances the current cursor position by one.
  67 Any character attributes set in
  68 .Fa ch
  69 will be merged with the background attributes currently set on
  70 .Dv stdscr .
  71 .Pp
  72 The
  73 .Fn waddch
  74 function is the same as the
  75 .Fn addch
  76 function, excepting that the character is added to the window specified by
  77 .Fa win .
  78 .Pp
  79 The
  80 .Fn mvaddch
  81 and
  82 .Fn mvwaddch
  83 functions are the same as the
  84 .Fn addch
  85 and
  86 .Fn waddch
  87 functions, respectively, excepting that
  88 .Fn wmove
  89 is called to move the cursor to the position specified by
  90 .Fa y ,
  91 .Fa x
  92 before the character is added to the window.
  93 .Ss LINE DRAWING CHARACTERS
  94 Some terminals support the display of line drawing and graphics characters.
  95 These characters can be added using their defined names, as shown in the
  96 table below.
  97 Where the terminal does not support a specific character, the default
  98 (non-graphics) character is displayed instead.
  99 .Bl -column -offset indent ".Sy System V Name" ".Sy Default"
 100 .It Sy "Name" Ta Sy "Default" Ta Sy "Description"
 101 .It ACS_RARROW Ta \*[Gt] Ta "Arrow pointing right"
 102 .It ACS_LARROW Ta \*[Lt] Ta "Arrow pointing left"
 103 .It ACS_UARROW Ta ^ Ta "Arrow pointing up"
 104 .It ACS_DARROW Ta v Ta "Arrow pointing down"
 105 .It ACS_BLOCK Ta # Ta "Solid square block"
 106 .It ACS_DIAMOND Ta + Ta "Diamond"
 107 .It ACS_CKBOARD Ta : Ta "Checker board (stipple)"
 108 .It ACS_DEGREE Ta ' Ta "Degree symbol"
 109 .It ACS_PLMINUS Ta # Ta "Plus/minus"
 110 .It ACS_BOARD Ta # Ta "Board of squares"
 111 .It ACS_LANTERN Ta # Ta "Lantern symbol"
 112 .It ACS_LRCORNER Ta + Ta "Lower right-hand corner"
 113 .It ACS_URCORNER Ta + Ta "Upper right-hand corner"
 114 .It ACS_ULCORNER Ta + Ta "Upper left-hand corner"
 115 .It ACS_LLCORNER Ta + Ta "Lower left-hand corner"
 116 .It ACS_PLUS Ta + Ta "Plus"
 117 .It ACS_HLINE Ta - Ta "Horizontal line"
 118 .It ACS_S1 Ta - Ta "Scan line 1"
 119 .It ACS_S9 Ta - Ta "Scan line 9"
 120 .It ACS_LTEE Ta + Ta "Left tee"
 121 .It ACS_RTEE Ta + Ta "Right tee"
 122 .It ACS_BTEE Ta + Ta "Bottom tee"
 123 .It ACS_TTEE Ta + Ta "Top tee"
 124 .It ACS_VLINE Ta | Ta "Vertical line"
 125 .It ACS_BULLET Ta o Ta "Bullet"
 126 .El
 127 .Pp
 128 The following additional,
 129 .Em ncurses
 130 compatible, characters are also supported.
 131 .Bl -column -offset indent ".Sy System V Name" ".Sy Default"
 132 .It Sy "Name" Ta Sy "Default" Ta Sy "Description"
 133 .It ACS_S3 Ta - Ta "Scan line 3"
 134 .It ACS_S7 Ta - Ta "Scan line 7"
 135 .It ACS_LEQUAL Ta \*[Lt] Ta "Less than or equal to"
 136 .It ACS_GEQUAL Ta \*[Gt] Ta "Greater than or equal to"
 137 .It ACS_PI Ta * Ta "Pi symbol"
 138 .It ACS_NEQUAL Ta ! Ta "Not equal to"
 139 .It ACS_STERLING Ta f Ta "Sterling symbol"
 140 .El
 141 .Pp
 142 For compatibility with some
 143 .Em System V
 144 implementations, the following definitions are also supported.
 145 .Bl -column -offset indent ".Sy System V Name" ".Sy Default"
 146 .It Sy "System V Name" Ta Sy "NetBSD Curses Name"
 147 .It ACS_SBBS Ta ACS_LRCORNER
 148 .It ACS_BBSS Ta ACS_URCORNER
 149 .It ACS_BSSB Ta ACS_ULCORNER
 150 .It ACS_SSBB Ta ACS_LLCORNER
 151 .It ACS_SSSS Ta ACS_PLUS
 152 .It ACS_BSBS Ta ACS_HLINE
 153 .It ACS_SSSB Ta ACS_LTEE
 154 .It ACS_SBSS Ta ACS_RTEE
 155 .It ACS_SSBS Ta ACS_BTEE
 156 .It ACS_BSSS Ta ACS_TTEE
 157 .It ACS_SBSB Ta ACS_VLINE
 158 .El
 159 .Sh RETURN VALUES
 160 Functions returning pointers will return
 161 .Dv NULL
 162 if an error is detected.
 163 The functions that return an int will return one of the following
 164 values:
 165 .Pp
 166 .Bl -tag -width ERR -compact
 167 .It Er OK
 168 The function completed successfully.
 169 .It Er ERR
 170 An error occurred in the function.
 171 .El
 172 .Sh SEE ALSO
 173 .Xr curses_addchstr 3 ,
 174 .Xr curses_addstr 3 ,
 175 .Xr curses_attributes 3 ,
 176 .Xr curses_cursor 3 ,
 177 .Xr curses_delch 3 ,
 178 .Xr curses_inch 3 ,
 179 .Xr curses_insertch 3
 180 .Sh STANDARDS
 181 The
 182 .Nx
 183 Curses library complies with the X/Open Curses specification, part of the
 184 Single Unix Specification.
 185 .Sh HISTORY
 186 The Curses package appeared in
 187 .Bx 4.0 .