Updated comments, and general cleanup

svn-id: r34203

1 files changed, 54 insertions, 30 deletions

diff --git a/backends/vkeybd/virtual-keyboard-parser.h b/backends/vkeybd/virtual-keyboard-parser.h
index 3f8f567d54..5ad353c516 100644
--- a/backends/vkeybd/virtual-keyboard-parser.h
+++ b/backends/vkeybd/virtual-keyboard-parser.h
@@ -30,8 +30,6 @@
 #include "backends/vkeybd/virtual-keyboard.h"
 
 /**
- TODO - information about optional attributes and their default values
-
 
                    ***************************************
                    ** Virtual Keyboard Pack File Format **
@@ -93,10 +91,12 @@ keyboard layouts for different screen resolutions.
 
 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
+required attributes:
+ - initial_mode: name of the mode the keyboard will show initially
+
+optional attributes:
  - v_align/h_align: where on the screen should the keyboard appear initially
+   (defaults to bottom/center).
 
 child tags:
  - mode
@@ -108,7 +108,7 @@ child tags:
 This tag encapsulates a single mode of the keyboard. Within are a number of 
 layouts, which provide the specific implementation at different resolutions.
 
-attributes:
+required attributes:
  - name: the name of the mode 
  - resolutions: list of the different layout resolutions 
 
@@ -124,25 +124,32 @@ 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:
+required 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
-
+ - type: key | modifier | switch_mode | submit | cancel | clear | delete | 
+   move_left | move_right - see VirtualKeyboard::EventType for explanation
+for key events
+ - code / ascii: describe a key press in ScummVM KeyState format
+for key and modifier events
+ - modifiers: modifier keystate as comma-separated list of shift, ctrl and/or 
+   alt.
+for switch_mode events
+ - mode: name of the mode that should be switched to
 -------------------------------------------------------------------------------
 
 <layout>
 
 These tags encapsulate an implementation of a mode at a particular resolution.
 
-attributes:
+required 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.
+
+optional attributes: 
+ - 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).
 
 child nodes:
  - map: this describes the image map using the same format as html image maps
@@ -151,11 +158,12 @@ child nodes:
 
 <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 
+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). For information on HTML image map
-format see 
+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 
  - http://www.w3schools.com/TAGS/tag_map.asp 
  - http://www.w3schools.com/TAGS/tag_area.asp
 
@@ -163,15 +171,29 @@ format see
 
 namespace Common {
 
-enum ParseMode {
-	kParseFull,				// when loading keyboard pack for first time
-	kParseCheckResolutions  // when re-parsing following a change in screen size
-};
-
-class VirtualKeyboardParser : public Common::XMLParser {
+/**
+ * Subclass of Common::XMLParser that parses the virtual keyboard pack
+ * description file
+ */ 
+class VirtualKeyboardParser : public XMLParser {
 
 public:
 
+	/**
+	 * Enum dictating how extensive a parse will be 
+	 */
+	enum ParseMode {
+		/**
+		 * Full parse - when loading keyboard pack for first time
+		 */
+		kParseFull, 
+		/** 
+		 * Just check resolutions and reload layouts if needed - following a 
+		 * change in screen size
+		 */
+		kParseCheckResolutions
+	};
+
 	VirtualKeyboardParser(VirtualKeyboard *kbd);
 	void setParseMode(ParseMode m) {
 		_parseMode = m;
@@ -216,22 +238,24 @@ protected:
 
 	/** internal state variables of parser */
 	ParseMode _parseMode;
-	VirtualKeyboard::Mode *_mode; // pointer to mode currently being parsed
+	VirtualKeyboard::Mode *_mode;
 	String _initialModeName;
 	bool _kbdParsed;
 	bool _layoutParsed;
 
-	void cleanup();
+	/** Cleanup internal state before parse */
+	virtual void cleanup();
 
+	/** Parser callback function */
 	bool parserCallback_keyboard(ParserNode *node);
 	bool parserCallback_mode(ParserNode *node);
 	bool parserCallback_event(ParserNode *node);
 	bool parserCallback_layout(ParserNode *node);
 	bool parserCallback_map(ParserNode *node);
 	bool parserCallback_area(ParserNode *node);
-	
-	bool closedKeyCallback(ParserNode *node);
+	virtual bool closedKeyCallback(ParserNode *node);
 
+	/** Parse helper functions */
 	byte parseFlags(const String& flags);
 	bool parseRect(Rect *rect, const String& coords);
 	bool parsePolygon(Polygon *poly, const String& coords);