when to bind *down-mouse* vs *mouse*?

["Drew Adams" <drew.adams@oracle.com>]

I sent this to help-gnu-emacs a few days ago, but got no response. Can
anyone here help?

--

When is it recommended to bind *down-mouse* and when is it recommended to
bind just *mouse*? If the intention is to bind a mouse _click_ event (as
opposed to a drag), then which is generally the key sequence to bind?

I haven't been able to find any recommendations on this in the Info manuals.

If you grep the Emacs Lisp sources for "down-mouse" you will find zillions
of bindings. If you search for "down-mouse" in the Elisp Info doc you will
find that it seems to be used there too, if not explicitly recommended.
Similarly, however, if you grep or Info-search for "mouse-[123]" (and
flush/ignore hits for "down-mouse").

It would seem to make sense generally to bind *mouse* instead of
*down-mouse* for a mouse-click event, but perhaps there are considerations
having to do with multi-click or drag events that confuse the issue.

Now, this I think I can understand:

 - down-mouse-1 is bound to mouse-drag-region.
 - mouse-1 is bound to mouse-set-point.

If you press mouse-1 and don't follow it by a release in the same spot, you
get mouse-drag-region. (In fact, you get mouse-drag-region when you press,
and then mouse-drag-region reads another event and calls mouse-set-point.)

However, some of the standard bindings seem contradictory to me (but I'm no
doubt missing some fundamental logic behind mouse-button bindings):

 - S-down-mouse-1 is bound to mouse-set-font.
 - M-mouse-2 is bound to mouse-yank-secondary.

So, for instance:

- If you want to override `mouse-set-font' in, say, Dired mode, you would
presumably do something like this:

 (define-key dired-mode-map [S-down-mouse-1] 'my-S-m1-cmd)

- If you want to override `mouse-yank-secondary' in Dired mode, you would
presumably do something (different) like this:

 (define-key dired-mode-map [M-mouse-2] 'my-M-m2-cmd)

- If however, you did the following (for instance), then clicking
[M-mouse-2] in Dired could presumably (depending on when you released the
mouse button): 1) open the clicked file in another frame and then 2)
`mouse-yank-secondary' into that opened file - probably not what you want.

 (define-key dired-mode-map [M-down-mouse-2]
    'dired-mouse-find-file-other-frame)

- Note that even this additional binding wouldn't help in that situation, if
you released the button after the clicked file was opened:

 (define-key dired-mode-map [M-mouse-2] 'ignore)

[This behavior is in fact what I see on Emacs 20. On Emacs 21, this problem
does not appear to arise (the `mouse-yank-secondary' does not take place) -
but I'm not sure why.]

Can someone clear this up for me? What is the recommendation? What is the
logic behind mouse bindings for click events? Are some of the standard
bindings inconsistent, or am I just missing something?

Thanks,

   Drew