gpm/doc

	NEW FEATURE IN BETA-2 OVER BETA-1 (ONLY TWIDDLER CHANGES)

Fixed typo in twiddler.c which prevented compiling
Fixed segfault when using more than one thumb-key at a time
Should fix problem when non-ascii chars appear in the cfg file
Changed algorithm for dhouble-click
Added shift etc. support
Added VT change and Execution of commands

	DETAILED DESCRIPTION OF GPM SUPPORT FOR THE TWIDDLER KEYBOARD


Gpm-1.14 and later support the twiddler keyboard, by HandyKey Corp.
(the keyboard is described at www.handykey.com). This document
describes the current status of the gpm decoder.

	Mouse support
	=============

	Motion
	------
The mouse functionality of the keyboard is supported by gpm. Three
decoders are currently available:

	- a "static" decoder, which turns twiddler position to mouse
		displacement.  The decoder locks the mouse when the
		``mouse'' button is pressed and any further motion
		moves the cursor, as long as ``mouse'' is kept down.
		This is compiled if "-DTWIDDLER_STATIC" (for example
		by invoking ``make CC="gcc -DTWIDDLER_STATIC"''.

	- a "ballistic" decoder, which turns twiddler position to
		mouse speed. If the keyboard is hole vertical the mouse
		cursor won't be moved. To compile this decoder
		-DTWIDDLER_BALLISTIC must be used.

	- a "mixed" decoder, that behaves like the static one when the
		device is near-to-vertical and like the ballistic one
		for large inclination. This is compiled by default


	Problems
	........

The current decoder doesn't allow tuning the parameters at run time.
I plan to implement twiddler chords to change the resolution,
acceleration and threshold of the mixed decoder, and the other ones as
well. If different people routinely use different decoders, I'll make
it possible to choose which decoder to run.

I will also implement the chord to switch up/down.


	Buttons
	-------

The first (left) mouse button is bound to the right key ("a", green,
R000).  The other buttons are bound to M000 ("e", blue) and L000
("SP", red). This is consistent with the twiddler manual.

To ease using the fingers like with conventional mice, keys 0R00 and
00R0 (i.e., "b" and "c") are bound to the middle and right button as
well.

Since someone prefers to reverse the order of the keys (i.e., L000 is
the left mouse button), they will use "-B 321" on the gpm command
line. To ease them, 0L00 is bound to the middle button, and 00L0 is
bound to the *left* button. Thus, with "-B 321" it will be the right
button.

In summary:

	Left button (B1):   R000 R000
	Middle button (B2): M000 0R00
	Right button (B3):  L000 00R0

For people using "-B 321"

	Left button (B1):   L000 L000
	Middle button (B2): M000 0L00
	Right button (B3):  R000 00L0



	Problems
	........

None, by now.


	Keyboard support
	================

	Configuration file
	------------------

The keyboard map is stored in run-time tables within gpm. There is no
precompiled table, so a configuration file is needed. I chose not to
precompile values because that would mean to pre-parse a configurazion
file, and provide documentation as well. Using a compulsory
configuration file reliefs my workload :-)

The file "gpm-twiddler.conf" that appears in the gpm configuration
includes the default keyboard map, and can be used right away. If the
file is not in place, gpm will complain about its absence. By default
the file must live in /usr/etc (or /usr/local/etc, or whatever you
gave as a prefix to ./configure). The behaviour is similar for
different installation prefixes. The file is not installed by "make
install".  If the file is missing, gpm will exit producing a message
like this:

	./gpm: /usr/etc/gpm-twiddler.conf: No such file or directory

The distributed configuration file includes its own documentation.

If you want to add keys to the default file, you can avoid editing it
by writing a "gpm-twiddler.user" file and putting it in the same
directory as gpm-twiddler.conf. Gpm will read both files, in sequence,
but won't complain if gpm-twiddler.user doesn't exist.

Gpm will print an error message for any incorrect line in any of the
configuration files: error messages include the file name and the
line number where the error appears, as well as a description of the
type of error. If any error is encountered, gpm will exit.

The daemon will print a warning message for any redefined key, but will
use the new definition. Therefore, if you want to redefine keys in your
user file, just redirect standard error to /dev/null after checking
you are willing to override default definitions.


	General information
	-------------------

A key press is reported when any key of the chord is released: this
avoides reporting false keys when a multi-key chord is being composed.

The twiddler driver in gpm implements auto-repeat. Auto-repeat is
invoked by double-clicking a chord and keeping it pressed. If the
double-click takes more than .3 seconds, it won't be considered a
double-click; auto-repeat will start .5 seconds after the
double-click.

Gpm unblanks the screen when keys are composed using the twiddler.


	Problems
	--------

Gpm doesn't currently report keypresses to the X server. You should
use other twiddler drivers for Linux if you need this functionality.
For example get the driver by Jeff Levine (there is a link to the
driver in www.handykey.com).





I would like to thank HandyKey Corp. for sending a twiddler keyboard
to me and Torben Fjerdingstad for his help in testing out the driver.