Virtual-Input Package

Introduction:

This package implements the XOE Interface IVirtualInput. It is a collection of classes implementing input methods other than a standard keyboard and pointing device. It is supposed to replace or supplement those on devices and platforms that do not have them or require additional features.

Everything to do with input, but not directly related to hardware is supposed to be part of this package.

This package includes the org.xoe.input.virtual.VirtualKeyboard class that replaces keyboard input on pda devices that do not have a physical keyboard and on which input can only be done using a pointing device (mouse or touch-screen).

Implementation:

The main class org.xoe.input.virtual.VirtualKeyboard is an implementation of the XOE service IVirtualInput. It can be either instantiated by providing an XML configuration file, or it can be extended to add additional functionality.

The configuration file is not a part of this package. It is normally a part of some other package, which instantiates VirtualKeyboard. Any package instantiating VirtualKeyboard should also include all other resources necessary. One example of a package instantiating VirtualKeyboard is package Virtual-Keyboard-US.

XML Configuration File:

This file should define only one <virtualkeyboard/>, if there is more than one all the others will not be considered. An instantiated virtual keyboard will be identified by the combination of two attributes 'language' and 'locale', eg:

<virtualkeyboard language="XX" locale="YY">.

It has to also include at least one <map/> defining mapping of keys to keyboard input. <map/> has following attributes: 'name', 'type', 'mode', 'image', 'shift', 'width' and 'height'. The attribute name should be unique, in order to identify a given <map/> within a <virtualkeyboard/>. Type is not a required filed, its default value is "MAP", but it can be set to "PEN". Value "PEN" sets areas not covered by special keys to perform stroke-based recognition for input.

Each <map/> can contain multiple <key/>'s that can be used to perform special actions or enter characters. A <key/> that is used to enter 'A' would look like:

<key char="A" x0="10" y0="10" x1="20 y1="20"/>.

Clicking anywhere within the square defined by points (x0, y0) and (x1, y1) would result in a keyboard event for letter 'A'. Another type of <key/> is an action key, eg:

<key action="CLOSE" x0="10" y0="10" x1="20 y1="20"/>.

Receiving an input within the defined rectangle would result in the closing of the virtual keyboard on the screen.

Example:

A simple layouts.xml defining virtual keyboard could look like that:

   
   <virtualkeyboard language="XX" locale="YY">
      <map name="simple" shift="simple-shift" image="simple.gif" width="80" height="20">
	 <key char="a"                   x0="0" y1"=0" x1="19" y1="19"/>
	 <key action="SHIFT"             x0="21" y1"=0" x1="39" y1="19"/>
	 <key action="GOTO:simple-shift" x0="41" y1"=0" x1="59" y1="19"/>
	 <key action="CLOSE"             x0="61" y1"=0" x1="79" y1="19"/>
      </map>
      
      <map name="simple-shift" shift="simple" image="simple-shift.gif" width="80" height="20">
	 <key char="A"                   x0="0" y1"=0" x1="19" y1="19"/>
	 <key action="SHIFT"             x0="21" y1"=0" x1="39" y1="19"/>
	 <key action="GOTO:simple"       x0="41" y1"=0" x1="59" y1="19"/>
	 <key action="CLOSE"             x0="61" y1"=0" x1="79" y1="19"/>
      </map>
   </virtualkeyboard>

layouts.xml specifications:

<virtualkeyboard/>

has two mandatory attributes which identify it uniquely:

<map/>

specifies collections of <key/>. <virtualkyeboard/> can have many <map/>'s, which can be switched. It has the following attributes:

<key/>

Specifies a mapping of a rectangular area into a character or special action.

File location:

The file layouts.xml should be stored in the resources directory, and images should be stored in a subdirectory named images directly below layouts.xml.

Creating a simple virtual keyboard:

In order to create a package defining a simple keyboard, we will need layouts.xml, 'package-in.xml', 'services.xml' and images for each <map/> defined in <virtualkeyboard/>.

For layouts.xml, we will use the example above and put it in the resources directory of our package. We will need to place 2 images simple.gif and simple-shift.gif in resources/images. We will have to create a package description file. A simple one could look like:

   
   <?xml version="1.0"?>
   <!DOCTYPE package PUBLIC "-//TVT//DTD XOEPKG 1.0//EN"
   "http://www.xoe.org/DTD/xoe-package.dtd">
   <package name="virtual-keyboard-us" version="0.1" task='true'>
      <info>
	 <description>
	    Simple virtual keyboard example
	 </description>
      </info>
      <requires>
	 <dep name="virtual-input" predepends="true" ns='http://www.xoe.org/installer/base/package' />
      </requires>
   </package>

If you need more information about package-in.xml file please look at the package system documentation. Since the virtual keyboard is a XOE service, we have to provide services.xml file in resources directory:

   
   <?xml version="1.0"?>
   <services>
      <service class='org.xoe.input.virtual.VirtualKeyboard' config='layouts.xml'/>
   </services>

A structure of our package is going to look like:


      
|-package-in.xml
|-resources
  \ 
   |-layouts.xml
   |-services.xml
   |-images
      \
      |-simple.gif
      |-simple-shift.gif