Generic mouse event translator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 7 filter-mouse


Synopsis
--------

::

  filter-mouse: [<file>]


Description
-----------


This filter translates mouse events according to a set of
translation rules.


Options
-------


:p:`file`
    The name of the configuration file. If none given, the filter will
    first look for the file `filter/mouse` in the user GGI directory
    (`$HOME/.ggi/` on UNIX), then in the base GGI directory if not
    found.


Configuration
-------------

The translation rules are specified through a simple text file. The
following example gives a good idea of the mouse filter usage. A ``#``
marks the rest of the line as a comment.


Example
-------

A set of mouse translation rules::

  # Syntax is:
  # incoming-type [type-specifics] TO outgoing type [type-specifics]

  #
  # Simulated mouse buttons on the keyboard
  #
  #KEY modmask modvalue button label  symbol TO BUT buttonnumber
  KEY 0x0004  0x0004   0xffff 0x000d 0xffff TO BUT 1		# Alt-Enter
  KEY 0x0004  0x0004   0xffff 0x0020 0xffff TO BUT 2		# Alt-Space
  KEY 0x0004  0x0004   0xffff 0x0008 0xffff TO BUT 3		# Alt-BackSpace

  #
  # Keyboard-Mouse on the Cursors
  #
  #KEY modmask modval button label  symbol TO REL axis value
  KEY 0x0004  0x0004 0xffff 0xe034 0xffff TO REL X    -5	# Alt-Left
  KEY 0x0004  0x0004 0xffff 0xe035 0xffff TO REL X     5	# Alt-Right
  KEY 0x0004  0x0004 0xffff 0xe032 0xffff TO REL Y    -5	# Alt-Up
  KEY 0x0004  0x0004 0xffff 0xe033 0xffff TO REL Y     5	# Alt-Down

  #
  # Keyboard mouse on the Numpad
  #
  KEY 0x0004 0x0004 0xffff 0xe231 0xffff TO REL X -5	# Alt-Num1
  KEY 0x0004 0x0004 0xffff 0xe231 0xffff TO REL Y  5	# Alt-Num1
  KEY 0x0004 0x0004 0xffff 0xe232 0xffff TO REL Y  5	# Alt-Num2
  KEY 0x0004 0x0004 0xffff 0xe233 0xffff TO REL X  5	# Alt-Num3
  KEY 0x0004 0x0004 0xffff 0xe233 0xffff TO REL Y  5	# Alt-Num3
  KEY 0x0004 0x0004 0xffff 0xe234 0xffff TO REL X -5	# Alt-Num4
  KEY 0x0004 0x0004 0xffff 0xe235 0xffff TO BUT 1	        # Alt-Num5 - Button
  KEY 0x0004 0x0004 0xffff 0xe236 0xffff TO REL X  5	# Alt-Num6
  KEY 0x0004 0x0004 0xffff 0xe237 0xffff TO REL X -5	# Alt-Num7
  KEY 0x0004 0x0004 0xffff 0xe237 0xffff TO REL Y -5	# Alt-Num7
  KEY 0x0004 0x0004 0xffff 0xe238 0xffff TO REL Y -5	# Alt-Num8
  KEY 0x0004 0x0004 0xffff 0xe239 0xffff TO REL X  5	# Alt-Num9
  KEY 0x0004 0x0004 0xffff 0xe239 0xffff TO REL Y -5	# Alt-Num9

  #
  # Home the cursor ...
  #
  KEY 0x0004 0x0004 0xffff 0xE038 0xffff TO ABS X 0	# Alt-Home
  KEY 0x0004 0x0004 0xffff 0xE038 0xffff TO ABS Y 0	# Alt-Home

  #
  # Invert mouse axis
  #
  #REL modmsk modval axis TO REL axis multiplier
  REL 0x0004 0x0004 X    TO REL Y    -1
  REL 0x0004 0x0004 Y    TO REL X    -1

  #
  # Accelerate mouse
  #
  #                             multiplier treshold higher-speed
  REL 0x0004 0x0004 X TO REL X 1          5        4
  REL 0x0004 0x0004 Y TO REL Y 1          5        4

  #
  #
  # Invert mouse buttons
  BUT 0x0004 0x0004 1 TO BUT 2
  BUT 0x0004 0x0004 2 TO BUT 1


