# HG changeset patch # User Kim F. Storm # Date 1069549163 0 # Node ID fb4a34f4191cf9ff594ff2a0f251c5e712c5ab61 # Parent 47eb6873df1673b0b4938dccb6cfc882215ebb9c (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. diff -r 47eb6873df16 -r fb4a34f4191c lispref/commands.texi --- 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