Read Me

+---------------------+
| Project information |
+---------------------+

Name .......... mouseOnStick

Description ...	mouseOnStick is a UNIX/Linux tool which translates SDL joystick
                input to mouse movement, keyboard input and/or command execution

Version ....... 0.8

Released ...... Never -- this is a development version

Status ........ Stable and 'production ready' (not necessarily 'bug-free')

Author(s) ..... William D. Blake (wdblake -at- gmail -dot- com)
                René Reucher (rene -dot- reucher -at- batcom-it -dot- net)

License ....... GPLv3 (see COPYING file)

Copyright .....	Copyright (C) 2011 - 2015 W. D. Blake and R. Reucher, All Rights
                Reserved

Requirements .. POSIX operating system (i. e. Linux), X11 and SDL (1 or 2)

+--------------------------+
| What is 'mouseOnStick'? |
+--------------------------+

mouseOnStick is a UNIX / Linux (X11) tool which translates SDL joystick input to
mouse movement, keyboard input and/or command execution.

+-------------------------------------+
| Build and installation instructions |
+-------------------------------------+

The usual way to use mouseOnStick is to just call 'make' in order to build the
binary and then run the resulting binary from the current working directory: 

$ make
...
$ ./mouseOnStick -v
...

It's up to you to copy the binary to somewhere else (/usr/local/bin is probably
a good place).

If you need to change any build-time configuration settings, just pass the
corresponding settings (and their values) on the make command line:

$ make DEBUG=1 POLLEVENTS=1
...

Supported build-time configuration settings and their possible values include:

Name		Default	  	Description
---------------	---------------	------------------------------------------------
DEBUG		0		0: produce no debug symbols, turn all warnings
				   off, exclude debug code
                        	1: produce debug symbols for gdb, turn all
				   warnings on, exclude debug code
				2: produce debug symbols for gdb, turn all
				   warnings on, include debug code

POLLEVENTS	0		0: wait for joystick events with SDL_WaitEvent()
				1: poll for joystick events with SDL_PollEvent()

XTEST		1		0: for mouse-button presses and releases use
				   XSendEvent(), for mouse movement use
				   XWarpPointer()
				1: for mouse-button presses and releases use
				   XTestFakeButton(), for mouse movement use
				   XTestFakeRelativeMotionEvent()

SDL		auto-detected	1: use SDL 1 (has precedence when auto-detected)
				2: use SDL 2

+----------------------+
| Command line options |
+----------------------+

These are the available command line options and their meanings:

Option				Meaning
-----------------------------	-----------------------------------------------
--assign, -a			Read assignments from <file>
--deadzone, -d			Setup deadzones (<dx>[:<dy>[:<dz>[:<dd>]]])
--display, -D			Open connection to alternate X <display>
--help, -h			Show command line help and quit
--ignore-sic, -i		Ignore single-instance check (force execution)
--joystick, -j			Use joystick at index <number>
--keepvisible, -k		Keep mouse pointer visible
--mousespeed, -m		Speed of mouse movement (relative <speed>)
--mousewheel, --wheel, -w	Enable mouse-wheel simulation (see --zmap)
--nullpointer, -n		Use an invisible pointer icon
--precisebutton, -p		Specify a <button> to enable 'precision mode'
--precisefactor, -P		Specify the speed <factor> in 'precision mode'
--quitbutton, -q		Specify a <button> number used to quit
--scan, -s			Scan for available joysticks and quit
--test, -t			Run in test-mode (axes values / button states)
--verbose, -v			Enable verbose output
--xaxis, -x			Select axis number <xaxis> as the x-axis
--yaxis, -y			Select axis number <yaxis> as the y-axis
--zaxis, -z			Select axis number <zaxis> as the z-axis
--zmap, -Z			Specify button numbers mapped to <z->:<z+>

>>> TODO (offer some examples) <<<

+-------------+
| Assignments |
+-------------+

>>> TODO <<<

+---------+
| Contact |
+---------+

Development site:
http://sourceforge.net/projects/mouseonstick/