GNU Info

(elisp)Accessing Events

---

Next: Strings of Events Prev: Classifying Events Up: Input Events

---

Enter node , (file) or (file)node

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.