.\"***************************************************************************
.\" Copyright 2020-2024,2025 Thomas E. Dickey                                *
.\" Copyright 1998-2007,2010 Free Software Foundation, Inc.                  *
.\"                                                                          *
.\" Permission is hereby granted, free of charge, to any person obtaining a  *
.\" copy of this software and associated documentation files (the            *
.\" "Software"), to deal in the Software without restriction, including      *
.\" without limitation the rights to use, copy, modify, merge, publish,      *
.\" distribute, distribute with modifications, sublicense, and/or sell       *
.\" copies of the Software, and to permit persons to whom the Software is    *
.\" furnished to do so, subject to the following conditions:                 *
.\"                                                                          *
.\" The above copyright notice and this permission notice shall be included  *
.\" in all copies or substantial portions of the Software.                   *
.\"                                                                          *
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
.\"                                                                          *
.\" Except as contained in this notice, the name(s) of the above copyright   *
.\" holders shall not be used in advertising or otherwise to promote the     *
.\" sale, use or other dealings in this Software without prior written       *
.\" authorization.                                                           *
.\"***************************************************************************
.\"
.\" $Id: curs_getyx.3x,v 1.55 2025/02/01 22:48:11 tom Exp $
.TH curs_getyx 3X 2025-02-01 "ncurses 6.5" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.\}
.el \{\
.ie t .ds `` ``
.el   .ds `` ""
.ie t .ds '' ''
.el   .ds '' ""
.\}
.
.SH NAME
\fB\%getyx\fP,
\fB\%getparyx\fP,
\fB\%getbegyx\fP,
\fB\%getmaxyx\fP \-
get \fIcurses\fR cursor and window coordinates
.SH SYNOPSIS
.nf
\fB#include <curses.h>
.PP
\fBvoid getyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
\fBvoid getbegyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
\fBvoid getmaxyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
.PP
\fBvoid getparyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
.fi
.SH DESCRIPTION
These macros obtain the cursor position and bounds information of a
.I curses
window
.IR win "."
.B \%getyx
stores
.IR win "'s"
cursor position in the variables
.I y
and
.IR x "."
.B \%getmaxyx
stores
.IR win "'s"
maximum valid line and column numbers in
.I y
and
.IR x ","
respectively.
.B \%getbegyx
similarly stores the position of
.IR win "'s"
origin relative to that of the screen
(for
.BR stdscr ","
these coordinates are always
.BR 0 ")."
.PP
If
.I win
is a subwindow
(see \fB\%subwin\fP(3X)),
the
.B \%getparyx
macro places the coordinates of its origin relative to its parent window
into
.I y
and
.IR x ","
and
.B \-1
into both if it is not.
.SH RETURN VALUE
No return values are defined for macros.
Do not use them as the right-hand side of assignment statements.
.SH NOTES
All of these interfaces are implemented as macros.
An \*(``&\*('' operator is not necessary before the variables
.I y
and
.IR x "."
.SH PORTABILITY
These macros are described in X/Open Curses Issue\ 4.
.PP
.I \%ncurses
also provides functions
.IR \%getbegy ","
.IR \%getbegx ","
.IR \%getcury ","
.IR \%getcurx ","
.IR \%getmaxy ","
.IR \%getmaxx ","
.IR \%getpary ","
and
.I \%getparx
for compatibility with System\ V
.I curses
that were not standardized;
.\" even by SVID 4
see \fB\%curs_legacy\fP(3X).
.PP
Although X/Open Curses does not address the issue,
many implementations expose members of the
.I \%WINDOW
structure containing values corresponding to these macros.
Do not rely on their availability;
some implementations make
.I \%WINDOW
opaque
(that is,
they do not allow direct access to its members).
.PP
Besides the problem of opaque structures,
the data stored in like-named members may not have values of the same
meaning across different implementations.
For example,
the values of
.I \%WINDOW._maxx
and
.I \%WINDOW._maxy
in
.I \%ncurses
have long
.\" (at least since its initial release, 1.8.1)
differed by one from some other implementations.
The
.I \%getmaxyx
macro hides this difference.
.SH HISTORY
4BSD (1980)
introduced
.IR \%getyx "."
.PP
SVr3 (1987)
added
.I \%getbegyx
and
.IR \%getmaxyx "."
SVr3.1 later that year supplied
.IR \%getparyx "."
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_legacy\fP(3X),
\fB\%curs_opaque\fP(3X)