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
The following two functions return a mouse position list (see Click Events), specifying the position of a mouse 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.
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.
This function returns non-
nil if object is a mouse
position list, in the format documented in Click Events); and
These functions take a mouse position list as argument, and return various parts of it:
Return the window that position is in. If position represents a location outside the frame where the event was initiated, return that frame instead.
Return the window area recorded in position. It returns
when the event occurred in the text area of the window; otherwise, it
is a symbol identifying the area in which the event occurred.
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.
Return the pixel-based x and y coordinates in position, as a
(x . y). These coordinates are
relative to the window given by
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)))))
This function returns a cons cell
(col . row),
containing the estimated column and row corresponding to buffer
position described by 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.) If the optional window argument is
nil, use the default character width in the window
indicated by position instead of the frame. (This makes a
difference if that window is showing a buffer with a non-default
zooming level, for instance.)
Note that row is counted from the top of the text area. If the window given by position possesses a header line (see Window Header Lines) or a tab line, they are not included in the row count.
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. See Click Events, for details. The function returns
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
Return the string object described by position, either
nil (which means position describes buffer text), or a
(string . string-pos).
Return the image object in position, either
there’s no image at position), or an image spec
Return the image or string object described by position, either
nil (which means position describes buffer text), an
(image …), or a cons cell
(string . string-pos).
Return the pixel-based x and y coordinates relative to the upper left
corner of the object described by position, as a cons cell
(dx . dy). If the position describes
buffer text, return the relative coordinates of the buffer-text character
closest to that position.
Return the pixel width and height of the object described by
position, as a cons cell
(width . height).
If the position describes a buffer position, return the size of
the character at that position.
Return the timestamp in position. This is the time at which the event occurred, in milliseconds. Such a timestamp is reported relative to an arbitrary starting time that varies according to the window system in use. On the X Window System, for example, it is the number of milliseconds since the X server was started.
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.
This function returns a position list for position pos in window. pos defaults to point in window; window defaults to the selected window.
nil if pos is not visible in
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
text area of the selected window.
If whole is non-
nil, the x coordinate is relative
to the entire window area including scroll bars, margins and fringes.