xf86-input-synaptics/README

Synaptics TouchPad driver for XFree86
-------------------------------------

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

This is a driver for the Synaptics TouchPad for XFree86 4.x. A
Synaptics touchpad by default operates in compatibility mode by
emulating a standard mouse. However, by using a dedicated driver, more
advance features of the touchpad becomes available, such as:

- Movement with adjustable, non-linear acceleration and speed.
- Button events through short touching of the touchpad.
- Double-Button events through double short touching of the touchpad.
- Dragging through short touching and holding down the finger on the
  touchpad.
- Middle and right button events on the upper and lower corner of
  the touchpad.
- Vertical scrolling (button four and five events) through moving
  the finger on the right side of the touchpad.
- The up/down button sends button four/five events.
- Horizontal scrolling (button six and seven events) through moving
  the finger on the lower side of the touchpad.
- The multi-buttons send button four/five events, and six/seven
  events for horizontal scrolling.
- Adjustable finger detection.
- Multifinger taps: two finger for middle button and three finger
  for right button events. (Needs hardware support. Not all models
  implement this feature.)
- Run-time configuration using shared memory. This means you can
  change parameter settings without restarting the X server.

Note that depending on the touchpad firmware, some of these features
might be available even without using the synaptics driver. Note also
that some functions are not available on all touchpad models, because
they need support from the touchpad hardware/firmware. (Multifinger
taps for example.)


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

See the INSTALL file for detailed installation instructions.


Compatibility
-------------

The driver has been reported to work on a number of different laptop
computers. See the COMPATIBILITY file for the list. If your computer
is not listed, please let me (petero2@telia.com) know if the driver
works on your computer.


Parameters
----------

The driver behavior can be configured with parameters. These
parameters are options in the InputDevice section in the XFree86
config file. See the INSTALL file for a working example. If you have
the SHMConfig parameter enabled, these parameters can also be changed
at runtime with the synclient program.

Parameter:		Type:   Description:

Device			String	Synaptics device
Protocol		String	"auto-dev" (automatic, default), "psaux" (raw) or
				"event" (linux 2.5 kernel events)
SHMConfig		Bool	switch on/off shared memory for configuration
LeftEdge		Int	coordinates for left edge
RightEdge		Int	coordinates for right edge
TopEdge			Int	coordinates for top edge
BottomEdge		Int	coordinates for bottom edge
FingerLow		Int	When finger pressure drops below this value, the
				driver counts it as a release.
FingerHigh		Int	When finger pressure goes above this value, the
				driver counts it as a touch.
MaxTapTime		Int	max. time (in milliseconds) for detecting a tap
MaxTapMove		Int	max. movement of the finger for detecting a tap
VertScrollDelta		Int	move distance of the finger for a scroll event
HorizScrollDelta	Int	move distance of the finger for a scroll event
EdgeMotionSpeed		Int	edge motion speed when dragging
Repeater		String	repeater device
MinSpeed		Float	min. Speed factor
MaxSpeed		Float	max. Speed factor
AccelFactor		Float	acceleration factor
UpDownScrolling		Bool	If on, the up/down buttons generate button 4/5 events.
				If off, the up button generates a double click and
				the down button generates a button 2 event.
EmulateMidButtonTime	Int	max time (in milliseconds) for middle button emulation.
TouchpadOff		Bool	If on, the Touchpad is switched off (useful
				if an external mouse is connected)
LockedDrags		Bool	If off, a tap and drag gesture ends when you release
				the finger. If on, the gesture is active until you
				tap a second time.

A tap event happens when the finger is touched and released in a time
interval shorter than MaxTapTime, and the touch and release
coordinates are less than MaxTapMove units apart. A "touch" event
happens when the Z value goes above FingerHigh, and an "untouch" event
happens when the Z value goes below FingerLow.


FAQ
---

* Is this free software?

    Yes, the source code is released under the GNU General Public
    License.

* How do I use this driver with Linux kernel 2.6.x?

    You need kernel 2.6.0-test6 or later and version 0.11.7 or later
    of the XFree86 driver. You need to have the "evdev" driver loaded
    or compiled into the kernel (CONFIG_INPUT_EVDEV). Set the
    "Protocol" parameter in the X configuration file to
    "auto-dev". Also, if you set the "Device" parameter to
    "/dev/psaux", the same X configuration file should work for a
    2.4.x kernel.

    When configuring the kernel, enable PS/2 mouse support
    (CONFIG_MOUSE_PS2) and synaptics touchpad support
    (CONFIG_MOUSE_PS2_SYNAPTICS).

* How can I configure tap-to-click behavior?

    If you set MaxTapTime=0 then the touchpad will not use tapping at
    all, i.e. touching/tapping will not be taken as a mouse click.

    If, instead, you set MaxTapMove=0, then the touchpad will not use
    tapping for a single finger tap (left mouse button click) but will
    for the two and three finger tap (middle and right button click).

* Why did tap-to-click stop working after I upgraded from an old version?

    Time is now measured in milliseconds instead of "number of
    packets". In practice, this means that if you are upgrading from
    an old version, you need to change MaxTapTime and
    EmulateMidButtonTime to make "tap to click" work. Good values are
    180 and 75 respectively.

* Gnome scrollbars scroll too much when using tap-to-click. Why?

    The MaxTapTime parameter is probably too big. Try setting it to
    180. Gnome scrollbars use auto repeat, ie if you press the left
    mouse button and keep it pressed, the scroll bar will move until
    you release the button. This will lead to problems if the tap time
    is longer than the delay before auto repeat starts.

* Can the driver be used together with gpm?

    No, not reliably, if you are using a 2.4.x kernel. The gpm driver
    and the X driver both try to read data from the touchpad, and if
    they try to read at the same time, both drivers see incomplete
    data and don't know how to interpret it.

    If you are running a 2.6.x kernel though, there should be no
    conflict, because the kernel driver will make sure both user space
    drivers receive all events from the touchpad.

* How do I compile the driver?

    Beginning with version 0.11.8, it should be possible to compile
    the driver by simply running "make". This will compile a driver
    for XFree86 4.2.x, which will also work for 4.3.x versions of
    XFree86.

    If you have an older version of XFree86, you will need an
    installed X source tree. On an RPM based distribution, you can
    build a suitable source tree by installing the XFree86 source RPM
    and compile it. For example, in RedHat 9, use the following
    commands:

      # rpm -vU XFree86-4.3.0-2.src.rpm
      # cd /usr/src/redhat/SPECS
      # rpmbuild -bb XFree86.spec

    Then change the TOP variable in the Makefile to match the version
    of XFree86 you are using. In the example above, set

      TOP = /usr/src/redhat/BUILD/XFree86-4.3.0/xc


Authors
-------

Many people have contributed to this driver. Look at the top of
synaptics.c and ps2comm.c for details.

The current maintainer is Peter Osterlund <petero2@telia.com>.