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)
- This is a symbol that indicates which mouse button was used. It is
one of the symbols
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
- This is a mouse position list specifying where the mouse click
occurred; see below for details.
- This is the number of rapid repeated presses so far of the same mouse
button. See Repeat Events.
To access the contents of a mouse position list in the
position slot of a click event, you should typically use the
functions documented in Accessing Mouse. The explicit format of
the list depends on where the click occurred. For clicks in the text
area, mode line, header line, or in the fringe or marginal areas, the
mouse position list has the form
(window pos-or-area (x . y) timestamp
object text-pos (col . row)
image (dx . dy) (width . height))
The meanings of these list elements are as follows:
- The window in which the click occurred.
- The buffer position of the character clicked on in the text area; or,
if the click was outside the text area, the window area where it
occurred. It is one of the symbols
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 registered
by Emacs. See Key Sequence Input.
- x, y
- The relative pixel coordinates of the click. For clicks in the text
area of a window, the coordinate origin
(0 . 0) is taken to be
the top left corner of the text area. See Window Sizes. For
clicks in a mode line or header line, the coordinate origin is the top
left corner of the window itself. For fringes, margins, and the
vertical border, x does not have meaningful data. For fringes
and margins, y is relative to the bottom edge of the header
line. In all cases, the x and y coordinates increase
rightward and downward respectively.
- The time at which the event occurred, as an integer number of
milliseconds since a system-dependent initial time.
nil if there is no string-type text property at the
click position, or a cons cell of the form (string
. string-pos) if there is one:
- The string which was clicked on, including any properties.
- The position in the string where the click occurred.
- 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
- col, row
- These are the actual column and row coordinate numbers of the glyph
under the x, y position. If x lies beyond the last
column of actual text on its line, col is reported by adding
fictional extra columns that have the default character width. Row 0
is taken to be the header line if the window has one, or the topmost
row of the text area otherwise. Column 0 is taken to be the leftmost
column of the text area for clicks on a window text area, or the
leftmost mode line or header line column for clicks there. For clicks
on fringes or vertical borders, these have no meaningful data. For
clicks on margins, col is measured from the left edge of the
margin area and row is measured from the top of the margin area.
- 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
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 clicks on a scroll bar, position has this form:
(window area (portion . whole) timestamp part)
- The window whose scroll bar was clicked on.
- This is the symbol
- The number of pixels from the top of the scroll bar to the click
position. On some toolkits, including GTK+, Emacs cannot extract this
data, so the value is always
- The total length, in pixels, of the scroll bar. On some toolkits,
including GTK+, Emacs cannot extract this data, so the value is always
- The time at which the event occurred, in milliseconds. On some
toolkits, including GTK+, Emacs cannot extract this data, so the value
- The part of the scroll bar on which the click occurred. It is one of
handle (the scroll bar handle),
(the area above the handle),
below-handle (the area below the
up (the up arrow at one end of the scroll bar), or
down (the down arrow at one end of the scroll bar).