21.6.13 Accessing Events

This section describes convenient functions for accessing the data in a mouse button or motion event.

These two functions return the starting or ending position of a mouse-button event, as a list of this form:

(window pos-or-area (x . y) timestamp
 object text-pos (col . row)
 image (dx . dy) (width . height))

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.

These functions take a position list as described above, and return various parts of it.

Function: posn-window position

Return the window that position is in.

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 these window-relative coordinates into frame-relative coordinates:

(defun frame-relative-coordinates (position) "Return frame-relative coordinates from POSITION." (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

Return the row and column (in units of the frame's default character height and width) of position, as a cons cell (col . row). These are computed from the x and y values actually found in position.

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 number in the window, and the actual character number in that row. It returns nil if position does not include actual positions values. You can use posn-col-row to get approximate values.

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 a buffer position, return the relative position in the character at 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.

These functions are useful for decoding scroll bar events.

Function: scroll-bar-event-ratio event

This function returns the fractional vertical position of a scroll bar event within the scroll bar. The value is a cons cell (portion . whole) containing two integers whose ratio is the fractional position.

Function: scroll-bar-scale ratio total

This function multiplies (in effect) ratio by total, rounding the result to an integer. The argument ratio is not a number, but rather a pair (num . denom)—typically a value returned by scroll-bar-event-ratio.

This function is handy for scaling a position on a scroll bar into a buffer position. Here's how to do that:

(+ (point-min) (scroll-bar-scale (posn-x-y (event-start event)) (- (point-max) (point-min))))

Recall that scroll bar events have two integers forming a ratio, in place of a pair of x and y coordinates.

Ce document a été généré par Eric Reinbold le 13 Octobre 2007 en utilisant texi2html 1.78.