From b84408647c43e9eed40b16153d0a0623dfa700c3 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 26 Nov 2022 13:56:30 +0200 Subject: [PATCH] Improve documentation of some posn-* functions * lisp/subr.el (posn-object-x-y): Doc fix. * doc/lispref/commands.texi (Click Events): More accurate documentation of what are DX and DY in POSITION. --- doc/lispref/commands.texi | 12 ++++++++---- lisp/subr.el | 7 ++++--- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 377b433cae5..662de29d45a 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -1676,10 +1676,14 @@ as returned by @code{find-image} (@pxref{Defining Images}); otherwise this is @code{nil}. @item @var{dx}, @var{dy} -These are the pixel coordinates of the click, relative to the top left -corner of @var{object}, which is @code{(0 . 0)}. If @var{object} is -@code{nil}, which stands for a buffer, the coordinates are relative to -the top left corner of the character glyph clicked on. +These are the pixel offsets of the click relative to the top left +corner of the @var{object}'s glyph that is the nearest one to the +click. The relevant @var{object}s can be either a buffer, or a string, +or an image, see above. If @var{object} is @code{nil} or a string, +the coordinates are relative to the top left corner of the character +glyph clicked on. Note that the offsets are always zero on text-mode +frames, when @var{object} is @code{nil}, since each glyph there is +considered to have exactly 1x1 pixel dimensions. @item @var{width}, @var{height} If the click is on a character, either from buffer text or from diff --git a/lisp/subr.el b/lisp/subr.el index 261ec512d89..4f671de918b 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -1792,10 +1792,11 @@ and `event-end' functions." (or (posn-image position) (posn-string position))) (defsubst posn-object-x-y (position) - "Return the x and y coordinates relative to the object of POSITION. + "Return the x and y coordinates relative to the glyph of object of POSITION. The return value has the form (DX . DY), where DX and DY are -given in pixels. POSITION should be a list of the form returned -by `event-start' and `event-end'." +given in pixels, and they are relative to the top-left corner of +the clicked glyph of object at POSITION. POSITION should be a +list of the form returned by `event-start' and `event-end'." (nth 8 position)) (defsubst posn-object-width-height (position) -- 2.39.5