elisp: Repeat Events
20.7.7 Repeat Events
--------------------
If you press the same mouse button more than once in quick succession
without moving the mouse, Emacs generates special “repeat” mouse events
for the second and subsequent presses.
The most common repeat events are “double-click” events. Emacs
generates a double-click event when you click a button twice; the event
happens when you release the button (as is normal for all click events).
The event type of a double-click event contains the prefix ‘double-’.
Thus, a double click on the second mouse button with <meta> held down
comes to the Lisp program as ‘M-double-mouse-2’. If a double-click
event has no binding, the binding of the corresponding ordinary click
event is used to execute it. Thus, you need not pay attention to the
double click feature unless you really want to.
When the user performs a double click, Emacs generates first an
ordinary click event, and then a double-click event. Therefore, you
must design the command binding of the double click event to assume that
the single-click command has already run. It must produce the desired
results of a double click, starting from the results of a single click.
This is convenient, if the meaning of a double click somehow builds
on the meaning of a single click—which is recommended user interface
design practice for double clicks.
If you click a button, then press it down again and start moving the
mouse with the button held down, then you get a “double-drag” event when
you ultimately release the button. Its event type contains
‘double-drag’ instead of just ‘drag’. If a double-drag event has no
binding, Emacs looks for an alternate binding as if the event were an
ordinary drag.
Before the double-click or double-drag event, Emacs generates a
“double-down” event when the user presses the button down for the second
time. Its event type contains ‘double-down’ instead of just ‘down’. If
a double-down event has no binding, Emacs looks for an alternate binding
as if the event were an ordinary button-down event. If it finds no
binding that way either, the double-down event is ignored.
To summarize, when you click a button and then press it again right
away, Emacs generates a down event and a click event for the first
click, a double-down event when you press the button again, and finally
either a double-click or a double-drag event.
If you click a button twice and then press it again, all in quick
succession, Emacs generates a “triple-down” event, followed by either a
“triple-click” or a “triple-drag”. The event types of these events
contain ‘triple’ instead of ‘double’. If any triple event has no
binding, Emacs uses the binding that it would use for the corresponding
double event.
If you click a button three or more times and then press it again,
the events for the presses beyond the third are all triple events.
Emacs does not have separate event types for quadruple, quintuple, etc.
events. However, you can look at the event list to find out precisely
how many times the button was pressed.
-- Function: event-click-count event
This function returns the number of consecutive button presses that
led up to EVENT. If EVENT is a double-down, double-click or
double-drag event, the value is 2. If EVENT is a triple event, the
value is 3 or greater. If EVENT is an ordinary mouse event (not a
repeat event), the value is 1.
-- User Option: double-click-fuzz
To generate repeat events, successive mouse button presses must be
at approximately the same screen position. The value of
‘double-click-fuzz’ specifies the maximum number of pixels the
mouse may be moved (horizontally or vertically) between two
successive clicks to make a double-click.
This variable is also the threshold for motion of the mouse to
count as a drag.
-- User Option: double-click-time
To generate repeat events, the number of milliseconds between
successive button presses must be less than the value of
‘double-click-time’. Setting ‘double-click-time’ to ‘nil’ disables
multi-click detection entirely. Setting it to ‘t’ removes the time
limit; Emacs then detects multi-clicks by position only.
Info Catalog
elisp: Button-Down Events
elisp: Input Events
elisp: Motion Events