(Accessing Events): Clarify posn-col-row and posn-actual-col-row.

(Accessing Events): New functions posn-at-point and posn-at-x-y.
Add example to posn-x-y.

1 files changed, 45 insertions, 10 deletions

diff --git a/lispref/commands.texi b/lispref/commands.texi
index 5a38179996f..44f0807ea02 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -1695,7 +1695,7 @@ position such events have.
 @end defun
 
 @cindex mouse position list, accessing
-  These seven functions take a position list as described above, and
+  These functions take a position list as described above, and
 return various parts of it.
 
 @defun posn-window position
@@ -1716,23 +1716,37 @@ is undefined.
 @end defun
 
 @defun posn-x-y position
-Return the pixel-based x and y coordinates in @var{position}, as a cons
-cell @code{(@var{x} . @var{y})}.
+Return the pixel-based x and y coordinates in @var{position}, as a
+cons cell @code{(@var{x} . @var{y})}.  These coordinates are relative
+to the window given by @code{posn-window}.
+
+This example shows how to convert these window-relative coordinates
+into frame-relative coordinates:
+
+@example
+(defun frame-relative-coordinates (position)
+  "Return frame-relative coordinates from POSITION."
+  (let* ((x-y (posn-x-y position))
+         (window (posn-window position))
+         (edges (window-inside-pixel-edges window)))
+    (cons (+ (car x-y) (car edges))
+          (+ (cdr x-y) (cadr edges)))))
+@end example
 @end defun
 
 @defun posn-col-row position
-Return the row and column (in units of frame default characters) of
-@var{position}, as a cons cell @code{(@var{col} . @var{row})}.  These
-are computed from the @var{x} and @var{y} values actually found in
-@var{position}.
+Return the row and column (in units of the frame's default character
+height and width) of @var{position}, as a cons cell @code{(@var{col} .
+@var{row})}.  These are computed from the @var{x} and @var{y} values
+actually found in @var{position}.
 @end defun
 
 @defun posn-actual-col-row position
 Return the actual row and column in @var{position}, as a cons cell
 @code{(@var{col} . @var{row})}.  The values are the actual row number
-in the window, and the actual character number in that row.  Return
-@code{nil} if @var{position} does not include the actual positions; in that
-case, @code{posn-col-row} can be used to get approximate values.
+in the window, and the actual character number in that row.  It returns
+@code{nil} if @var{position} does not include actual positions values.
+You can use @code{posn-col-row} to get approximate values.
 @end defun
 
 @defun posn-string position
@@ -1771,6 +1785,27 @@ Return the timestamp in @var{position}.  This is the time at which the
 event occurred, in milliseconds.
 @end defun
 
+  These functions compute a position list given particular buffer
+position or screen position.  You can access the data in this position
+list with the functions described above.
+
+@defun posn-at-point &optional pos window
+This function returns a position list for position @var{pos} in
+@var{window}.  @var{pos} defaults to point in @var{window};
+@var{window} defaults to the selected window.
+
+@code{posn-at-point} returns @code{nil} if @var{pos} is not visible in
+@var{window}.
+@end defun
+
+@defun posn-at-x-y x y &optional frame-or-window
+This function returns position information corresponding to pixel
+coordinates @var{x} and @var{y} in a specified frame or window,
+@var{frame-or-window}, which defaults to the selected window.
+The coordinates @var{x} and @var{y} are relative to the
+frame or window used.
+@end defun
+
   These functions are useful for decoding scroll bar events.
 
 @defun scroll-bar-event-ratio event