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 92These functions and macros locate and position cursors and windows. 93.Pp 94The 95.Fn getcury 96and 97.Fn getcurx 98functions get the current row and column positions, respectively, of the cursor in 99the window 100.Fa win . 101The 102.Fn getyx 103macro sets the values of 104.Fa y 105and 106.Fa x 107to the current row and column positions of the cursor in the window 108.Fa win . 109.Pp 110The origin row and columns of a window 111.Fa win 112can be 113determined by calling the 114.Fn getbegy 115and 116.Fn getbegx 117functions, respectively, and the maximum row and column for the window can be 118found by calling the functions 119.Fn getmaxy 120and 121.Fn getmaxx , 122respectively. 123The 124.Fn getbegyx 125and 126.Fn getmaxyx 127macros set the values of 128.Fa y 129and 130.Fa x 131to the origin and maximum row and column positions, respectively, for the window 132.Fa win . 133.Pp 134The 135.Fn getpary 136and 137.Fn getparx 138functions return the row and column position of the given subwindow relative to 139the window's parent. 140The macro 141.Fn getparyx 142sets the values of 143.Fa y 144and 145.Fa x 146to the origin of the subwindow relative to the window's parent. 147.Pp 148The 149.Fn move 150function positions the cursor on the current window at the position given by 151.Fa y , 152.Fa x . 153The cursor position is not changed on the screen until the next 154.Fn refresh . 155.Pp 156The 157.Fn wmove 158function is the same as the 159.Fn move 160function, excepting that the cursor is moved in the window specified by 161.Fa win . 162.Pp 163The function 164.Fn mvcur 165moves the cursor to 166.Fa y , 167.Fa x 168on the screen. 169The arguments 170.Fa oldy , 171.Fa oldx 172define the previous cursor position for terminals that do not support 173absolute cursor motions. 174The curses library may optimise the cursor motion based on these values. 175If the 176.Fn mvcur 177succeeds then the curses internal structures are updated with the new 178position of the cursor. 179If the destination arguments for 180.Fn mvcur 181exceed the terminal bounds an error will be returned and the cursor 182position will be unchanged. 183.Pp 184The 185.Fn wcursyncup 186function sets the cursor positions of all ancestors of 187.Fa win 188to that of 189.Fa win . 190.Sh RETURN VALUES 191Functions returning pointers will return 192.Dv NULL 193if an error is detected. 194The functions that return an int will return one of the following 195values: 196.Pp 197.Bl -tag -width ERR -compact 198.It Er OK 199The function completed successfully. 200.It Er ERR 201An error occurred in the function. 202.El 203.Sh SEE ALSO 204.Xr curses_refresh 3 205.Sh STANDARDS 206The 207.Nx 208Curses library complies with the X/Open Curses specification, part of 209the Single Unix Specification. 210The 211.Fn getbegx , 212.Fn getbegy , 213.Fn getcurx , 214.Fn getcury , 215.Fn getmaxx , 216.Fn getmaxy , 217.Fn getparx , 218and 219.Fn getpary 220functions are extensions. 221.Sh HISTORY 222The Curses package appeared in 223.Bx 4.0 . 224