lib/libcurses/curses_line.3

   1 .\"     $NetBSD: curses_line.3,v 1.6 2010/02/20 10:23:04 wiz 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 February 19, 2010
  34 .Dt CURSES_LINE 3
  35 .Os
  36 .Sh NAME
  37 .Nm curses_line ,
  38 .Nm hline ,
  39 .Nm whline ,
  40 .Nm vline ,
  41 .Nm wvline ,
  42 .Nm mvhline ,
  43 .Nm mvwhline ,
  44 .Nm mvvline ,
  45 .Nm mvwvline
  46 .Nd curses draw lines on windows routines
  47 .Sh LIBRARY
  48 .Lb libcurses
  49 .Sh SYNOPSIS
  50 .In curses.h
  51 .Ft int
  52 .Fn hline "chtype ch" "int n"
  53 .Ft int
  54 .Fn whline "WINDOW *win" "chtype ch" "int n"
  55 .Ft int
  56 .Fn mvhline "int y" "int x" "chtype ch" "int n"
  57 .Ft int
  58 .Fn mvwvline "WINDOW *win" "int y" "int x" "chtype c" "int n"
  59 .Ft int
  60 .Fn vline "chtype c" "int n"
  61 .Ft int
  62 .Fn wvline "WINDOW *win" "chtype c" "int n"
  63 .Ft int
  64 .Fn mvvline "int y" "int x" "chtype ch" "int n"
  65 .Ft int
  66 .Fn mvwhline "WINDOW *win" "int y" "int x" "chtype c" "int n"
  67 .Sh DESCRIPTION
  68 These functions draw lines on
  69 .Dv stdscr
  70 or on the specified window.
  71 .Pp
  72 The
  73 .Fn hline
  74 function draws a horizontal line of the character
  75 .Fa ch
  76 on
  77 .Dv stdscr
  78 starting at the current cursor position and extending for
  79 .Fa n
  80 characters, or until the right hand side of
  81 .Dv stdscr
  82 is reached.
  83 If the text portion of
  84 .Fa ch
  85 is 0 then the line will be drawn with the
  86 .Dv ACS_HLINE
  87 character.
  88 .Pp
  89 The
  90 .Fn whline
  91 function is the same as the
  92 .Fn hline
  93 function, excepting that the line is drawn in the window specified by
  94 .Fa win .
  95 .Pp
  96 The
  97 .Fn vline
  98 function draws a vertical line of character
  99 .Fa ch
 100 on
 101 .Dv stdscr
 102 starting at the current cursor position and moving down until either
 103 .Fa n
 104 characters have been drawn or the bottom of
 105 .Dv stdscr
 106 is reached.
 107 If the text portion of
 108 .Fa ch
 109 is 0 then the line will be drawn with the
 110 .Dv ACS_VLINE
 111 character.
 112 .Pp
 113 The
 114 .Fn wvline
 115 function is the same as the
 116 .Fn vline
 117 function, excepting that the line is drawn on the given window.
 118 .Pp
 119 The
 120 .Fn mvhline ,
 121 .Fn mvwhline ,
 122 .Fn mvvline
 123 and
 124 .Fn mvwvline
 125 functions are the same as the
 126 .Fn hline ,
 127 .Fn whline ,
 128 .Fn vline
 129 and
 130 .Fn wvline
 131 functions, respectively, excepting that
 132 .Fn wmove
 133 is called to move the cursor to the position specified by
 134 .Fa y ,
 135 .Fa x
 136 before the line is drawn on the window.
 137 .Sh RETURN VALUES
 138 Functions returning pointers will return
 139 .Dv NULL
 140 if an error is detected.
 141 The functions that return an int will return one of the following
 142 values:
 143 .Pp
 144 .Bl -tag -width ERR -compact
 145 .It Er OK
 146 The function completed successfully.
 147 .It Er ERR
 148 An error occurred in the function.
 149 .El
 150 .Sh SEE ALSO
 151 .Xr curses_border 3
 152 .Sh STANDARDS
 153 The
 154 .Nx
 155 Curses library complies with the X/Open Curses specification, part of
 156 the Single Unix Specification.
 157 .Pp
 158 The use of
 159 .Dv ACS_HLINE
 160 and
 161 .Dv ACS_VLINE
 162 as default drawing character in
 163 .Fn hline
 164 and
 165 .Fn vline
 166 is a
 167 .Nx
 168 extension which should not be relied on in portable code.
 169 .Sh HISTORY
 170 The Curses package appeared in
 171 .Bx 4.0 .