elisp: Accessing Mouse
20.7.13 Accessing Mouse Events
------------------------------
This section describes convenient functions for accessing the data in a
mouse button or motion event. Keyboard event data can be accessed using
the same functions, but data elements that aren’t applicable to keyboard
events are zero or ‘nil’.
The following two functions return a mouse position list (
Click
Events), specifying the position of a mouse event.
-- Function: event-start event
This returns the starting position of EVENT.
If EVENT is a click or button-down event, this returns the location
of the event. If EVENT is a drag event, this returns the drag’s
starting position.
-- Function: event-end event
This returns the ending position of EVENT.
If EVENT is a drag event, this returns the position where the user
released the mouse button. If EVENT is a click or button-down
event, the value is actually the starting position, which is the
only position such events have.
-- Function: posnp object
This function returns non-‘nil’ if OBJECT is a mouse position list,
in either of the formats documented in Click Events); and
‘nil’ otherwise.
These functions take a mouse position list as argument, and return
various parts of it:
-- Function: posn-window position
Return the window that POSITION is in. If POSITION represents a
location outside the frame where the event was initiated, return
that frame instead.
-- Function: posn-area position
Return the window area recorded in 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 event occurred.
-- Function: posn-point position
Return the buffer position in 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.
-- Function: posn-x-y position
Return the pixel-based x and y coordinates in POSITION, as a cons
cell ‘(X . Y)’. These coordinates are relative to the window given
by ‘posn-window’.
This example shows how to convert the window-relative coordinates
in the text area of a window into frame-relative coordinates:
(defun frame-relative-coordinates (position)
"Return frame-relative coordinates from POSITION.
POSITION is assumed to lie in a window text area."
(let* ((x-y (posn-x-y position))
(window (posn-window position))
(edges (window-inside-pixel-edges window)))
(cons (+ (car x-y) (car edges))
(+ (cdr x-y) (cadr edges)))))
-- Function: posn-col-row position
This function returns a cons cell ‘(COL . ROW)’, containing the
estimated column and row corresponding to buffer position in
POSITION. The return value is given in units of the frame’s
default character width and default line height (including
spacing), as computed from the X and Y values corresponding to
POSITION. (So, if the actual characters have non-default sizes,
the actual row and column may differ from these computed values.)
Note that ROW is counted from the top of the text area. If the
window given by POSITION possesses a header line (Header
Lines), it is _not_ included in the ROW count.
-- Function: posn-actual-col-row position
Return the actual row and column in POSITION, as a cons cell ‘(COL
. ROW)’. The values are the actual row and column numbers in the
window given by POSITION. Click Events, for details. The
function returns ‘nil’ if POSITION does not include actual position
values; in that case ‘posn-col-row’ can be used to get approximate
values.
Note that this function doesn’t account for the visual width of
characters on display, like the number of visual columns taken by a
tab character or an image. If you need the coordinates in
canonical character units, use ‘posn-col-row’ instead.
-- Function: posn-string position
Return the string object in POSITION, either ‘nil’, or a cons cell
‘(STRING . STRING-POS)’.
-- Function: posn-image position
Return the image object in POSITION, either ‘nil’, or an image
‘(image ...)’.
-- Function: posn-object position
Return the image or string object in POSITION, either ‘nil’, an
image ‘(image ...)’, or a cons cell ‘(STRING . STRING-POS)’.
-- Function: posn-object-x-y position
Return the pixel-based x and y coordinates relative to the upper
left corner of the object in POSITION as a cons cell ‘(DX . DY)’.
If the POSITION is on buffer text, return the relative position of
the buffer-text character closest to that position.
-- Function: posn-object-width-height position
Return the pixel width and height of the object in POSITION as a
cons cell ‘(WIDTH . HEIGHT)’. If the POSITION is a buffer
position, return the size of the character at that position.
-- Function: posn-timestamp position
Return the timestamp in POSITION. This is the time at which the
event occurred, in milliseconds.
These functions compute a position list given particular buffer
position or screen position. You can access the data in this position
list with the functions described above.
-- Function: posn-at-point &optional pos window
This function returns a position list for position POS in WINDOW.
POS defaults to point in WINDOW; WINDOW defaults to the selected
window.
‘posn-at-point’ returns ‘nil’ if POS is not visible in WINDOW.
-- Function: posn-at-x-y x y &optional frame-or-window whole
This function returns position information corresponding to pixel
coordinates X and Y in a specified frame or window,
FRAME-OR-WINDOW, which defaults to the selected window. The
coordinates X and Y are relative to the frame or window used. If
WHOLE is ‘nil’, the coordinates are relative to the window text
area, otherwise they are relative to the entire window area
including scroll bars, margins and fringes.
Info Catalog
elisp: Classifying Events
elisp: Input Events
elisp: Accessing Scroll