Added comments in virtual-keyboard-parser.h describing the file format. Added a delay functionality to the delivery of artificial events in DefaultEventManager, to get round events being ignored when delivered consecutively.

svn-id: r33012

4 files changed, 148 insertions, 4 deletions

diff --git a/backends/common/virtual-keyboard-parser.cpp b/backends/common/virtual-keyboard-parser.cpp
index 8e788f53d4..7b1e79e937 100644
--- a/backends/common/virtual-keyboard-parser.cpp
+++ b/backends/common/virtual-keyboard-parser.cpp
@@ -260,6 +260,9 @@ bool VirtualKeyboardParser::parserCallback_Event() {
 
 		evt.type = VirtualKeyboard::kEventSwitchMode;
 		evt.data = new Common::String(evtNode->values["mode"]);
+	} else if (type == "close") {
+		evt.type = VirtualKeyboard::kEventClose;
+		evt.data = 0;
 	} else
 		return parserError("Event type '%s' not known", type.c_str());
 
diff --git a/backends/common/virtual-keyboard-parser.h b/backends/common/virtual-keyboard-parser.h
index 69ca0a99a6..cd2ea28faf 100644
--- a/backends/common/virtual-keyboard-parser.h
+++ b/backends/common/virtual-keyboard-parser.h
@@ -29,6 +29,138 @@
 #include "common/xmlparser.h"
 #include "backends/common/virtual-keyboard.h"
 
+/**
+ TODO - information about optional attributes and their default values
+
+
+                   ***************************************
+                   ** Virtual Keyboard Pack File Format **
+                   ***************************************
+
+The new virtual keyboard for ScummVM is implemented in the same way as a HTML 
+ImageMap. It uses a single bitmap of the entire keyboard layout and then a 
+image map description allows certain areas of the bitmap to be given special 
+actions. Most of these actions will be a virtual key press event, but there 
+will also be special keys that will change the keyboard layout or close the 
+keyboard. The HTML image map description is contained in a larger XML file that
+can describe all the different modes of the keyboard, and also different 
+keyboard layouts for different screen resolutions.
+
+                ********************************************
+                ** Example keyboard pack description 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>
+
+*************************
+** Description of tags **
+*************************
+
+<keyboard>
+
+This is the required, root element of the file format. 
+
+attributes:
+ - modes: lists all the modes that the keyboard pack contains
+ - initial_mode: which mode the keyboard should show initially
+ - v_align/h_align: where on the screen should the keyboard appear initially
+
+child tags:
+ - mode
+
+-------------------------------------------------------------------------------
+
+<mode>
+
+This tag encapsulates a single mode of the keyboard. Within are a number of 
+layouts, which provide the specific implementation at different resolutions.
+
+attributes:
+ - name: the name of the mode 
+ - resolutions: list of the different layout resolutions 
+
+child tags:
+ - layout
+ - event
+
+-------------------------------------------------------------------------------
+
+<event>
+
+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
+same as an event's name.
+
+attributes:
+ - name: name of the event
+ - type: what sort of event is it (key | switch_mode | close)
+ - for key events
+   - code / ascii / modifiers: describe a key press in ScummVM KeyState format
+ - for switch_mode events
+   - mode: the mode that should be switched to
+
+-------------------------------------------------------------------------------
+
+<layout>
+
+These tags encapsulate an implementation of a mode at a particular resolution.
+
+attributes:
+ - 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,b,g format that will be used for keycolor 
+   transparency.
+
+child nodes:
+ - 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 exact 
+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). For information on HTML image map
+format see 
+ - http://www.w3schools.com/TAGS/tag_map.asp 
+ - http://www.w3schools.com/TAGS/tag_area.asp
+
+*/
+
 namespace Common {
 
 enum ParseMode {
@@ -42,7 +174,6 @@ class VirtualKeyboardParser : public Common::XMLParser {
 
 public:
 
-
 	VirtualKeyboardParser(VirtualKeyboard *kbd);
 	void setParseMode(ParseMode m) {
 		_parseMode = m;
diff --git a/backends/events/default/default-events.cpp b/backends/events/default/default-events.cpp
index 6113f0e65c..76a61d1342 100644
--- a/backends/events/default/default-events.cpp
+++ b/backends/events/default/default-events.cpp
@@ -193,6 +193,7 @@ DefaultEventManager::DefaultEventManager(OSystem *boss) :
 	}
 
 	_vk = new Common::VirtualKeyboard();
+	_artificialEventCounter = 0;
 }
 
 DefaultEventManager::~DefaultEventManager() {
@@ -351,10 +352,15 @@ void DefaultEventManager::processMillis(uint32 &millis) {
 bool DefaultEventManager::pollEvent(Common::Event &event) {
 	uint32 time = _boss->getMillis();
 	bool result;
-
+	
 	if (!_artificialEventQueue.empty()) {
-		event = _artificialEventQueue.pop();
-		result = true;
+		// delay the feeding of artificial events
+		if (++_artificialEventCounter % kArtificialEventDelay == 0) {
+			event = _artificialEventQueue.pop();
+			result = true;
+			_artificialEventCounter = 0; 
+		} else
+			result = _boss->pollEvent(event);
 	} else 	
 		result = _boss->pollEvent(event);
 
diff --git a/backends/events/default/default-events.h b/backends/events/default/default-events.h
index e836160188..1a968cad0a 100644
--- a/backends/events/default/default-events.h
+++ b/backends/events/default/default-events.h
@@ -49,6 +49,10 @@ class DefaultEventManager : public Common::EventManager {
 	Common::VirtualKeyboard *_vk;
 
 	Common::Queue<Common::Event> _artificialEventQueue;
+	int _artificialEventCounter;
+	enum {
+		kArtificialEventDelay = 10
+	};
 
 	Common::Point _mousePos;
 	int _buttonState;