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-
nilif 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
nilwhen 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 cons cell
). 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
), 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.)
Note that row is counted from the top of the text area. If the window given by position possesses a header line (see Header Lines), it is not included in the row count.
Return the actual row and column in position, as a cons cell
). The values are the actual row and column numbers in the window given by position. See Click Events, for details. The function returns
nilif position does not include actual position values; in that case
posn-col-rowcan 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 cons cell
Return the image object in position, either
nil(if 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
(image ...), or a cons cell
Return the pixel-based x and y coordinates relative to the upper left corner of the object described by position, as a cons cell
). 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
). 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.
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.
nilif pos is not visible in window.
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.