
		       The IREQ Mouse Library:
	      Mouse Commands and Bindings for Epoch 4.0


1. INTRODUCTION
---------------

IMOUSE is a package compatible with the standard epoch event handlers.
The mouse handler is modified slightly and the mouse button bindings
are orthogonal and simpler to remember.

Apart from the binding scheme, IMOUSE includes several new or
updated commands:

 - Multi-click support for word/line/paragraph selection like xterm
   and cmdtool

 - Emacs window resizing by modeline dragging

 - Text scrolling by dragging

 - Interface to the thing package for logical unit selection

 - Fixes undo chaining by calling undo-boundary in the mouse handler.

 - An on-line tutorial


2. AUDIENCE and COMPATIBILITY
-----------------------------

The package modifies the standard epoch mouse bindings, from release
4.0 beta 0 (this is the goal).  The standard mouse handler
(mouse::handler in mouse.el) is also modified to take care of command
chaining and undo boundaries.  Two functions in motion.el are also
modified; end-mouse-drag and extend-mouse-drag.  The first one is
modified to keep the region highlighted between mouse clicks (if the
semantics allows it), while extend-mouse-drag is entirely reworked to
support word/line/paragraph/etc. selection on multiple clicks.  To my
knowledge, these changes do not introduce incompatibilities if one
does not attempt to reload the original epoch modules (mouse.el and
motion.el).  See the INSTALL file for instructions.

IMOUSE has been tested with Epoch 4.0b0 (previous releases will not
work and are not supported, this is beta testing!), on twm and olwm
2.0, X11R5p3, on Sun3s and SPARCs running SunOS 4.1.1.  There are some
bugs that I know about but haven't had time or courage to fix.  You
can use it, experiment with it, but don't expect infallibility nor
extensive support.



3. CUSTOMIZATION
----------------

Since the buttons and modifiers are orthogonal, it is easy to
customize the mouse bindings to match those of the preferred graphic
interface standard.  A well-known difference between OpenLook and TWM,
for instance, is the default placement of the PASTE function on the
right or middle mouse button, respectively.  With imouse, one can
easily follow the TWM convention by evaluating these forms:

(setq imouse-modify mouse-right)
(setq imouse-paste mouse-middle)

Thus, three 'functions' are assigned to mouse buttons: SELECT, MODIFY,
and PASTE.  The variables controlling the assignment of the mouse
buttons are, along with their default values:

mouse-select [mouse-left]:   select an object, a word, etc.
mouse-modify [mouse-middle]: modify the selection boundaries
mouse-paste  [mouse-right]:  paste the selection

The scrolling commands are permanently assigned to LEFT, MIDDLE,
and RIGHT buttons because it does not make sense otherwise (the
skeptics are invited to experiment ;-) )


The modifiers (control, meta, and shift) are also used to group mouse
commands according to their functionality, each modifier having its own
signification.  The choices are: DELETE, THING, and WINDOW, which are
by default assigned to SHIFT, CONTROL, and META.  The modifiers are
not mutually exclusive (i.e. SHIFT+CONTROL LEFT-BUTTON makes sense)
and care was taken to ensure modularity; if CONTROL-LEFT selects a
word, then SHIFT-CONTROL-LEFT deletes that word.

The variables controlling modifier assignment are,
along with their default values:

mouse-delete-modifier [mouse-shift]:   delete selection, pointed object, etc.
mouse-thing-modifier  [mouse-control]: operate on objects (defined by thing.el)
mouse-window-modifier [mouse-meta]:    operate on emacs windows

If imouse is preloaded, or loaded in any way before the above
variables are bound, calling the function imouse-do-bindings (no
arguments) will re-bind the mouse buttons according to the new
settings.

By default, each mouse click writes the coordinates of the mouse
(column, line) in the echo area.  This can be turned off by setting
mouse-show-position to nil.

These and other options are described in the section on the X
selection and at the top of the imouse.el file, in the configuration
section.



4. UNDERSTANDING BINDINGS AND USING THE MOUSE
---------------------------------------------

This is a technical discussion, for a better way to learn how to use
imouse, try the tutorial (press Meta+Control+Shift and the RIGHT
button).

