First of all the users must be aware that this software is still alpha and under active developpement, be patient and if something goes wrong feel free to report the problem to lecoanet@ath.cena.fr. Ideas for improvement (and even better code) are also much appreciated even though I may not incorporate them. This said, here are some notes on how to use it. Enjoy ! This extension implements three tcl commands that give access to additional input devices manipulation at the tcl level. To use it simply do a: 'package require XI' or even more basically a 'load xi1.0.so' in wish. It should be a 8.0.x wish. I have not tested it on the alpha 8.1.x versions. If for some reason the package is not installed in the usual location (/usr/lib/TkXInput or /usr/local/lib/TkXInput), the tcl variable $auto_path should point to the TkXInput directory or an immediate ancestor. If using load directly, the directory containing the binary module must be known by the dynamic loader. A quick way to fix the problem is to add the path to the $LD_LIBRARY_PATH environment variable. The extension add its commands in a namespace named 'xi'. The first command, 'xi:bindevent', binds tcl scripts to input events occuring in a widget. This may not be an elegant way of doing it but it's simpler than modifying 'bind' up front. It may be thought as a 'fileevent' command that acts on widgets and input devices rather than channels. The syntax is: xi::bindevent widget deviceName <eventSpec> script 'widget' is the full pathname of a widget defined in the current interpreter. 'deviceName' is the name of a device hooked to the X server, see the xi::device list command for a list of available devices. 'eventSpec' is the name of the event to handle. It can be one of: <KeyPress> <KeyRelease> <ButtonPress> <ButtonPressGrab> <ButtonPressOwnerGrab> <ButtonRelease> <Motion> <MotionHint> <ButtonMotion> <B1Motion> <B2Motion> <B3Motion> <B4Motion> <B5Motion> <FocusIn> <FocusOut> <ProximityIn> <ProximityOut> <DeviceState> <DeviceMapping> <ChangeDevice> 'script' is the script to be invoked when an event matching 'eventSpec' is received from 'deviceName' for 'widget'. The script can contain % characters that will be substituted with values from the event. The valid character sequences are as follow: %# The number of the last request processed by the server. %0-9 The value of valuator n (0-9). %* The name of a device (as encoded in a valuator by the switch virtual device). Only useful with a motion reported by the switch device. %b The button number for events related to buttons. %h The motion hint field from the event. %k The keycode for events related to keys. %s The state field from the event (the core that is). %t The time field from the event. %x The x coord of the core pointer. %y The y coord of the core pointer. %C The name of the core device that changed (only for DeviceChange events). %D The device name that has emitted the event. %E The send_event field from the event. %S The device state field from the event. %T The type field from the event, as an event name. %W The window receiving the event. %X The root window x coord of the core pointer. %Y The root window y coord of the core pointer. Some expansions make senses only for a restricted set of events. The second command, 'xi::device', manipulates the input devices. It has subcommands for listing the devices and configuring them. It also provides commands to change the core devices. The syntax of the various subcommands along with some explanation is detailed below. In all of these forms 'device' is the name of a device as reported by 'xi::device list'. All of these commands has support for specifying a different display than the main window's one, simply add the option '-displayof win'. The display on which win is located will be used in place of the default display. xi::device axisinfo device axisIndex Reports in order: the minimum and maximum values that can be reported by the valuator of index 'axisIndex' and its resolution. The first two numbers are useful for example to map the raw input events coordinates to a window. xi::device buttonmap device ?button1? ?button2? ... ?buttonn? Invoked without any button index specification, the command returns a list of button indices describing the current button mapping. The first element describes the first button, etc. E.g. "2 1 3" means first button is the second of the device, second is the first and third is the third. If the command is invoked with integer indices, they are used to change the button mapping. "xi::device buttonmap mouse 2 1 3" establishes the previously described mapping. Any unspecified buttons are untouched. Buttons are numbered from 1. xi::device corekeyboard ?device? Invoked without a device name, the command returns the name of the device that is currently the core keyboard. If a device name is given it will become the core keyboard. xi::device corepointer ?device? ?xIndex yIndex? Invoked without parameters, the command returns the name of the device that is currently the core pointer. If a device name is given it will become the core pointer. If the two indices are given, they define which valuators of 'device' should be used as X and Y axes. Valuators are numbered from zero. xi::device features device Describes which features are supported by the named device. The return list includes in order: the number of buttons, the number of keys, the number of axes, the size of the motion history buffer, 0/1 depending if the device is focusable and 0/1 depending if the device can report proximity events. There is no means to know if a device accept Relative or Absolute motion reporting (but it is possible to know the current mode see 'xi::device mode'). xi::device focus device ?focusWin revertTo? When called without the last two parameters, the command reports the focus window associated with the given device (if it has been set). If the last parameters are given they must be the name of a currently mapped window or the two special value 'pointer' and 'keyboard'. If a window name is given the focus is set to this window. If pointer is given the focus dynamically follows the pointer. If keyboard is given the focus follows the keyboard focus. The revertTo parameter specifies what to do when the focus window disappear. It admits the same values as the focusWin parameter. xi::device getmotions device startTime stopTime Reports the motion values that are kept in the device motion history buffer. startTime and stopTime delimit the time interval of interest. It is possible to use the values reported by events with the %t expansion. The most useful event to use in combination with motion history is the <MotionHint> event. It is also possible to specify the 'current' special value which means use the current server time. The first value in the returned list is a time ???. The second value is the number of valuators reported for each event. Follow a list of integers that should be read by groups of 'number of valuators' ints. xi::device intfeedback device ?feedbackId? ?value? When called without the last two parameters, the command report all the integer feedbacks that are supported by the device, giving for each id/minval/maxval/resolution . If 'feedbackId' is given it should match one of the ids reported by the command. In this case the command returns the minval/maxval/resolution of the feedback. If feedbackId and value are both provided, the feedback is set to the value. xi::device kbdfeedback device Not implemented. xi::device list Returns the name of all the devices known to the server. xi::device mode device ?value? When called without the last parameter, the command return the current mode of the device which can be either 'absolute' or 'relative'. If the last parameter is specified it should be one of these two values and it is used to change the mode of the device. xi::device ptrfeedback device threshold numerator denominator Not implemented. The third command 'sendevent' is meant to give applications the means to craft and send extended input events to other applications. This command has yet to be implemented.
