XOE Developers Guide v1.0: A guide to application development within the XOE framework | ||
---|---|---|
Prev | Appendix A. Reference Material | Next |
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).
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.
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.
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>
<virtualkeyboard/>
has two mandatory attributes which identify it uniquely:
language
locale
<map/>
specifies collections of <key/>. <virtualkyeboard/> can have many <map/>'s, which can be switched. It has the following attributes:
name: has to be a unique name identifying this map within <virtualkeyboard/> (required)
mode: if not set, defaults to type "MAP" otherwise can be set to "PEN" which meansthat input will be passed to a character recognition algorithm (optional)
image: specifies an image to use as the background for this <map/> (required)
shift: specifies a name of a map to switch for next character, it is used by <key/> action "SHIFT", look below for full explanation of <key/>(optional)
width: specifies the width of the keymap, should be the same as the width of the image (required)
height: specifies the height of the keymap, should be the same height as the height of the image (required)
Specifies a mapping of a rectangular area into a character or special action.
char: specifies a character that should be issued (required if no 'action' is present)
action: specifies an action to perform (required if no 'char' is present), possible actions are:
SHIFT: switch for next character to map specified by shift attribute of <map/>
CLOSE: close virtual keyboard
GOTO:name: switch permanently to the <map/> identified by 'name'
x0: specifies upper left x coordinate of rectangular area (required)
y0: specifies upper left y coordinate of rectangular area (required)
x1: specifies lower right x coordinate of rectangular area (required)
y1: specifies lower right y coordinate of rectangular area (required)
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.
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