Once one understands the assignment of mouse buttons and modifier
keys, it should be fairly easy to use the IREQ mouse package.  Let's
start by a quick look at the button/key assignment (remember that the
position of SELECT, MODIFY, and PASTE can vary from one window manager
to another and so can the assignment of the DELETE, THING, and WINDOW
modifiers).  The Open Look users will recognize the standard
positioning of the PASTE function (on the right button).  Most other
users can simply interchange the last two columns.


                    SELECT                MODIFY                 PASTE
		                                                             
Normal      	set point or select   set mark or bounds   paste sel. at mouse
DELETE      	delete character      kill region          move sel. at mouse
THING       	select thing          select bigger thing  copy thing at point
DELETE+THING    kill thing            kill bigger thing    move thing at point

WINDOW      	toggle focus screen   drag scroll          menu
WINDOW+DELETE	indent                fill                 exec kbd macro
MODELINE        this window only      move modeline        split window
MODELINE+DELETE delete window         move buffer          split to buffer
            	                                                             

The following buttons cannot be reassigned:

		   LEFT                  MIDDLE               RIGHT
Scrolling:
WINDOW+THING  	line to top           line to center       line to bottom

Help:
C+S+Meta        this summary          mouse play           mouse tutorial
		                                                             

The unmodified SELECT button (usually bound to mouse-left) is special
because it also supports multiple mouse clicks (the only one to do
so); the first click sets the point, but quick successive clicks
select the current word or line.  This behavior is similar to the way
xterm and shelltool/cmdtool handle the left mouse button.  The MODIFY
function also follows the same convention; it modifies the selection
boundaries according to the current selection level (character, word,
or line).


Now that the specification is out of the way,
here are some practical observations:

1. The PASTE button always inserts some text where the mouse is clicked.

2. The DELETE modifier always deletes some text (usually from the
   current buffer).

3. The SELECT button always selects an object to be worked on.  MODIFY
   changes the extend of text to be worked on.  They never modify the
   buffer unless the DELETE key is pressed, in which case the object
   that would be selected is deleted (to the Kill Ring).

4. PASTE + DELETE is a move operation (the selected object is deleted
   from its original position and pasted where the mouse or cursor
   is).

5. Clicking on a MODELINE is associated with emacs window functions.

The following exceptions remain:

6. MODIFY scrolls the text by dragging it when modified by WINDOW.

7. PASTE calls a menu when modified by WINDOW, because the PASTE button
   is usually also the menu button.

8. WINDOW + DELETE does not follow the signification of SELECT/MODIFY/PASTE.
   Instead, the buttons call commands which are very common but not
   strictly defined in the IREQ mouse package.



5. UNCOMMON COMMANDS
--------------------

While most buttons call well-known commands, a few of them are not
common or are even original in imouse.

The thing package is a very neat one, and one of the best features of
mouse-based edition.  Simply put, a region of text is selected with a
single click, based on where the mouse is clicked and the syntax of
the current buffer.  If one clicks on a character in a word, this
entire word is selected.  If one clicks at the end of a line, the
entire line is selected.  If one clicks on a parenthesis, the entire
region from the opening parenthesis to its closing counterpart is
selected.  There are other variants, but the above three are the most
important.  Look in thing.el for more information.

Associated with thing selection is the MODIFY button; it is programmed
to recognize the nature of the last selection and to modify its
boundaries by the same units.  If a parenthesized expression is
selected, others can be added to the selection by clicking MODIFY
anywhere in another selection.  The same goes for any kind of object
selected.  Simply remember that using SELECT to select another object
sets the nature of objects that MODIFY will look for.

