This documents an old version of bs::framework. Click here to see the latest release.
GUIElementBase Class Referenceabstract

Description

Base class for all GUI elements (visible or layout).

Inherited by GUIElement, GUIFixedSpace, GUIFlexibleSpace, and GUILayout.

Methods

 GUIElementBase (const GUIDimensions &dimensions)
 
void setPosition (INT32 x, INT32 y)
 Sets element position relative to parent GUI panel. More...
 
void setWidth (UINT32 width)
 Sets element width in pixels. More...
 
void setFlexibleWidth (UINT32 minWidth=0, UINT32 maxWidth=0)
 Sets element width in pixels. More...
 
void setHeight (UINT32 height)
 Sets element height in pixels. More...
 
void setSize (UINT32 width, UINT32 height)
 Sets width and height of a GUI element in pixels. More...
 
void setFlexibleHeight (UINT32 minHeight=0, UINT32 maxHeight=0)
 Sets element height in pixels. More...
 
virtual void resetDimensions ()
 Resets element dimensions to their initial values dictated by the element's style. More...
 
void setVisible (bool visible)
 Hides or shows this element and recursively applies the same state to all the child elements. More...
 
void setActive (bool active)
 Activates or deactives this element and recursively applies the same state to all the child elements. More...
 
void setDisabled (bool disabled)
 Disables or enables the element. More...
 
Rect2I getBounds (GUIPanel *relativeTo=nullptr)
 Returns non-clipped bounds of the GUI element. More...
 
void setBounds (const Rect2I &bounds)
 Sets the bounds of the GUI element. More...
 
Rect2I getGlobalBounds ()
 Returns non-clipped bounds of the GUI element. More...
 
Rect2I getScreenBounds () const
 Returns non-clipped bounds of the GUI element in screenspace. More...
 
virtual Rect2I getVisibleBounds ()
 Returns non-clipped visible bounds of the GUI element (bounds exclude the margins). More...
 
Internal
virtual void _updateLayout (const GUILayoutData &data)
 Updates child elements positions, sizes, clip rectangles and depths so they fit into the provided bounds, while respecting their layout options. More...
 
virtual void _updateOptimalLayoutSizes ()
 Calculates optimal sizes of all child elements, as determined by their style and layout options. More...
 
virtual void _updateLayoutInternal (const GUILayoutData &data)
 Updates child elements positions, sizes, clip rectangles and depths so they fit into the provided bounds, while respecting their layout options. More...
 
virtual void _getElementAreas (const Rect2I &layoutArea, Rect2I *elementAreas, UINT32 numElements, const Vector< LayoutSizeRange > &sizeRanges, const LayoutSizeRange &mySizeRange) const
 Calculates positions & sizes of all elements in the layout. More...
 
virtual void _setLayoutData (const GUILayoutData &data)
 Updates layout data that determines GUI elements final position & depth in the GUI widget. More...
 
const GUILayoutData_getLayoutData () const
 Retrieves layout data that determines GUI elements final position & depth in the GUI widget. More...
 
void _setParent (GUIElementBase *parent)
 Sets a new parent for this element. More...
 
UINT32 _getNumChildren () const
 Returns number of child elements. More...
 
GUIElementBase_getChild (UINT32 idx) const
 Return the child element at the specified index. More...
 
virtual Vector2I _getOptimalSize () const =0
 Returns previously calculated optimal size for this element. More...
 
const GUIDimensions_getDimensions () const
 Returns layout options that determine how is the element positioned and sized. More...
 
virtual LayoutSizeRange _calculateLayoutSizeRange () const
 Calculates element size range constrained by its layout options. More...
 
virtual LayoutSizeRange _getLayoutSizeRange () const
 Returns element size range constrained by its layout options. More...
 
virtual const RectOffset_getPadding () const =0
 Returns element padding that determines how far apart to space out this element from other elements in a layout.
 
virtual Type _getType () const =0
 Returns specific sub-type of this object. More...
 
GUIElementBase_getParent () const
 Returns parent GUI base element. More...
 
GUIElementBase_getUpdateParent () const
 Returns the parent element whose layout needs to be updated when this elements contents change. More...
 
GUIWidget_getParentWidget () const
 Returns parent GUI widget, can be null. More...
 
bool _isVisible () const
 Checks if element is visible or hidden. More...
 
bool _isActive () const
 Checks if element is active or inactive. More...
 
bool _isDisabled () const
 Checks if element is disabled. More...
 
