From 1d4c82885ddcc0442671c863eef643aef2dc7dda Mon Sep 17 00:00:00 2001 From: Max Horn Date: Sat, 17 Jul 2010 18:38:42 +0000 Subject: DEBUGGER: Simplify how our console debugger works / is used * Remove _isAttached member var and isAttached method * Engines now always call the onFrame method; whether it does something is decided by the debugger class resp. its subclasses * Make detach() protected instead of private, so that subclasses can invoke it * Remove _detach_now member var (call detach() instead). * Rename _frame_countdown to _frameCountdown and properly document it. * Add more doxygen comments * Cleanup svn-id: r50963 --- gui/debugger.h | 116 +++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 96 insertions(+), 20 deletions(-) (limited to 'gui/debugger.h') diff --git a/gui/debugger.h b/gui/debugger.h index 07fdddb808..6f06befdf1 100644 --- a/gui/debugger.h +++ b/gui/debugger.h @@ -43,20 +43,46 @@ public: int DebugPrintf(const char *format, ...); + /** + * The onFrame() method should be invoked by the engine at regular + * intervals (usually once per main loop iteration) whenever the + * debugger is attached. + * This will open up the console and accept user input if certain + * preconditions are met, such as the frame countdown having + * reached zero. + * + * Subclasses can override this to e.g. check for breakpoints being + * triggered. + */ virtual void onFrame(); + /** + * 'Attach' the debugger. This ensures that the next time onFrame() + * is invoked, the debugger will activate and accept user input. + */ virtual void attach(const char *entry = 0); - bool isAttached() const { return _isAttached; } + + /** + * Return true if the debugger is currently active (i.e. executing + * a command or waiting for use input). + */ + bool isActive() const { return _isActive; } protected: typedef Common::Functor2 Debuglet; - // Convenience macro for registering a method of a debugger class - // as the current command. + /** + * Convenience macro that makes it either to register a method + * of a debugger subclass as a command. + * Usage example: + * DCmd_Register("COMMAND", WRAP_METHOD(MyDebugger, MyCmd)); + * would register the method MyDebugger::MyCmd(int, const char **) + * under the command name "COMMAND". + */ #define WRAP_METHOD(cls, method) \ new Common::Functor2Mem(this, &cls::method) - enum { + enum VarType { DVAR_BYTE, DVAR_INT, DVAR_BOOL, @@ -67,50 +93,100 @@ protected: struct DVar { Common::String name; void *variable; - int type; - int optional; + VarType type; + int arraySize; }; - int _frame_countdown; - bool _detach_now; + + /** + * Register a variable with the debugger. This allows the user to read and modify + * this variable. + * @param varname the identifier with which the user may access the variable + * @param variable pointer to the actual storage of the variable + * @param type the type of the variable (byte, int, bool, ...) + * @paral arraySize for type DVAR_INTARRAY this specifies the size of the array + * + * @todo replace this single method by type safe variants. + */ + void DVar_Register(const Common::String &varname, void *variable, VarType type, int arraySize); + void DCmd_Register(const Common::String &cmdname, Debuglet *debuglet); + private: + /** + * The frame countdown specifies a number of frames that must pass + * until the console will show up. This value is decremented by one + * each time onFrame() is called, until it reaches 0, at which point + * onFrame() will open the console and handle input into it. + * + * The user can modify this value using the debug_countdown command. + * + * Note: The console must be in *attached* state, otherwise, it + * won't show up (and the countdown won't count down either). + */ + uint _frameCountdown; + Common::Array _dvars; typedef Common::HashMap, Common::IgnoreCase_Hash, Common::IgnoreCase_EqualTo> CommandsMap; CommandsMap _cmds; - bool _isAttached; + /** + * True if the debugger is currently active (i.e. executing + * a command or waiting for use input). + */ + bool _isActive; + char *_errStr; + + /** + * Initially true, set to false when Debugger::enter is called + * the first time. We use this flag to show a greeting message + * to the user once, when he opens the debugger for the first + * time. + */ bool _firstTime; + #ifndef USE_TEXT_CONSOLE GUI::ConsoleDialog *_debuggerDialog; #endif protected: - // Hook for subclasses: Called just before enter() is run + /** + * Hook for subclasses which is called just before enter() is run. + * A typical usage example is pausing music and sound effects. + */ virtual void preEnter() {} - // Hook for subclasses: Called just after enter() was run + /** + * Hook for subclasses which is called just after enter() was run. + * A typical usage example is resuming music and sound effects. + */ virtual void postEnter() {} - // Hook for subclasses: Process the given command line. - // Should return true if and only if argv[0] is a known command and was - // handled, false otherwise. - virtual bool handleCommand(int argc, const char **argv, bool &keepRunning); - + /** + * Subclasses should invoke the detach() method in their Cmd_FOO methods + * if that command will resume execution of the program (as opposed to + * executing, say, a "single step through code" command). + * + * This currently only hides the virtual keyboard, if any. + */ + void detach(); private: - void detach(); void enter(); bool parseCommand(const char *input); bool tabComplete(const char *input, Common::String &completion) const; -protected: - void DVar_Register(const Common::String &varname, void *pointer, int type, int optional); - void DCmd_Register(const Common::String &cmdname, Debuglet *debuglet); + /** + * Process the given command line. + * Returns true if and only if argv[0] is a known command and was + * handled, false otherwise. + */ + virtual bool handleCommand(int argc, const char **argv, bool &keepRunning); +protected: bool Cmd_Exit(int argc, const char **argv); bool Cmd_Help(int argc, const char **argv); bool Cmd_DebugFlagsList(int argc, const char **argv); -- cgit v1.2.3