1 files changed, 151 insertions, 9 deletions

diff --git a/engines/sherlock/user_interface.h b/engines/sherlock/user_interface.h
index acbb0c0ed0..8a0f4f5613 100644
--- a/engines/sherlock/user_interface.h
+++ b/engines/sherlock/user_interface.h
@@ -74,14 +74,14 @@ public:
 	bool _windowOpen;
 	bool _endKeyActive;
 	int _invLookFlag;
-	int _windowStyle;
+	bool _slideWindows;
 	bool _helpStyle;
 	Common::Rect _windowBounds;
 	bool _lookScriptFlag;
 
 	// TODO: Not so sure these should be in the base class. May want to refactor them to SherlockEngine, or refactor
 	// various Scalpel dialogs to keep their own private state of key/selections
-	int _key, _oldKey;
+	char _key, _oldKey;
 	int _selector, _oldSelector;
 	int _temp, _oldTemp;
 	int _temp1;
@@ -89,17 +89,50 @@ public:
 public:
 	static UserInterface *init(SherlockEngine *vm);
 
+	/**
+	 * Resets the user interface
+	 */
 	virtual void reset() {}
+
+	/**
+	 * Draw the user interface onto the screen's back buffers
+	 */	
 	virtual void drawInterface(int bufferNum = 3) {}
+
+	/**
+	 * Main input handler for the user interface
+	 */
 	virtual void handleInput() {}
 
-	virtual void doInvJF() {}
+	/**
+	 * Displays a passed window by gradually scrolling it vertically on-screen
+	 */
 	virtual void summonWindow(const Surface &bgSurface, bool slideUp = true) {}
+
+	/**
+	 * Slide the window stored in the back buffer onto the screen
+	 */
 	virtual void summonWindow(bool slideUp = true, int height = CONTROLS_Y) {}
+
+	/**
+	 * Close a currently open window
+	 * @param flag	0 = slide old window down, 1 = slide prior UI back up
+	 */
 	virtual void banishWindow(bool slideUp = true) {}
+
+	/**
+	 * Clears the info line of the screen
+	 */
 	virtual void clearInfo() {}
+
+	/**
+	 * Clear any active text window
+	 */
 	virtual void clearWindow() {}
 
+	/**
+	 * Print the previously selected object's decription
+	 */
 	virtual void printObjectDesc() {}
 };
 
@@ -110,10 +143,12 @@ class ScalpelUserInterface: public UserInterface {
 private:
 	ImageFile *_controlPanel;
 	ImageFile *_controls;
-	int _bgFound;
-	int _oldBgFound;
-	int _keycode;
+	char _keyPress;
+	int _lookHelp;
+	int _bgFound, _oldBgFound;
 	int _help, _oldHelp;
+	char _key, _oldKey;
+	int _temp, _oldTemp;
 	int _oldLook;
 	bool _keyboardInput;
 	bool _pause;
@@ -123,54 +158,158 @@ private:
 	int _find;
 	int _oldUse;
 private:
+	/**
+	 * Draws the image for a user interface button in the down/pressed state.
+	 */
 	void depressButton(int num);
 
+	/**
+	 * If he mouse button is pressed, then calls depressButton to draw the button
+	 * as pressed; if not, it will show it as released with a call to "restoreButton".
+	 */
 	void pushButton(int num);
 
+	/**
+	 * By the time this method has been called, the graphics for the button change
+	 * have already been drawn. This simply takes care of switching the mode around
+	 * accordingly
+	 */
 	void toggleButton(int num);
 
+	/**
+	 * Creates a text window and uses it to display the in-depth description
+	 * of the highlighted object
+	 */
 	void examine();
 
+	/**
+	 * Print the name of an object in the scene
+	 */
 	void lookScreen(const Common::Point &pt);
 
+	/**
+	 * Gets the item in the inventory the mouse is on and display's it's description
+	 */
 	void lookInv();
 
+	/**
+	 * Handles input when the file list window is being displayed
+	 */
 	void doEnvControl();
+	
+	/**
+	 * Handle input whilst the inventory is active
+	 */
 	void doInvControl();
+	
+	/**
+	 * Handles waiting whilst an object's description window is open.
+	 */
 	void doLookControl();
+	
+	/**
+	 * Handles input until one of the user interface buttons/commands is selected
+	 */
 	void doMainControl();
+	
+	/**
+	 * Handles the input for the MOVE, OPEN, and CLOSE commands
+	 */
 	void doMiscControl(int allowed);
+	
+	/**
+	 * Handles input for picking up items
+	 */
 	void doPickControl();
+	
+	/**
+	 * Handles input when in talk mode. It highlights the buttons and available statements,
+	 * and handles allowing the user to click on them
+	 */
 	void doTalkControl();
+	
+	/**
+	 * Handles events when the Journal is active.
+	 * @remarks		Whilst this would in theory be better in the Journal class, since it displays in
+	 *		the user interface, it uses so many internal UI fields, that it sort of made some sense
+	 *		to put it in the UserInterface class.
+	 */
 	void journalControl();
 
+	/**
+	 * Checks to see whether a USE action is valid on the given object
+	 */
 	void checkUseAction(const UseType *use, const Common::String &invName, const char *const messages[],
-		int objNum, int giveMode);
+		int objNum, bool giveMode);
+	
+	/**
+	 * Called for OPEN, CLOSE, and MOVE actions are being done
+	 */
 	void checkAction(ActionType &action, const char *const messages[], int objNum);
 
+	/**
+	 * Print the previously selected object's decription
+	 */
 	void printObjectDesc(const Common::String &str, bool firstTime);
 public:
 	ScalpelUserInterface(SherlockEngine *vm);
 	~ScalpelUserInterface();
 
+	/**
+	 * Handles counting down whilst checking for input, then clears the info line.
+	 */
 	void whileMenuCounter();
 
+	/**
+	 * Draws the image for the given user interface button in the up
+	 * (not selected) position
+	 */
 	void restoreButton(int num);
 public:
+	/**
+	 * Resets the user interface
+	 */
 	virtual void reset();
 
+	/**
+	 * Main input handler for the user interface
+	 */
 	virtual void handleInput();
 
+	/**
+	 * Draw the user interface onto the screen's back buffers
+	 */	
 	virtual void drawInterface(int bufferNum = 3);
 
-	virtual void doInvJF();
-
+	/**
+	 * Displays a passed window by gradually scrolling it vertically on-screen
+	 */
 	virtual void summonWindow(const Surface &bgSurface, bool slideUp = true);
+
+	/**
+	 * Slide the window stored in the back buffer onto the screen
+	 */
 	virtual void summonWindow(bool slideUp = true, int height = CONTROLS_Y);
+
+	/**
+	 * Close a currently open window
+	 * @param flag	0 = slide old window down, 1 = slide prior UI back up
+	 */
 	virtual void banishWindow(bool slideUp = true);
+
+	/**
+	 * Clears the info line of the screen
+	 */
 	virtual void clearInfo();
+
+	/**
+	 * Clear any active text window
+	 */
 	virtual void clearWindow();
 
+	/**
+	 * Print the previously selected object's decription
+	 */	
 	virtual void printObjectDesc();
 };
 
@@ -178,6 +317,9 @@ class TattooUserInterface : public UserInterface {
 public:
 	TattooUserInterface(SherlockEngine *vm);
 public:
+	/**
+	 * Main input handler for the user interface
+	 */
 	virtual void handleInput();
 };