.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getyx.3x,v 1.42 2024/03/16 15:35:01 tom Exp $
-.TH curs_getyx 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $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
\fB#include <curses.h>
.PP
\fBvoid getyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
-\fBvoid getparyx(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
-The \fB\%getyx\fP macro places the current cursor position
-of the given window in the two integer variables \fIy\fP and \fIx\fP.
-.PP
-If \fIwin\fP is a subwindow, the \fB\%getparyx\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.
+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 \fB\%getyx\fP, the \fB\%getbegyx\fP and \fB\%getmaxyx\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 \*(``&\*('' 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
-\fB\%getyx\fP,
-\fB\%getparyx\fP,
-\fB\%getbegyx\fP and
-\fB\%getmaxyx\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
-\fB\%getbegx\fP,
-\fB\%getbegy\fP,
-\fB\%getcurx\fP,
-\fB\%getcury\fP,
-\fB\%getmaxx\fP,
-\fB\%getmaxy\fP,
-\fB\%getparx\fP and
-\fB\%getpary\fP
-for compatibility with older versions of \fIcurses\fP;
+.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 \fB\%WINDOW\fP structure
-containing values corresponding to these macros.
-For best portability, do not rely on using the data in \fB\%WINDOW\fP,
-since some implementations make \fB\%WINDOW\fP 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 \fB\%WINDOW._maxx\fP and \fB\%WINDOW._maxy\fP values
-in \fI\%ncurses\fP have
-(at least since release 1.8.1)
+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 difference is hidden by means of the macro \fB\%getmaxyx\fP.
+The
+.B \%getmaxyx
+macro hides this difference.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_legacy\fP(3X),
projects / ncurses.git / blobdiff