void _setVisible (bool visible)
 Internal version of setVisible() that doesn't modify local visibility, instead it is only meant to be called on child elements of the element whose visibility was modified.
 
void _setActive (bool active)
 Internal version of setActive() that doesn't modify local state, instead it is only meant to be called on child elements of the element whose state was modified. More...
 
void _setDisabled (bool disabled)
 Internal version of setDisabled() that doesn't modify local state, instead it is only meant to be called on child elements of the element whose state was modified. More...
 
virtual void _changeParentWidget (GUIWidget *widget)
 Changes the active GUI element widget. More...
 
void _registerChildElement (GUIElementBase *element)
 Registers a new child element. More...
 
void _unregisterChildElement (GUIElementBase *element)
 Unregisters an existing child element. More...
 
virtual bool _isDestroyed () const
 Checks if element has been destroyed and is queued for deletion. More...
 
void _markLayoutAsDirty ()
 Marks the element's dimensions as dirty, triggering a layout rebuild. More...
 
void _markContentAsDirty ()
 Marks the element's contents as dirty, which causes the sprite meshes to be recreated from scratch. More...
 
void _markMeshAsDirty ()
 Mark only the elements that operate directly on the sprite mesh without requiring the mesh to be recreated as dirty. More...
 
bool _isDirty () const
 Returns true if elements contents have changed since last update. More...
 
