lib/libcurses/curses_cursor.3

   1 .\"     $NetBSD: curses_cursor.3,v 1.7 2010/02/24 13:02:13 drochner 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 23, 2010
  34 .Dt CURSES 3
  35 .Os
  36 .Sh NAME
  37 .Nm curses_cursor ,
  38 .Nm getcury ,
  39 .Nm getcurx ,
  40 .Nm getyx ,
  41 .Nm getbegy ,
  42 .Nm getbegx ,
  43 .Nm getbegyx ,
  44 .Nm getmaxy ,
  45 .Nm getmaxx ,
  46 .Nm getmaxyx ,
  47 .Nm getpary ,
  48 .Nm getparx ,
  49 .Nm getparyx ,
  50 .Nm move ,
  51 .Nm wmove ,
  52 .Nm mvcur ,
  53 .Nm wcursyncup
  54 .Nd curses cursor and window location and positioning routines
  55 .Sh LIBRARY
  56 .Lb libcurses
  57 .Sh SYNOPSIS
  58 .In curses.h
  59 .Ft int
  60 .Fn getcury "WINDOW *win"
  61 .Ft int
  62 .Fn getcurx "WINDOW *win"
  63 .Ft void
  64 .Fn getyx "WINDOW *win" "int y" "int x"
  65 .Ft int
  66 .Fn getbegy "WINDOW *win"
  67 .Ft int
  68 .Fn getbegx "WINDOW *win"
  69 .Ft void
  70 .Fn getbegyx "WINDOW *win" "int y" "int x"
  71 .Ft int
  72 .Fn getmaxy "WINDOW *win"
  73 .Ft int
  74 .Fn getmaxx "WINDOW *win"
  75 .Ft void
  76 .Fn getmaxyx "WINDOW *win" "int y" "int x"
  77 .Ft int
  78 .Fn getpary "WINDOW *win"
  79 .Ft int
  80 .Fn getparx "WINDOW *win"
  81 .Ft void
  82 .Fn getparyx "WINDOW *win" "int y" "int x"
  83 .Ft int
  84 .Fn move "int y" "int x"
  85 .Ft int
  86 .Fn wmove "WINDOW *win" "int y" "int x"
  87 .Ft int
  88 .Fn mvcur "int oldy" "int oldx" "int y" "int x"
  89 .Ft void
  90 .Fn wcursyncup "WINDOW *win"
  91 .Sh DESCRIPTION
  92 These functions and macros locate and position cursors and windows.
  93 .Pp
  94 The
  95 .Fn getcury
  96 and
  97 .Fn getcurx
  98 functions get the current row and column positions, respectively, of the cursor in
  99 the window
 100 .Fa win .
 101 The
 102 .Fn getyx
 103 macro sets the values of
 104 .Fa y
 105 and
 106 .Fa x
 107 to the current row and column positions of the cursor in the window
 108 .Fa win .
 109 .Pp
 110 The origin row and columns of a window
 111 .Fa win
 112 can be
 113 determined by calling the
 114 .Fn getbegy
 115 and
 116 .Fn getbegx
 117 functions, respectively, and the maximum row and column for the window can be
 118 found by calling the functions
 119 .Fn getmaxy
 120 and
 121 .Fn getmaxx ,
 122 respectively.
 123 The
 124 .Fn getbegyx
 125 and
 126 .Fn getmaxyx
 127 macros set the values of
 128 .Fa y
 129 and
 130 .Fa x
 131 to the origin and maximum row and column positions, respectively, for the window
 132 .Fa win .
 133 .Pp
 134 The
 135 .Fn getpary
 136 and
 137 .Fn getparx
 138 functions return the row and column position of the given subwindow relative to
 139 the window's parent.
 140 The macro
 141 .Fn getparyx
 142 sets the values of
 143 .Fa y
 144 and
 145 .Fa x
 146 to the origin of the subwindow relative to the window's parent.
 147 .Pp
 148 The
 149 .Fn move
 150 function positions the cursor on the current window at the position given by
 151 .Fa y ,
 152 .Fa x .
 153 The cursor position is not changed on the screen until the next
 154 .Fn refresh .
 155 .Pp
 156 The
 157 .Fn wmove
 158 function is the same as the
 159 .Fn move
 160 function, excepting that the cursor is moved in the window specified by
 161 .Fa win .
 162 .Pp
 163 The function
 164 .Fn mvcur
 165 moves the cursor to
 166 .Fa y ,
 167 .Fa x
 168 on the screen.
 169 The arguments
 170 .Fa oldy ,
 171 .Fa oldx
 172 define the previous cursor position for terminals that do not support
 173 absolute cursor motions.
 174 The curses library may optimise the cursor motion based on these values.
 175 If the
 176 .Fn mvcur
 177 succeeds then the curses internal structures are updated with the new
 178 position of the cursor.
 179 If the destination arguments for
 180 .Fn mvcur
 181 exceed the terminal bounds an error will be returned and the cursor
 182 position will be unchanged.
 183 .Pp
 184 The
 185 .Fn wcursyncup
 186 function sets the cursor positions of all ancestors of
 187 .Fa win
 188 to that of
 189 .Fa win .
 190 .Sh RETURN VALUES
 191 Functions returning pointers will return
 192 .Dv NULL
 193 if an error is detected.
 194 The functions that return an int will return one of the following
 195 values:
 196 .Pp
 197 .Bl -tag -width ERR -compact
 198 .It Er OK
 199 The function completed successfully.
 200 .It Er ERR
 201 An error occurred in the function.
 202 .El
 203 .Sh SEE ALSO
 204 .Xr curses_refresh 3
 205 .Sh STANDARDS
 206 The
 207 .Nx
 208 Curses library complies with the X/Open Curses specification, part of
 209 the Single Unix Specification.
 210 The
 211 .Fn getbegx ,
 212 .Fn getbegy ,
 213 .Fn getcurx ,
 214 .Fn getcury ,
 215 .Fn getmaxx ,
 216 .Fn getmaxy ,
 217 .Fn getparx ,
 218 and
 219 .Fn getpary
 220 functions are extensions.
 221 .Sh HISTORY
 222 The Curses package appeared in
 223 .Bx 4.0 .