Open main menu
ScummVM :: Wiki

Difference between revisions of "Virtual Keyboard"

Virtual Keyboard (view source)

Revision as of 13:51, 9 June 2009

833 bytes added ,  13:51, 9 June 2009
Cleanup table format and start to improve text a little.
(Cleanup table format and start to improve text a little.)
Line 1: Line 1:
The ScummVM virtual keyboard hopes to provide a generalised implementation
== Introduction ==
of a virtual keyboard that will be usable on all backends that
 
require it.
'''Note:''' The virtual keyboard is being actively developed.
 
The ScummVM virtual keyboard provides a generalised implementation
of a virtual keyboard that will be usable on any backends that wish to make use of it.


== Introduction ==
== Design ==


The keyboard uses a 'queued events' model (so anything you type is queued and then passed back to the main event routine when the keyboard is closed) so it is best used for entering input rather then as part of the game input system (look towards the [[Keymapping_Improvements]] for systems for real time input).  
The 1st key design consideration people need to be aware of is that the keyboard is rendered onto our 16bit overlay. This means that the keyboard exists outside of the scope of the running engine (the engine is paused when the overlay/keyboard is shown).


This also means that the virtual keyboard (in it's default state) will ensure the engine is paused when it is active.
By virtue of this design consideration the keyboard uses a 'queued events' model (so anything you select is queued and then injected back to the main event routine when the keyboard is closed) so it is best used for entering strings (save names etc.) rather than as part of the game input system (look towards the [[Keymapping_Improvements]] for systems for real time input).  


The virtual keyboard requires a valid 'keyboard pack' in order to operate. The
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.
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
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.
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
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.
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.


== Key Features ==
== Key Features ==


* Automatic resolution selection - with re-loading on change of resolution
* ''Automatic resolution selection - with re-loading on change of resolution'' - Not sure this works.


* Preview display - to show the keys that have been pressed while keyboard is active
* Preview display - to show the keys that have been pressed while keyboard is active
Line 37: Line 30:
* Transparency support - using keycolor bitmaps  
* Transparency support - using keycolor bitmaps  


* Draggable
* Can be dragged around the screen


== Special Events ==
== Special Events ==
Line 61: Line 54:
<event name="name_of_image_map_rect" type="delete" />
<event name="name_of_image_map_rect" type="delete" />
</syntax>
</syntax>
* move_left - Move left one place in the stacked event queue (moves the position in the display_area).
* move_left - Move left one place in the stacked event list (moves the position in the display_area).
<syntax type="xml">
<syntax type="xml">
<event name="name_of_image_map_rect" type="move_left" />
<event name="name_of_image_map_rect" type="move_left" />
</syntax>
</syntax>
* move_right - Move right one place in the stacked event queue if your not at the last event (moves the position in the display_area).
* move_right - Move right one place in the stacked event list if you’re not at the last event (moves the position in the display_area).
<syntax type="xml">
<syntax type="xml">
<event name="name_of_image_map_rect" type="move_right" />
<event name="name_of_image_map_rect" type="move_right" />
Line 84: Line 77:
=== Keyboard bitmaps ===
=== 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 color value to be used for transparency. By default the color used for transparency is set to be #FF00FF, but if you want to use a different color this can be specified in the configuration file.
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 ===
=== XML configuration file ===
Line 92: Line 85:
After creating all the image maps you should put the exported HTML for all the bitmaps into a single XML file. Then you can start adding the rest of the configuration XML around it. The rest of this section provides descriptions of the tags and example complete file.
After creating all the image maps you should put the exported HTML for all the bitmaps into a single XML file. Then you can start adding the rest of the configuration XML around it. The rest of this section provides descriptions of the tags and example complete file.


==== Tag descriptions ====
==== Tag Descriptions ====


'''''TODO: format table properly'''''
{| border="1" cellspacing="0"
{|  
! Tag  
| Tag  
! Description
| Description
! Required Attributes
| Required attributes
! Optional Attributes
| Optional attributes
! Children
| Children
|- style="background:AliceBlue; color:black"
|-  
! <keyboard>
| <keyboard>
| This is the required, root element of the file format.  
| This is the required, root element of the file format.  
| initial_mode: name of the mode the keyboard will show initially.
| '''initial_mode''': name of the mode the keyboard will show initially.
| v_align/h_align: where on the screen should the keyboard appear initially (defaults to bottom/center).
| '''v_align'''/'''h_align''': where on the screen should the keyboard appear initially (defaults to bottom/centre).
| mode
! <mode>
|-
|- style="background:Azure; color:black"
| <mode>  
! <mode>
| This tag encapsulates a single mode of the keyboard. Within are a number of  
| This tag encapsulates a single mode of the keyboard. Within are a number of  
layouts, which provide the specific implementation at different resolutions.
layouts, which provide the specific implementation at different resolutions.
| name: the name of the mode  
| '''name''': the name of the mode  
resolutions: list of the different layout resolutions  
'''resolutions''': list of the different layout resolutions  
| layout
|  
event
| '''<layout>''' and '''<event>'''
|- style="background:HoneyDew; color:black"
! <layout>
| These tags encapsulate an implementation of a mode at a particular resolution.
| '''resolution''': the screen resolution that this layout is designed for
'''bitmap''': filename of the 24-bit bitmap that will be used for this layout (with no path)
| '''transparent_color''': color in r,g,b format that will be used for keycolor transparency (defaults to (255,0,255).
'''display_font_color''': color in r,g,b format that will be used for the text of the keyboard display (defaults to (0,0,0).
| '''<map>''': This describes the image map using the same format as HTML image maps.
|-
|-
| <event>
! <map>
| These tags describe the image map for a particular layout. It uses the same
format as HTML image maps. The only area shapes that are supported are
rectangles and polygons. The target attribute of each area should be the name
of an event for this mode (see <event> tag). They will usually be generated by
an external tool such as GIMP's Image Map plugin, and so will not be written
by hand, but for more information on HTML image map format see W3Schools pages on the [http://www.w3schools.com/TAGS/tag_map.asp <map>] and [http://www.w3schools.com/TAGS/tag_area.asp <area>] tags.
|
|
| '''<area>''': This is part of the image map using the same format as HTML image maps.
|- style="background:HoneyDew; color:black"
! <event>
| These tags describe a particular event that will be triggered by a mouse click
| These tags describe a particular event that will be triggered by a mouse click
on a particular area. The target attribute of each image map area should be the
on a particular area. The target attribute of each image map area should be the
same as an event's name.
same as an event's name.
| name: name of the event
| name: name of the event
type: key | modifier | switch_mode | submit | cancel | clear | delete | move_left | move_right - see VirtualKeyboard::EventType for explanation
type: '''key''' | '''modifier''' | '''switch_mode''' | '''submit''' | '''cancel''' | '''clear''' | '''delete''' | '''move_left''' | '''move_right'''


for key events
for key events
code / ascii: describe a key press in ScummVM KeyState format  
code / ASCII: describe a key press in ScummVM KeyState format  


for key and modifier events
for key and modifier events
Line 131: Line 142:
for switch_mode events
for switch_mode events
mode: name of the mode that should be switched to
mode: name of the mode that should be switched to
|
|
|-
| <layout>
| These tags encapsulate an implementation of a mode at a particular resolution.
| resolution: the screen resolution that this layout is designed for
bitmap: filename of the 24-bit bitmap that will be used for this layout
| transparent_color: color in r,g,b format that will be used for keycolor transparency (defaults to (255,0,255).
display_font_color: color in r,g,b format that will be used for the text of the keyboard display (defaults to (0,0,0).
| map: this describes the image map using the same format as html image maps
|-
| <map>
| These tags describe the image map for a particular layout. It uses the same
format as HTML image maps. The only area shapes that are supported are
rectangles and polygons. The target attribute of each area should be the name
of an event for this mode (see <event> tag). They will usually be generated by
an external tool such as GIMP's Image Map plugin, and so will not be written
by hand, but for more information on HTML image map format see W3Schools pages on the [http://www.w3schools.com/TAGS/tag_map.asp <map>] and [http://www.w3schools.com/TAGS/tag_area.asp <area>] tags.
|
|
|
|
|
Line 208: Line 200:


== Information for users ==
== Information for users ==
 
The keyboard will pause the underlying game engine when in use.
'''''TODO'''''
All text/events that are going to be passed back to the game engine are shown in the preview area (display_area in the keyboard pack).
pauses system
preview area
DJWillis
208

edits

Retrieved from "https://wiki.scummvm.org/index.php?title=Special:MobileDiff/11123"