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