elisp: Click Events
20.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 a “mouse position list” specifying where the mouse click
occurred; see below for details.
CLICK-COUNT
This is the number of rapid repeated presses so far of the same
mouse button. 
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:
WINDOW
The window in which the click occurred.
POS-OR-AREA
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 ‘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
registered by Emacs. 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. 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.
TIMESTAMP
The time at which the event occurred, as an integer number of
milliseconds since a system-dependent initial time.
OBJECT
Either ‘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:
STRING
The string which was clicked on, including any properties.
STRING-POS
The position in the string where the click occurred.
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 clicks on the mode line or the header line,
this is ‘nil’. For other events, it is the buffer position closest
to the click.
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.
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 clicks on a scroll bar, POSITION has this form:
(WINDOW AREA (PORTION . WHOLE) TIMESTAMP PART)
WINDOW
The window whose scroll bar was clicked on.
AREA
This is the symbol ‘vertical-scroll-bar’.
PORTION
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 ‘0’.
WHOLE
The total length, in pixels, of the scroll bar. On some toolkits,
including GTK+, Emacs cannot extract this data, so the value is
always ‘0’.
TIMESTAMP
The time at which the event occurred, in milliseconds. On some
toolkits, including GTK+, Emacs cannot extract this data, so the
value is always ‘0’.
PART
The part of the scroll bar on which the click occurred. It is one
of the symbols ‘handle’ (the scroll bar handle), ‘above-handle’
(the area above the handle), ‘below-handle’ (the area below the
handle), ‘up’ (the up arrow at one end of the scroll bar), or
‘down’ (the down arrow at one end of the scroll bar).
Info Catalog
elisp: Mouse Events
elisp: Input Events
elisp: Drag Events