Re: `posn-at-point' and `posn-at-x-y' not in manual

[David PONCE <david.ponce@wanadoo.fr>]

Richard Stallman wrote:
>     FYI, I noticed that the functions `posn-at-point' and `posn-at-x-y'
>     are not documented in the Emacs Lisp Reference Manual.
> 
> Would someone like to write text for the manual about them?
> 
> Explaining explicitly that using window-inside-pixel-edges
> is the way to turn this into frame-relative would be useful.

Hi,

Here is a text I wrote that could serve as a starting point.  I am not
sure in which file to add it.  Feel free to proof read it, and use a
better English than mine ;-)

Sincerely,
David

------------------------- [ cut here ] ------------------------------
These functions return position information similar to that returned
by @code{event-start}, from a visible position on the display.

@defun posn-at-point &optional pos window
Return position information for buffer @var{pos} in @var{window}.
@var{pos} defaults to point in @var{window}; @var{window} defaults to
the selected window.

Return @code{nil} if position is not visible in window.  Otherwise,
the return value is similar to that returned by @code{event-start} for
a mouse click at the upper left corner of the glyph corresponding to
the given buffer position:

@example
(@var{window} @var{area-or-pos} (@var{x} . @var{y}) @var{timestamp}
 @var{object} @var{text-pos} (@var{col} . @var{row})
 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
@end example

The @code{posn-} functions access elements of such lists.
@end defun

@defun posn-at-x-y x y &optional frame-or-window
Return position information for pixel coordinates @var{x} and @var{y}.
By default, @var{x} and @var{y} are relative to text area of the
selected window.  Optional third arg @var{frame_or_window}
non-@code{nil} specifies frame or window.

The return value is similar to a mouse click position:

@example
(@var{window} @var{area-or-pos} (@var{x} . @var{y}) @var{timestamp}
 @var{object} @var{text-pos} (@var{col} . @var{row})
 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
@end example

The @code{posn-} functions access elements of such lists.
@end defun

The following sample function illustrates how the function
@code{window-inside-pixel-edges} can be used to convert
window-relative coordinates, like those returned by the
@code{posn-at-} functions, 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
------------------------- [ cut here ] ------------------------------