Further, it is possible to select an object and to subsequently select
its "enclosing" object.  In the case of a word, this may be the
sentence in which the word appears.  In the case of a variable name,
it may be the statement in which the variable appears.  For
parenthesized expressions, it may be the enclosing parentheses.  And
so on.  To try it, click THING MODIFY anywhere in succession (take
your time, it's not double-clicking) and observe how the selection
expands.  This can be thought of as "geometric expansion" as opposed
to the "linear expansion" performed by the simple MODIFY button.  The
nature of the last object selected is nevertheless recognized by
MODIFY if one wants to linearly move the selection boundaries.

IMOUSE implements the concept of scroll dragging by clicking on the
text, holding the mouse, and moving it to indicate where the text
should appear in the window.  To try it, go in a buffer large enough
not to fit entirely in the window, click WINDOW+MODIFY, hold the mouse
button down, move the mouse and release.  Dragging a modeline to
change the size of a window is just as easy.  At this moment, the
scrolling is not interactive, but it should be possible, with epoch,
to display the text while it is being scrolled.  This may be slow, and
is not on my priority list, so don't hold your breath.


6. THE X SELECTION
------------------

The imouse event handlers support copying to and from the X selection
mechanism, just as the normal epoch handlers do, but there are some
added options.  First, there are two variables controlling whether
setting the epoch region also sets the X selection and, inversely,
whether pasted text comes from the X selection.  Then, another
variable controls whether copying text to the X selection also copies
it to the kill buffer.  The three variables are:

auto-set-X-selection: when t, each time the epoch selection is made,
		      then the selected text is also copied to the X
		      selection.  When nil, the only way to set the
		      selection is to call set-X-selection.

auto-get-X-selection: when t, the PASTE button inserts the X selection
		      or the cut-buffer if the X selection does not
		      exist.  If nil, the X selection has to be
		      retrieved explicitly, by get-X-selection, and
		      the PASTE button will either insert the epoch
		      selection, if set, or yank the kill buffer.

auto-X-selection-to-killbuffer: when set, the selected text is copied
				to the kill buffer at the same time it
				is copied to the X selection.  Thus,
				the value of this variable is used
				only when the X selection is set.

The default for all three is t, which defines a behavior very close to
that of the standard epoch.

Why are these options provided?  First, I like to leave the X
selection alone; because editing is an activity a bit different from
cutting and pasting in xterm windows, it makes sense to the selection
for command-line editing, file-name pasting, etc.  This is the
rationale for setting auto-set-X-selection to nil.  Second, I have
found by experience that cutting and pasting between "terminal
emulator" windows and emacs is not as common as killing and yanking
within emacs.  Given that I did not want to use another button to
differentiate between the very common "yanking" and the less common
"copy the X selection" commands, I was forced to use a variable to let
the user decide how often she/he needed to copy the X selection into
emacs.  This is the reason for the auto-get-X-selection variable; I
find it more convenient to unset it, in order to allow quick killing
and yanking, but a user who interacts a lot with xterm may find it
more useful to keep it set.  The last variable,
auto-X-selection-to-killbuffer, is really a matter of taste; I unset
it to leave the kill buffer alone.  In short, setting all three gives
maximum coupling with the other X clients, while unsetting all three
gives maximum independence from the other clients.



7. CAVEATS
----------

Some commands are not yet implemented:

WINDOW SELECT:		toggle focus screen
WINDOW PASTE:		menu  (next on my agenda)
WINDOW+DELETE MODIFY:	fill
MODELINE+DELETE MODIFY: move buffer
Control+Shift+Meta:	mouse play (see how it's done in sky-mouse)

The X selection variables should be replaced by a mechanism that would
insert the most recent or either the X selection, the Epoch selection,
or the kill buffer.  I didn't do it because I couldn't find a way to
get the timestamp of the X selection.

The whole thing should be re-implemented on top of the sky-mouse
package; it is more flexible, complete, and portable.  I didn't have
time for that, unfortunately.


8. CREDITS
----------

To the epoch development team, of course, many thanks for a wonderful
research and test platform.

To Heinz Schmidt <hws@icsi.berkeley.edu>, for his sky-mouse package,
because the best way to learn is to observe and compare.  Some of his
ideas for mouse bindings, commands, user feedback are used in imouse.
The portability between different mouse support schemes is impressive.

To Jeff Peck, and others, for the original SunView emacstool support
functions.  Some code and ideas in imouse are derived from sun-fns.el
and sun-mouse.el.

To the UniPress Emacs old-timers (you know who you are), for
early and original ideas on mouse handling, specially for text and
modeline dragging.

Gardner Cohen <beldar@rimulac.microunity.com> hunted down the X
selection bug and proposed a temporary fix for mouse::copy-button.


9. AVAILABILITY
---------------

IMOUSE is available by ftp in

ireq-robot.hydro.qc.ca:/pub/emacs/lisp/imouse.tar.Z

You can use and distribute it according to the GNU Copyleft License.


Please send comments, bug reports and fixes to the author:

Martin Boyer                            mboyer@ireq-robot.hydro.qc.ca
Institut de recherche d'Hydro-Quebec    mboyer@ireq-robot.uucp
Varennes, QC, Canada   J3X 1S1
+1 514 652-8412
