Index: ps/trunk/source/gui/CGUISettingsObject.h =================================================================== --- ps/trunk/source/gui/CGUISettingsObject.h (revision 65) +++ ps/trunk/source/gui/CGUISettingsObject.h (revision 66) @@ -1,111 +1,124 @@ /* Object with settings by Gustav Larsson gee@pyro.nu --Overview-- Generic object that stores a struct with settings --Usage-- If an object wants settings with a standard, it will use this as a middle step instead of being directly derived from CGUIObject --Examples-- instead of: class CButton : public CGUIObject you go: class CButton : public CGUISettingsObject and SButtonSettings will be included as m_Settings with all gets and sets set up --More info-- Check GUI.h */ #ifndef CGUISettingsObject_H #define CGUISettingsObject_H //-------------------------------------------------------- // Includes / Compiler directives //-------------------------------------------------------- #include "GUI.h" //-------------------------------------------------------- // Macros //-------------------------------------------------------- //-------------------------------------------------------- // Types //-------------------------------------------------------- //-------------------------------------------------------- // Error declarations //-------------------------------------------------------- //-------------------------------------------------------- // Declarations //-------------------------------------------------------- -// Generic object that stores a struct with settings - +/** + * @author Gustav Larsson + * + * Appends more settings to the CGUIObject. + * Can be used with multiple inheritance. + * + * @see CGUIObject + */ template class CGUISettingsObject : virtual public CGUIObject { public: CGUISettingsObject() {} virtual ~CGUISettingsObject() {} - // Get Offsets - // important so it returns this m_Offsets and not CGUIObject::m_SettingsInfo + /** + * Get Offsets, important to include so it returns this + * m_Offsets and not CGUIObject::m_SettingsInfo + * + * @return Settings infos + */ virtual map_Settings GetSettingsInfo() const { return m_SettingsInfo; } - // GetSettings() - // returns a copy of m_Settings + /** + * @return Returns a copy of m_Settings + */ SETTINGS GetSettings() const { return m_Settings; } - // SetSettings - // Sets m_Settings to _set + /// Sets settings void SetSettings(const SETTINGS &Set) { m_Settings = Set; //CheckSettingsValidity(); // Since that function out-commented above really // does just update the base settings, we'll call // the message immediately instead try { HandleMessage(GUIM_SETTINGS_UPDATED); } catch (...) { } } protected: - // Settings + /// Settings struct SETTINGS m_Settings; - // Offset database - // tells us where a variable by a string name is - // located hardcoded, in order to acquire a pointer - // for that variable... Say "frozen" gives - // the offset from CGUIObject to m_Frozen - // note! _NOT_ from SGUIBaseSettings to m_Frozen! - // - // Note that it's imperative that this m_SettingsInfo includes - // all offsets of m_BaseSettings too, because when - // using this class, this m_SettingsInfo will be the only - // one used. + /** + * Offset database
+ * tells us where a variable by a string name is + * located hardcoded, in order to acquire a pointer + * for that variable... Say "frozen" gives + * the offset from CGUIObject to m_Frozen. + * + * note! _NOT_ from SGUIBaseSettings to m_Frozen! + * + * Note that it's imperative that this m_SettingsInfo includes + * all offsets of m_BaseSettings too, because when + * using this class, this m_SettingsInfo will be the only + * one used. + */ static map_Settings m_SettingsInfo; }; #endif \ No newline at end of file Index: ps/trunk/source/gui/CGUIButtonBehavior.h =================================================================== --- ps/trunk/source/gui/CGUIButtonBehavior.h (revision 65) +++ ps/trunk/source/gui/CGUIButtonBehavior.h (revision 66) @@ -1,59 +1,69 @@ /* GUI Object - Button by Gustav Larsson gee@pyro.nu --Overview-- Interface class that enhance the CGUIObject with buttony behavior (click and release to click a button), and the GUI message GUIM_PRESSED. When creating a class with extended settings and buttony behavior, just do a multiple inheritance. --More info-- Check GUI.h */ #ifndef CGUIButtonBehavior_H #define CGUIButtonBehavior_H //-------------------------------------------------------- // Includes / Compiler directives //-------------------------------------------------------- #include "GUI.h" //-------------------------------------------------------- // Macros //-------------------------------------------------------- //-------------------------------------------------------- // Types //-------------------------------------------------------- //-------------------------------------------------------- // Declarations //-------------------------------------------------------- -// Abstract Data Type +/** + * @author Gustav Larsson + * + * Appends button behaviours to the CGUIObject. + * Can be used with multiple inheritance alongside + * CGUISettingsObject and such. + * + * @see CGUIObject + */ class CGUIButtonBehavior : virtual public CGUIObject { public: CGUIButtonBehavior(); virtual ~CGUIButtonBehavior(); - // Handle Messages + /// Handle Messages virtual void HandleMessage(const EGUIMessage &Message); protected: - // Everybody knows how a button works, you don't simply press it, - // you have to first press the button, and then release it... - // in between those two steps you can actually leave the button - // area, as long as you release it within the button area... Anyway - // this lets us know we are done with step one (clicking). + /** + * Everybody knows how a button works, you don't simply press it, + * you have to first press the button, and then release it... + * in between those two steps you can actually leave the button + * area, as long as you release it within the button area... Anyway + * this lets us know we are done with step one (clicking). + */ bool m_Pressed; }; #endif \ No newline at end of file Index: ps/trunk/source/gui/CGUISprite.h =================================================================== --- ps/trunk/source/gui/CGUISprite.h (revision 65) +++ ps/trunk/source/gui/CGUISprite.h (revision 66) @@ -1,80 +1,102 @@ /* A GUI Sprite by Gustav Larsson gee@pyro.nu --Overview-- A GUI Sprite, which is actually a collage of several sprites. --Usage-- Used internally and declared in XML files, read documentations on how. --More info-- Check GUI.h */ #ifndef CGUISprite_H #define CGUISprite_H //-------------------------------------------------------- // Includes / Compiler directives //-------------------------------------------------------- #include "GUI.h" //-------------------------------------------------------- // Macros //-------------------------------------------------------- //-------------------------------------------------------- // Types //-------------------------------------------------------- //-------------------------------------------------------- // Error declarations //-------------------------------------------------------- //-------------------------------------------------------- // Declarations //-------------------------------------------------------- -// Actual sprite +/** + * @author Gustav Larsson + * + * A CGUISprite is actually a collage of several real + * sprites, this struct represents is such real sprite. + */ struct SGUIImage { CStr m_Texture; // Placement modifiers int m_Pixel[4]; float m_Percent[4]; // Texture modifiers int m_TexturePixel[4]; float m_TexturePercent[4]; //CColor m_BackColor; //CColor m_BorderColor; int m_BorderSize; }; -// The GUI sprite, is actually several real sprites (images). +/** + * @author Gustav Larsson + * + * The GUI sprite, is actually several real sprites (images) + * like a collage. View the section in the GUI + * TDD for more information. + */ class CGUISprite { public: CGUISprite() {} virtual ~CGUISprite() {} - // Execute a drawing request for this sprite + /** + * Execute a drawing request for this sprite + * + * @param z Draw in what depth. + * @param rect Outer rectangle to draw the collage. + */ void Draw(const float &z, const CRect &rect, const CRect &clipping); + /** + * Adds an image to the sprite collage. + * + * @param image Adds this image to the sprite collage. + */ void AddImage(const SGUIImage &image) { m_Images.push_back(image); } private: + /// List of images std::vector m_Images; }; #endif \ No newline at end of file Index: ps/trunk/source/gui/CGUIObject.h =================================================================== --- ps/trunk/source/gui/CGUIObject.h (revision 65) +++ ps/trunk/source/gui/CGUIObject.h (revision 66) @@ -1,299 +1,363 @@ /* The base class of an object by Gustav Larsson gee@pyro.nu --Overview-- All objects are derived from this class, it's an ADT so it can't be used per se Also contains a Dummy object which is used for completely blank objects. --Usage-- Write about how to use it here --Examples-- Provide examples of how to use this code, if necessary --More info-- Check GUI.h */ #ifndef CGUIObject_H #define CGUIObject_H //-------------------------------------------------------- // Includes / Compiler directives //-------------------------------------------------------- #include "GUI.h" #include #include struct SGUISetting; class CGUI; -//extern CGUI g_GUI; - //-------------------------------------------------------- // Macros //-------------------------------------------------------- //-------------------------------------------------------- // Types //-------------------------------------------------------- // Map with pointers typedef std::map map_Settings; typedef std::vector vector_pObjects; //-------------------------------------------------------- // Error declarations //-------------------------------------------------------- //-------------------------------------------------------- // Declarations //-------------------------------------------------------- // TEMP struct CRect { CRect() {} CRect(int _l, int _b, int _r, int _t) : top(_t), bottom(_b), right(_r), left(_l) {} int bottom, top, left, right; bool operator ==(const CRect &rect) const { return (bottom==rect.bottom) && (top==rect.top) && (left==rect.left) && (right==rect.right); } bool operator !=(const CRect &rect) const { return !(*this==rect); } }; // TEMP struct CColor { float r, g, b, a; }; // Text alignments enum EAlign { EAlign_Left, EAlign_Right, EAlign_Center }; enum EValign { EValign_Top, EValign_Bottom, EValign_Center }; -// Stores the information where to find a variable -// in a GUI-Object object, also what type it is +/** + * Stores the information where to find a variable + * in a GUI-Object object, also what type it is. + */ struct SGUISetting { size_t m_Offset; // The offset from CGUIObject to the variable (not from SGUIBaseSettings or similar) CStr m_Type; // "string" or maybe "int" }; -// Base settings, all objects possess these settings -// in their m_BaseSettings -// Instructions can be found in the documentations +/** + * Base settings, all objects possess these settings + * in their m_BaseSettings + * Instructions can be found in the documentations. + */ struct SGUIBaseSettings { bool m_Hidden; bool m_Enabled; bool m_Absolute; CRect m_Size; CStr m_Style; float m_Z; CStr m_Caption; // Is usually set within an XML element and not in the attributes }; ////////////////////////////////////////////////////////// -// GUI object such as a button or an input-box. -// Abstract data type ! +/** + * @author Gustav Larsson + * + * GUI object such as a button or an input-box. + * Abstract data type ! + */ class CGUIObject { friend class CGUI; friend class GUI; public: CGUIObject(); virtual ~CGUIObject(); - // Get Offsets + /** + * Get offsets + * + * @return Retrieves settings info + */ virtual map_Settings GetSettingsInfo() const { return m_SettingsInfo; } - // Is mouse over - // because it's virtual you can change the - // mouse over demands, such as making a round - // button, or just modifying it when changed, - // like for a combo box. - // The default one uses m_Size + /** + * Is mouse over + * because it's virtual you can change the + * mouse over demands, such as making a round + * button, or just modifying it when changed, + * like for a combo box. + * + * The default one uses m_Size. + * + * @return true if mouse is over + */ virtual bool MouseOver(); - // + //-------------------------------------------------------- // Leaf Functions - // + //-------------------------------------------------------- + /** @name Leaf Functions */ + //@{ - // Get/Set - // Name + /// Get object name, name is unique CStr GetName() const { return m_Name; } + + /// Get object name void SetName(const CStr &Name) { m_Name = Name; } - // Fill a map_pObjects with this object (does not include recursion) + /** + * Fill a map_pObjects with this object (does not include recursion) + * + * @param ObjectMap Adds this to the map_pObjects. + */ void AddToPointersMap(map_pObjects &ObjectMap); - // Add child + /** + * Add child + * + * @param pChild Add child by pointer + */ void AddChild(CGUIObject *pChild); - // + //@} + //-------------------------------------------------------- // Iterate - // - + //-------------------------------------------------------- + /** @name Iterate */ + //@{ + vector_pObjects::iterator ChildrenItBegin() { return m_Children.begin(); } vector_pObjects::iterator ChildrenItEnd() { return m_Children.end(); } - // + //@} + //-------------------------------------------------------- // Settings Management - // + //-------------------------------------------------------- + /** @name Settings Management */ + //@{ SGUIBaseSettings GetBaseSettings() const { return m_BaseSettings; } void SetBaseSettings(const SGUIBaseSettings &Set); - // Checks if settings exists, only available for derived - // classes that has this set up, that's why the base - // class just returns false + /** + * Checks if settings exists, only available for derived + * classes that has this set up, that's why the base + * class just returns false + * + * @param Setting setting name + * @return true if settings exist + */ bool SettingExists(const CStr &Setting) const; - // Setup base pointers + /// Setup base pointers void SetupBaseSettingsInfo(map_Settings &SettingsInfo); - // Set Setting by string + /// Set Setting by string void SetSetting(const CStr &Setting, const CStr &Value); - // Should be called every time the settings has been updated - // will also send a message GUIM_SETTINGS_UPDATED, so that - // if a derived object wants to add things to be updated, - // they add it in that message part, this is a better solution - // than making this virtual, since the updates that the base - // class does, are the most essential. - // This is not private since there should be no harm in - // checking validity + /** + * Should be called every time the settings has been updated + * will also send a message GUIM_SETTINGS_UPDATED, so that + * if a derived object wants to add things to be updated, + * they add it in that message part, this is a better solution + * than making this virtual, since the updates that the base + * class does, are the most essential. + * This is not private since there should be no harm in + * checking validity. + */ void CheckSettingsValidity(); + //@} protected: - // + //-------------------------------------------------------- // Methods that the CGUI will call using // its friendship, these should not // be called by user. // - // These functions' security are alot + // These functions' security are a lot // what constitutes the GUI's - // - - // Calls Destroy on all children, and deallocates all memory + //-------------------------------------------------------- + /** @name Internal methods that uses friendship */ + //@{ + + /** + * Calls Destroy on all children, and deallocates all memory + */ virtual void Destroy(); - // Messages - // This function is called with different messages - // for instance when the mouse enters the object. + /** + * This function is called with different messages + * for instance when the mouse enters the object. + * + * @param Message EGUIMessage. + */ virtual void HandleMessage(const EGUIMessage &Message)=0; - // Draw + /** + * Draws the object + */ virtual void Draw()=0; - - // Setting and getting the GUI object can only be done - // from within - // SetGUI uses a first parameter that fits into RecurseObject + // This is done internally CGUI *GetGUI() { return m_pGUI; } const CGUI *GetGUI() const { return m_pGUI; } void SetGUI(CGUI * const &pGUI) { m_pGUI = pGUI; } // Set parent void SetParent(CGUIObject *pParent) { m_pParent = pParent; } - // NOTE! This will not just return m_pParent, when that is need - // use it! There is one exception to it, when the parent is - // the top-node (the object that isn't a real object), this - // will return NULL, so that the top-node's children are - // seemingly parentless. + /** + * NOTE! This will not just return m_pParent, when that is need + * use it! There is one exception to it, when the parent is + * the top-node (the object that isn't a real object), this + * will return NULL, so that the top-node's children are + * seemingly parentless. + * + * @return Pointer to parent + */ CGUIObject *GetParent(); - // Clear children, removes all children - // Update objects, will basically use the this base class - // to access a private member in CGUI, this base - // class will be only one with permission + /** + * Clear children, removes all children + * Update objects, will basically use the this base class + * to access a private member in CGUI, this base + * class will be only one with permission + */ // void UpdateObjects(); // Get cached mouse x/y from CGUI u16 GetMouseX() const; u16 GetMouseY() const; - private: // Functions used fully private and by friends (mainly the CGUI) - // You input pointer, and if the Z value of this object - // is greater than the one inputted, the pointer is changed to this. + /** + * You input pointer, and if the Z value of this object + * is greater than the one inputted, the pointer is changed to this. + * + * @param pObject Object pointer + */ void ChooseMouseOverAndClosest(CGUIObject* &pObject); - // Update Mouse Over (for this object only) + /** + * Update Mouse Over (for this object only) + * + * @param pMouseOver + */ void UpdateMouseOver(CGUIObject * const &pMouseOver); // Variables protected: - // Name of object + /// Name of object CStr m_Name; - // Constructed on the heap, will be destroyed along with the the object + /// Constructed on the heap, will be destroyed along with the the object vector_pObjects m_Children; - // Pointer to parent + /// Pointer to parent CGUIObject *m_pParent; - // Base settings + /// Base settings SGUIBaseSettings m_BaseSettings; // More variables - // Is mouse hovering the object? used with the function MouseOver() + /// Is mouse hovering the object? used with the function MouseOver() bool m_MouseHovering; - // Offset database - // tells us where a variable by a string name is - // located hardcoded, in order to acquire a pointer - // for that variable... Say "frozen" gives - // the offset from CGUIObject to m_Frozen - // note! _NOT_ from SGUIBaseSettings to m_Frozen! + /** + * Offset database + * tells us where a variable by a string name is + * located hardcoded, in order to acquire a pointer + * for that variable... Say "frozen" gives + * the offset from CGUIObject to m_Frozen. + * note! NOT from SGUIBaseSettings to + * m_Frozen! + */ static map_Settings m_SettingsInfo; private: - // An object can't function stand alone + /// An object can't function stand alone CGUI *m_pGUI; }; -//-------------------------------------------------------- -// Dummy object used primarily for the root object -// which isn't a *real* object in the GUI. -//-------------------------------------------------------- +/** + * @author Gustav Larsson + * + * Dummy object used primarily for the root object + * which isn't a *real* object in the GUI. + */ class CGUIDummyObject : public CGUIObject { virtual void HandleMessage(const EGUIMessage &Message) {} virtual void Draw() {} }; #endif \ No newline at end of file Index: ps/trunk/source/gui/CButton.h =================================================================== --- ps/trunk/source/gui/CButton.h (revision 65) +++ ps/trunk/source/gui/CButton.h (revision 66) @@ -1,76 +1,97 @@ /* GUI Object - Button by Gustav Larsson gee@pyro.nu --Overview-- GUI Object representing a simple button --More info-- Check GUI.h */ #ifndef CButton_H #define CButton_H //-------------------------------------------------------- // Includes / Compiler directives //-------------------------------------------------------- #include "GUI.h" //-------------------------------------------------------- // Macros //-------------------------------------------------------- //-------------------------------------------------------- // Types //-------------------------------------------------------- //-------------------------------------------------------- // Declarations //-------------------------------------------------------- -// Settings +/** + * Button Settings + */ struct SButtonSettings { bool m_Disabled; CStr m_Font; CStr m_Sprite; CStr m_SpriteDisabled; CStr m_SpriteOver; CStr m_SpritePressed; EAlign m_TextAlign; CColor m_TextColor; CColor m_TextColorDisabled; CColor m_TextColorOver; CColor m_TextColorPressed; EValign m_TextValign; CStr m_ToolTip; CStr m_ToolTipStyle; }; /////////////////////////////////////////////////////////////////////////////// +/** + * @author Gustav Larsson + * + * Button + * + * @see CGUIObject + * @see CGUISettingsObject + * @see CGUIButtonBehavior + * @see SButtonSettings + */ class CButton : public CGUISettingsObject, public CGUIButtonBehavior { GUI_OBJECT(CButton) public: CButton(); virtual ~CButton(); - - // Since we're doing multiple inheritance, this is to avoid error message + /** + * Since we're doing multiple inheritance, this is to avoid error message + * + * @return Settings infos + */ virtual map_Settings GetSettingsInfo() const { return CGUISettingsObject::m_SettingsInfo; } - // Handle Messages + /** + * Handle Messages + * + * @param Message GUI Message + */ virtual void HandleMessage(const EGUIMessage &Message); - // Draw + /** + * Draws the Button + */ virtual void Draw(); }; #endif \ No newline at end of file Index: ps/trunk/source/gui/GUIbase.h =================================================================== --- ps/trunk/source/gui/GUIbase.h (revision 65) +++ ps/trunk/source/gui/GUIbase.h (revision 66) @@ -1,111 +1,115 @@ /* GUI Core, stuff that the whole GUI uses by Gustav Larsson gee@pyro.nu --Overview-- Contains defines, includes, types etc that the whole GUI should have included. --More info-- http://gee.pyro.nu/wfg/GUI/ */ #ifndef GUIbase_H #define GUIbase_H //-------------------------------------------------------- // Includes / Compiler directives //-------------------------------------------------------- //-------------------------------------------------------- // Forward declarations //-------------------------------------------------------- class CGUIObject; //-------------------------------------------------------- // Macros //-------------------------------------------------------- // Global CGUI #define g_GUI CGUI::GetSingleton() // Temp #define CInput nemInput //#define CStr std::string // Example // GUI_ADD_OFFSET(CButton, SButtonSettings, m_Settings, "frozen", m_Frozen); // #define GUI_ADD_OFFSET(_class, _struct, name, type, str, var) \ m_SettingsInfo[str].m_Offset = offsetof(_class, name) + offsetof(_struct, var); \ m_SettingsInfo[str].m_Type = type; // Declares the static variable in CGUISettingsObject<> #define DECLARE_SETTINGS_INFO(_struct) \ map_Settings CGUISettingsObject<_struct>::m_SettingsInfo; // Setup an object's ConstructObject function #define GUI_OBJECT(obj) \ public: \ static CGUIObject *ConstructObject() { return new obj(); } //-------------------------------------------------------- // Types //-------------------------------------------------------- -// Message send to HandleMessage in order -// to give life to Objects manually with -// a derived HandleMessage(). +/** + * Message send to CGUIObject::HandleMessage() in order + * to give life to Objects manually with + * a derived HandleMessage(). + */ enum EGUIMessage { GUIM_PREPROCESS, GUIM_POSTPROCESS, GUIM_MOUSE_OVER, GUIM_MOUSE_ENTER, GUIM_MOUSE_LEAVE, GUIM_MOUSE_PRESS_LEFT, GUIM_MOUSE_PRESS_RIGHT, GUIM_MOUSE_DOWN_LEFT, GUIM_MOUSE_DOWN_RIGHT, GUIM_MOUSE_RELEASE_LEFT, GUIM_MOUSE_RELEASE_RIGHT, GUIM_SETTINGS_UPDATED, GUIM_PRESSED }; -// Recurse restrictions, when we recurse, if an object -// is hidden for instance, you might want it to skip -// the children also -// Notice these are flags! and we don't really need one -// for no restrictions, because then you'll just enter 0 +/** + * Recurse restrictions, when we recurse, if an object + * is hidden for instance, you might want it to skip + * the children also + * Notice these are flags! and we don't really need one + * for no restrictions, because then you'll just enter 0 + */ enum { GUIRR_HIDDEN=1, GUIRR_DISABLED=2 }; // Typedefs typedef std::map map_pObjects; //-------------------------------------------------------- // Error declarations //-------------------------------------------------------- DECLARE_ERROR(PS_NAME_TAKEN) DECLARE_ERROR(PS_OBJECT_FAIL) DECLARE_ERROR(PS_SETTING_FAIL) DECLARE_ERROR(PS_VALUE_INVALID) DECLARE_ERROR(PS_NEEDS_PGUI) DECLARE_ERROR(PS_NAME_AMBIGUITY) DECLARE_ERROR(PS_NEEDS_NAME) DECLARE_ERROR(PS_LEXICAL_FAIL) DECLARE_ERROR(PS_SYNTACTICAL_FAIL) #endif \ No newline at end of file Index: ps/trunk/source/gui/GUIutil.h =================================================================== --- ps/trunk/source/gui/GUIutil.h (revision 65) +++ ps/trunk/source/gui/GUIutil.h (revision 66) @@ -1,325 +1,345 @@ /* GUI util by Gustav Larsson gee@pyro.nu --Overview-- Contains help class GUI<>, which gives us templated parameter to all functions within GUI. --More info-- http://gee.pyro.nu/wfg/GUI/ */ #ifndef GUIutil_H #define GUIutil_H //-------------------------------------------------------- // Includes / Compiler directives //-------------------------------------------------------- #include "GUI.h" //-------------------------------------------------------- // Forward declarations //-------------------------------------------------------- class CGUI; class CGUIObject; -//-------------------------------------------------------- -// Base class to only the class GUI. This superclass is -// kind of a templateless extention of the class GUI. -// Used for other functions to friend with, because it -// it can't friend with GUI since it's templated. -//-------------------------------------------------------- +/** + * Base class to only the class GUI. This superclass is + * kind of a templateless extention of the class GUI. + * Used for other functions to friend with, because it + * it can't friend with GUI since it's templated. + */ class CInternalCGUIAccessorBase { protected: - // Get object pointer + /// Get object pointer static CGUIObject * GetObjectPointer(CGUI &GUIinstance, const CStr &Object); - // const version + /// const version static const CGUIObject * GetObjectPointer(const CGUI &GUIinstance, const CStr &Object); }; -//-------------------------------------------------------- -// Includes static functions that needs one template -// argument. -//-------------------------------------------------------- -// int is only to please functions that doesn't even use T -// and are only within this class because it's convenient + +/** + * Includes static functions that needs one template + * argument. + * + * int is only to please functions that doesn't even use T + * and are only within this class because it's convenient + */ template class GUI : public CInternalCGUIAccessorBase { // Private functions further ahead friend class CGUI; friend class CGUIObject; public: - //-------------------------------------------------------- - // Retrieves a setting by name - // Input: - // pObject Object pointer - // Setting Setting by name - // Output: - // Value Stores value here - // note type T! - //-------------------------------------------------------- + /** + * Retrieves a setting by name from object pointer + * + * @param pObject Object pointer + * @param Setting Setting by name + * @param Value Stores value here, note type T! + */ static PS_RESULT GetSetting(const CGUIObject *pObject, const CStr &Setting, T &Value) { if (pObject == NULL) return PS_OBJECT_FAIL; if (!pObject->SettingExists(Setting)) return PS_SETTING_FAIL; // Set value Value = *(T*)((size_t)pObject+pObject->GetSettingsInfo()[Setting].m_Offset); return PS_OK; } - //-------------------------------------------------------- - // Sets a value by name using a real datatype as input - // Input: - // pObject Object pointer - // Setting Setting by name - // Value Sets value to this - // note type T! - //-------------------------------------------------------- + /** + * Sets a value by name using a real datatype as input + * + * @param pObject Object pointer + * @param Setting Setting by name + * @param Value Sets value to this, note type T! + */ static PS_RESULT SetSetting(CGUIObject *pObject, const CStr &Setting, const T &Value) { if (pObject == NULL) return PS_OBJECT_FAIL; if (!pObject->SettingExists(Setting)) return PS_SETTING_FAIL; // Set value // This better be the correct adress *(T*)((size_t)pObject+pObject->GetSettingsInfo()[Setting].m_Offset) = Value; pObject->CheckSettingsValidity(); return PS_OK; } - //-------------------------------------------------------- - // Retrieves a setting and object name - // Input: - // GUI GUI Object const ref - // Object Object name - // Setting Setting by name - // Output: - // Value Stores value here - // note type T! - //-------------------------------------------------------- + /** + * Retrieves a setting by settings name and object name + * + * @param GUI GUI Object const ref + * @param Object Object name + * @param Setting Setting by name + * @param Value Stores value here, note type T! + */ static PS_RESULT GetSetting( const CGUI &GUIinstance, const CStr &Object, const CStr &Setting, T &Value) { if (!GUIinstance.ObjectExists(Object)) return PS_OBJECT_FAIL; // Retrieve pointer and call sibling function const CGUIObject *pObject = GetObjectPointer(GUIinstance, Object); return GetSetting(pObject, Setting, Value); } - //-------------------------------------------------------- - // Sets a value by setting and object name using a real - // datatype as input - // Input: - // GUI GUI Object reference since - // we'll be changing values - // Object Object name - // Setting Setting by name - // Value Sets value to this - // note type T! - //-------------------------------------------------------- + /** + * Sets a value by setting and object name using a real + * datatype as input + * + * @param GUI GUI Object, reference since we'll be changing values + * @param Object Object name + * @param Setting Setting by name + * @param Value Sets value to this, note type T! + */ static PS_RESULT SetSetting( CGUI &GUIinstance, const CStr &Object, const CStr &Setting, const T &Value) { if (!GUIinstance.ObjectExists(Object)) return PS_OBJECT_FAIL; // Retrieve pointer and call sibling function // Important, we don't want to use this T, we want // to use the standard T, since that will be the // one with the friend relationship CGUIObject *pObject = GetObjectPointer(GUIinstance, Object); return SetSetting(pObject, Setting, Value); } //-------------------------------------------------------- // This function returns the C++ structure of the // inputted string. For instance if you input // "0 0 10 10" and request a CRect, it will give you // a CRect(0,0,10,10). // This function is widely used within the GUI. // Input: // String The Value in string format // Return: // Returns the value in the structure T. //-------------------------------------------------------- /* static T GetStringValue(const CStr &String) { if (typeid(T) == typeid(int)) { return atoi(String.c_str()); } if (typeid(T) == typeid(float) || typeid(T) == typeid(double)) { return atof(String.c_str()); } if (typeid(T) == typeid(CRect)) { (CRect)return CRect(); } if (typeid(T) == typeid(CColor)) { return CColor(); } switch(typeid(T)) { case typeid(int): return atoi(String); case typeid(float): case typeid(double): return atof(String); case typeid(CRect): return CRect(0,0,0,0); case typeid(CColor): return CColor(0,0,0,0); default: // Repport error unrecognized return T(); } // If this function is called T is unrecognized // TODO repport error return T(); } */ /* static T GetStringValue(const CStr &String) { return atoi(String.c_str()); } */ // int /* static int GetStringValue(const CStr &String) { // If this function is called T is unrecognized // TODO repport error return 10; } */ private: // templated typedef of function pointer typedef void (CGUIObject::*void_Object_pFunction_argT)(const T &arg); typedef void (CGUIObject::*void_Object_pFunction_argRefT)(T &arg); typedef void (CGUIObject::*void_Object_pFunction)(); - //-------------------------------------------------------- - // Recurses an object calling a function on itself - // and all children (and so forth) - // Input: - // RR Recurse Restrictions - // pObject Object to iterate - // pFunc Function to recurse - // Argument Argument of type T - //-------------------------------------------------------- + /** + * If you want to call a CGUIObject-function + * on not just an object, but also on ALL of their children + * you want to use this recursion system. + * It recurses an object calling a function on itself + * and all children (and so forth). + * + * Restrictions:
+ * You can also set restrictions, so that if the recursion + * reaches an objects with certain setup, it just doesn't + * call the function on the object, nor it's children for + * that matter. i.e. it cuts that object off from the + * recursion tree. What setups that can cause restrictions + * are hardcoded and specific. Check out the defines + * GUIRR_* for all different setups. + * + * @param RR Recurse Restrictions + * @param pObject Object to iterate + * @param pFunc Function to recurse + * @param Argument Argument of type T + */ static void RecurseObject(const int &RR, CGUIObject *pObject, void_Object_pFunction_argT pFunc, const T &Argument) { if (CheckIfRestricted(RR, pObject)) return; (pObject->*pFunc)(Argument); // Iterate children vector_pObjects::iterator it; for (it = pObject->ChildrenItBegin(); it != pObject->ChildrenItEnd(); ++it) { RecurseObject(RR, *it, pFunc, Argument); } } - //-------------------------------------------------------- - // Same as above only with reference - //-------------------------------------------------------- + /** + * Argument is reference. + * + * @see RecurseObject() + */ static void RecurseObject(const int &RR, CGUIObject *pObject, void_Object_pFunction_argRefT pFunc, T &Argument) { if (CheckIfRestricted(RR, pObject)) return; (pObject->*pFunc)(Argument); // Iterate children vector_pObjects::iterator it; for (it = pObject->ChildrenItBegin(); it != pObject->ChildrenItEnd(); ++it) { RecurseObject(RR, *it, pFunc, Argument); } } - //-------------------------------------------------------- - // Same as above only with no argument - //-------------------------------------------------------- + /** + * With no argument. + * + * @see RecurseObject() + */ static void RecurseObject(const int &RR, CGUIObject *pObject, void_Object_pFunction pFunc) { if (CheckIfRestricted(RR, pObject)) return; (pObject->*pFunc)(); // Iterate children vector_pObjects::iterator it; for (it = pObject->ChildrenItBegin(); it != pObject->ChildrenItEnd(); ++it) { RecurseObject(RR, *it, pFunc); } } private: - // Sub functions + /** + * Checks restrictions for the iteration, for instance if + * you tell the recursor to avoid all hidden objects, it + * will, and this function checks a certain object's + * restriction values. + * + * @param RR What kind of restriction, for instance hidden or disabled + * @param pObject Object + * @return true if restricted + */ static bool CheckIfRestricted(const int &RR, CGUIObject *pObject) { if (RR & GUIRR_HIDDEN) { if (pObject->GetBaseSettings().m_Hidden) return true; } if (RR & GUIRR_DISABLED) { if (pObject->GetBaseSettings().m_Enabled) return true; } // false means not restricted return false; } }; #endif \ No newline at end of file Index: ps/trunk/source/gui/CGUI.h =================================================================== --- ps/trunk/source/gui/CGUI.h (revision 65) +++ ps/trunk/source/gui/CGUI.h (revision 66) @@ -1,206 +1,287 @@ /* CGUI by Gustav Larsson gee@pyro.nu --Overview-- This is the top class of the whole GUI, all objects and settings are stored within this class. --More info-- Check GUI.h */ #ifndef CGUI_H #define CGUI_H //-------------------------------------------------------- // Includes / Compiler directives //-------------------------------------------------------- #include "GUI.h" #include #include #include ///// janwas: yeah I don't know how the including etiquette is really #include "../ps/Singleton.h" #include "input.h" // JW: grr, classes suck in this case :P class XERCES_CPP_NAMESPACE::DOMElement; //-------------------------------------------------------- // Macros //-------------------------------------------------------- //-------------------------------------------------------- // Types //-------------------------------------------------------- //-------------------------------------------------------- // Error declarations //-------------------------------------------------------- //-------------------------------------------------------- // Declarations //-------------------------------------------------------- +/** + * @author Gustav Larsson + * + * The main object that includes the whole GUI. Is singleton + * and accessed by g_GUI. + */ class CGUI : public Singleton { - // Only CGUIObject's leaf functions uses CGUI // freely. friend class CGUIObject; friend class CInternalCGUIAccessorBase; private: // Private typedefs typedef CGUIObject *(*ConstructObjectFunction)(); - // don't want to pass this around with the ChooseMouseOverAndClosest broadcast - - // we'd need to pack this and pNearest in a struct - u16 m_MouseX, m_MouseY; - public: CGUI(); ~CGUI(); - // Initialize - void Initialize(/*/*nemInput *pInput*/); + /** + * Initializes the GUI, needs to be called before the GUI is used + */ + void Initialize(); - // Process + /** + * @deprecated Will be removed + */ void Process(); - // Draw + /** + * Displays the whole GUI + */ void Draw(); - // Shutdown + /** + * Clean up, call this to clean up all memory allocated + * within the GUI. + */ void Destroy(); + /** + * The replacement of Process(), handles an SDL_Event + * + * @param ev SDL Event, like mouse/keyboard input + */ bool HandleEvent(const SDL_Event& ev); - // Load a GUI XML file + /** + * Load a GUI XML file into the GUI. + * + * @param Filename Name of file + */ void LoadXMLFile(const std::string &Filename); - // Checks if object exists and return true or false accordingly + /** + * Checks if object exists and return true or false accordingly + * + * @param Name String name of object + * @return true if object exists + */ bool ObjectExists(const CStr &Name) const; - // Get pInput -/// CInput *GetInput() { return m_pInput; } - - // to add a type: - // AddObjecType("button", &CButton::ConstructObject); + /** + * The GUI needs to have all object types inputted and + * their constructors. Also it needs to associate a type + * by a string name of the type. + * + * To add a type:
+ * AddObjectType("button", &CButton::ConstructObject); + * + * @param str Reference name of object type + * @param pFunc Pointer of function ConstuctObject() in the object + * + * @see CGUI#ConstructObject() + */ void AddObjectType(const CStr &str, ConstructObjectFunction pFunc) { m_ObjectTypes[str] = pFunc; } private: + /** + * Updates the object pointers, needs to be called each + * time an object has been added or removed. + */ void UpdateObjects(); - // Adds an object to the GUI's object database - // Private, you can only add objects through XML files. + /** + * Adds an object to the GUI's object database + * Private, since you can only add objects through + * XML files. Why? Becasue it enables the GUI to + * be much more encapsulated and safe. + */ void AddObject(CGUIObject* pObject); - // Report a XML parsing error + /** + * Report an XML parsing error + * + * @param str Error message + */ void ReportParseError(const CStr &str, ...); - // Construct an object + /** + * You input the name of the object type, and let's + * say you input "button", then it will construct a + * CGUIObjet* as a CButton. + * + * @param str Name of object type + * @return Newly constructed CGUIObject (but constructed as a subclass) + */ CGUIObject *ConstructObject(const CStr &str); - // + //-------------------------------------------------------- // XML Reading Xerces C++ specific subroutines - // + //-------------------------------------------------------- + /** + * @name Xerces_* Read Function + * + * These does not throw! + * Because when reading in XML files, it won't be fatal + * if an error occurs, perhaps one particular object + * fails, but it'll still continue reading in the next. + * All Error are reported with ReportParseError + */ + //@{ - /** + /* Xerces_* functions tree ========================== (ReadRootObjects) | +- (ReadObject) | +- | +-Optional Type Extensions (CGUIObject::ReadExtendedElement) TODO | +-«object» *recursive* (ReadRootStyles) | +-