ZXDS Kempston mouse documentation
=================================

ZXDS can emulate the Kempston mouse interface. To be able to use this feature,
you will need Spectrum software which supports the Kempston mouse itself.

The Kempston mouse however was nowhere near as widespread as the Kempston joystick,
which was natively supported by most games and other software.

Fortunately, many games and utilities were later on adapted to support Kempston
mouse and you can get many of them from here: http://velesoft.speccy.cz/kmsoft.htm .

If you just want to try it out, you can use the test program found in samples/tests/input.tap.

Controls
--------

Once you have the appropriate software, you have to set up the ZXDS controls
so you can use the mouse comfortably. The default KEYS4 button config shows
an example setup:

Left:  LMB (Left Mouse Button)
Right: RMB (Right Mouse Button)
Up:    MMB (Middle Mouse Button)
Down:  Keyboard (action shortcut)

Of course, if you are left handed, you can map these to A, B, X, and Y buttons instead.

Using mouse
-----------

Now to activate the mouse mode, press one of the buttons with mouse buttons assigned.
Once active, you can control the mouse by touching and sliding your stylus
on the touch screen and pressing the buttons with mouse buttons assigned.

To leave the mouse mode, press Down, assuming you use the example setup. 
You can also press Start or any other button which has been assigned
to switch the bottom screen to whichever display you desire.

The mouse button you use to activate the mouse selects one of the mouse modes available:
LMB selects absolute mode and brings the main screen to the bottom,
RMB selects relative mode and also brings the main screen to the bottom, while
MMB selects relative mode but keeps the main screen at the top.

Mouse modes
-----------

In relative mode, you simply move the mouse around by sliding the stylus on the touch screen.

In absolute mode, the mouse attempts to move to wherever you touch the touch screen.
However, you need to align the touch screen position with the mouse pointer first.
There are two ways to do this:

- When you press LMB to activate the mouse mode, keep it held down and touch
  the mouse pointer before you release LMB.

- Once the mouse mode is already active, touch the two opposite diagonal corners
  of the area where the mouse can move. Or just touch all four if you prefer.
  As long as the mouse area is restricted, this will align the touch position with
  mouse pointer. 

Once aligned, you can either slide the stylus around to move the mouse as usual,
or just touch anywhere and the mouse will automatically move there quickly.

In case the touch position and mouse pointer become misaligned again,
just align them again, preferably with the second described method.

See also the Troubleshooting section if you have problems getting it working properly.

Mouse in Multiplayer
--------------------

Normally, ZXDS emulates one mouse. However, if you enter WiFi peer-to-peer multiplayer
session, it automatically switches into the dual master/slave mouse mode compatible
with Kmouse 2008 interface (see http://velesoft.speccy.cz/kmturbo2008-cz.htm).
The host mouse becomes the master mouse and the client mouse becomes the slave mouse.

This means that either the host gets to control the mouse if the application
supports just one mouse, or both host and client can control their own mouse
if you have an application with support for two mouse interfaces included.

Kempston mouse vs Kempston joystick
-----------------------------------

One last thing you should perhaps know: the I/O ports used by Kempston mouse
interface clash with the I/O ports used by Kempston joystick interface.

Therefore, when Kempston mouse is in use, the Kempston joystick ports return
erroneous input values, and vice versa. This makes it practically impossible
to reliably use both at the same time.

To avoid this, ZXDS doesn't enable mouse ports until you press any mouse button,
and disables them again when you press any Kempston joystick direction or fire button.

Therefore, if you intend to use Kempston joystick after having used Kempston mouse,
just remember to press any Kempston joystick button to make it start working properly again.

Troubleshooting
---------------

Q1: I activated the mouse mode but the mouse pointer doesn't respond at all.

A: Make sure you have the software with Kempston mouse support included.

   Also make sure that the software is set up to use the Kempston mouse.
   Sometimes this requires enabling mouse ports before launching the software.
   Sometimes it needs to be enabled in the software itself, by some key or other action.

Q2: I activated the mouse mode and the mouse pointer moves and clicks erratically around the screen.

A: This often happens when the software is set up to use Kempston joystick.
   See if you can control the pointer with Kempston joystick - if you can, this is the case.

   Therefore make sure the software is set up not to use the Kempston joystick.
   Sometimes this requires enabling mouse ports before launching the software.
   Sometimes it needs to be disabled in the software itself, by some key or other action.

Q3: When using the absolute mouse mode, the mouse doesn't move around correctly at all.

A: First of all, make sure you have aligned the touch position with the mouse pointer first.

   If you have done that, but the mouse still keeps getting out of alignment afterwards,
   the mouse driver is likely to blame. It either clamps, scales, or accelerates
   the mouse movement, or contains bugs often related to sign overflow, or both.

   To verify if this is the case, activate relative mouse mode, touch the
   mouse pointer with the stylus, and then quickly slide it around as if you
   were drawing a large circle about a dozen times. Repeat it few more times if you wish.
   Just make sure you draw only in the area where the mouse can move.
   The mouse pointer shall finish under the stylus in the very same position.
   If it has drifted away in any direction, the mouse driver suffers from one
   of the issues mentioned above, and can't be used reliably in absolute mode.

   In such case, you will either have to try to find another version of the software
   with properly working mouse driver, or refrain from using the absolute mode and
   stick with the relative mode. The issues, while still present, shall be much less noticeable.

Q4: When using the absolute mouse mode, the mouse all of sudden gets out of the alignment.

A: First check the previous answer. If the mouse driver passes the test,
   either the software repositions the mouse under some circumstances,
   or you slide your stylus while the software doesn't allow moving
   the mouse around, for example when pressing and holding the mouse button.
   Try to avoid doing the latter, and just realign the touch position with
   the mouse pointer.

   If it becomes unbearable, again try different version of the software,
   or just use the relative mouse mode instead.
  
Q5: When using the absolute mouse mode, the mouse is sometimes slightly out of the alignment.

A: This may happen if your touch screen is not calibrated properly.
   If the mouse is aligned at some position but consistently misaligned
   near the corners, this may be the case. Use the system settings
   to calibrate the touch screen and try again.

   Sometimes, however, the mouse driver itself scales the movement in one or both axes.
   If you have calibrated the touch screen but the mouse still appears to be
   moving slower (or faster) than your stylus in some direction, this is
   likely the case. As usual, you will have to try different version
   with different mouse driver, or just use the relative mouse mode instead.
   
   

And that's all. Good luck and enjoy controlling your Spectrum with the touch screen.
