Context menus and mouse-3 [was: Changes for emacs 28]

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

Ergus> The real problem is that now the right click
Ergus> is bind to mouse-save-then-kill which I have
Ergus> never ever used, but probably others have.

and earlier:

Ergus> Sadly we have <mouse-3> bind to mouse-save-then-kill
Ergus> which I don't find useful at all, but maybe
Ergus> somebody will complain if we change it to
Ergus> C-<mouse-3> and move the panel to <mouse-3>.

I suspect that people who use a mouse but feel
that `mouse-save-then-kill' isn't useful have
never really understood what it offers.

Part of the lack of understanding may come from
not having read the manual about it.  Node `Mouse
Commands' of the Emacs manual makes the behavior
clear, and thus how useful it can be.

`mouse-3' lets you select text, delete or kill
text, and extend or reduce the selection.
That's a lot, and the actions to do those things
fit well together.

The extend-or-reduce bit works in a special way
if you've selected text by multiple clicking:
double-clicking or triple-clicking `mouse-1'.
I invite you to read the full text, if you
haven't already.  And then play with it a bit.
___

What happens if you just read the doc string?
You don't get a great idea of the richness of
`mouse-3' behavior, IMO.  It's OK, as far as a
doc string goes.  But it's unlikely to teach
someone what they can do with it.

Here's a suggestion for that doc string, and
also for the doc strings for other `mouse-*'
bindings (keys and commands): Provide a link
to that `Mouse Commands' node in the manual.
___

To me, the behavior of `mouse-save-then-kill'
is super useful.  So much so that my library
`mouse3.el' has, as a big part of its design,
to keep that behavior, while supplementing it
with `mouse-3' context menus.

You can of course optionally just get the menus.
But that's not where it's at - not the default
behavior.  The idea is to let you use the normal
behavior as many times as you like - extend,
reduce, kill, whatever - and then, if you like,
click `mouse-3' at the same place again, to pop
up a context menu.

The first part is optional, and so is the menu
popping.  Click in the same spot for the menu.
Click anywhere else for the vanilla behavior.

The other big part of the design is context
menu definition and behavior.  Those two parts
are logically independent, but it makes sense
for them to be in the same library.

There are alternative ways to define the menus,
and alternative ways to present them.  Menus can
be mode-dependent or not, dynamic (programmed)
or static.

Menus can, and generally do, differ, depending
on whether or not the region is active.  When
active, a context menu provides actions on the
region or things in it.  When inactive, it
provides actions on thing(s) located where you
click.

(There are always multiple things located at the
spot where you click.  It's up to a particular
menu to decide which things to act on.)
___

Should a context menu include _only_ items that
pertain to the region or the location clicked?
In general, no.  But you can certainly have
menus that do provide only that, if you want.

Should a context menu include global menus as
submenus, i.e., major-mode menus or menu-bar
menus?  That's up to you - an option controls
this.  If non-nil then yes: if the menu-bar is
visible then include the major-mode menus; else
include the menu-bar menus.
___

There are two alternative ways to define the
menus: (1) use keymaps and extended menu items
or (2) use the `x-poup-menu' form.  The former
is the default method.  It gives you more
control: keywords such as :visible and :enable,
for instance.  The latter is a bit simpler for
defining, perhaps.

Simple example code of using each method is
provided in `mouse3.el', with explanation.
An example of method #1 is provided for use
with Dired mode.  An example of #2 is provided
for use with Picture mode.
___

`mouse3.el' is completely compatible with the
traditional Emacs `mouse-3' behavior.  The
only place where they overlap is if you click
`mouse-3' twice at the same spot.

If you do that to delete the selected text,
then to get that effect with `mouse3.el' you
double-click instead.  Vanilla Emacs doesn't
distinguish a double-click from two clicks
separated by more than the double-click time.

(You can swap those two behaviors: slow 2-click
to delete instead of to show menu.)