changeset 53136:fb4a34f4191c

(Click Events): Describe enhancements to event position lists, including new text-pos and (col . row) items. Mention left-fringe and right-fringe area events. (Accessing Events): New functions posn-area, posn-object, and posn-actual-col-row. Mention posn-timestamp. Mention that posn-point in non-text area still returns buffer position. Clarify posn-col-row.

--- a/lispref/commands.texi	Sun Nov 23 00:58:56 2003 +0000
+++ b/lispref/commands.texi	Sun Nov 23 00:59:23 2003 +0000
@@ -1119,27 +1119,13 @@
 @cindex mouse click event
 
 When the user presses a mouse button and releases it at the same
-location, that generates a @dfn{click} event.  Mouse click events have
-this form:
+location, that generates a @dfn{click} event.  All mouse click event
+share the same format:
 
 @example
-(@var{event-type}
- (@var{window} @var{buffer-pos} (@var{x} . @var{y})
-  @var{timestamp})
- @var{click-count})
+(@var{event-type} @var{position} @var{click-count})
 @end example
 
-or, for clicks on strings in the mode line, header line or marginal
-areas:
-
-@example
-(@var{event-type}
- (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp} (@var{string} . @var{string-pos})
- @var{click-count})
-@end example
-
-Here is what the elements normally mean:
-
 @table @asis
 @item @var{event-type}
 This is a symbol that indicates which mouse button was used.  It is
@@ -1155,53 +1141,97 @@
 @code{mouse-1}, that binding would apply to all events whose
 @var{event-type} is @code{mouse-1}.
 
-@item @var{window}
-This is the window in which the click occurred.
-
-@item @var{x}, @var{y}
-These are the pixel-denominated coordinates of the click, relative to
-the top left corner of @var{window}, which is @code{(0 . 0)}.
-
-@item @var{buffer-pos}
-This is the buffer position of the character clicked on.
-
-@item @var{timestamp}
-This is the time at which the event occurred, in milliseconds.  (Since
-this value wraps around the entire range of Emacs Lisp integers in about
-five hours, it is useful only for relating the times of nearby
-events.)
-
-@item @var{string}
-This is the string on which the click occurred, including any
-properties.
-
-@item @var{string-pos}
-This is the position in the string on which the click occurred,
-relevant if properties at the click need to be looked up.
+@item @var{position}
+This is the position where the mouse click occurred.  The actual
+format of @var{position} depends on what part of a window was clicked
+on.  The various formats are described below.
 
 @item @var{click-count}
 This is the number of rapid repeated presses so far of the same mouse
 button.  @xref{Repeat Events}.
 @end table
 
-The meanings of @var{buffer-pos}, @var{x} and @var{y} are somewhat
-different when the event location is in a special part of the screen,
-such as the mode line or a scroll bar.
-
-If the location is in a scroll bar, then @var{buffer-pos} is the symbol
-@code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair
-@code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion}
-. @var{whole})}, where @var{portion} is the distance of the click from
-the top or left end of the scroll bar, and @var{whole} is the length of
-the entire scroll bar.
-
-If the position is on a mode line, the vertical line separating
-@var{window} from its neighbor to the right, or in a marginal area,
-then @var{buffer-pos} is the symbol @code{mode-line},
-@code{header-line}, @code{vertical-line}, @code{left-margin}, or
-@code{right-margin}.  For the mode line, @var{y} does not have
-meaningful data.  For the vertical line, @var{x} does not have
-meaningful data.
+For mouse click events in the text area, mode line, header line, or in
+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}))
+@end example
+
+@table @asis
+@item @var{window}
+This is the window in which the click occurred.
+
+@item @var{pos-or-area}
+This is the buffer position of the character clicked on in the text
+area, or if clicked outside the text area, it is the window area in
+which the click occurred.  It is one of the symbols @code{mode-line},
+@code{header-line}, @code{vertical-line}, @code{left-margin},
+@code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
+
+@item @var{x}, @var{y}
+These are the pixel-denominated coordinates of the click, relative to
+the top left corner of @var{window}, which is @code{(0 . 0)}.  
+For the mode or header line, @var{y} does not have meaningful data.
+For the vertical line, @var{x} does not have meaningful data.
+
+@item @var{timestamp}
+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}).
+
+@item @var{string}
+This is the string on which the click occurred, including any
+properties.  
+
+@item @var{string-pos}
+This is the position in the string on which the click occurred,
+relevant if properties at the click need to be looked up.
+
+@item @var{text-pos}
+For clicks on a marginal area or on a fringe, this is the buffer
+position of the first visible character in the corresponding line in
+the window.  For other events, it is the current buffer position in
+the window.
+
+@item @var{col}, @var{row}
+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.
+@end table
+
+For mouse clicks on a scroll-bar, @var{position} has this form:
+
+@example
+(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
+@end example
+
+@table @asis
+@item @var{window}
+This is the window whose scroll-bar was clicked on.
+
+@item @var{area}
+This is the scroll bar where the click occurred.  It is one of the
+symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
+
+@item @var{portion}
+This is the distance of the click from the top or left end of
+the scroll bar.
+
+@item @var{whole}
+This is the length of the entire scroll bar.
+
+@item @var{timestamp}
+This is the time at which the event occurred, in milliseconds.
+
+@item @var{part}
+This is the part of the scroll-bar which was clicked on.  It is one
+of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
+@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
+@end table
 
 In one special case, @var{buffer-pos} is a list containing a symbol (one
 of the symbols listed above) instead of just the symbol.  This happens
@@ -1629,7 +1659,7 @@
 mouse-button event, as a list of this form:
 
 @example
-(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
+(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} @var{object} @var{text-pos} (@var{col} . @var{row}))
 @end example
 
 @defun event-start event
@@ -1650,15 +1680,29 @@
 @end defun
 
 @cindex mouse position list, accessing
-  These five functions take a position list as described above, and
+  These seven functions take a position list as described above, and
 return various parts of it.
 
 @defun posn-window position
 Return the window that @var{position} is in.
 @end defun
 
+@defun posn-area position
+Return the window area recorded in @var{position}.  It returns 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
+
 @defun posn-point position
-Return the buffer position in @var{position}.  This is an integer.
+Return the buffer position in @var{position}.  When the event occurred
+in the text area of the window, in a marginal area, or on a fringe,
+this is an integer specifying a buffer position.  Otherwise, the value
+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
@@ -1667,9 +1711,18 @@
 @end defun
 
 @defun posn-col-row position
-Return the row and column (in units of 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 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}.
+@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
+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
 
 @cindex mouse event, timestamp