21.7.4 Click Events

When the user presses a mouse button and releases it at the same location, that generates a click event. All mouse click event share the same format:

     (event-type position click-count)

event-type

This is a symbol that indicates which mouse button was used. It is one of the symbols mouse-1, mouse-2, …, where the buttons are numbered left to right.

You can also use prefixes ‘A-’, ‘C-’, ‘H-’, ‘M-’, ‘S-’ and ‘s-’ for modifiers alt, control, hyper, meta, shift and super, just as you would with function keys.

This symbol also serves as the event type of the event. Key bindings describe events by their types; thus, if there is a key binding for mouse-1, that binding would apply to all events whose event-type is mouse-1.

position

This is the position where the mouse click occurred. The actual format of position depends on what part of a window was clicked on.

For mouse click events in the text area, mode line, header line, or in the marginal areas, position has this form:

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

window

This is the window in which the click occurred.

pos-or-area

This is the buffer position of the character clicked on in the text area, or if clicked outside the text area, it is the window area in which the click occurred. It is one of the symbols mode-line, header-line, vertical-line, left-margin, right-margin, left-fringe, or right-fringe.

In one special case, pos-or-area is a list containing a symbol (one of the symbols listed above) instead of just the symbol. This happens after the imaginary prefix keys for the event are inserted into the input stream. See Key Sequence Input.

x, y

These are the pixel coordinates of the click, relative to the top left corner of window, which is (0 . 0). For the mode or header line, y does not have meaningful data. For the vertical line, x does not have meaningful data.

timestamp

This is the time at which the event occurred, in milliseconds.

object

This is the object on which the click occurred. It is either nil if there is no string property, or it has the form (string . string-pos) when there is a string-type text property at the click position.

string

This is the string on which the click occurred, including any properties.

string-pos

This is the position in the string on which the click occurred, relevant if properties at the click need to be looked up.

text-pos

For clicks on a marginal area or on a fringe, this is the buffer position of the first visible character in the corresponding line in the window. For other events, it is the current buffer position in the window.

col, row

These are the actual coordinates of the glyph under the x, y position, possibly padded with default character width glyphs if x is beyond the last glyph on the line.

image

This is the image object on which the click occurred. It is either nil if there is no image at the position clicked on, or it is an image object as returned by find-image if click was in an image.

dx, dy

These are the pixel coordinates of the click, relative to the top left corner of object, which is (0 . 0). If object is nil, the coordinates are relative to the top left corner of the character glyph clicked on.

width, height

These are the pixel width and height of object or, if this is nil, those of the character glyph clicked on.

For mouse clicks on a scroll-bar, position has this form:

          (window area (portion . whole) timestamp part)

window

This is the window whose scroll-bar was clicked on.

area

This is the scroll bar where the click occurred. It is one of the symbols vertical-scroll-bar or horizontal-scroll-bar.

portion

This is the distance of the click from the top or left end of the scroll bar.

whole

This is the length of the entire scroll bar.

timestamp

This is the time at which the event occurred, in milliseconds.

part

This is the part of the scroll-bar which was clicked on. It is one of the symbols above-handle, handle, below-handle, up, down, top, bottom, and end-scroll.

click-count

This is the number of rapid repeated presses so far of the same mouse button. See Repeat Events.