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