Author: Heinz Schmidt (hws@icsi.berkeley.edu)
Copyright (C) 1990, International Computer Science Institute
THIS DOCUMENT IS PART OF FREE SOFTWARE; YOU CAN REDISTRIBUTE IT AND/OR
MODIFY IT UNDER THE TERMS OF THE GNU EMACS GENERAL PUBLIC LICENSE.  FOR MORE
DETAILS CF THE END OF THIS DOCUMENT.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You are looking at the MOUSE-TUTORIAL. 
The characters ">>" at the left margin indicate directions for you to try
using a command. When you are starting an exercise, make sure you have the
full exercise in view.


This text assumes you are familiar with the notions 'point', 'mark', 'region,
'kill-ring', 'save', 'kill', 'yank'. If you are not, you may wish to consult
the Emacs tutorial now or later on when you feel you are missing something.
You can do so at any time while reading this by entering C-h t.  The tutorial
will also tell you that you can come back here by C-x b RET and that you can
end the dialog by C-x C-c. To be honest, this additional mouse tutorial is,
basically, the wrong approach. Why should you start learning the cursor
movements in the first place when there is a mouse to point to a place in your
text. Ideally we would like to have a new Emacs Tutorial that tells about key
sequences and mice in the same context. But which good soul in this universe is
going to write it?

Speaking in key abbreviations, like C-x b RET, Emacs commands generally involve
the CONTROL key (sometimes labeled CTRL or CTL) or the META key (sometimes
labeled EDIT).  Rather than write out META or CONTROL each time we want you to
prefix a character, we'll use the following abbreviations:

 C-<char>  means hold the CONTROL key while typing the character <char>
	  Thus, C-f would be: hold the CONTROL key and type f.
 M-<char>  means hold the META or EDIT key down while typing <char>.
	  If there is no META or EDIT key, type <ESC>, release it,
	  then type the character <char>.  "<ESC>" stands for the
	  key labeled "ALT" or "ESC".

These abbreviations include mouse buttons. We assume that you have a 3-button
mouse and we refer to the buttons by abbreviations such as

 C-Left, M-Right, C-M-Right-Up, S-Left-Down

where the new prefix S means shift and sometimes up and down are explicitly
distinguishing whether you just press or release a mouse button. Unless you
have a special event registration with your window manager, these 'button
transitions', like key sequences, can trigger any command that edits your text
in a more or less complex way. And, yes, any combination of modifier keys can
be used with the mouse (including apparently insane combinations like
C-M-S-<button>, insane at least on some keyboards and for some people).


			     POINTING AND MARKING
			     --------------------

>> Let's start. Try this: move the mouse over this (*) asterisk and click.
   And this: point to this (*) asterisk and now drag the mouse to this one (*).

Did you use Left? I did, before I realized that it is not explicitly required.
Left means Select in most window systems and is usually guaranteed to be
without side-effect. A click means you press and release the button and we simply
refer to the above click as 'Left' rather than 'Left-Down Left-Up'.  Usually we
will not deal with Up and Down transitions of a button explicitly.  We will
speak of clicks and drags instead. For instance 'Drag Left' is short for
Left-Down, Move the mouse, Left-Up. As important as this simplification turns
out to be, sometimes it is an over-simplification and there will be situations
when you have to face the two independent transitions in one semantic action.
(A well-known example is the change of a modifier key during a Drag to mean
constraining the mouse to horizontal or vertical movement. For instance in
describing a sequence like Left-Down, Drag, S-Drag, S-Left-Up we have separated
the two transitions.)

>> Now click S-Left multiple times on each item. S-Left is mark-thing:

   in the middle of this *WORD*,

   on a hyphen in this *MULTI-WORD-SYMBOL*,

   to the right of this line,

   to the left of this line,

   on any of the following parentheses

         (many programming
	   (languages rely on
	      { strange syntax }
            few [editors] know to derive charm
	  from it)))

In each case a different entity is marked, a word, a symbol, white space, a
line, an expression. (The parentheses above are deliberately unbalanced.)
Emacs knows about syntax (cf. modes and syntax in the Emacs documentation) and
what the S-Left (mark-thing) command selects can be customized.  If this does
not work as described, check your setting of the variable thing-boundary-alist.
You will learn to appreciate thing.el when you use Emacs' programming language
modes, including modes like TeX mode.
 