void _markAsClean ()
 Marks the element contents to be up to date (meaning it's processed by the GUI system). More...
 

Public Types

enum  Type {
  Layout, Element, FixedSpace, FlexibleSpace,
  Panel
}
 Valid types of GUI base elements. More...
 

Protected Types

enum  GUIElementFlags {
  GUIElem_Dirty = 0x01, GUIElem_Hidden = 0x02, GUIElem_Inactive = 0x04, GUIElem_HiddenSelf = 0x08,
  GUIElem_InactiveSelf = 0x10, GUIElem_Disabled = 0x20, GUIElem_DisabledSelf = 0x40
}
 Flags that signal the state of the GUI element. More...
 

Method documentation

◆ _calculateLayoutSizeRange()

virtual LayoutSizeRange _calculateLayoutSizeRange ( ) const
virtual

Calculates element size range constrained by its layout options.

Reimplemented in GUIScrollArea, GUIFlexibleSpace, GUIPanel, GUIFixedSpace, GUILayoutX, and GUILayoutY.

◆ _changeParentWidget()

virtual void _changeParentWidget ( GUIWidget widget)
virtual

Changes the active GUI element widget.

This allows you to move an element to a different viewport, or change element style by using a widget with a different skin. You are allowed to pass null here, but elements with no parent will be unmanaged. You will be responsible for deleting them manually, and they will not render anywhere.

Reimplemented in GUIElement.

◆ _getChild()

GUIElementBase* _getChild ( UINT32  idx) const

Return the child element at the specified index.

◆ _getDimensions()

const GUIDimensions& _getDimensions ( ) const

Returns layout options that determine how is the element positioned and sized.

◆ _getElementAreas()

virtual void _getElementAreas ( const Rect2I layoutArea,
Rect2I elementAreas,
UINT32  numElements,
const Vector< LayoutSizeRange > &  sizeRanges,
const LayoutSizeRange mySizeRange 
) const
virtual

Calculates positions & sizes of all elements in the layout.

This method expects a pre-allocated array to store the data in.

Parameters
[in]layoutAreaParent layout area to position the child elements in.
[out]elementAreasArray to hold output areas. Must be the same size as the number of child elements.
[in]numElementsSize of the element areas array.
[in]sizeRangesRanges of possible sizes used for the child elements. Array must be same size as elements array.
[in]mySizeRangeSize range of this element.

Reimplemented in GUIPanel, GUILayoutX, and GUILayoutY.

◆ _getLayoutData()

const GUILayoutData& _getLayoutData ( ) const

Retrieves layout data that determines GUI elements final position & depth in the GUI widget.

◆ _getLayoutSizeRange()

virtual LayoutSizeRange _getLayoutSizeRange ( ) const
virtual

Returns element size range constrained by its layout options.

This is different from _calculateLayoutSizeRange() because this method may return cached size range.

Reimplemented in GUIScrollArea, and GUILayout.

◆ _getNumChildren()

UINT32 _getNumChildren ( ) const

Returns number of child elements.

◆ _getOptimalSize()

virtual Vector2I _getOptimalSize ( ) const
pure virtual

◆ _getParent()

GUIElementBase* _getParent ( ) const

Returns parent GUI base element.

◆ _getParentWidget()

GUIWidget* _getParentWidget ( ) const

Returns parent GUI widget, can be null.

◆ _getType()

virtual Type _getType ( ) const
pure virtual

Returns specific sub-type of this object.

Implemented in GUIElement, GUIFlexibleSpace, GUILayout, GUIPanel, and GUIFixedSpace.

◆ _getUpdateParent()

GUIElementBase* _getUpdateParent ( ) const

Returns the parent element whose layout needs to be updated when this elements contents change.

Note

Due to the nature of the GUI system, when a child element bounds or contents change, its parents and siblings usually need their layout bound updated. This function returns the first parent of all the elements that require updating. This parent usually has fixed bounds or some other property that allows its children to be updated independently from the even higher-up elements.

◆ _isActive()

bool _isActive ( ) const

Checks if element is active or inactive.

Inactive elements are not visible, don't take up space in their parent layouts, and can't be interacted with.

◆ _isDestroyed()

virtual bool _isDestroyed ( ) const
virtual

Checks if element has been destroyed and is queued for deletion.

Reimplemented in GUIElement.

◆ _isDirty()

bool _isDirty ( ) const

Returns true if elements contents have changed since last update.

◆ _isDisabled()

bool _isDisabled ( ) const

Checks if element is disabled.

Disabled elements cannot be interacted with and have a faded out appearance.

◆ _isVisible()

bool _isVisible ( ) const

Checks if element is visible or hidden.

◆ _markAsClean()

void _markAsClean ( )

Marks the element contents to be up to date (meaning it's processed by the GUI system).

◆ _markContentAsDirty()

void _markContentAsDirty ( )

Marks the element's contents as dirty, which causes the sprite meshes to be recreated from scratch.

◆ _markLayoutAsDirty()

void _markLayoutAsDirty ( )

Marks the element's dimensions as dirty, triggering a layout rebuild.

◆ _markMeshAsDirty()

void _markMeshAsDirty ( )

Mark only the elements that operate directly on the sprite mesh without requiring the mesh to be recreated as dirty.

This includes position, depth and clip rectangle. This will cause the parent widget mesh to be rebuilt from its child element's meshes.

◆ _registerChildElement()

void _registerChildElement ( GUIElementBase element)

Registers a new child element.

◆ _setActive()

void _setActive ( bool  active)

Internal version of setActive() that doesn't modify local state, instead it is only meant to be called on child elements of the element whose state was modified.

Activates or deactives this element and recursively applies the same state to all the child elements. This has the same effect as setVisible(), but when disabled it will also remove the element from the layout, essentially having the same effect is if you destroyed the element.

◆ _setDisabled()

void _setDisabled ( bool  disabled)

Internal version of setDisabled() that doesn't modify local state, instead it is only meant to be called on child elements of the element whose state was modified.

Disables or enables the element. Disabled elements cannot be interacted with and have a faded out appearance.

◆ _setLayoutData()

virtual void _setLayoutData ( const GUILayoutData data)
virtual

Updates layout data that determines GUI elements final position & depth in the GUI widget.

Reimplemented in GUIElement.

◆ _setParent()

void _setParent ( GUIElementBase parent)

Sets a new parent for this element.

◆ _unregisterChildElement()

void _unregisterChildElement ( GUIElementBase element)

Unregisters an existing child element.

◆ _updateAUParents()

void _updateAUParents ( )
protected

Finds anchor and update parents and recursively assigns them to all children.

◆ _updateLayout()

virtual void _updateLayout ( const GUILayoutData data)
virtual

Updates child elements positions, sizes, clip rectangles and depths so they fit into the provided bounds, while respecting their layout options.

Parameters
[in]dataLayout data containing the necessary bounds and restrictions to use for calculating the child element layout data.

◆ _updateLayoutInternal()

virtual void _updateLayoutInternal ( const GUILayoutData data)
virtual

Updates child elements positions, sizes, clip rectangles and depths so they fit into the provided bounds, while respecting their layout options.

Parameters
[in]dataLayout data containing the necessary bounds and restrictions to use for calculating the child element layout data.

Reimplemented in GUIPanel, GUISlider, GUIDropDownContent, GUIProgressBar, GUILayoutX, and GUILayoutY.

◆ _updateOptimalLayoutSizes()

virtual void _updateOptimalLayoutSizes ( )
virtual

Calculates optimal sizes of all child elements, as determined by their style and layout options.

Reimplemented in GUIScrollArea, GUIPanel, GUILayoutX, and GUILayoutY.

◆ destroyChildElements()

void destroyChildElements ( )
protected

Unregisters and destroys all child elements.

◆ findUpdateParent()

GUIElementBase* findUpdateParent ( )
protected

Finds the first parent element whose size doesn't depend on child sizes.

Note

This allows us to optimize layout updates and trigger them only on such parents when their child elements contents change, compared to doing them on the entire GUI hierarchy.

◆ getBounds()

Rect2I getBounds ( GUIPanel relativeTo = nullptr)

Returns non-clipped bounds of the GUI element.

Relative to a parent GUI panel.

Parameters
[in]relativeToParent panel of the provided element relative to which to return the bounds. If null the bounds relative to the first parent panel are returned. Behavior is undefined if provided panel is not a parent of the element.
Note
This call can be potentially expensive if the GUI state is dirty.

◆ getGlobalBounds()

Rect2I getGlobalBounds ( )

Returns non-clipped bounds of the GUI element.

Relative to a parent GUI widget.

Note
This call can be potentially expensive if the GUI state is dirty.

◆ getScreenBounds()

Rect2I getScreenBounds ( ) const

Returns non-clipped bounds of the GUI element in screenspace.

Note
This call can be potentially expensive if the GUI state is dirty.

◆ getVisibleBounds()

virtual Rect2I getVisibleBounds ( )
virtual

Returns non-clipped visible bounds of the GUI element (bounds exclude the margins).

Relative to the parent GUI panel.

Note
This call can be potentially expensive as the bounds need to be calculated based on current GUI state.

Reimplemented in GUIElement.

◆ refreshChildUpdateParents()

void refreshChildUpdateParents ( )
protected

Refreshes update parents of all child elements.

◆ resetDimensions()

virtual void resetDimensions ( )
virtual

Resets element dimensions to their initial values dictated by the element's style.

Reimplemented in GUIElement.

◆ setActive()

void setActive ( bool  active)

Activates or deactives this element and recursively applies the same state to all the child elements.

This has the same effect as setVisible(), but when disabled it will also remove the element from the layout, essentially having the same effect is if you destroyed the element.

◆ setAnchorParent()

void setAnchorParent ( GUIPanel anchorParent)
protected

Helper method for recursion in _updateAUParents().

Sets the provided anchor parent for all children recursively. Recursion stops when a child anchor is detected.

◆ setBounds()

void setBounds ( const Rect2I bounds)

Sets the bounds of the GUI element.

Relative to a parent GUI panel. Equivalent to calling setPosition(), setWidth() and setHeight().

◆ setDisabled()

void setDisabled ( bool  disabled)

Disables or enables the element.

Disabled elements cannot be interacted with and have a faded out appearance.

◆ setFlexibleHeight()

void setFlexibleHeight ( UINT32  minHeight = 0,
UINT32  maxHeight = 0 
)

Sets element height in pixels.

Element will be resized according to its contents and parent layout but will always stay within the provided range. If maximum height is zero, the element is allowed to expand as much as it needs.

◆ setFlexibleWidth()

void setFlexibleWidth ( UINT32  minWidth = 0,
UINT32  maxWidth = 0 
)

Sets element width in pixels.

Element will be resized according to its contents and parent layout but will always stay within the provided range. If maximum width is zero, the element is allowed to expand as much as it needs.

◆ setHeight()

void setHeight ( UINT32  height)

Sets element height in pixels.

◆ setPosition()

void setPosition ( INT32  x,
INT32  y 
)

Sets element position relative to parent GUI panel.

Note

Be aware that this value will be ignored if GUI element is part of a layout since then the layout controls its placement.

◆ setSize()

void setSize ( UINT32  width,
UINT32  height 
)

Sets width and height of a GUI element in pixels.

◆ setUpdateParent()

void setUpdateParent ( GUIElementBase updateParent)
protected

Helper method for recursion in _updateAUParents().

Sets the provided update parent for all children recursively. Recursion stops when a child update parent is detected.

◆ setVisible()

void setVisible ( bool  visible)

Hides or shows this element and recursively applies the same state to all the child elements.

This will not remove the element from the layout, the room for it will still be reserved but it just won't be visible.

◆ setWidth()

void setWidth ( UINT32  width)

Sets element width in pixels.

Member Enumeration Documentation

◆ GUIElementFlags

enum GUIElementFlags
protected

Flags that signal the state of the GUI element.

◆ Type

enum Type
strong

Valid types of GUI base elements.