Commit c5cb5297 authored by Kim F. Storm's avatar Kim F. Storm
Browse files

(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.
parent 1ce7c819
......@@ -1119,27 +1119,13 @@ binding of the key sequence.
@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})
@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})
(@var{event-type} @var{position} @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 @@ describe events by their types; thus, if there is a key binding for
@code{mouse-1}, that binding would apply to all events whose
@var{event-type} is @code{mouse-1}.
@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
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)}.
@item @var{buffer-pos}
This is the buffer position of the character clicked on.
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. (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.)
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.
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{click-count}
This is the number of rapid repeated presses so far of the same mouse
button. @xref{Repeat Events}.
@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
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 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 @@ a mouse button or motion event.
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 @@ position such events have.
@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 @@ cell @code{(@var{x} . @var{y})}.
@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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment