Pyrogenesis HEAD
Pyrogenesis, a RTS Engine
IGUIObject Class Referenceabstract

GUI object such as a button or an input-box. More...

#include <IGUIObject.h>

Inheritance diagram for IGUIObject:
Collaboration diagram for IGUIObject:

Public Member Functions

 NONCOPYABLE (IGUIObject)
 
 IGUIObject (CGUI &pGUI)
 
virtual ~IGUIObject ()
 
virtual bool IsMouseOver () const
 This function checks if the mouse is hovering the rectangle that the base setting "size" makes. More...
 
virtual bool IsMouseHovering () const
 This function returns true if the mouse is hovering over this GUI object and if this GUI object is the topmost object in that screen location. More...
 
Leaf Functions
const CStr & GetName () const
 Get object name, name is unique. More...
 
void SetName (const CStr &Name)
 Get object name. More...
 
CStr GetPresentableName () const
 
const std::vector< IGUIObject * > & GetChildren () const
 Return all child objects of the current object. More...
 
Settings Management
void RegisterSetting (const CStr &Name, IGUISetting *setting)
 Registers the given setting with the GUI object. More...
 
void ReregisterSetting (const CStr &Name, IGUISetting *setting)
 
bool SettingExists (const CStr &Setting) const
 Returns whether there is a setting with the given name registered. More...
 
bool SetSettingFromString (const CStr &Setting, const CStrW &Value, const bool SendMessage)
 Set a setting by string, regardless of what type it is. More...
 
bool IsEnabled () const
 Returns whether this object is set to be hidden or ghost. More...
 
bool IsHidden () const
 Returns whether this is object is set to be hidden. More...
 
void SetHidden (bool hidden)
 
bool IsHiddenOrGhost () const
 Returns whether this object is set to be hidden or ghost. More...
 
void PlaySound (const CStrW &soundPath) const
 Retrieves the configured sound filename from the given setting name and plays that once. More...
 
InReaction SendEvent (EGUIMessageType type, const CStr &eventName)
 Send event to this GUI object (HandleMessage and ScriptEvent) More...
 
InReaction SendMouseEvent (EGUIMessageType type, const CStr &eventName)
 Same as SendEvent, but passes mouse coordinates and button state as an argument. More...
 
virtual void UpdateCachedSize ()
 All sizes are relative to resolution, and the calculation is not wanted in real time, therefore it is cached, update the cached size with this function. More...
 
CRect GetComputedSize ()
 Updates and returns the size of the object. More...
 
virtual const CStrW & GetTooltipText () const
 
virtual const CStr & GetTooltipStyle () const
 
virtual void ResetStates ()
 Reset internal state of this object. More...
 
void RegisterScriptHandler (const CStr &eventName, const CStr &Code, CGUI &pGUI)
 Set the script handler for a particular object-specific action. More...
 
JSObject * GetJSObject ()
 Retrieves the JSObject representing this GUI object. More...
 

Friends

class CGUI
 
class IGUISetting
 
template<typename T >
class JSI_GUIProxy
 

Called by CGUI and friends

Methods that the CGUI will call using its friendship, these should not be called by user.

TODO: this comment is old and the following interface should be cleaned up.

CRect m_CachedActualSize
 Cached size, real size m_Size is actually dependent on resolution and can have different real outcomes, this is the real outcome cached to avoid slow calculations in real time. More...
 
virtual void Tick ()
 Called on every GUI tick unless the object or one of its parent is hidden/ghost. More...
 
virtual void HandleMessage (SGUIMessage &Message)
 This function is called with different messages for instance when the mouse enters the object. More...
 
template<typename... Args>
void RecurseObject (bool(IGUIObject::*isRestricted)() const, void(IGUIObject::*callbackFunction)(Args... args), Args &&... args)
 Calls an IGUIObject member function recursively on this object and its children. More...
 
CGUIGetGUI ()
 
const CGUIGetGUI () const
 
void SetFocus ()
 Take focus! More...
 
void ReleaseFocus ()
 Release focus. More...
 
virtual void Draw (CCanvas2D &canvas)=0
 Draws the object. More...
 
