/* Enhanced scroller-aware mouse driver.              V0.5 [20011227] */

              PRELIMINARY RELEASE -- USE AT YOUR OWN RISK


Table of contents
-----------------

  Introduction
  What's new
  Contents
  Installation
  Command line switches
  KVM switches
  User-defined actions
  What (and why)


Introduction
------------

This package contains an enhanced mouse driver.  It is intended to
replace the standard mouse.sys driver or the one included in the
scrollms.exe package.

Please note that this driver does NOT work with SMP systems.  Also, if
you use the AMouse.sys package, you will lost the benefits added by the
AMouse package.

This driver can be used with standard 2-buttons and 3-buttons mice and
trackballs.


What's new
----------

It adds support for the following mouse types:

  - Intellimouse Explorer (five buttons + wheel)
  - Logitech MouseMan (three buttons)
  - Logitech M-BJ58 Optical scroll mouse (three buttons + wheel)
    and many other Logitech scroll mice
  - Logitech M-RG45 Cordless wheel mouse (three buttons + wheel)
    and many other Logitech wireless wheel mice
  - Logitech Marble Fx Trackball (3 buttons + scroll button)
  - a series of 3- and 5-buttons 2-wheels mice
  - Primax CyberNavigator, aka IBM Versatile mouse (6 buttons + wheel)
    [no autodetect]

It also enhance the detection fallback routine, in that it attempt to
fallback as an intellimouse or intellimouse explorer mouse before going
down to a plain two buttons mouse, if the mouse seems to support one of
those two protocols.

It also allows user-defined actions for the new mouse events (wheel or
stick events, extra buttons events).  Those user-defined actions are
session-dependant.

Finally, it allows you to force a given protocol to be used, so that it
cooperates better with KVM switches.


Contents
--------

This package contains three files:

  mouseset.exe
  readme
  xmouse.h
  xmouse.sys


Installation
------------

If your mouse is a scrolling mouse, a recommended prerequisite is the
scrollms package (available from the device driver repository on the IBM
web site).  Using this package without this prerequisite has not been
tested, but should cause no problems.

To install this enhanced scroller-aware mouse driver, place xmouse.sys
somewhere on your disk (possibly in ?:\os2\boot, ? denoting your boot
drive).

You now have to update your config.sys accordingly:

REM out the line looking like "DEVICE=?:\OS2\BOOT\MOUSE.SYS", and insert
a new line looking like "DEVICE=?:\OS2\BOOT\XMOUSE.SYS" (adjust the path
according to where you put XMOUSE.SYS, and add remaining parameters if
some were following MOUSE.SYS).

Depending on your mouse model and configuration, you may have to add
some command line switches.  Refer to the Command line switches section
for more details.

Be sure to REM out the line containing your old mouse driver.  Failing
to do so may result in a system trap.

You now have to reboot for this updated driver to be taken into account.


Command line switches
---------------------

This release adds two new command line switches to the xmouse.sys
driver:

PROTOCOL=n

  If your mouse is not correctly autodetected, or if it is not
  autodetected in the mode you want, you can force xmouse.sys to
  use a given protocol.  To do so, add the PROTOCOL=n option on
  the xmouse.sys line in your config.sys, n being a number defined
  as follows:

   0 - Plain PS/2 mouse (2 buttons)
   1 - Plain PS/2 mouse (3 buttons)
   2 - Plain PS/2 mouse (4 buttons, aka ballpoint)
   3 - Primax CyberNavigator (6 buttons plus wheel)
   4 - Intellimouse (3 buttons plus wheel(s))
   5 - Intellimouse Explorer (5 buttons plus wheel(s))
   6 - MouseMan+ PS/2 (3 to 5 buttons plus wheel(s)/stick)
   7 - MouseMan+ PS/2 Wireless (3 to 5 buttons plus wheel(s)/stick)
   8 - Logitech Marble FX trackball
   9 - Trackpoint (2 buttons)
  10 - Traskpoint (3 buttons)
  11 - Primax (3 buttons plus stick)
  12 - Screen Reader (8 buttons, in fact not a pointing device)

  If you specify a number outside that range, 0 will be assumed.  You
  can use "mouseset /q" to find the currently in use protocol (check
  the "Mouse protocol #" line).

  Specifying a protocol has some advantages, but also some drawbacks.
  On the plus side, it allows the use of advanced mouse features (for
  example, if you have a Primax CyberNavigator, aka IBM Versatile
  mouse, you have to specify PROTOCOL=3 if you want to be able to
  use the three additional buttons).  It may also fix some problems
  with KVM switches.  The drawback is that, if you change your mouse
  to an incompatible model, xmouse.sys will fail to detect the change
  and will hence be unable to operate your new mouse (up until you
  either adapt the protocol option or remove it).

  Example:  if you own a Primax CyberNavigator, use the following
            line in your config.sys:

    DEVICE=?:\OS2\BOOT\XMOUSE.SYS PROTOCOL=3

  (where ? is your boot drive).

DELAYATTACH

  To fix a problem with some setups, xmouse.sys now attach itself to
  the keyboard driver at initialization time by default.  If this cause
  problems to your system setup, add the DELAYATTACH option to the
  xmouse.sys line in config.sys.  You will then reverse to the old
  behaviors (i.e., xmouse.sys will attach to the keyboard driver on
  the first time an extra event is generated).

