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 buffer-position (x . y) timestamp)

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 five 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-point position

Return the buffer position in position. This is an integer.

Function: posn-x-y position

Return the pixel-based x and y coordinates in position, as a cons cell (x . y).

Function: posn-col-row position

Return the row and column (in units of characters) of position, as a cons cell (col . row). These are computed from the x and y values actually found in position.

Function: posn-timestamp position

Return the timestamp in position.

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.