xstroke - X based gesture recognition based on libstroke.

Copyright (C) 2000 Carl Worth <cworth@east.isi.edu>

Comments are welcome.

What is xstroke?
----------------
xstroke is a gesture recognition program. Performing known gestures
with the X pointer, (ie. a mouse or a stylus) will cause actions to be
performed, (most commonly to send character events to the currently
focused window). The known strokes actions and their corresponding
actions are defined in the ${HOME}/.xstrokerc file described
below. The underlying recognizer is libstroke which was most recently
available at http://www.etla.net/libstroke/

Installing xstroke
------------------
Copy the default xstrokerc file to ~/.xstrokerc:

	 cp xstrokerc ${HOME}/.xstrokerc

Run xstroke

Using xstroke
-------------
Tap on the little xstroke window to toggle xstroke between Off and
On. When xstroke is active, it uses the entire display for
gestures. Perform the gesture of interest anywhere on the screen and
the generated keystroke will be sent to the currently focused
window. Gestures may be performed with a mouse by clicking and
dragging the first mouse button. With a stylus you should be able to
simply stroke the gesture.

The default xstrokerc file included with this version of xstroke
defines an alphabet for all lowercase/capital letters, all numbers,
and all punctuation that is on my keyboard, (pc104 US), including
Space, BackSpace, Return, Tab, Escape and the four cursor arrows. It
does not define any accented characters, (although I have heard of
successful reports of configuring xstroke to use dead keys to generate
accented characters). Also, xstroke does not yet support modifier
keys. (Note: You can put a modifier key specification in the
configuration file, but currently it will just send a single KeyPress
event followed by a KeyRelease event for that key, just as it does
with all other keys. So this is not very useful for entering modified
keys using strokes.) The next release of xstroke will include support
for modifiers.

What alphabet is this?
----------------------
The default alphabet in xstrokerc is an original alphabet that I
created. I made many strokes similar to the strokes in the program
xscribble. The big difference in my alphabet is that I do not use any
shift modes, (capitals, num-shift, punc-shift, etc). Instead, I have
all letters, numbers, and punctuation defined in a single alphabet. To
do this, I've implemented capital letters as strokes just like the
corresponding lowercase stroke, but with the last line segment
repeated in the opposit direction. For example, the capital 'L' stroke
goes down, to the right, then back to the left, (1478987). Most
numbers, (except 6, 8, and 9), are drawn in reverse to distinguish
them from letters. My punctuation alphabet is largely custom. The
alphabet also includes many strokes shaped like lowercase letters, (b,
d, e, etc.) that do not exist in xscribble.

See doc/alphabet.ps for a more exact depiction of the alphabet.

Also, see doc/xstroke_vs_xscribble if you are interested in how this
alphabet differs from xscribble's.

Using other programs with xstroke
---------------------------------
If you do a single mouse click, (or a stylus tap), then xstroke will
pass a mouse click through to other applications. In this way,
programs that rely on a mouse only for clicks will still be usable
with xstroke.

In order to use programs that expect dragging or other mouse motion,
you will need to disable xstroke, (by clicking in its control window),
before performing the drag.

Compiling xstroke
-----------------
If you would like to compile xstroke, simply edit the Makefile to
point to correct locations for X and type make. (Yes, this is a
primitive build environment -- something fancy like autoconf will come
in a future release).

This version of xstroke ships with a bundled libstroke version
0.4. The only changes I made are to 3 global parameters in stroke.h:

	#define MIN_POINTS 25
	#define BIN_COUNT_PERCENT 0.05
	#define SCALE_RATIO 3

Will you add support for modes?
-------------------------------
I plan to make a future release of xstroke that will support
modes. Then, anyone that cares to could implement their favorite modal
alphabet.

Can I make my own strokes?
--------------------------
The xstroke configuration file, (${HOME}/.xstrokerc), defines strokes
and actions to be performed when the stroke is entered. Currently, the
only supported action is to send a KeyPress and KeyRelease event to
the currently focused window. Future releases of xstroke will add
support for addition actions including sending strings of characters,
(macro expansion), as well as executing commands. See the
doc/configuration file for an explanation of the syntax of
${HOME}/.xstrokerc or just dive in and figure it out!

Well, that's about it. Feel free to send me comments, suggestions, or
bug fixes.

-Carl Worth <cworth@east.isi.edu>