FINDMOUSE=OFF
NUMTABS=NUM_TAB_MIN..NUM_TAB_MAX or else DEFAULT_NUM_TABS
QSIZE=n (10 if > 100)
TYPE=
STYPE=
TRANSPARENT (does nothing)
SERIAL=1..4
RELAXED
FORCEON

  To be documented.  Some of those are defined in the online reference
  manual.


KVM switches
------------

Sometimes when using a KVM switch (i.e., a device to share a keyboard/
video/mouse between more than one computer), the mouse is not always
autodetected, or may be incorrectly recognized.  In those cases, the
PROTOCOL switch of xmouse.sys can be used to force the use of a
specified protocol.

Also, KVM switches may have problems if the various systems do not all
use the same mouse protocol.  Again, the PROTOCOL xmouse.sys's switch
can help.

If you know what protocol your mouse use, or what protocols the other
systems you use use, just specify it on the driver line in your
config.sys.  If you do not know which protocol your mouse use, you can
check the autodetected protocol by issuing "mouseset /q" on an OS/2
command prompt.  It will report the current protocol #.

[Please note that some mice can emulate multiple protocols, and hence
 the autodetected one, even if working as expected, may not be the
 one used by other systems.  For example, many Logitech mice understand
 both the MouseMan+ protocol and the intellimouse or intellimouse
 explorer one.]


User-defined actions
--------------------

There are three kind of extra mouse events.  The first kind is the level
1 wheel or stick events.  Those events occur when the wheel or stick is
actionned for the first time, or for a limited continuous period.  The
second kind is the level 2 wheel or stick events.  If your mouse does
not have a stick, you most probably will never encounter those level 2
events.  They occur when you maintain the stick deflection (or the wheel
rotation) for an extended period.  Those level 2 events implement
proportionality.  The longer the user action is maintained, the faster
the events will be produced.  Finally, the third kind of extra mouse
events is the extra buttons events.  Those events occur when the extra
buttons are pressed.  (The extra buttons do not include the three
standard mouse buttons.)

By default, the extra mouse events produce the following actions:

  Wheel or stick up      : up arrow
                 down    : down arrow
    (level 1)    left    : left arrow
                 right   : right arrow

  Wheel or stick up      : page up
                 down    : page down
    (level 2)    left    : shift-tab (*)
                 right   : tab (*)

  Button 4               : page down
  Button 5               : page up
  Button 6               : home

  (*) in fact, the level 1 action is repeated 6 times.

Although those defaults are quite appropriate for most non-scroller-
aware applications, it is possible to redefine those actions on a
session per session basis.

[Note: if you think some other defaults would be more appropriate,
       especially for extra buttons events, please let me know.]

There is currently no user-friendly ways to reassign the events, but you
can use the provided mouseset.exe utility to do it.  The changes are not
persistent (i.e., they disappear when you restart or switch off your
computer).

To modify the level 1 wheel events, use:

  mouseset /level1up:nnnn
  mouseset /level1down:nnnn
  mouseset /level1left:nnnn
  mouseset /level1right:nnnn

where nnnn is the desired scancode, in hex notation (0xabcd), or in
octal notation (0123456), or in decimal notation (1234).  The only
supported scancode are the 'extended' ones (i.e., two bytes).

For the level 2 wheel/stick events, replace "level1" with "level2".

For the extra buttons, use:

  mouseset /button4:nnnn
  mouseset /button5:nnnn
  mouseset /button6:nnnn

For example, to assign the F1 key to the mouse button 4, issue:

  mouseset /button4:0x3be0

[You can find scancode lists from various places on the internet.  Use
 your preferred search engine with "scancode".]

Please note that those changes are session specific.  Changing some
settings in a fullscreen OS/2 session does not affect the PM session
(and respectively, changing the PM session settings have no effects on
the existing or new OS/2 sessions).


What (and why)
--------------

This device driver adds support for the Intellimouse Explorer-compatible
mice (that include intellimouse explorer and intellimouse optical mice
with one or two wheels and two extra buttons, plus many other brands
models), for Logitech Marble FX trackballs, for Primax CyberNavigator
mice, and some other.

If such a mouse is detected, the 'page down' key is associated with its
mouse button 4, the 'page up' key is with its mouse button 5, and the
'home' key is with its mouse button 6 (if the buttons are presents).

The purpose of this preliminary release is double.  First, I want other
people with a previously non-supported mouse to test it and let me know
if it also works for them.  Second, as I had to modify the autodetection
code, I would like to know if I broke something while doing so.

If the above two conditions are met, I will release updates with added
functionality, and possibly (as long as I can get the needed info)
add support for more mouse protocols.

So, to summarize:

  If your mouse was working fine with the scrollms-included driver, it
  should continue to do so with this enhanced driver.  If it does not,
  please let me know.

  If your mouse was not working properly with the scrollms-included
  driver, please try this new driver and let me know your results.
  Include the COMPLETE output produced by the "mouseset /query" command
  in a WINDOWED OS/2 command prompt (DO NOT RUN MOUSESET IN A FULLSCREEN
  SESSION IF YOU ARE USING THE IBM-PROVIDED MOUSE.SYS DRIVER) and a
  PRECISE description of your mouse model.  (An example of a precise
  description would be something like "Logitech pilot wheel mouse
  optical m-bd 58".  "Logitech pilot" or ... is not precise enough.
  You can usually find this info on the back of your mouse.)

If the enhanced driver works fine, you don't have to uninstall it.  If
it does not work, just un-REM the MOUSE.SYS line in your config.sys and
REM out the XMOUSE.SYS one, and reboot.

That's it.  Thanks for your help.


Martin Lafaix <lafaix@online.fr>
