
			   IMOUSE Tutorial


1. OVERVIEW
-----------

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.



2. TO AVOID READING THIS
------------------------

Under Open Look (the default with imouse):


    LEFT		    MIDDLE		    RIGHT

set point or          set mark and          insert the X selection
select word/line      highlight the region  or the kill buffer
with multiple clicks


Under TWM, MIDDLE and RIGHT are interchanged.


By default, imouse always copies the selected text to the X selection.
Similarly, the PASTE button inserts the X selection.  If you want to
change this behavior, see the description of the auto-set-X-selection
and auto-get-X-selection variables in the README file.


If you want to know more about the features (and shortcomings) of
imouse, read on...



3. SETTING POINT AND MARK
-------------------------

**** Type C-u 4 C-l (that's CONTROL 'u' 4 CONTROL 'l') on this line
     to center the window.

These are the most common operations.  The point is set with the
SELECT button (usually the left button), and the mark is set with the
MODIFY button (middle button for Open Look users, right button for TWM
users).


**** Click SELECT here: <P>

**** Click MODIFY here: <M>


Note how the region from the P to just before the M character is
highlighted (if you clicked MODIFY on the 'M' character).  You can
verify that the highlighted text is indeed the 'region' as emacs
understands it by typing 'C-X C-X' a few times.  This will transpose
the position of the cursor and the mark.

The size and position of the region can be modified by clicking MODIFY
anywhere in the buffer.  If you click outside the region,
the region will grow towards the location of the click.  If you click
inside the region, near its beginning, the beginning of the region
will move to match the location of the mouse click.  And so on for the
end of the region.  You can practice a little until you're comfortable
with the concept.

At this point, it is important to note that the text is highlighted when
the mark is set WITH THE MOUSE, but not when point or mark are moved
by keyboard commands.  As a result, the highlighted text can be
misleading.  The advantage of leaving the region highlighted is the
capability to select some text somewhere, move to another location or
even another buffer and then paste the text while it is still visible.



4. PASTING TEXT
---------------

**** Type C-u 4 C-l on this line to center the window.

After a region is selected, it can be pasted (copied) with the PASTE
button (right button for Open Look, middle for TWM).  Try this
example:


**** Click SELECT here: <1>

**** Click MODIFY here: <2>

**** Click PASTE here: <>


The whole region from the '1' to just before the '2' should be copied
between the '<>'.  If you wish to try again, just type 'C-x u' (the
UNDO command) and repeat the exercise.



5. CUTTING TEXT
---------------

**** Type C-u 4 C-l on this line

Just as a region can be selected, it can be deleted with the DELETE
modifier.  The operation is the same as for selecting text, except
that the DELETE modifier is applied when the region is defined:


**** Click SELECT here: <1>

**** Hold DELETE (usually the Shift key) and click MODIFY here: <2>


The whole region between the first and second clicks is deleted (a '2'
should appear on the 'Click SELECT here' line).  Again, you can try
the exercise from scratch by typing C-x u.

The text is deleted from the buffer, but copied to the killbuffer so
that it can be retrieved later:


**** Click SELECT and type 'C-y' (yank) here: <4>

**** Click PASTE here: <5>



You should have two copies of the deleted region, one on the 'yank'
line and one on the 'PASTE' line.  This demonstrates a particularity
of the PASTE command:

	When a region is highlighted, PASTE inserts it,
	otherwise, the contents of the kill buffer is inserted.

Thus, when the region was deleted, nothing was left highlighted and the
PASTE button acts as a 'yank' command.



6. MOVING TEXT
--------------

**** Type C-u 4 C-l

Text can also be deleted and pasted in a single operation.  If PASTE
is used in conjunction with DELETE, the selected text is moved from it
original location to the point:


**** Click SELECT here: <1> and MODIFY here: <2> 

**** Hold DELETE and click PASTE here: <3>


See how the selected region moves from the first line to the second.



7. SELECTING LOGICAL UNITS
--------------------------

**** Type C-u 4 C-l on this line.

There is a concept that has been used with mouse-based editing for
several years that allows selection of text based on its syntax.  Just
as emacs provides commands to move by word, by line, or even by
program statement, it is possible to use the mouse to select and
operate on logical units.  The "thing" package is used to do this, and
is 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 you click
on a character in a word, that entire word is selected.  If you click
at the end of a line, the entire line is selected.  When clicking on a
parenthesis, the entire region from the opening parenthesis to its
closing counterpart is selected.  Try the following exercises:


**** Hold THING and click SELECT here: <111111>

Note that all 1's are highlighted.


**** Hold THING and click SELECT on a 2,
     then release THING and click MODIFY on a 3: <222 333>

Note that all 2's are highlighted, and then the region is expanded to
include the 3's.  This is a feature of the MODIFY button:

	The MODIFY button is programmed to recognize the nature of
	the last selection and to modify its boundaries by the same
	units.

Thus, 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.


**** Hold THING and click SELECT past the end of the line <4>:

Note that the whole line is selected.

**** Release THING and click MODIFY anywhere on this line <5>

Note that all three lines are selected.


**** Hold THING and click SELECT on a parenthesis <6>:

(defun what-cursor-coordinates ()
  "Print line and column number of the cursor."
  (interactive)
  (message "(%d, %d)"
           (current-column) (1+ (count-lines 1 (point)))))

The selection should extend from one parenthesis to another.


**** Release THING and click SELECT here: <7>
     Hold THING and click PASTE on any "thing".

This sequence should have copied the object you selected just before
the '7'.


Remember that you can undo the changes with C-x u.


There are many types and variants of "things", but the above are
the most representative.  Look in thing.el for more information.



8. SELECTING BIGGER LOGICAL UNITS
---------------------------------

**** Type C-u 4 C-l on this line.

With the mouse, 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.  Try this:


**** Click THING MODIFY twice on any of the 1's:

(defun foo ()
  (case bar
    (111 (message "one"))
    (222 (message "two"))
    (333 (message "three"))))

The first time, all the 111's are selected, because they are all part
of the same word.  On the second click, the whole parenthesized
expression is selected because it encloses the "111" symbol.  To
experiment with text instead of code, click THING MODIFY one, two,
three and four times in this paragraph.  The first time, a word is
selected.  The second time, a sentence is selected. Third, the whole
paragraph is selected, and, finally, the whole page is selected on the
fourth click.  The fifth click reselects a word.

For an interesting twist, you can delete "things" just as easily.
First, hold the THING and DELETE modifiers and click SELECT on this
<444>.  See how "444" was deleted?  Holding the same modifiers, click
first with SELECT on this <555>, and then, again with THING+DELETE,
click on MODIFY.  Note that this time, a word is first deleted, and
the MODIFY button is used to expand the previous action do delete an
entire sentence.  Just for fun, and to reassure you, click PASTE (no
modifiers) on the next line:

<6>

Because the deletions are done successively, they are ordered properly
in the kill ring and can be recalled all at once.  This feature
enables you to move logical units painlessly.


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.



9. SCROLLING
------------

**** Type C-u 4 C-l on this line.

There are two ways to scroll text with imouse; dragging the text
or setting a target for the moused line.  Drag scrolling is more
intuitive: 

**** Hold WINDOW (usually the Meta key) and click MODIFY here: <1>
     While holding the button down, move the mouse up by a few lines.
     Release the mouse.

The buffer reappears scrolled by the same amount as the mouse
movement.  This scrolling also works sideways.  I find it quicker and
more useful that other types of scrolling, but this is a matter of
taste.  Unfortunately, the scrolling is not interactive; the effect is
visible only when the mouse is released.



The second type of scrolling is more precise:

**** Hold WINDOW and THING and click LEFT on this line <2>.

The <2> line is now at the top of the window.  Note that the LEFT
button is used, regardless of its meaning.

**** Hold WINDOW and THING and click MIDDLE on this line <3>.

The <3> line is now at the center of the window.  Note that the MIDDLE
button is used.

To put the next line at the bottom of the window:

**** Hold WINDOW and THING and click RIGHT on this line <4>.



10. OPERATIONS ON WINDOWS
------------------------

Some operations are pretty straightforward, such as clicking SELECT on a
window's modeline to delete all other windows.  The same button,
accompanied by DELETE, deletes that window from the screen.

Windows can be split by clicking PASTE on a modeline (it "copies" the
window).  Modified by DELETE, this action prompts for another buffer
to be displayed in the new window.  In a way, SELECT and PASTE cancel
each other in this context.

The MODIFY button can be used to modify window sizes or locations.
Clicking MODIFY on a modeline will "drag" it as described in the first
dragging method above.  The net result is a change in the window
height.  This method does not work on the vertical line between
side-by-side windows.  When modified by DELETE, the same button should
move windows up and down, but this is not implemented yet.



11. LOCAL OPERATIONS
--------------------

The last three buttons call common commands at point; when the WINDOW
and DELETE modifiers are held, SELECT indents the current line and
PASTE executes the keyboard macro at point.  Try this, for instance:


    **** Hold WINDOW+DELETE and click SELECT on this line <1>.

The line is re-indented to the leftmost column.



12. HELP
--------

Holding all three modifiers (Control, Meta, and Shift) and clicking on
a button invokes help.  The LEFT button prints a summary of the mouse
commands and the RIGHT button invokes this tutorial.
