Introduction
Most graphical user interfaces are based on the idea that the user interacts with the computer through a keyboard and a single pointing device (mouse, trackball, touchpad, etc). There are however cases where the use of two (or more) pointing devices can be appropriate, as demonstrated by evaluations and systems that feature bi-manual interaction. The use of a second pointing device, such as a trackball in the non-dominant hand, can for instance be useful to control camera altitude (zoom level) in a ZUI, or the position of a floating palette grouping click-through tools. The MPD add-on for ZVTM enables programmers to support multiple pointing devices in their ZVTM-based applications. This specific module is distributed as an add-on because its use implies many constraining requirements, both at compile time and run time.
Requirements
The ZVTM-MPD module relies on the Domino library (included in the package) for handling events sent by USB pointing devices that respect the HID protocol. Domino has the following requirements:
- Linux with module evdev loaded and handling pointing devices (most of the Debian and SuSE distributions do this by default). You can test for evdev by typing (as root): modprobe evdev. If evdev is not present on your system, please refer to your distribution or documentation on the Web to find out how to install it.
- a Java VM v1.5.0 or later.
- an XML parser supporting DOM level 3 and an XSLT engine (included in the release).
Installation
MPD in ZVTM
Download and uncompress ZVTM-MPD in ZVTM's main directory. This will add zvtm-mpd.jar in your lib/ directory, and package net.claribole.zvtm.mpd in the source code and class trees. Other Xerces and Batik-derived libraries will be copied in your lib/ directory and should be included in your classpath. Note that these may interfere with the version of Xerces that ships with ZVTM. it is a good idea to remove xmlParserApis.jar and xercesImpl.jar from your classpath (equivalent classes are included in the Xerces and Batik libraries that ship with ZVTM-MPD).
The included build.xml Ant file should also be used in replacement of the standard one. You can also copy the Domino and Xerces pathelement declarations from this file to your own if you would rather keep your own file.
ZVTM-MPD's JAR file can be rebuilt with the following command: ant mpdjar
Linux and X
First, add a directory entry to your LD_LIBRARY_PATH environment variable pointing to the directory that contains libdomino.so. By default this file is placed in ZVTM's lib/ directory.
Most of the time, you will not want all pointing devices to control the cursor: only the pointing device associated with the dominant hand will. You should therefore edit your XF86Config or xorg.conf file so that the "Device" option of the pointing device in the InputDevice section excludes the non-dominant hand pointing device (e.g. change it from /dev/input/mice to /dev/input/mouse0 or whatever suits you).
Finally, you should check that you have /dev/input/event* entries on your filesystem, with -rw-rw-rw- access rights (if note change them with chmod).
Testing
You can try to launch net.claribole.zvtm.mpd.MPDManager (with all appropriate JAR files in your classpath) to test the module. This program should list all available USB pointing devices.
Using MPD capabilities in ZVTM
Non-dominant hand pointing devices (as opposed to the main pointing device, supposed to be operated by the user's dominant hand) are handled through net.claribole.zvtm.mpd.MPDManager and your own instantiation of interface net.claribole.zvtm.mpd.MPDAppEventHandler. The latter approximately mirrors events found in com.xerox.VTM.engine.AppEventHandler that is used for handling main pointing device events.
The first thing to do is to define a class that implements interface MPDAppEventHandler. This is where to put the code executed in response to events fired by secondary pointing devices. All callbacks provide a link to the device that fired the event, through the Domino Socket object. It is possible to identify which pointing device fired the event for instance by getting its name, e.g. (if s is the Socket): s.getDeviceDescriptor().getName(), which returns a String such as "Logitech USB-PS/2 Optical Mouse". Note however that it will be faster to test the Socket object itself. The entire list of pointing devices can be obtained through MPDManager's getAvailablePointingDevices() method.
Once the implementation of MPDAppEvtHandler has been defined, you can create an instance of MPDManager. The constructor takes as arguments:
- an instance of the previously defined MPDAppEvtHandler implementation,
- the ZVTM view this MPD event handler should be associated with.
The MPDManager class instance lets you access all available pointing devices as Socket objects as mentioned earlier. Based on each device name (or any other attribute), you can then decide whether you want the MPD module to listen for events fired by it or not, using method addListener().
The following code shows an example of how to create an MPDManager and listen to all pointing devices except the one called "Logitech USB-PS/2 Optical Mouse", which is supposed to be the main pointing device (and which is thus handled through Java's main AWT event queue and controls ZVTM's cursor).
Refer to the ZVTM-MPD API documentation for more information about this package.
Terminating ZVTM-MPD based applications
IMPORTANT: Domino launches various threads on its own when invoked from ZVTM-MPD, that need to be terminated correctly before exiting client applications. It is therefore very important to call MPDManager.terminate(); when exiting your application (e.g. just before doing System.exit(0);).