virtual InReaction PreemptEvent (const SDL_Event_ *ev)
 Some objects need to be able to pre-emptively process SDL_Event_. More...
 
virtual InReaction ManuallyHandleKeys (const SDL_Event_ *ev)
 Some objects need to handle the text-related SDL_Event_ manually. More...
 
bool ApplyStyle (const CStr &StyleName)
 Applies the given style to the object. More...
 
virtual float GetBufferedZ () const
 Returns not the Z value, but the actual buffered Z value, i.e. More...
 
void RegisterChild (IGUIObject *child)
 Add an object to the hierarchy. More...
 
void UnregisterChild (IGUIObject *child)
 Remove an object from the hierarchy. More...
 
void SetParent (IGUIObject *pParent)
 Set parent of this object. More...
 
bool IsFocused () const
 Check if object is focused. More...
 
IGUIObjectGetParent () const
 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 nullptr, so that the top-node's children are seemingly parentless. More...
 
virtual bool HandleAdditionalChildren (const XMBData &file, const XMBElement &child)
 Handle additional children to the <object>-tag. More...
 
virtual void AdditionalChildrenHandled ()
 Allow the GUI object to process after all child items were handled. More...
 
void ScriptEvent (const CStr &eventName)
 Execute the script for a particular action. More...
 
bool ScriptEventWithReturn (const CStr &eventName)
 Execute the script for a particular action. More...
 
void ScriptEvent (const CStr &eventName, const JS::HandleValueArray &paramData)
 Execute the script for a particular action. More...
 
bool ScriptEventWithReturn (const CStr &eventName, const JS::HandleValueArray &paramData)
 Execute the script for a particular action. More...
 
void SetScriptHandler (const CStr &eventName, JS::HandleObject Function)
 Assigns a JS function to the event name. More...
 
void UnsetScriptHandler (const CStr &eventName)
 Deletes an event handler assigned to the given name, if such a handler exists. More...
 
