TrustedUser
574
edits
Difference between revisions of "Virtual Keyboard"
Jump to navigation
Jump to search
→Information for keyboard pack creators: Removed Reference to SVN and changed link to Git SCM
(→Information for keyboard pack creators: Removed Reference to SVN and changed link to Git SCM) |
|||
| (6 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
''''' | == Introduction == | ||
'''Note:''' The virtual keyboard is being actively developed. | |||
The ScummVM virtual keyboard provides a generalized implementation | |||
of a virtual keyboard that will be usable on any backends that wish to make use of it. | |||
== Design == | |||
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). | |||
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 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. | |||
of | |||
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. | |||
== Key Features == | |||
* ''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 | |||
pressed | |||
* Modifier keys - allow Shift, Control, and Alt to be added to keystroke without using a separate mode | |||
* | * Special events - to submit or cancel the keyboard, switch mode, etc | ||
* | * Transparency support - using keycolor bitmaps | ||
* | * Can be dragged around the screen | ||
== Special Events == | |||
In addition to the mapping of keys and the keyboard modes you can also wire up a number of special events to image map areas. | |||
* | The current 'special events' are as follows. | ||
* submit - Submit all the events queues (as shown in the display area) and close the keyboard. | |||
<syntax type="xml"> | |||
<event name="name_of_image_map_rect" type="submit" /> | |||
</syntax> | |||
* cancel - Close the keyboard and cancel all queued events. | |||
<syntax type="xml"> | |||
<event name="name_of_image_map_rect" type="cancel" /> | |||
</syntax> | |||
* clear - Clear all queued events. | |||
<syntax type="xml"> | |||
<event name="name_of_image_map_rect" type="clear" /> | |||
</syntax> | |||
* delete - Delete the last event from the queue (think backspace). | |||
<syntax type="xml"> | |||
<event name="name_of_image_map_rect" type="delete" /> | |||
</syntax> | |||
* move_left - Move left one place in the stacked event list (moves the position in the display_area). | |||
<syntax type="xml"> | |||
<event name="name_of_image_map_rect" type="move_left" /> | |||
</syntax> | |||
* 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"> | |||
<event name="name_of_image_map_rect" type="move_right" /> | |||
</syntax> | |||
== Information for keyboard pack creators == | == Information for keyboard pack creators == | ||
''''' | '''NOTE:''' It should be noted that the ''wise'' keyboard pack author uses SVG for there keyboard image(s) and just saves bitmaps at whatever resolutions are needed. It also makes it easy to add extra resolution images later if needed. | ||
In order to create a keyboard pack these are the main stages: | |||
* Create the keyboard bitmaps. | |||
* Construct the HTML image maps (use something like GIMP). | |||
* Writing the XML configuration file and incorporate the image maps. | |||
You can view the files that make up our default keyboard pack in our source code repository [https://github.com/scummvm/scummvm/tree/master/backends/vkeybd/packs/vkeybd_default here]. This should serve as a useful reference in conjunction with the information below. | |||
=== Keyboard bitmaps === | === Keyboard bitmaps === | ||
| Line 53: | 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 | ==== Tag Descriptions ==== | ||
{| border="1" cellspacing="0" | |||
{| | ! Tag | ||
! Description | |||
! Required Attributes | |||
! Optional Attributes | |||
! Children | |||
|- style="background:AliceBlue; color:black" | |||
|- | ! <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/ | | '''v_align'''/'''h_align''': where on the screen should the keyboard appear initially (defaults to bottom/centre). | ||
! <mode> | |||
|- | |- style="background:Azure; color:black" | ||
! <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 | | | ||
| '''<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 | type: '''key''' | '''modifier''' | '''switch_mode''' | '''submit''' | '''cancel''' | '''clear''' | '''delete''' | '''move_left''' | '''move_right''' | ||
for key events | for key events | ||
code / | code / ASCII: describe a key press in ScummVM KeyState format | ||
for key and modifier events | for key and modifier events | ||
| Line 92: | 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 | ||
| | | | ||
| | | | ||
| Line 169: | Line 200: | ||
== Information for users == | == Information for users == | ||
The keyboard will pause the underlying game engine when in use. | |||
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). | |||
preview area | |||