[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master b84408647c: Improve documentation of some posn-* functions
From: |
Eli Zaretskii |
Subject: |
master b84408647c: Improve documentation of some posn-* functions |
Date: |
Sat, 26 Nov 2022 06:58:10 -0500 (EST) |
branch: master
commit b84408647c43e9eed40b16153d0a0623dfa700c3
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>
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 377b433cae..662de29d45 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 261ec512d8..4f671de918 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)
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master b84408647c: Improve documentation of some posn-* functions,
Eli Zaretskii <=