void UpdateMouseOver (IGUIObject *const &pMouseOver)
 Inputes the object that is currently hovered, this function updates this object accordingly (i.e. More...
 

Internal functions

CStr m_Name
 
std::vector< IGUIObject * > m_Children
 
IGUIObjectm_pParent
 
double m_LastClickTime [6]
 
bool m_MouseHovering
 This variable is true if the mouse is hovering this object and this object is the topmost object shown in this location. More...
 
std::map< CStr, IGUISetting * > m_Settings
 Settings pool, all an object's settings are located here. More...
 
CGUIm_pGUI
 
std::map< CStr, JS::Heap< JSObject * > > m_ScriptHandlers
 
std::unique_ptr< IGUIProxyObjectm_JSObject
 
CGUISimpleSetting< bool > m_Enabled
 
CGUISimpleSetting< bool > m_Hidden
 
CGUISimpleSetting< CGUISizem_Size
 
CGUISimpleSetting< CStr > m_Style
 
CGUIHotkey m_Hotkey
 
CGUISimpleSetting< float > m_Z
 
CGUISimpleSetting< bool > m_Absolute
 
CGUISimpleSetting< bool > m_Ghost
 
CGUISimpleSetting< float > m_AspectRatio
 
CGUISimpleSetting< CStrW > m_Tooltip
 
CGUISimpleSetting< CStr > m_TooltipStyle
 
static const CStr EventNameMouseEnter = "MouseEnter"
 
static const CStr EventNameMouseMove = "MouseMove"
 
static const CStr EventNameMouseLeave = "MouseLeave"
 
virtual void CreateJSObject ()
 Creates the JS object representing this page upon first use. More...
 
void SettingChanged (const CStr &Setting, const bool SendMessage)
 Updates some internal data depending on the setting changed. More...
 
void ChooseMouseOverAndClosest (IGUIObject *&pObject)
 Inputs a reference pointer, checks if the new inputted object if hovered, if so, then check if this's Z value is greater than the inputted object... If so then the object is closer and we'll replace the pointer with this. More...
 
bool IsBaseObject () const
 Returns whether this is the object all other objects are descendants of. More...
 
bool IsRootObject () const
 Returns whether this object is a child of the base object. More...
 
void TraceMember (JSTracer *trc)
 
static void Trace (JSTracer *trc, void *data)
 

Detailed Description

GUI object such as a button or an input-box.

Abstract data type !

Constructor & Destructor Documentation

◆ IGUIObject()

IGUIObject::IGUIObject ( CGUI pGUI)

◆ ~IGUIObject()

IGUIObject::~IGUIObject ( )
virtual

Member Function Documentation

◆ AdditionalChildrenHandled()

virtual void IGUIObject::AdditionalChildrenHandled ( )
inlineprotectedvirtual

Allow the GUI object to process after all child items were handled.

Useful to avoid iterator invalidation with push_back calls.

Reimplemented in COList.

◆ ApplyStyle()

bool IGUIObject::ApplyStyle ( const CStr &  StyleName)
protected

Applies the given style to the object.

Returns false if the style is not recognised (and thus has not been applied).

◆ ChooseMouseOverAndClosest()

void IGUIObject::ChooseMouseOverAndClosest ( IGUIObject *&  pObject)
private

Inputs a reference pointer, checks if the new inputted object if hovered, if so, then check if this's Z value is greater than the inputted object... If so then the object is closer and we'll replace the pointer with this.

Also Notice input can be nullptr, which means the Z value demand is out. NOTICE you can't input nullptr as const so you'll have to set an object to nullptr.

Parameters
pObjectObject pointer, can be either the old one, or the new one.

◆ CreateJSObject()

virtual void IGUIObject::CreateJSObject ( )
privatevirtual

Creates the JS object representing this page upon first use.

This function (and its derived versions) are defined in the GUIProxy implementation file for convenience.

Reimplemented in CButton, CList, CMiniMap, and CText.

◆ Draw()

virtual void IGUIObject::Draw ( CCanvas2D canvas)
protectedpure virtual

◆ GetBufferedZ()

float IGUIObject::GetBufferedZ ( ) const
protectedvirtual

Returns not the Z value, but the actual buffered Z value, i.e.

if it's defined relative, then it will check its parent's Z value and add the relativity.

Returns
Actual Z value on the screen.

Reimplemented in CDropDown, and CTooltip.

◆ GetChildren()

const std::vector< IGUIObject * > & IGUIObject::GetChildren ( ) const
inline

Return all child objects of the current object.

◆ GetComputedSize()

CRect IGUIObject::GetComputedSize ( )

Updates and returns the size of the object.

◆ GetGUI() [1/2]

CGUI & IGUIObject::GetGUI ( )
inline

◆ GetGUI() [2/2]

const CGUI & IGUIObject::GetGUI ( ) const
inline

◆ GetJSObject()

JSObject * IGUIObject::GetJSObject ( )

Retrieves the JSObject representing this GUI object.

◆ GetName()

const CStr & IGUIObject::GetName ( ) const
inline

Get object name, name is unique.

◆ GetParent()

IGUIObject * IGUIObject::GetParent ( ) const
protected

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 nullptr, so that the top-node's children are seemingly parentless.

Returns
Pointer to parent

◆ GetPresentableName()

CStr IGUIObject::GetPresentableName ( ) const

◆ GetTooltipStyle()

virtual const CStr & IGUIObject::GetTooltipStyle ( ) const
inlinevirtual

◆ GetTooltipText()

virtual const CStrW & IGUIObject::GetTooltipText ( ) const
inlinevirtual

Reimplemented in CText.

◆ HandleAdditionalChildren()

virtual bool IGUIObject::HandleAdditionalChildren ( const XMBData file,
const XMBElement child 
)
inlineprotectedvirtual

Handle additional children to the <object>-tag.

In IGUIObject, this function does nothing. In CList and CDropDown, it handles the <item>, used to build the data.

Returning false means the object doesn't recognize the child. Should be reported. Notice 'false' is default, because an object not using this function, should not have any additional children (and this function should never be called).

Reimplemented in CList, and COList.

◆ HandleMessage()

virtual void IGUIObject::HandleMessage ( SGUIMessage Message)
inlinevirtual

This function is called with different messages for instance when the mouse enters the object.

Parameters
MessageGUI Message

Reimplemented in CButton, CChart, CCheckBox, CDropDown, CHotkeyPicker, CInput, CList, CMiniMap, COList, CProgressBar, CRadioButton, CSlider, CText, and CTooltip.

◆ IsBaseObject()

bool IGUIObject::IsBaseObject ( ) const
private

Returns whether this is the object all other objects are descendants of.

◆ IsEnabled()

bool IGUIObject::IsEnabled ( ) const

Returns whether this object is set to be hidden or ghost.

◆ IsFocused()

bool IGUIObject::IsFocused ( ) const
protected

Check if object is focused.

◆ IsHidden()

bool IGUIObject::IsHidden ( ) const

Returns whether this is object is set to be hidden.

◆ IsHiddenOrGhost()

bool IGUIObject::IsHiddenOrGhost ( ) const

Returns whether this object is set to be hidden or ghost.

◆ IsMouseHovering()

virtual bool IGUIObject::IsMouseHovering ( ) const
inlinevirtual

This function returns true if the mouse is hovering over this GUI object and if this GUI object is the topmost object in that screen location.

For example when hovering dropdown list items, the buttons beneath the list won't return true here.

◆ IsMouseOver()

bool IGUIObject::IsMouseOver ( ) const
virtual

This function checks if the mouse is hovering the rectangle that the base setting "size" makes.

Although it is virtual, so one could derive an object from CButton, which changes only this to checking the circle that "size" makes.

This function also returns true if there is a different GUI object shown on top of this one.

Reimplemented in CButton, CDropDown, CGUIDummyObject, and CMiniMap.

◆ IsRootObject()

bool IGUIObject::IsRootObject ( ) const
private

Returns whether this object is a child of the base object.

◆ ManuallyHandleKeys()

virtual InReaction IGUIObject::ManuallyHandleKeys ( const SDL_Event_ ev)
inlineprotectedvirtual

Some objects need to handle the text-related SDL_Event_ manually.

For instance the input box.

Only the object with focus will have this function called.

Returns either IN_PASS or IN_HANDLED. If IN_HANDLED, then the key won't be passed on and processed by other handlers. This is used for keys that the GUI uses.

Reimplemented in CDropDown, CInput, and CList.

◆ NONCOPYABLE()

IGUIObject::NONCOPYABLE ( IGUIObject  )

◆ PlaySound()

void IGUIObject::PlaySound ( const CStrW &  soundPath) const

Retrieves the configured sound filename from the given setting name and plays that once.

◆ PreemptEvent()

virtual InReaction IGUIObject::PreemptEvent ( const SDL_Event_ ev)
inlineprotectedvirtual

Some objects need to be able to pre-emptively process SDL_Event_.

Only the object with focus will have this function called.

Returns either IN_PASS or IN_HANDLED. If IN_HANDLED, then the event won't be passed on and processed by other handlers.

Reimplemented in CHotkeyPicker.

◆ RecurseObject()

template<typename... Args>
void IGUIObject::RecurseObject ( bool(IGUIObject::*)() const  isRestricted,
void(IGUIObject::*)(Args... args)  callbackFunction,
Args &&...  args 
)
inline

Calls an IGUIObject member function recursively on this object and its children.

Aborts recursion at IGUIObjects that have the isRestricted function return true. The arguments of the callback function must be references.

◆ RegisterChild()

void IGUIObject::RegisterChild ( IGUIObject child)
protected

Add an object to the hierarchy.

◆ RegisterScriptHandler()

void IGUIObject::RegisterScriptHandler ( const CStr &  eventName,
const CStr &  Code,
CGUI pGUI 
)

Set the script handler for a particular object-specific action.

Parameters
eventNameName of action
CodeJavascript code to execute when the action occurs
pGUIGUI instance to associate the script with

◆ RegisterSetting()

void IGUIObject::RegisterSetting ( const CStr &  Name,
IGUISetting setting 
)

Registers the given setting with the GUI object.

Enable XML and JS to modify the given variable.

◆ ReleaseFocus()

void IGUIObject::ReleaseFocus ( )

Release focus.

◆ ReregisterSetting()

void IGUIObject::ReregisterSetting ( const CStr &  Name,
IGUISetting setting 
)

◆ ResetStates()

void IGUIObject::ResetStates ( )
virtual

Reset internal state of this object.

Reimplemented in CButton, CCheckBox, CInput, CList, CSlider, and CText.

◆ ScriptEvent() [1/2]

void IGUIObject::ScriptEvent ( const CStr &  eventName)
protected

Execute the script for a particular action.

Does nothing if no script has been registered for that action. The mouse coordinates will be passed as the first argument.

Parameters
eventNameName of action

◆ ScriptEvent() [2/2]

void IGUIObject::ScriptEvent ( const CStr &  eventName,
const JS::HandleValueArray &  paramData 
)
protected

Execute the script for a particular action.

Does nothing if no script has been registered for that action.

Parameters
eventNameName of action
paramDataJS::HandleValueArray arguments to pass to the event.

◆ ScriptEventWithReturn() [1/2]

bool IGUIObject::ScriptEventWithReturn ( const CStr &  eventName)
protected

Execute the script for a particular action.

Does nothing if no script has been registered for that action. The mouse coordinates will be passed as the first argument.

Parameters
eventNameName of action
Returns
True if the script returned something truthy.

◆ ScriptEventWithReturn() [2/2]

bool IGUIObject::ScriptEventWithReturn ( const CStr &  eventName,
const JS::HandleValueArray &  paramData 
)
protected

Execute the script for a particular action.

Does nothing if no script has been registered for that action.

Parameters
eventNameName of action
paramDataJS::HandleValueArray arguments to pass to the event.
Returns
True if the script returned something truthy.

◆ SendEvent()

InReaction IGUIObject::SendEvent ( EGUIMessageType  type,
const CStr &  eventName 
)

Send event to this GUI object (HandleMessage and ScriptEvent)

Parameters
typeType of GUI message to be handled
eventNameString representation of event name
Returns
IN_HANDLED if event was handled, or IN_PASS if skipped

◆ SendMouseEvent()

InReaction IGUIObject::SendMouseEvent ( EGUIMessageType  type,
const CStr &  eventName 
)

Same as SendEvent, but passes mouse coordinates and button state as an argument.

◆ SetFocus()

void IGUIObject::SetFocus ( )

Take focus!

◆ SetHidden()

void IGUIObject::SetHidden ( bool  hidden)
inline

◆ SetName()

void IGUIObject::SetName ( const CStr &  Name)
inline

Get object name.

◆ SetParent()

void IGUIObject::SetParent ( IGUIObject pParent)
inlineprotected

Set parent of this object.

◆ SetScriptHandler()

void IGUIObject::SetScriptHandler ( const CStr &  eventName,
JS::HandleObject  Function 
)
protected

Assigns a JS function to the event name.

◆ SetSettingFromString()

bool IGUIObject::SetSettingFromString ( const CStr &  Setting,
const CStrW &  Value,
const bool  SendMessage 
)

Set a setting by string, regardless of what type it is.

Used to parse setting values from XML files. For example a CRect(10,10,20,20) is created from "10 10 20 20".

Returns
false if the setting does not exist or the conversion fails, otherwise true.

◆ SettingChanged()

void IGUIObject::SettingChanged ( const CStr &  Setting,
const bool  SendMessage 
)
private

Updates some internal data depending on the setting changed.

◆ SettingExists()

bool IGUIObject::SettingExists ( const CStr &  Setting) const

Returns whether there is a setting with the given name registered.

Parameters
Settingsetting name
Returns
True if settings exist.

◆ Tick()

virtual void IGUIObject::Tick ( )
inlinevirtual

Called on every GUI tick unless the object or one of its parent is hidden/ghost.

Reimplemented in CHotkeyPicker.

◆ Trace()

static void IGUIObject::Trace ( JSTracer *  trc,
void *  data 
)
inlinestaticprivate

◆ TraceMember()

void IGUIObject::TraceMember ( JSTracer *  trc)
private

◆ UnregisterChild()

void IGUIObject::UnregisterChild ( IGUIObject child)
protected

Remove an object from the hierarchy.

◆ UnsetScriptHandler()

void IGUIObject::UnsetScriptHandler ( const CStr &  eventName)
protected

Deletes an event handler assigned to the given name, if such a handler exists.

◆ UpdateCachedSize()

void IGUIObject::UpdateCachedSize ( )
virtual

All sizes are relative to resolution, and the calculation is not wanted in real time, therefore it is cached, update the cached size with this function.

Reimplemented in CButton, CChart, CDropDown, CInput, CList, CText, and CTooltip.

◆ UpdateMouseOver()

void IGUIObject::UpdateMouseOver ( IGUIObject *const &  pMouseOver)
protected

Inputes the object that is currently hovered, this function updates this object accordingly (i.e.

if it's the object being inputted one thing happens, and not, another).

Parameters
pMouseOverObject that is currently hovered, can be nullptr too!

Friends And Related Function Documentation

◆ CGUI

friend class CGUI
friend

◆ IGUISetting

friend class IGUISetting
friend

◆ JSI_GUIProxy

template<typename T >
friend class JSI_GUIProxy
friend

Member Data Documentation

◆ EventNameMouseEnter

const CStr IGUIObject::EventNameMouseEnter = "MouseEnter"
staticprotected

◆ EventNameMouseLeave

const CStr IGUIObject::EventNameMouseLeave = "MouseLeave"
staticprotected

◆ EventNameMouseMove

const CStr IGUIObject::EventNameMouseMove = "MouseMove"
staticprotected

◆ m_Absolute

CGUISimpleSetting<bool> IGUIObject::m_Absolute
protected

◆ m_AspectRatio

CGUISimpleSetting<float> IGUIObject::m_AspectRatio
protected

◆ m_CachedActualSize

CRect IGUIObject::m_CachedActualSize
protected

Cached size, real size m_Size is actually dependent on resolution and can have different real outcomes, this is the real outcome cached to avoid slow calculations in real time.

◆ m_Children

std::vector<IGUIObject*> IGUIObject::m_Children
protected

◆ m_Enabled

CGUISimpleSetting<bool> IGUIObject::m_Enabled
protected

◆ m_Ghost

CGUISimpleSetting<bool> IGUIObject::m_Ghost
protected

◆ m_Hidden

CGUISimpleSetting<bool> IGUIObject::m_Hidden
protected

◆ m_Hotkey

CGUIHotkey IGUIObject::m_Hotkey
protected

◆ m_JSObject

std::unique_ptr<IGUIProxyObject> IGUIObject::m_JSObject
protected

◆ m_LastClickTime

double IGUIObject::m_LastClickTime[6]
protected

◆ m_MouseHovering

bool IGUIObject::m_MouseHovering
protected

This variable is true if the mouse is hovering this object and this object is the topmost object shown in this location.

◆ m_Name

CStr IGUIObject::m_Name
protected

◆ m_pGUI

CGUI& IGUIObject::m_pGUI
protected

◆ m_pParent

IGUIObject* IGUIObject::m_pParent
protected

◆ m_ScriptHandlers

std::map<CStr, JS::Heap<JSObject*> > IGUIObject::m_ScriptHandlers
protected

◆ m_Settings

std::map<CStr, IGUISetting*> IGUIObject::m_Settings
protected

Settings pool, all an object's settings are located here.

◆ m_Size

CGUISimpleSetting<CGUISize> IGUIObject::m_Size
protected

◆ m_Style

CGUISimpleSetting<CStr> IGUIObject::m_Style
protected

◆ m_Tooltip

CGUISimpleSetting<CStrW> IGUIObject::m_Tooltip
protected

◆ m_TooltipStyle

CGUISimpleSetting<CStr> IGUIObject::m_TooltipStyle
protected

◆ m_Z

CGUISimpleSetting<float> IGUIObject::m_Z
protected

The documentation for this class was generated from the following files: