Annotation of src/lib/libcurses/curses_cursor.3, Revision 1.6
1.6 ! wiz 1: .\" $NetBSD: curses_cursor.3,v 1.5 2004/07/23 13:38:48 wiz Exp $
1.1 blymn 2: .\"
3: .\" Copyright (c) 2002
1.2 grant 4: .\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au)
1.1 blymn 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: .\"
1.5 wiz 33: .Dd July 23, 2004
1.1 blymn 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
1.3 wiz 57: .In curses.h
1.1 blymn 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
1.4 snj 128: to the origin and maximum row and column positions, respectively, for the window
1.1 blymn 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.
1.5 wiz 200: The
201: .Fn getbegx ,
202: .Fn getbegy ,
1.6 ! wiz 203: .Fn getcurx ,
! 204: .Fn getcury ,
1.5 wiz 205: .Fn getmaxx ,
1.6 ! wiz 206: .Fn getmaxy ,
! 207: .Fn getparx ,
1.5 wiz 208: and
1.6 ! wiz 209: .Fn getpary
1.5 wiz 210: functions are extensions.
1.1 blymn 211: .Sh HISTORY
212: The Curses package appeared in
213: .Bx 4.0 .
CVSweb <webmaster@jp.NetBSD.org>