Updated comments, and general cleanup

svn-id: r34203

5 files changed, 197 insertions, 97 deletions

diff --git a/backends/vkeybd/virtual-keyboard-gui.h b/backends/vkeybd/virtual-keyboard-gui.h
index ae6385e30b..e99d552479 100644
--- a/backends/vkeybd/virtual-keyboard-gui.h
+++ b/backends/vkeybd/virtual-keyboard-gui.h
@@ -34,21 +34,61 @@
 
 namespace Common {
 
+/**
+ * Class to handle the drawing of the virtual keyboard to the overlay, and the
+ * execution of the keyboard's main loop.
+ * This includes the blitting of the appropriate bitmap in the correct location,
+ * as well as the drawing of the virtual keyboard display.
+ */
 class VirtualKeyboardGUI {
 
 public:
 
 	VirtualKeyboardGUI(VirtualKeyboard *kbd);
 	~VirtualKeyboardGUI();
-	
+
+	/**
+	 * Updates the GUI when the Mode of the keyboard is changes
+	 */
 	void initMode(VirtualKeyboard::Mode *mode);
-	void checkScreenChanged();
+
+	/**
+	 * Starts the drawing of the keyboard, and runs the main event loop.
+	 */
 	void run();
+
+	/**
+	 * Interrupts the event loop and resets the overlay to its initial state.
+	 */	 
 	void close();
+	
 	bool isDisplaying() { return _displaying; }
+
+	/**
+	 * Reset the class to an initial state
+	 */
 	void reset();
+
+	/**
+	 * Activates drag mode. Takes the keyboard-relative coordinates of the 
+	 * cursor as an argument.
+	 */
 	void startDrag(int16 x, int16 y);
+
+	/**
+	 * Deactivates drag mode
+	 * */
 	void endDrag();
+	
+	/**
+	 * Checks for a screen change in the backend and re-inits the virtual 
+	 * keyboard if it has.
+	 */
+	void checkScreenChanged();
+	
+	/**
+	 * Sets the GUI's internal screen size variables
+	 */ 
 	void initSize(int16 w, int16 h);
 
 private:
diff --git a/backends/vkeybd/virtual-keyboard-parser.cpp b/backends/vkeybd/virtual-keyboard-parser.cpp
index 8a276cd959..a2b035f1b5 100644
--- a/backends/vkeybd/virtual-keyboard-parser.cpp
+++ b/backends/vkeybd/virtual-keyboard-parser.cpp
@@ -173,7 +173,7 @@ bool VirtualKeyboardParser::parserCallback_event(ParserNode *node) {
 	if (_mode->events.contains(name))
 		return parserError("Event '%s' has already been defined", name.c_str());
 
-	VirtualKeyboard::Event *evt = new VirtualKeyboard::Event();
+	VirtualKeyboard::VKEvent *evt = new VirtualKeyboard::VKEvent();
 	evt->name = name;
 
 	String type = node->values["type"];
@@ -182,7 +182,7 @@ bool VirtualKeyboardParser::parserCallback_event(ParserNode *node) {
 			delete evt;
 			return parserError("Key event element must contain code and ascii attributes");
 		}
-		evt->type = VirtualKeyboard::kEventKey;
+		evt->type = VirtualKeyboard::kVKEventKey;
 
 		KeyState *ks = (KeyState*) malloc(sizeof(KeyState));
 		ks->keycode = (KeyCode)atoi(node->values["code"].c_str());
@@ -198,7 +198,7 @@ bool VirtualKeyboardParser::parserCallback_event(ParserNode *node) {
 			return parserError("Key modifier element must contain modifier attributes");
 		}
 		
-		evt->type = VirtualKeyboard::kEventModifier;
+		evt->type = VirtualKeyboard::kVKEventModifier;
 		byte *flags = (byte*) malloc(sizeof(byte));
 		*(flags) = parseFlags(node->values["modifiers"]);
 		evt->data = flags;
@@ -209,24 +209,24 @@ bool VirtualKeyboardParser::parserCallback_event(ParserNode *node) {
 			return parserError("Switch mode event element must contain mode attribute");
 		}
 
-		evt->type = VirtualKeyboard::kEventSwitchMode;
+		evt->type = VirtualKeyboard::kVKEventSwitchMode;
 		String& mode = node->values["mode"];
 		char *str = (char*) malloc(sizeof(char) * mode.size() + 1);
 		memcpy(str, mode.c_str(), sizeof(char) * mode.size());
 		str[mode.size()] = 0;
 		evt->data = str;
 	} else if (type.equalsIgnoreCase("submit")) {
-		evt->type = VirtualKeyboard::kEventSubmit;
+		evt->type = VirtualKeyboard::kVKEventSubmit;
 	} else if (type.equalsIgnoreCase("cancel")) {
-		evt->type = VirtualKeyboard::kEventCancel;
+		evt->type = VirtualKeyboard::kVKEventCancel;
 	} else if (type.equalsIgnoreCase("clear")) {
-		evt->type = VirtualKeyboard::kEventClear;
+		evt->type = VirtualKeyboard::kVKEventClear;
 	} else if (type.equalsIgnoreCase("delete")) {
-		evt->type = VirtualKeyboard::kEventDelete;
+		evt->type = VirtualKeyboard::kVKEventDelete;
 	} else if (type.equalsIgnoreCase("move_left")) {
-		evt->type = VirtualKeyboard::kEventMoveLeft;
+		evt->type = VirtualKeyboard::kVKEventMoveLeft;
 	} else if (type.equalsIgnoreCase("move_right")) {
-		evt->type = VirtualKeyboard::kEventMoveRight;
+		evt->type = VirtualKeyboard::kVKEventMoveRight;
 	} else {
 		delete evt;
 		return parserError("Event type '%s' not known", type.c_str());
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);
diff --git a/backends/vkeybd/virtual-keyboard.cpp b/backends/vkeybd/virtual-keyboard.cpp
index 0b2933fca0..f76940343e 100644
--- a/backends/vkeybd/virtual-keyboard.cpp
+++ b/backends/vkeybd/virtual-keyboard.cpp
@@ -54,9 +54,9 @@ VirtualKeyboard::~VirtualKeyboard() {
 
 void VirtualKeyboard::deleteEvents() {
 	ModeMap::iterator it_m;
-	EventMap::iterator it_e;
+	VKEventMap::iterator it_e;
 	for (it_m = _modes.begin(); it_m != _modes.end(); it_m++) {
-		EventMap *evt = &(it_m->_value.events);
+		VKEventMap *evt = &(it_m->_value.events);
 		for (it_e = evt->begin(); it_e != evt->end(); it_e++)
 			delete it_e->_value;
 	}
@@ -73,7 +73,7 @@ void VirtualKeyboard::reset() {
 	_kbdGUI->reset();
 }
 
-bool VirtualKeyboard::loadKeyboardPack(Common::String packName) {
+bool VirtualKeyboard::loadKeyboardPack(String packName) {
 
 	_kbdGUI->initSize(_system->getOverlayWidth(), _system->getOverlayHeight());
 
@@ -130,7 +130,7 @@ bool VirtualKeyboard::loadKeyboardPack(Common::String packName) {
 		return false;
 	}
 
-	_parser->setParseMode(kParseFull);
+	_parser->setParseMode(VirtualKeyboardParser::kParseFull);
 	_loaded = _parser->parse();
 	if (_loaded)
 		printf("Keyboard pack '%s' loaded successfully!\n", packName.c_str());
@@ -140,50 +140,50 @@ bool VirtualKeyboard::loadKeyboardPack(Common::String packName) {
 
 bool VirtualKeyboard::checkModeResolutions()
 {
-	_parser->setParseMode(kParseCheckResolutions);
+	_parser->setParseMode(VirtualKeyboardParser::kParseCheckResolutions);
 	_loaded = _parser->parse();
 	if (_currentMode) _kbdGUI->initMode(_currentMode);
 	return _loaded;
 }
 
-Common::String VirtualKeyboard::findArea(int16 x, int16 y) {
+String VirtualKeyboard::findArea(int16 x, int16 y) {
 	return _currentMode->imageMap.findMapArea(x, y);
 }
 
-void VirtualKeyboard::processAreaClick(const Common::String& area) {
+void VirtualKeyboard::processAreaClick(const String& area) {
 	if (!_currentMode->events.contains(area)) return;
-	Event *evt = _currentMode->events[area];
+	VKEvent *evt = _currentMode->events[area];
 
 	switch (evt->type) {
-	case kEventKey: {
+	case kVKEventKey: {
 		// add virtual keypress to queue
-		_keyQueue.insertKey(*(Common::KeyState*)evt->data);
+		_keyQueue.insertKey(*(KeyState*)evt->data);
 		break;
 	}
-	case kEventModifier:
+	case kVKEventModifier:
 		_keyQueue.toggleFlags(*(byte*)(evt->data));
 		break;
-	case kEventSwitchMode:
+	case kVKEventSwitchMode:
 		// switch to new mode
 		switchMode((char *)evt->data);
 		_keyQueue.clearFlags();
 		break;
-	case kEventSubmit:
+	case kVKEventSubmit:
 		close(true);
 		break;
-	case kEventCancel:
+	case kVKEventCancel:
 		close(false);
 		break;
-	case kEventClear:
+	case kVKEventClear:
 		_keyQueue.clear();
 		break;
-	case kEventDelete:
+	case kVKEventDelete:
 		_keyQueue.deleteKey();
 		break;
-	case kEventMoveLeft:
+	case kVKEventMoveLeft:
 		_keyQueue.moveLeft();
 		break;
-	case kEventMoveRight:
+	case kVKEventMoveRight:
 		_keyQueue.moveRight();
 		break;
 	}
@@ -194,7 +194,7 @@ void VirtualKeyboard::switchMode(Mode *newMode) {
 	_currentMode = newMode;
 }
 
-void VirtualKeyboard::switchMode(const Common::String& newMode) {
+void VirtualKeyboard::switchMode(const String& newMode) {
 	if (!_modes.contains(newMode)) {
 		warning("Keyboard mode '%s' unknown", newMode.c_str());
 		return;
@@ -231,13 +231,13 @@ void VirtualKeyboard::show() {
 		assert(eventMan);
 
 		// push keydown & keyup events into the event manager
-		Common::Event evt;
+		Event evt;
 		evt.synthetic = false;
 		while (!_keyQueue.empty()) {
 			evt.kbd = _keyQueue.pop();
-			evt.type = Common::EVENT_KEYDOWN;
+			evt.type = EVENT_KEYDOWN;
 			eventMan->pushEvent(evt);
-			evt.type = Common::EVENT_KEYUP;
+			evt.type = EVENT_KEYUP;
 			eventMan->pushEvent(evt);
 		}
 	} else {
@@ -285,8 +285,8 @@ void VirtualKeyboard::KeyPressQueue::clearFlags() {
 void VirtualKeyboard::KeyPressQueue::insertKey(KeyState key) {
 	_strChanged = true;
 	key.flags ^= _flags;
-	if ((key.keycode >= Common::KEYCODE_a) && (key.keycode <= Common::KEYCODE_z))
-		key.ascii = (key.flags & Common::KBD_SHIFT) ? key.keycode - 32 : key.keycode;
+	if ((key.keycode >= KEYCODE_a) && (key.keycode <= KEYCODE_z))
+		key.ascii = (key.flags & KBD_SHIFT) ? key.keycode - 32 : key.keycode;
 	clearFlags();
 
 	String keyStr;
diff --git a/backends/vkeybd/virtual-keyboard.h b/backends/vkeybd/virtual-keyboard.h
index 2325b4b251..f2f7485c6d 100644
--- a/backends/vkeybd/virtual-keyboard.h
+++ b/backends/vkeybd/virtual-keyboard.h
@@ -41,49 +41,80 @@ namespace Common {
 class VirtualKeyboardGUI;
 class VirtualKeyboardParser;
 
+/**
+ * Class that handles the functionality of the virtual keyboard.
+ * This includes storage of the virtual key press events when the user clicks
+ * a key and delivery of them when the keyboard is closed, as well as managing
+ * the internal state of the keyboard, such as its active mode.
+ */  
 class VirtualKeyboard {
 protected:
-	enum EventType {
-		kEventKey,
-		kEventModifier,
-		kEventSwitchMode,
-		kEventSubmit,
-		kEventCancel,
-		kEventClear,
-		kEventDelete,
-		kEventMoveLeft,
-		kEventMoveRight
+
+	/**
+	 * Enum to describe the different types of events that can be associated
+	 * with an area of the virtual keyboard bitmap.
+	 */
+	enum VKEventType {
+		/** Standard key press event */
+		kVKEventKey,
+		/** Modifier key press event */
+		kVKEventModifier,
+		/** Switch the mode of the keyboard */
+		kVKEventSwitchMode,
+		/** Close the keyboard, submitting all keypresses */
+		kVKEventSubmit,
+		/** Close the keyboard, without submitting keypresses */
+		kVKEventCancel,
+		/** Clear the virtual keypress queue */ 
+		kVKEventClear,
+		/** Move the keypress queue insert position backwards */
+		kVKEventMoveLeft,
+		/** Move the keypress queue insert position forwards */
+		kVKEventMoveRight,
+		/** Delete keypress from queue at the current insert position */
+		kVKEventDelete
 	};
 
-	struct Event {
-		Common::String name;
-		EventType type;
+	/** VKEvent struct encapsulates data on a virtual keyboard event */
+	struct VKEvent {
+		String name;
+		VKEventType type;
+		/** 
+		 * Void pointer that will point to different types of data depending
+		 * on the type of the event, these are:
+		 * - KeyState struct for kVKEventKey events
+		 * - a flags byte for kVKEventModifier events
+		 * - c-string stating the name of the new mode for kSwitchMode events
+		 */ 
 		void *data;
 		
-		Event() : data(0) {}
-		~Event() {
+		VKEvent() : data(0) {}
+		~VKEvent() {
 			if (data) free(data);
 		}
 	};
 	
-	typedef Common::HashMap<Common::String, Event*> EventMap; 
+	typedef HashMap<String, VKEvent*> VKEventMap; 
 
+	/**
+	 * Mode struct encapsulates all the data for each mode of the keyboard
+	 */
 	struct Mode {
-		Common::String		name;
-		Common::String		resolution;
-		Common::String		bitmapName;
+		String				name;
+		String				resolution;
+		String				bitmapName;
 		Graphics::Surface	*image;
 		OverlayColor		transparentColor;
-		Common::ImageMap	imageMap;
-		EventMap			events;
-		Common::Rect		*displayArea;
+		ImageMap			imageMap;
+		VKEventMap			events;
+		Rect				*displayArea;
 		OverlayColor		displayFontColor;
 
 		Mode() : image(0), displayArea(0) {}
 		~Mode() { delete displayArea; }
 	};
 	
-	typedef Common::HashMap<Common::String, Mode, Common::IgnoreCase_Hash, Common::IgnoreCase_EqualTo> ModeMap;
+	typedef HashMap<String, Mode, IgnoreCase_Hash, IgnoreCase_EqualTo> ModeMap;
 
 	enum HorizontalAlignment {
 		kAlignLeft,
@@ -98,10 +129,15 @@ protected:
 	};
 
 	struct VirtualKeyPress {
-		Common::KeyState key;
+		KeyState key;
+		/** length of the key presses description string */
 		uint strLen;
 	};
 
+	/** 
+	 * Class that stores the queue of virtual key presses, as well as
+	 * maintaining a string that represents a preview of the queue
+	 */
 	class KeyPressQueue {
 	public:
 		KeyPressQueue();
@@ -132,10 +168,10 @@ protected:
 		uint _strPos;
 	};
 
-
-
 public:
+
 	VirtualKeyboard();
+
 	virtual ~VirtualKeyboard();
 	
 	/**
@@ -145,7 +181,7 @@ public:
 	 * searches for a compressed keyboard pack by looking for packName.zip.
 	 * @param packName	name of the keyboard pack
 	 */
-	bool loadKeyboardPack(Common::String packName);
+	bool loadKeyboardPack(String packName);
 
 	/**
 	 * Shows the keyboard, starting an event loop that will intercept all
@@ -173,7 +209,7 @@ public:
 		return _loaded;
 	}
 
-protected:	// TODO : clean up all this stuff
+protected:	
 
 	OSystem *_system;
 
@@ -189,11 +225,11 @@ protected:	// TODO : clean up all this stuff
 	void deleteEvents();
 	bool checkModeResolutions();
 	void switchMode(Mode *newMode);
-	void switchMode(const Common::String& newMode);
+	void switchMode(const String& newMode);
 	void handleMouseDown(int16 x, int16 y);
 	void handleMouseUp(int16 x, int16 y);
 	String findArea(int16 x, int16 y);
-	void processAreaClick(const Common::String &area);
+	void processAreaClick(const String &area);
 
 	bool _loaded;
 
@@ -211,7 +247,7 @@ protected:	// TODO : clean up all this stuff
 };
 
 
-} // End of namespace GUI
+} // End of namespace Common
 
 
 #endif