That was S-Left or S-Select if you wish. It is easy to recall: 

			   Shift constrains Select.

In this case the constraint is syntax.

The selected region is marked under Epoch, usually by underlining the full
region or displaying it in reverse video depending on your choice. If you are
running x-mouse, selection feedback is provided by letting the cursor jump away
from the mouse to the other end of the region for a short period of time.

You may also select a region free-hand, i.e. independently of the current syntax
and mode as you did above in the Drag exercise. 

The next paragraph is generic, there are different standards for different
window systems. Openwindows (olwm) tries to comply with the Openlook standard
in that Middle is the Extend/Adjust key. Under non-olwm systems like twm this
uses to be the Right button. We will simply refer to the button as the Extend
button to simplify the discourse. The third button (Right under olwm, Middle
else) is the Paste button and serves to move text between different
applications.

>> Try again: Drag Left from here (*) to here (*) and now Drag Extend to (*)
   here.

Recall, Drag means you press a button, move the mouse and then release the
button. Perhaps you noticed that an extension can start anywhere on the screen.
Point will simply move to the mouse and the regions join appropriately. You may
also Click Extend, this is often easier to control and less tiring for the fingers. 

>> Try it right here, Drag Left to select the first two asterisks in the
   above exercise.
   Now Click Extend here: (*).

When you mark a piece of text with the mouse, it is always the current region.
That is it is delimited by Mark and Point. Usually it is the Point which
follows the mouse just like it is the Point that follows forward and backward
commands issued from the keyboard.


				SAVE/KILL/YANK
				--------------

Once you have marked a region you can apply to it all the region commands that
you know already (cf. the Emacs Tutorial if necessary).  You may try it right
here.  (We are going to modify this text, make sure this is not read-only and
you understand how to avoid to write back a damaged text. If the mode-line
shows the read-only flag %%, you may enter M-x toggle-read-only or simply C-x
C-q.  For undoing major changes with this file you may, for instance,  do M-x
revert-buffer from time to time and confirm Emacs in really forgetting all the
changes you made when the editor prompts for confirmation.)

>> Now ... try this: Drag Left from here (*) to here (*). Then press C-w. Then Click
   S-Left to mark the  following symbol [*some-symbol*]. You recall perhaps
   that you may have to click to '-' to select the symbol. Have you got the
   symbol now?  Then go ahead and press C-w to kill the region. Now click Left
   to the hole () above where the first region disappeared and yank it back
   using C-y M-y (yank, yank-pop). Then make the second region appear here
   after the colon: 
   by pointing to the blank that follows it (Click Left) and pressing C-y and
   M-y that many times you may need to get back the text '*some-symbol*'.

Done?  Because you may have killed text in another document before you started
to read this document there might have been any number of entries in the
kill-ring (including 0 if you just started Emacs on this document and only 
followed the instructions).  And the simple exercise happens to make sure that 
you have to cycle through the whole kill-ring -- unless you know advanced ways
to position to entries in the kill-ring.

You may have noticed how ineffective it is to move your mouse hand forth and
back between mouse and keyboard in a situation like the above. And such
situations occur frequently. Rather than parking the mouse it is more helpful
to allow the user to forget the keyboard for some time that mainly involves
selections, copies and similar mouse interaction. For this reason, there is a
well-known mouse command that we call mouse-save-kill-yank. It descends from a
long line of Emacs extensions at MIT (EINE = Eine Is Not Emacs, ZWEI = Zwei Was
Eine Initially, Zmacs =?= Zetalisp Emacs based on Zwei). To feel the difference
let's use it in the above situation:

>> Try this: Drag Left from here (*) to here (*). Now Click S-Middle and
   watch the Minibuffer. It should provide the feedback 'Saved.' Click S-Middle
   again. The Minibuffer correctly tells 'Killed.' once the marked text is
   'swallowed by the mouse', i.e. disappears to the kill-ring.  Now Click
   S-Left to mark the symbol [*some-symbol*] . (This time you got it right the
   first time, right?) Again Click S-Middle twice to kill the region. Now click
   Left to the hole () to define the target for yanking and Click S-Middle to
   yank back ... the wrong text..., once again to exchange it with the right text.
   Similarly proceed to fill the other hole again. Position by Click Left. Yank
   and yank-pop by repeated S-Middle until you get back the right 'kill'.

