Virtual Keyboard

The new ScummVM virtual keyboard hopes to provide a generalised implementation of a virtual keyboard that will be usable on all of the small backends that require it.

Introduction

The virtual keyboard requires a valid 'keyboard pack' in order to operate. The pack should consist of an XML configuration file and a collection of 24-bit bitmaps. It can come in the form of a compressed zip file or a directory.

In order to make pack creation quick and easy, the virtual keyboard display uses complete bitmap images. To go with each bitmap a HTML-style image map must be created that defines the clickable regions of the image. The primary purpose of the XML configuration file is to contain the image map definitions along with associated event definitions and additional data.

As it is impractical to display all possible keys at the same time, the virtual keyboard has the ability to switch to different modes when special keys are pressed. Also, the virtual keyboard has to work at a range of different resolutions. Therefore, the pack must provide a bitmap and configuration data for each mode at each resolution.

Features

• automatic resolution selection - with re-loading on change of resolution

• preview display - to show the keys that have been pressed while keyboard is active

• modifier keys - allow shift, control, and alt to be added to keystroke without using a separate mode

• special key events - to submit or cancel the keyboard, switch mode, etc

• transparency support - using keycolor bitmaps

• fully draggable

Creating a keyboard pack

In order to create a keyboard pack there are two main stages: creating the bitmaps, and, writing the XML configuration file.

Keyboard bitmaps

ScummVM's image manager can only decode 24-bit BMP images, so make sure you save your images in this format. You need to reserve a particular colour value to be used for transparency. By default the colour used for transparency is set to be #FF00FF, but if you want to use a different colour this can be specified in the configuration file.

XML configuration file

The first step in creating the XML configuration file is to create the HTML imagemap data. The easiest way to do this is by using an standard image map creation tool such as GIMP's Image Map plugin (find it under Filters -> Web -> Image Map...).

Example configuration file

<keyboard modes="normal,caps" initial_mode="normal" v_align="bottom" h_align="centre">
  <mode name="normal" resolutions="640x400,320x200">
    <layout resolution="640x400" bitmap="normal_640x400.bmp" transparent_color="255,0,255">
      <map>
        <area shape="poly" coords="65,50,67,48,94,48,96,50,96,77,94,79,67,79,65,77" target="q" />
        <area shape="poly" coords="105,50,107,48,134,48,136,50,136,77,134,79,107,79,105,77" target="w" />
        <area shape="poly" coords="146,50,148,48,174,48,176,50,176,77,174,79,148,79,146,77" target="e" />
		...
        <area shape="poly" coords="11,89,12,88,69,88,70,89,70,116,69,117,12,117,11,116" target="caps" />
      </map>
	</layout>
	<layout resolution="320x200" bitmap="normal_320x200.bmp" transparent_color="255,0,255">
	  ...
	</layout>
    <event name="a" type="key" code="97" ascii="97" modifiers="" />
    <event name="b" type="key" code="98" ascii="98" modifiers="" />
    <event name="c" type="key" code="99" ascii="99" modifiers="" />
	...
	<event name="caps" type="switch_mode" mode="caps" />
  </mode>

  <mode name="caps" resolutions="640x400">
    <layout resolution="640x400" bitmap="caps_640x480.bmp" transparent_color="255,0,255">
      <map>
        <area shape="poly" coords="65,50,67,48,94,48,96,50,96,77,94,79,67,79,65,77" target="Q" />
		...
      </map>
    </layout>
    <event name="A" type="key" code="97" ascii="65" modifiers="shift" />
    <event name="B" type="key" code="98" ascii="66" modifiers="shift" />
    <event name="C" type="key" code="99" ascii="67" modifiers="shift" />
	...
  </mode>
</keyboard>

Inclusion in build

By default the virtual keyboard is disabled from a ScummVM build. In order to enable it use the --enable-vkeybd flag when running configure.

Using the keyboard

defining keyboard pack path / name of keyboard

in game: pauses system preview area