changeset 53183:61e2da7a49f4

(Click Events): Click object may be an images. Describe (dx . dy) element of click positions. (Accessing Events): Remove duplicate posn-timestamp. New functions posn-object and posn-object-x-y.

--- a/lispref/commands.texi	Thu Nov 27 21:53:51 2003 +0000
+++ b/lispref/commands.texi	Thu Nov 27 21:54:19 2003 +0000
@@ -1155,7 +1155,8 @@
 the marginal areas, @var{position} has this form:
 
 @example
-(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} @var{object} @var{text-pos} (@var{col} . @var{row}))
+(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
+ @var{object} @var{text-pos} (@var{col} . @var{row}) (@var{dx} . @var{dy}))
 @end example
 
 @table @asis
@@ -1179,9 +1180,11 @@
 This is the time at which the event occurred, in milliseconds.
 
 @item @var{object}
-This is the object on which the click occurred.  It is either nil (for
-a click in a marginal area with no associated object, or it has the
-form (@var{string} . @var{string-pos}).
+This is the object on which the click occurred.  It is either
+@code{nil} if there is no string property or image at the position
+clicked on, or it has the form (@var{string} . @var{string-pos}) when
+there is a string-type text property at the click position, or it is
+an image object as returned by @code{find-image} if click was in an image.
 
 @item @var{string}
 This is the string on which the click occurred, including any
@@ -1201,6 +1204,12 @@
 These are the actual coordinates of the glyph under the @var{x},
 @var{y} position, possibly padded with default character width
 glyphs if @var{x} is beyond the last glyph on the line.
+
+@item @var{dx}, @var{dy}
+These are the pixel-denominated coordinates of the click, relative to
+the top left corner of @var{object}, which is @code{(0 . 0)}.  If
+@var{object} is @code{nil}, the coordinates are relative to the top
+left corner of the character glyph clicked on.
 @end table
 
 For mouse clicks on a scroll-bar, @var{position} has this form:
@@ -1659,7 +1668,8 @@
 mouse-button event, as a list of this form:
 
 @example
-(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} @var{object} @var{text-pos} (@var{col} . @var{row}))
+(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
+ @var{object} @var{text-pos} (@var{col} . @var{row}) (@var{dx} . @var{dy}))
 @end example
 
 @defun event-start event
@@ -1688,7 +1698,7 @@
 @end defun
 
 @defun posn-area position
-Return the window area recorded in @var{position}.  It returns nil
+Return the window area recorded in @var{position}.  It returns @code{nil}
 when the event occurred in the text area of the window; otherwise, it
 is a symbol identifying the area in which the the event occurred.
 @end defun
@@ -1700,11 +1710,6 @@
 is undefined.
 @end defun
 
-@defun posn-timestamp
-Return the timestamp in @var{position}.  This is the time at which the
-event occurred, in milliseconds.
-@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})}.
@@ -1721,14 +1726,26 @@
 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
-nil if @var{position} does not include the actual positions; in that
+@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.
 @end defun
 
+@defun posn-object position
+Return the object in @var{position}, either @code{nil}, a cons
+cell @code{(@var{string} . @var{string-pos})}, or an image
+@code{(image ...)}.
+@end defun
+
+@defun posn-object-x-y position
+Return the pixel-based x and y coordinates relative to the upper left
+corner of the object in @var{position}, as a cons cell @code{(@var{dx} . @var{dy})}.
+@end defun
+
 @cindex mouse event, timestamp
 @cindex timestamp of a mouse event
-@defun posn-timestamp position
-Return the timestamp in @var{position}.
+@defun posn-timestamp
+Return the timestamp in @var{position}.  This is the time at which the
+event occurred, in milliseconds.
 @end defun
 
   These functions are useful for decoding scroll bar events.