X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_getyx.3x;h=e6ff67014864f15d27039d28ef6b264ca7cb16c6;hp=1964aba8c64ebf84bd990bceaafa633409f52b97;hb=HEAD;hpb=71c0306f0824ef2b10c4c5813fb003db48f3012e diff --git a/man/curs_getyx.3x b/man/curs_getyx.3x index 1964aba8..92b48af9 100644 --- a/man/curs_getyx.3x +++ b/man/curs_getyx.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. * +.\" 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 * .\" copy of this software and associated documentation files (the * @@ -26,81 +27,134 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getyx.3x,v 1.17 2010/07/31 16:12:01 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\fR, -\fBgetparyx\fR, -\fBgetbegyx\fR, -\fBgetmaxyx\fR \- get \fBcurses\fR 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 \fR -.sp -\fBvoid getyx(WINDOW *win, int y, int x);\fR -.br -\fBvoid getparyx(WINDOW *win, int y, int x);\fR -.br -\fBvoid getbegyx(WINDOW *win, int y, int x);\fR -.br -\fBvoid getmaxyx(WINDOW *win, int y, int x);\fR -.br -.SH DESCRIPTION -The \fBgetyx\fR macro places the current cursor position of the given window in -the two integer variables \fIy\fR and \fIx\fR. +.nf +\fB#include +.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\fR is a subwindow, the \fBgetparyx\fR macro places the beginning -coordinates of the subwindow relative to the parent window into two integer -variables \fIy\fR and \fIx\fR. -Otherwise, \fB\-1\fR is placed into \fIy\fR and \fIx\fR. +\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\fR, the \fBgetbegyx\fR and \fBgetmaxyx\fR 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&\fR" is not necessary before the variables \fIy\fR and \fIx\fR. +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\fR, -\fBgetparyx\fR, -\fBgetbegyx\fR and -\fBgetmaxyx\fR -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\fR, -\fBgetbegy\fR, -\fBgetcurx\fR, -\fBgetcury\fR, -\fBgetmaxx\fR, -\fBgetmaxy\fR, -\fBgetparx\fR and -\fBgetpary\fR -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\fR(3X), -\fBcurs_legacy\fR(3X), -\fBcurs_opaque\fR(3X) -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +\fB\%curses\fP(3X), +\fB\%curs_legacy\fP(3X), +\fB\%curs_opaque\fP(3X)