Debian Codegraph @

upstream/debian-unstable/man3/getyx.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2020-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2007,2010 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_getyx.3x,v 1.55 2025/02/01 22:48:11 tom Exp $
31 .TH getyx 3NCURSES 2025-02-01 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .SH NAME
44 \fB\%getyx\fP,
45 \fB\%getparyx\fP,
46 \fB\%getbegyx\fP,
47 \fB\%getmaxyx\fP \-
48 get \fIcurses\fR cursor and window coordinates
49 .SH SYNOPSIS
50 .nf
51 \fB#include <curses.h>
52 .PP
53 \fBvoid getyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
54 \fBvoid getbegyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
55 \fBvoid getmaxyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
56 .PP
57 \fBvoid getparyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
58 .fi
59 .SH DESCRIPTION
60 These macros obtain the cursor position and bounds information of a
61 .I curses
62 window
63 .IR win "."
64 .B \%getyx
65 stores
66 .IR win "'s"
67 cursor position in the variables
68 .I y
69 and
70 .IR x "."
71 .B \%getmaxyx
72 stores
73 .IR win "'s"
74 maximum valid line and column numbers in
75 .I y
76 and
77 .IR x ","
78 respectively.
79 .B \%getbegyx
80 similarly stores the position of
81 .IR win "'s"
82 origin relative to that of the screen
83 (for
84 .BR stdscr ","
85 these coordinates are always
86 .BR 0 ")."
87 .PP
88 If
89 .I win
90 is a subwindow
91 (see \fB\%subwin\fP(3NCURSES)),
92 the
93 .B \%getparyx
94 macro places the coordinates of its origin relative to its parent window
95 into
96 .I y
97 and
98 .IR x ","
99 and
100 .B \-1
101 into both if it is not.
102 .SH RETURN VALUE
103 No return values are defined for macros.
104 Do not use them as the right-hand side of assignment statements.
105 .SH NOTES
106 All of these interfaces are implemented as macros.
107 An \*(``&\*('' operator is not necessary before the variables
108 .I y
109 and
110 .IR x "."
111 .SH PORTABILITY
112 These macros are described in X/Open Curses Issue\ 4.
113 .PP
114 .I \%ncurses
115 also provides functions
116 .IR \%getbegy ","
117 .IR \%getbegx ","
118 .IR \%getcury ","
119 .IR \%getcurx ","
120 .IR \%getmaxy ","
121 .IR \%getmaxx ","
122 .IR \%getpary ","
123 and
124 .I \%getparx
125 for compatibility with System\ V
126 .I curses
127 that were not standardized;
128 .\" even by SVID 4
129 see \fB\%legacy\fP(3NCURSES).
130 .PP
131 Although X/Open Curses does not address the issue,
132 many implementations expose members of the
133 .I \%WINDOW
134 structure containing values corresponding to these macros.
135 Do not rely on their availability;
136 some implementations make
137 .I \%WINDOW
138 opaque
139 (that is,
140 they do not allow direct access to its members).
141 .PP
142 Besides the problem of opaque structures,
143 the data stored in like-named members may not have values of the same
144 meaning across different implementations.
145 For example,
146 the values of
147 .I \%WINDOW._maxx
148 and
149 .I \%WINDOW._maxy
150 in
151 .I \%ncurses
152 have long
153 .\" (at least since its initial release, 1.8.1)
154 differed by one from some other implementations.
155 The
156 .I \%getmaxyx
157 macro hides this difference.
158 .SH HISTORY
159 4BSD (1980)
160 introduced
161 .IR \%getyx "."
162 .PP
163 SVr3 (1987)
164 added
165 .I \%getbegyx
166 and
167 .IR \%getmaxyx "."
168 SVr3.1 later that year supplied
169 .IR \%getparyx "."
170 .SH SEE ALSO
171 \fB\%ncurses\fP(3NCURSES),
172 \fB\%legacy\fP(3NCURSES),
173 \fB\%opaque\fP(3NCURSES)