If you were searching several times for the Shift key, this was unnecessary
because it was the only modifier involved. You only need to release it for
positioning and press it for marking things or save/kill/yank them.

As you noticed correctly, the first S-Left Click only saves the region.  You
can then immediately position Point someplace else and yank the saved text to
that point. If you like you may try it anywhere on this text now, but I think
it's clear without exercise.  (Maybe this is a point where you want to do a
revert-buffer).

Once you have saved a region, but also whenever you have marked a region with
the mouse, it is automatically stored in the X cut buffer and you can also
transfer it to a window owned by another process. Pasting some piece of text
that you get from another process' window is supported by the command
mouse-paste-cut-buffer.


				  MOUSE HELP
				  ----------

This is a good point for a short summary of what we have so far. Here is a
table of the most commonly used mouse commands and their default installation.

Mod	Left 			Middle			Right
	
--	Select			Extend			Paste	  	olwm
--	Select			Paste			Extend		twm

S	Mark Thing		Save/Kill/Yank		

All relate to selection, copy, cut and paste. But unlike other editors, the
Emacs mouse selects in a syntax dependent way and exploits two central concepts
of Emacs, the region and the kill-ring.

These are already enough functions that you may want to get help on them from
time to time. You may wonder where-is Save/Kill/Yank?, what was S-Left? or 
can I get more info on Extend?


>> Try this: Type C-h z while watching the Minibuffer.


The Minibuffer says something like: Play Mouse. (Type RET to exit.)
If it does not, try M-x help-with-mouse, instead.

>> Continue by pressing Left ... then release after some while.


The Minibuffer gives a brief description of the key transition and recalls how
you can exit. A temporary *Help* window describes the command installed on the
button transition. Actually you would get the same output by describe-function
(C-h d). The mouse is small enough to play through the number of relevant
combinations of modifiers and buttons. 


				YANK TO POINT
				-------------

You may continue for a while to poke around with mouse buttons. Then type RET
to continue with this exercise.

Another mouse technique is called mouse-yank-to-point. 


