Read Me
Important note:
---------------
This is an early release of Input Configurator. It still has bugs and is poorly documented. For the moment, no support will be provided for it, including answers to questions sent by e-mail. Also read the copyright notice before using it.
Installation (all platforms, Eclipse installed):
------------------------------------------------
* Uncompress inputConfigurator.zip into a directory of your choice
* ... (COMPLETE ME)
* See the list of executable classes below.
Installation (Windows, no Eclipse):
-----------------------------------
* Uncompress inputConfigurator.zip into a directory of your choice
* Launch 'runIConDraw' in ICon's main folder. Go to the configure menu to open input configurator. If it works, well done. Remember the Alt+C keystroke, it will stop your configuration in case of troube.
Installation (all platforms, no Eclipse):
-----------------------------------------
* Uncompress inputConfigurator.zip into a directory of your choice
* To use ICon library, add in your classpath all .jar files that are in the lib/ directory. They are all required for compilation, except those in lib/examples/. You can also choose to add classes/ path instead of icon.jar.
* See the list of executable classes below.
List of examples:
-----------------
* ... (COMPLETE ME)
How to (re)compile ICon:
----------------------
ICon is precompiled, both into individual class files (classes/) and a big jar file (lib/icon.jar). To regenerate classes and the jar file:
* Download & install ant (http://ant.apache.org)
* From ICon's main directory type 'ant'. This will execute 'build.xml', which is a sort of makefile.
Description of the files:
-------------------------
* IC Files : Input configuration files samples
* native/ : Native libraries (DLLs under windows), mainly for input device management
* icon.jar : Full ICon library
* ibmjs.jar : IBM Java Speech lib for speech recognition (to use it you must install ViaVoice)
* js.jar : Lib for javascript parsing, used by the "Script" device.
* satin.jar : Satin lib, used for geture recognition (see satin_COPYRIGHT.TXT)
* quill.jar : gesture configurator (see satin_COPYRIGHT.TXT)
* lib/jmf/lib/*.jar sun JMF2.1.1 jar files (see http://java.sun.com/products/java-media/jmf/)
* lib/jmf/native/* sun JMF2.1.1 native files (windows and linux)
* xinput.jar : Input device management under X (beta)
* run*.bat : Shortcuts for launching examples under Windows
Short description of the Java packages:
---------------------------------------
* fr.emn.reactiveinput : THE main ICon package containing all basic classes and interfaces: Device, etc.
* fr.emn.reactiveinput.devices : Contains all devices of the library (visible in the left pane of the graphical editor)
* fr.emn.reactiveinput.descriptor : Contains device descriptors (for device serialization/deserialization).
* fr.emn.reactiveinput.net : 'Socket' part, experimental.
* fr.emn.inputeditor : the input configuration visual editor
* fr.emn.lite : graphical objects used in the configuration editor
* fr.emn.cursors : for displaying floating tools on overlay (cursors, toolglasses, etc.)
* fr.emn.win32input.jdirectinput : Windows-specific JNI things, but which are still compiling under other platforms
* fr.emn.win32input.juser32 : the same
* fr.emn.win32input.jwintab : the same
How to use video capture devices (webcams) in ICon ?
------------------------------------------
ICon uses the Java Media Framework (see http://java.sun.com/products/java-media/jmf/) to manage video capture devices such as webcams.
You don't have to install it by your own, as it's provided in the ICon libs path.
JMF does not automatically detect capture devices. It maintains a static list of devices. So, you have to refresh this
registry each time you add or remove a video capture device. There is 2 methods to do it:
1/ you can use the jvm command line argument:
"-Dicon.detect.video=true" (false by default) to force ICon to detect plugged devices at startup
2/ you can use the "refresh" button of the Input editor at runtime.
Devices detection may take a while when devices has a lot of formats (Only RGB formats are supported in ICon).
When available devices are connected to the system, corresponding ICon prototypes are in the
"extended/videocapture".
How to use it inside my application ??
--------------------------------------
At now, there is no full doc provided with ICon. Here is a short explanation on how to begin ICon integration within your software:
1. Include ICon library in your project (see Installation section)
2. Choose something you want to control in your application, and think about how you would describe this using slots (channels). For example, a 'copy' command is described with a boolean slot. A location is described with two float or integer slot.
3. Subclass AbstractDevice, and add one input slot by channel (addIn() method). Put code that controls your application in the update() method. This method is called every time an input slot has changed value. Remember update() must run fast.
4. Subclass ClassFolder, and add an instance of your device.
5. In your main window constructor, create a root folder (FRoot) with your own folder, create a new Configuration with the root folder, and create a new JInputEditor window. You can show this window straight away, or put a 'Configure' command somewhere in your application.
6. Launch your app and edit the empty configuration. You should see your device in the 'application' folder. Drag it in the workspace, and connect something (e.g. a keyboard key) to it. Start the configuration. If it works, try other input configurations or write other devices to control your application.
* For further information:
- Check the fr.emn.reactiveinput package in the JavaDoc API (there is few chances that you'll have to use other packages).
- Look at sources of the fr.emn.examples.icondraw example. Seeing the JIconDraw source will help you a lot for the step 5 previously described.
- Look at the Device sources in the fr.emn.reactiveinput.devices package. It should help you for writing complicated devices.
* Design tips:
- First start with something easy, e.g. launching a command. Use ICon to control global states or commands, then describe more context-sensitive things. ICon integration is a progressive process.
- Never think about how your application will be controlled: no 'mouse' or 'enter key' slot ! Devices and slots must only describe your application model.
Additional notes:
-----------------
This product includes software developed by the Group for User Interface Research at the University of California at Berkeley (Satin).