.\"***************************************************************************
-.\" Copyright 2020,2021 Thomas E. Dickey *
+.\" Copyright 2020-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2007,2010 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getyx.3x,v 1.22 2021/12/25 21:50:36 tom Exp $
-.TH curs_getyx 3X ""
+.\" $Id: curs_getyx.3x,v 1.45 2024/05/11 20:39:53 tom Exp $
+.TH curs_getyx 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.SH NAME
-\fBgetyx\fP,
-\fBgetparyx\fP,
-\fBgetbegyx\fP,
-\fBgetmaxyx\fP \- get \fBcurses\fP cursor and window coordinates
+\fB\%getyx\fP,
+\fB\%getparyx\fP,
+\fB\%getbegyx\fP,
+\fB\%getmaxyx\fP \-
+get \fIcurses\fR cursor and window coordinates
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBvoid getyx(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fP
-.br
-\fBvoid getparyx(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fP
-.br
-\fBvoid getbegyx(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fP
-.br
-\fBvoid getmaxyx(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fP
-.br
-.SH DESCRIPTION
-The \fBgetyx\fP macro places the current cursor position of the given window in
-the two integer variables \fIy\fP and \fIx\fP.
+.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
-If \fIwin\fP is a subwindow, the \fBgetparyx\fP macro places the beginning
-coordinates of the subwindow relative to the parent window into two integer
-variables \fIy\fP and \fIx\fP.
-Otherwise, \fB\-1\fP is placed into \fIy\fP and \fIx\fP.
+\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 row 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
-Like \fBgetyx\fP, the \fBgetbegyx\fP and \fBgetmaxyx\fP macros store
-the current beginning coordinates and size of the specified window.
+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
-The return values of these macros are undefined (i.e.,
-they should not be used as the right-hand side of assignment statements).
+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 macros.
-A "\fB&\fP" is not necessary before the variables \fIy\fP and \fIx\fP.
+All of these interfaces are implemented as macros.
+An \*(``&\*('' operator is not necessary before the variables
+.I y
+and
+.IR x "."
.SH PORTABILITY
-The
-\fBgetyx\fP,
-\fBgetparyx\fP,
-\fBgetbegyx\fP and
-\fBgetmaxyx\fP
-macros are described in the XSI Curses standard, Issue 4.
+These macros are described in X/Open Curses,
+Issue 4.
.PP
-This implementation also provides functions
-\fBgetbegx\fP,
-\fBgetbegy\fP,
-\fBgetcurx\fP,
-\fBgetcury\fP,
-\fBgetmaxx\fP,
-\fBgetmaxy\fP,
-\fBgetparx\fP and
-\fBgetpary\fP
-for compatibility with older versions of curses.
+.I \%ncurses
+also provides functions
+.BR \%getbegx ","
+.BR \%getbegy ","
+.BR \%getcurx ","
+.BR \%getcury ","
+.BR \%getmaxx ","
+.BR \%getmaxy ","
+.BR \%getparx ","
+and
+.B \%getpary
+for compatibility with older versions of
+.IR curses ";"
+see \fB\%curs_legacy\fP(3X).
.PP
-Although X/Open Curses does not address this,
-many implementations provide members of the WINDOW structure
-containing values corresponding to these macros.
-For best portability, do not rely on using the data in WINDOW,
-since some implementations make WINDOW opaque (do not allow
-direct use of its members).
+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 like-values in
-different implementations.
-For example, the WINDOW._maxx and WINDOW._maxy values in ncurses
-have (at least since release 1.8.1) differed by one from some
-other implementations.
-The difference is hidden by means of the macro \fBgetmaxyx\fP.
+the data stored in like-named members may not have values of the same
+meaning different implementations.
+For example,
+the values of
+.B \%WINDOW._maxx
+and
+.B \%WINDOW._maxy
+in
+.I \%ncurses
+have long
+.\" (at least since its initial release, 1.8.1)
+differed by one from some other implementations.
+The
+.B \%getmaxyx
+macro hides this difference.
.SH SEE ALSO
-\fBcurses\fP(3X),
-\fBcurs_legacy\fP(3X),
-\fBcurs_opaque\fP(3X)
+\fB\%curses\fP(3X),
+\fB\%curs_legacy\fP(3X),
+\fB\%curs_opaque\fP(3X)
projects / ncurses.git / blobdiff