>> Try this: place the cursor here after the following colon
   by Click Left: 


   Now click to the word, the-symbol, and smaller or larger expressions, or behind 
   a line multiple times by Click Meta-Middle:

   ((alpha beta gamma) {(int)foo(bar)}

   copy-me-by-clicking-behind-me

   copy-me-too

Maybe Meta-Middle does not work because you have told your window manager to
filter various Meta clicks? Then maybe C-M-Middle works for you instead. We 
found that in Lisp and C mode C-M-Left for marking and C-M-Middle for yanking
comes to mind often due to the frequent use of expression-related commands like
C-M-f, C-M-b, or C-M-q and C-M-k and have provided it, but still want the single 
modifier combination.

Yanking also works across screens. For this purpose open a new screen by typing
C-z 2 and move the second screen such that the two screens do not cover each
other too much. Select another file, dummy say in the other screen and 
fill in some kills by  pointing and yanking (Click Left, S-Middle, Left,
S-Middle) or by pasting some piece of this buffer over there. Avoid working
on this buffer in the other screen, because you might get confused if you change 
this very exercise accidentally. 

>> Now fix the focus on the second screen by clicking M-Left. Move the
   mouse back to this screen, yank some of the above exercise over to the
   other screen in quick succession by clicking M-Middle several times at
   different places. Finally click M-Right to warp the mouse to the focus
   and release the focus with M-Left (mouse-toggle-focus-screen).

The Meta sequence, focus-to-point, yank-to-point need not end with
warp-to-point. You may also click M-Left (mouse-toggle-focus-screen) to another
screen to shift the focus, but it will stay fixed until you click to the
current focus screen a second time.


			   'OTHER' MOUSE FUNCTIONS
			   -----------------------

The remainder describes mouse commands that are useful and nice, actually we
can use them a lot. But to some extent the choice is random and the purpose is
to demonstrate extremes of defining a 'semantic mouse'. For that reason you
might want to reconsider the button placement of these commands. We come back
to that point later.  Let us first see what the commands do.  Below we define a
keyboard macro that changes the form of some function arguments (we use Lisp
here but macros could be used in a similar way with any programming language).
The macro we are going to define will translate calls as follows

		     (foo X Y Z) => (foo (bar X baz) Y Z)

We assume that not all foo calls are to be translated this way and that we 
have to search and select them on a one-by-one basis anyway. As usual
we define the macro by just telling Emacs to watch how we do it. Recall
that C-( is C-S-9 and C-) is C-S-0. 

>> First make sure you get the full exercise in view by:
   Click Left to the three asterisks below and type C-l. Now Click Left
   to the symbol foo in the next line:

       (foo X Y Z)

   Now type (we explain later, but note: comma in between separates key
   strokes, and as you go along it may be a good idea to move the mouse to the
   end of what you have typed so far from time to time, or just stop at the
   marks in the subsequent line to watch what you have done so far at Point.

	C-x,C-(,C-M-f,C-M-f,C-M-b,(,b,a,r,SPACE,C-M-f,SPACE,b,a,z,),C-x,C-)
	       |                 |             |     |             |
                                     *** 
   In you mistyped something, type C-G and restart, or if you are familiar
   with kbd macros, simply define your own macro that does something local on 
   the expression above.
   Now the transformed expression sits in the place of the original 
   expression (foo X Y Z) in the line containing Point and the minibuffer 
   displays "Keyboard macro defined."
	
   Now Click M-S-Left to the symbol foo in the first, third and fourth
   line below:

   1  	(assq kwd (foo x y z))
   2    (foo (a b) (c d e) f)
   3       (cond ((foo (foo x y z) bar baz) 
   4    (defvar *my-var* '((foo (b a a) c f) 
   5    (foo (b a a) c f)

M-S-Left is mouse-execute-kbd-macro. Actually the last macro is executed if
any. And you could have achieved the same effect by pointing to the respective
foo occurrences and invoking call-last-kbd-macro (C-x e) at that point.
	 
For the following exercise you should move temporarily into Lisp Mode.  We want
to exercise mouse-fill-or-indent. Rather than having different mode-dependent
mouse commands and a complex logic of exchanging mouse commands when modes and
buffers are switched, this one command behaves differently in different modes.
Actually it just distinguishes two kinds of modes. Text and mail mode are
assumed to be free text while anything else is assumed to be programming
language mode and to have some form of indentation restrictions.

>> Try this: Get the full exercise in view and Type M-x lisp-mode.
   Now Click C-M-Right to the first parenthesis of the line marked with (***).
   Then try this: Click C-M-Right to the parenthesis preceding 'defun'.

(defun mouse-kill-to-point (arg &rest ignore)
  "Kills the region from current point to mouse. The killed text is 
also saved in the X cut buffer to be yanked to other application."
  (interactive "d")
                                     (let ((from (point)))           ;; ***
                                                     (mouse-set-point arg)   
                                            (store-cut-buffer from (point))
                                (kill-region from (point))
    ))

>> (<< intentionally left blank)


Mouse-fill-or-indent has a simple logic to figure whether it is on a piece of
program text and should do indent. You may later see the documentation that you
get with C-h z. Right now see how you can use the same button to fill comment.

>> Try this: Drag C-M-Right starting at the comment beginning and
    marking the comment lines to the end.
  
;;; Given a region, throw a series of save/kill/yank requests to a buffer.
;;; The first one saves, the next kills, the next yanks 
;;; and subsequent ones
;;; yank then yank back the kill (if this was
;;; not what what you wanted), subsequent ones yank-pop.
;;; Any other region related commands 
;;; reset the machine, i.e. leave the buffer
;;; region-less, so that the next s/k/y request can yank the top of the 
;;; kill ring. Usually the saved region. 
;;; Yank-to-point additionally allows to fix the insertion point and stream 
;;; into it a series of kills from different sources (like the procedure calls
;;; and body templates when procedures are composed).
;;; Since this logic is target oriented (the target point is fixed)
;;; and the visual marking provides a clear feedback, the logic
;;; nicely complements the cut buffer button logic of Epoch which
;;; is source oriented (the source point is fixed). If the keys are
;;; kept somewhat independent one gets quickly used to it without
;;; much danger of confusion and starts to like the fast way 
;;; things can changed reliably. 

>> (<< intentionally left blank)


The text should be filled floating around the comment characters. For the other
applications of this mouse command simply look at the documentation using help
mouse (C-h z).

Let us finish with a short remark on the last two commands and a hint to other
related documentation.

The last two commands, mouse-execute-kbd-macro and mouse-fill-or-indent, are
maybe considered too generic or too special-purpose to deserve a fixed mouse
installation.  For both commands we might argue that they do not need to have a
permanent place on the mouse. For instance the first one,
mouse-execute-kbd-macro, allows you to use the mouse to throw the last kbd-macro
repeatedly at a certain point. This feature could be generalized to a concept of
a 'Temporary Mouse Command' including the possibility of throwing the last
command, whatever it was to the buffer at some point, or the default command
whatever you have chosen to be your default command. In any event, there are not
sufficiently many mouse buttons to allow you to place all these various
possibilities on the mouse. For that reason, it would be wiser to just have a
'Temporary Command' button and have it pop up a a menu that lets you select one
of the actions having this 'temporary' character.

While mouse-execute-kbd-command has a temporary, and therefore somewhat
unspecific character (its semantics changes with every macro),
mouse-fill-or-indent has a fixed meaning but is somewhat over-specialized. For
that matter, you may have many specialized commands that would equally deserve
to be installed on the mouse. Again we may argue, it would be wiser to install
the 'Region Commands' command on the mouse instead and have it pop up a, perhaps
mode-dependent, menu from which you could then select. My feeling is that the
additional selection is less cumbersome than moving the hands from the mouse to
the keyboard. Thus the 'Mouse-region-commands' would just be an alternative for
keyboard invocation of very common region commands when you happen to have the
hands on the mouse.


			     MOUSE SCROLLING MODE
			     --------------------

There is a minor mouse scrolling mode that can be toggled into and out of
using C-Right. Here is a short overview of the mouse functions in this mode.


      |           Left              Middle             Right
----------------------------------------------------------------------
      |
  -   |        Line to top        Drag Scroll     Line to bottom
      |
  S   |          Page up          Page percent       Page down
      |
  M   |          All up              Help            All down
      |          
 M-S  |           Help               Help              Help
      |
  C   |       End scrolling     End scrolling     End scrolling
      |


The commands `Line to top' and `Line to bottom' push away the line you point
to so that the line ends up at the top or bottom of the window, respectively.
With `Drag Scroll' you drag a line along with the mouse. When you release the
button, scrolling will take effect.

`Page up' and `Page Down' scroll one page up and down, just like vertical
scrolling commands C-v and M-v.

`Page percent' scrolls to a line whose position in the whole buffer is like
the position of the line you click to relative to the current window.  For
instance, if you click to the top line, you will end up at the top of the
buffer. If you click to 1/3 of the current window from top you will end up 1/3
in between the top and the bottom of the entire buffer.  Calculation are done
in lines rather than characters.

`All up' and `All down' scroll to the buffer top and bottom, respectively.

You may try it right here, recall that C-Right will also bring you back
from this scrolling excursion to the normal mouse mode.


				 MULTIPLE CLICKS
                                 ---------------

Under Epoch, multi-click processing is supported. Actually the underlying model
is Multi-click hints. These allow mouse commands to `extend their meaning'
depending on the number of clicks that invoked them. 

For instance, the command mark-thing takes advantage of multi-click hints as
follows

	Click to	Multi-click-hint	Selection

        word                 nil                   word
        symbol               nil                  symbol

	word/symbol           2                   symbol
	word/symbol	      3                   line
	word/symbol           4                   sentence
        word/symbol           5                   paragraph

	paren                nil                  group
	paren                n=2,3,..          outward n levels


The current implementation is limited because timeouts and event times are not
visible to Emacs Lisp. This can lead to confusion when the machine is busy
between the physical mouse click and the arrival of the event in the mouse
handler or when commands are executed that move the object under the move away,
for instance by inserting into the same window before that object.  (Cf. more
on this in the Section about mouse programming and multi-click hints below).


			     CUSTOMIZING THE MOUSE
			     ---------------------

MOUSE RELATED VARIABLES: 

Multi-click processing is controlled by two user variables:

  multi-click-timeout is measured in micro-seconds, the default value is 400.
  multi-click-outspace is measured in pixels, the default value is 2.

Two clicks are considered parts of the same multi-click sequence if their
temporal and spatial distance is less or equal these values, respectively.


THING SYNTAX: 

thing-boundary-alist -- pairs  (char-syntax function-to-call)
thing-multi-click-boundary-alist -- sequences (char-syntax fn1 fn2 ...)


MOUSE BUTTON BINDINGS:

The major way to customize the mouse is to bind mouse commands to mouse
buttons.  Emacs has special command tables called mouse maps for this purpose.
Each buffer can have an independent mouse map. The sky-mouse package extends
the x-mouse mouse handling to support buffer-local mouse maps like Epoch does.
To keep some independence of the underlying host mouse system, sky-mouse
provides an abstraction in terms of the functions

create-mouse-map
mouse-local-map
mouse-use-local-map
defmouse.

The command mouse-define provides an interactive version of defmouse, in which
the mouse is used to select a button to install functions interactively
selected by the user.

For a detailed description of these functions cf. their online documentation.
Here only a few examples to sketch the functionality of defmouse and therefore
mouse-define:

 (defmouse ':global  "C-Middle" 'mouse-extend-drag-point 'mouse-kill-region
     mouse-kills-glyph)

Defmouse supports the association of commands to clicks. A selection method
(here: mouse-extend-drag-point) is installed on the button down transition and
an operation on the selected region is installed on the up transition (here:
mouse-kill-region). While dragging (button down), the selection and hence the
subsequent operation can be aborted by dragging the mouse out of the window and
releasing the button outside. Moreover the dragging gesture documents the
planned operation (here: mouse-kill-region) by providing feedback via a
specific mouse cursor glyph (here: mouse-kills-glyph).  This feedback is
ignored under plain Emacs.

The first argument ':global, ':local or a mouse map tells defmouse where to
install the button binding. Note that a mouse map is associated to a buffer.
It will be in effect under all windows that view into the buffer!

Here is another example from scroll-mouse, a minor mode in which the mouse is
used to browse some file:

(defmouse mouse-scroll-map "S-Left" 
  'mouse-ignore
  '(lambda (arg) "Next page." (message "Page up.") (scroll-up))
   v-scroll-up-glyph)

For a list and description of mouse commands cf. C-h d mouse- M-TAB 
or glance through the file sky-mouse.el.



			    WRITING MOUSE COMMANDS
			    ----------------------

We distinguish `click-type', `drag-type', `cue-type', and `mode-type' commands.

The simplest kind of commands are click-type and drag-type commands, in which
the down-transition function and the optional drag selects the object on which
the up-transition function operates. While drag-type commands pull an object or
the whole buffer around, cue-type commands are typically pushing an object.
Like the drag method which is the down part of a drag-type command, the
cue-type command is installed on a down-transition for the immediate pushing
feel and visible effect. The up-transition of a cue-type command usually does
not have any effect other than maybe cleanup.  Finally there are mode-type
commands in which the down transition or the entire click changes the way the
mouse works. The different mode may last just for the next up-transition or for
a series of mouse operations.

Mouse commands are called with one argument, a list containing the necessary
information about the current button. This list is different for Epoch and
Emacs x-mouse. Sky-mouse just follows the basic handler conventions of the
underlying system. Usually it is not necessary to make runtime decisions to
figure out under which package a command is running. But if this happens to be
necessary, the boolean variables running-epoch and running-x-mouse can be
read.  Rather than using runtime decisions we prefer to hide the differences in
functionality in a set of basic functions provided by x-mouse-base.el and
epoch-mouse-base.el respectively.


CLICK-TYPE AND DRAG-TYPE MOUSE COMMANDS:

A single click-type command is mouse-execute-kbd-macro, a multiple click-type
command is mouse-extend-drag-point. mouse-drag-point or scroll-point-to-mouse
are examples of drag-type commands. mouse-extend-drag-point sets the point and
an optional region by a first click (down and up transition). Then a second
click extends the region.  The drag-type commands start a drag with the down
transition and completes it with the up transition.  The following selection
methods can be used with these types of commands:

Down selection                      Up command works 

mouse-set-point                     from point -- region is empty
mouse-drag-point                    on region defined by freehand drag
mouse-extend-drag-point             an extension of previous region
mouse-drag-and-drop                 from point to perhaps in other buffer
mouse-mark-thing                    a region defined by the language syntax

You may easily extend these methods by building on them. Note that each of the
above saves the current situation (mark,point,buffer etc.) so that programmers
can achieve a similar effect as save-excursion does in this event-driven
programming paradigm. The immediately following up-command finds the saved
situation in the variable mouse-save-excursion-info (cf. the variable doc for
more info.)

Dragging is only possible after mouse-drag-point and mouse-extend-drag-point.
And in this case the down-command must start with a call to
mouse-end-drag-point to complete the dragging interaction. It is a good idea to
make the up-command interactive, so one can use a complex command on
non-mouse interfaces by first selecting a region and then invoking the command
via a keystroke and/or with interactive prompting.


CUE-TYPE MOUSE COMMANDS: 

mouse-mark-thing and mouse-yank-thing-to-point are cue-type command. Typically
a cue-type command has an immediate effect on the button-down transition and
the up transition is bound to mouse-ignore or some cleanup operation. A
cue-type command body thus combines an appropriate selection AND the command
proper.


MODE-TYPE MOUSE COMMANDS:

The down-transition of a mode-type command toggles into the new mouse mode.

mouse-scroll-mode is an example for such a kind of command. It is a mode that
lasts for an arbitrary number of clicks. A mouse mode changes the mouse map
and/or the mouse handler. mouse-scroll-mode for instance, changes to a
mouse-scroll command map. A number of buttons allow to toggle off the mode
later.

For a temporary mode-change the down-command toggles into the mode and sees to
making the up transition toggle out of the mode. In general it is undesirable
to end all mode dependent commands in mode toggling calls. Rather the BUTTON
HANDLER is customized. The standard sky-mouse button handler has a hook that
is executed after handling the button event proper (cf. Section `Handler Hook'
below).


			      MODE DEPENDENT MICE
			      -------------------

There are a few common ways to mock up an Emacs mode to use the mouse.  All of
these are based on associating mouse maps to a buffer using buffer-local
variables. 

1. MINOR MOUSE MODE:

A minor mode is added allowing the user to switch explicitly to/from a
different mouse table. For a detailed example see scroll-mouse.el.  The local
mouse map is created by

        (create-mouse-map)                      ; creates an undefined map

or by   (create-mouse-map m)                    ; creates a map copying from m

Then    (mouse-use-local-map such-and-such-mouse-map)

toggles into the use of the new map. Actually a buffer-local variable

   mouse::local-map

is set to the new map. mouse-use-local-map works under Epoch and plain Emacs.
However, Emacs x-mouse does not actually support buffer-local mouse maps. It
will modify the system mouse map according to the value of mouse::local-map.
You best save the active mouse map once you have defined it

   (setq saved-mouse-map (mouse-local-map))

and restore it by

   (mouse-use-local-map saved-mouse-map)

when you need to. mouse-use-local-map deinstalls the local mouse map properly,
if saved-mouse-map is nil.


2. MODE HOOK:

A mode hook is used to associate a local mouse map to the mode.  The mode hook
makes sure the `right' mode-specific mouse map will be used initially or later
when you select a specific mode. Under Emacs this works under the restrictions
sketched above. The local mouse map is created and put into effect as described
under 1.

The usual hook programming pattern looks like this:

(push 'my-hook such-and-such-mode-hook)
(defun my-hook ()
    ;; this runs but does not work as expected under plain emacs
    (mouse-use-local-map such-and-such-mouse-map))


				   FEEDBACK
				   --------

Feedback hints can be provided with a defmouse call. Currently feedback hints
specify cursor glyphs that are shown while the button is pressed. This works
only under Epoch. Moreover, under Epoch mouse-drag-point and mouse-extend-drag-point
underline or reverse-video the current selection while the user is dragging,
depending on the chosen drag-button style.

For a click-type or drag-type command the cursor feedback it is meant to
indicate what the command proper is going to do. For `busy' feedback (watch)
use the macro with-busy-feedback in the body of the command proper.


			       MULTI-CLICK HINTS
			       -----------------

The mouse handlers of the sky-mouse package give multi-click hints only. 
This means commands figure in which situation they are invoked. The number of
clicks is not an independent dimension for dispatching from events to commands.

The current implementation of multi-cliks (sky-mouse-1-1) is limited.
Multi-click sequences are not integrated. Each click in a click-sequence is
handled separately. The value of multi-click-hint, if non-nil, is a number
telling which click of a multi-click series the current click is.

On the one hand, mouse programming with multi-click hints tends to give rise
to semantically coherent interpretations of multi-clicks. This is because one
command is usually thought of as a series of extensions of one basic command.
Moreover multi-click hints do not require more complex command tables in
which the number of clicks is an independent dimension.

On the other hand, our implementation is limited because Epoch does not (yet)
allow access to the true event information, in particular the time of an
event and whether or not new button events have arrived.  This can be
confusing because the time-stamps can only be taken when the events are
received and may not represent the correct times of device events if the
system is busy.  If this is more often a problem than not, we recommend to
set multi-click-timeout to 0, which means to treat all clicks as single
clicks.

Another source for confusion for the user are side-effects. If the single-click
version of a command has a side-effect, sometimes it may be necessary to undo
it in the extended version. For instance in the above multi-click
interpretation of mark-thing, the command yank-thing-to-point which calls
mark-thing becomes a multi-click command. When called another time it has
already yanked some thing. Moreover, if this yank was into the window from
which the user is yanking, scrolling may occur in the middle of a multi-click
sequence. It can cause headaches when a large piece of text has been yanked in
the wrong place.  Luckily there is manual undo.

It seems the side-effect story above points to the limitations of multi-click
hints without timeouts. Without timeouts, a multi-click sequence would be
`compressed' to a single click event. In multi-click hint implementation the
hint would be given and the command called, avoiding unnecessary multiple
calls of the same command.


				 HANDLER HOOK
				 ------------

Two optional hook functions allow to pass control to user programs
after button event processing:

mouse-handler-down-hook  -- is called after processing down events
mouse-handler-up-hook    -- is called after processing up events.

These hooks are called by the default sky-mouse handlers.  
(Under Epoch all handlers exhibit this behavior, if they are defined by means
of the handler definition macro with-button-handler-info. Cf. the online
documentation of with-button-handler-info for more info on this macro.)

A common use of mouse hooks is to do general cleanup operations or to collect
some statistics about mouse handling. Mode-type commands can use the hooks to
toggle out of a temporary mouse mode by means of the following programming
pattern:

down command ends with:       (setq mouse-handler-up-hook 'toggle-outof-tmp-mode)
toggle-outof-tmp-mode looks like:
  (defun toggle-outof-tmp-mode (arg)
	(unwind-protect
	     <what it means to toggle out of tmp mode>
	  (setq mouse-handler-up-hook nil)))


			       MORE INFORMATION
			       ----------------

Where do you find more information?

First of all there is a README file listing which files contain what and
containing a fast install guide.  Then there is an INSTALL file containing an
Emacs command that installs the files and adds the relevant load instructions
to your .emacs file.  It also contains hints what you may watch for to avoid
collisions with your X resource definitions and/or your window manager
customization as far as mouse buttons are concerned.

Writing your own mouse commands is simple enough if you are familiar with
Emacs Lisp. Have a look at the online documentation of mouse-define and
glance through sky-mouse.el to see some examples.


				  CONCLUSION
				  ----------

Remember, to exit Emacs permanently use C-x C-c.  

This tutorial is meant to be understandable to all new users, so if
you found something unclear, don't sit and blame yourself - complain!

******************************************************************************
			       COPYRIGHT NOTICE

Copyright (C) 1990, International Computer Science Institute

Some paragraphs, and the style of this tutorial are copied from the Emacs
Tutorial which descends from a long line of Emacs tutorials 
( Copyright (c) 1985 Free Software Foundation ).

WE DISTRIBUTE THIS TEXT IN THE HOPE THAT IT WILL BE USEFUL. BUT EXCEPT WHEN
OTHERWISE STATED IN WRITING, THE INTERNATIONAL COMPUTER SCIENCE INSTITUTE
AND/OR THE AUTHOR(S) PROVIDE THIS CODE "AS IS" WITHOUT WARRANTY OF ANY KIND.

THIS DOCUMENT IS PART OF FREE SOFTWARE; YOU CAN REDISTRIBUTE IT AND/OR MODIFY
IT UNDER THE TERMS OF THE GNU EMACS GENERAL PUBLIC LICENSE.  For more details
cf. the file named COPYING in your Emacs distribution or simply type C-h C-c
if you are reading this using the Emacs editor.  Otherwise, write to the Free
Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. )


