GUIScrollArea Class Reference

Description

A GUI element container with support for vertical & horizontal scrolling.

Inherits GUIElementContainer.

Methods

GUILayoutgetLayout () const
 Returns the scroll area layout that you may use to add elements inside the scroll area. More...
 
void scrollUpPx (UINT32 pixels)
 Scrolls the area up by specified amount of pixels, if possible. More...
 
void scrollDownPx (UINT32 pixels)
 Scrolls the area down by specified amount of pixels, if possible. More...
 
void scrollLeftPx (UINT32 pixels)
 Scrolls the area left by specified amount of pixels, if possible. More...
 
void scrollRightPx (UINT32 pixels)
 Scrolls the area right by specified amount of pixels, if possible. More...
 
void scrollUpPct (float percent)
 Scrolls the area up by specified percentage (ranging [0, 1]), if possible. More...
 
void scrollDownPct (float percent)
 Scrolls the area down by specified percentage (ranging [0, 1]), if possible. More...
 
void scrollLeftPct (float percent)
 Scrolls the area left by specified percentage (ranging [0, 1]), if possible. More...
 
void scrollRightPct (float percent)
 Scrolls the area right by specified percentage (ranging [0, 1]), if possible. More...
 
void scrollToVertical (float pct)
 Scrolls the contents to the specified position (0 meaning top-most part of the content is visible, and 1 meaning bottom-most part is visible).
 
void scrollToHorizontal (float pct)
 Scrolls the contents to the specified position (0 meaning left-most part of the content is visible, and 1 meaning right-most part is visible)
 
float getVerticalScroll () const
 Returns how much is the scroll area scrolled in the vertical direction. More...
 
float getHorizontalScroll () const
 Returns how much is the scroll area scrolled in the horizontal direction. More...
 
Rect2I getContentBounds ()
 Returns the bounds of the scroll area not including the scroll bars (meaning only the portion that contains the contents).
 
Internal
ElementType _getElementType () const override
 Gets internal element style representing the exact type of GUI element in this object. More...
 
- Methods inherited from GUIElement
 GUIElement (const String &styleName, const GUIDimensions &dimensions)
 
void setFocus (bool enabled)
 Sets or removes focus from an element. More...
 
virtual void setTint (const Color &color)
 Sets the tint of the GUI element. More...
 
void resetDimensions () override
 Resets element dimensions to their initial values dictated by the element's style. More...
 
void setStyle (const String &styleName)
 Sets new style to be used by the element. More...
 
const StringgetStyleName () const
 Returns the name of the style used by this element. More...
 
void setBlockPointerEvents (bool block)
 Determines will this element block elements underneath it from receiving pointer events (clicks, focus gain/lost, hover on/off, etc.). More...
 
bool getBlockPointerEvents () const
 Determines will this element block elements underneath it from receiving pointer events (clicks, focus gain/lost, hover on/off, etc.). More...
 
void setContextMenu (const SPtr< GUIContextMenu > &menu)
 Assigns a new context menu that will be opened when the element is right clicked. More...
 
Rect2I getVisibleBounds () override
 Returns non-clipped visible bounds of the GUI element (bounds exclude the margins). More...
 
void _updateRenderElements ()
 Recreates the internal render elements. More...
 
virtual bool _textInputEvent (const GUITextInputEvent &ev)
 Called when some text is input and the GUI element has input focus. More...
 
virtual bool _virtualButtonEvent (const GUIVirtualButtonEvent &ev)
 Called when a virtual button is pressed/released and the GUI element has input focus. More...
 
void _setElementDepth (UINT8 depth)
 Set element part of element depth. More...
 
UINT8 _getElementDepth () const
 Retrieve element part of element depth. More...
 
void _setLayoutData (const GUILayoutData &data) override
 Updates layout data that determines GUI elements final position & depth in the GUI widget. More...
 
void _changeParentWidget (GUIWidget *widget) override
 Changes the active GUI element widget. More...
 
virtual UINT32 _getRenderElementDepth (UINT32 renderElementIdx) const
 Returns depth for a specific render element. More...
 
virtual UINT32 _getRenderElementDepthRange () const
 Returns the range of depths that the child elements can be rendered it. More...
 
Type _getType () const override
 Gets internal element style representing the exact type of GUI element in this object. More...
 
bool _isDestroyed () const override
 Checks if element has been destroyed and is queued for deletion. More...
 
void _refreshStyle ()
 Update element style based on active GUI skin and style name. More...
 
const GUIElementStyle_getStyle () const
 Gets the currently active element style. More...
 
const Rect2I_getClippedBounds () const
 Gets GUI element bounds relative to parent widget, clipped by specified clip rect. More...
 
const RectOffset_getPadding () const override
 Returns GUI element padding. More...
 
UINT32 _getDepth () const
 Returns GUI element depth. More...
 
virtual bool _isInBounds (const Vector2I position) const
 Checks is the specified position within GUI element bounds. More...
 
virtual bool _hasCustomCursor (const Vector2I position, CursorType &type) const
 Checks if the GUI element has a custom cursor and outputs the cursor type if it does. More...
 
virtual bool _acceptDragAndDrop (const Vector2I position, UINT32 typeId) const
 Checks if the GUI element accepts a drag and drop operation of the specified type. More...
 
virtual SPtr< GUIContextMenu_getContextMenu () const
 Returns a context menu if a GUI element has one. More...
 
virtual WString _getTooltip () const
 Returns text to display when hovering over the element. More...
 
virtual Vector2I _getTextInputOffset () const
 Returns a clip rectangle relative to the element, used for offsetting the input text. More...
 
virtual Rect2I _getTextInputRect () const
 Returns a clip rectangle relative to the element, used for clipping the input text. More...
 
- Methods inherited from GUIElementBase
 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...
 
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...
 
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...
 
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...
 
const GUIDimensions_getDimensions () const
 Returns layout options that determine how is the element positioned and sized. 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...
 
void _registerChildElement (GUIElementBase *element)
 Registers a new child element. More...
 
void _unregisterChildElement (GUIElementBase *element)
 Unregisters an existing child element. 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...
 

Static methods

static const StringgetGUITypeName ()
 Returns type name of the GUI element used for finding GUI element styles. More...
 
static GUIScrollAreacreate (ScrollBarType vertBarType, ScrollBarType horzBarType, const String &scrollBarStyle=StringUtil::BLANK, const String &scrollAreaStyle=StringUtil::BLANK)
 Creates a new empty scroll area. More...
 
static GUIScrollAreacreate (ScrollBarType vertBarType, ScrollBarType horzBarType, const GUIOptions &options, const String &scrollBarStyle=StringUtil::BLANK, const String &scrollAreaStyle=StringUtil::BLANK)
 Creates a new empty scroll area. More...
 
static GUIScrollAreacreate (const String &scrollBarStyle=StringUtil::BLANK, const String &scrollAreaStyle=StringUtil::BLANK)
 Creates a new empty scroll area. More...
 
static GUIScrollAreacreate (const GUIOptions &options, const String &scrollBarStyle=StringUtil::BLANK, const String &scrollAreaStyle=StringUtil::BLANK)
 Creates a new empty scroll area. More...
 
- Static methods inherited from GUIElement
static void destroy (GUIElement *element)
 Destroy the element. More...
 

Static fields

static const UINT32 ScrollBarWidth
 Number of pixels the scroll bar will occupy when active. More...
 

Additional Inherited Members

- Fields inherited from GUIElement
Event< void(bool)> onFocusChanged
 Triggered when the element loses or gains focus. More...
 
- Public Types inherited from GUIElement
enum  ElementType {
  Label, Button, Toggle, Texture,
  InputBox, ListBox, ScrollArea, Layout,
  Undefined
}
 Different sub-types of GUI elements. More...
 
- Public Types inherited from GUIElementBase
enum  Type {
  Layout, Element, FixedSpace, FlexibleSpace,
  Panel
}
 Valid types of GUI base elements. More...
 
- Protected Types inherited from GUIElementBase
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

LayoutSizeRange _calculateLayoutSizeRange ( ) const
overrideprotectedvirtual

Calculates element size range constrained by its layout options.

Reimplemented from GUIElementBase.

ElementType _getElementType ( ) const
overridevirtual

Gets internal element style representing the exact type of GUI element in this object.

Reimplemented from GUIElement.

LayoutSizeRange _getLayoutSizeRange ( ) const
overrideprotectedvirtual

Returns element size range constrained by its layout options.

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

Reimplemented from GUIElementBase.

Vector2I _getOptimalSize ( ) const
overrideprotectedvirtual

Returns previously calculated optimal size for this element.

Reimplemented from GUIElementContainer.

void _updateOptimalLayoutSizes ( )
overrideprotectedvirtual

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

Reimplemented from GUIElementBase.

static GUIScrollArea* create ( ScrollBarType  vertBarType,
ScrollBarType  horzBarType,
const String scrollBarStyle = StringUtil::BLANK,
const String scrollAreaStyle = StringUtil::BLANK 
)
static

Creates a new empty scroll area.

Parameters
[in]vertBarTypeVertical scrollbar options.
[in]horzBarTypeHorizontal scrollbar options.
[in]scrollBarStyleStyle used by the scroll bars.
[in]scrollAreaStyleStyle used by the scroll content area.
static GUIScrollArea* create ( ScrollBarType  vertBarType,
ScrollBarType  horzBarType,
const GUIOptions options,
const String scrollBarStyle = StringUtil::BLANK,
const String scrollAreaStyle = StringUtil::BLANK 
)
static

Creates a new empty scroll area.

Parameters
[in]vertBarTypeVertical scrollbar options.
[in]horzBarTypeHorizontal scrollbar options.
[in]optionsOptions that allow you to control how is the element positioned and sized. This will override any similar options set by style.
[in]scrollBarStyleStyle used by the scroll bars.
[in]scrollAreaStyleStyle used by the scroll content area.
static GUIScrollArea* create ( const String scrollBarStyle = StringUtil::BLANK,
const String scrollAreaStyle = StringUtil::BLANK 
)
static

Creates a new empty scroll area.

Scroll bars will be show if needed and hidden otherwise.

Parameters
[in]scrollBarStyleStyle used by the scroll bars.
[in]scrollAreaStyleStyle used by the scroll content area.
static GUIScrollArea* create ( const GUIOptions options,
const String scrollBarStyle = StringUtil::BLANK,
const String scrollAreaStyle = StringUtil::BLANK 
)
static

Creates a new empty scroll area.

Scroll bars will be show if needed and hidden otherwise.

Parameters
[in]optionsOptions that allow you to control how is the element positioned and sized. This will override any similar options set by style.
[in]scrollBarStyleStyle used by the scroll bars.
[in]scrollAreaStyleStyle used by the scroll content area.
static const String& getGUITypeName ( )
static

Returns type name of the GUI element used for finding GUI element styles.

float getHorizontalScroll ( ) const

Returns how much is the scroll area scrolled in the horizontal direction.

Returned value represents percentage where 0 means no scrolling is happening, and 1 means area is fully scrolled to the right.

GUILayout& getLayout ( ) const

Returns the scroll area layout that you may use to add elements inside the scroll area.

float getVerticalScroll ( ) const

Returns how much is the scroll area scrolled in the vertical direction.

Returned value represents percentage where 0 means no scrolling is happening, and 1 means area is fully scrolled to the bottom.

void scrollDownPct ( float  percent)

Scrolls the area down by specified percentage (ranging [0, 1]), if possible.

void scrollDownPx ( UINT32  pixels)

Scrolls the area down by specified amount of pixels, if possible.

void scrollLeftPct ( float  percent)

Scrolls the area left by specified percentage (ranging [0, 1]), if possible.

void scrollLeftPx ( UINT32  pixels)

Scrolls the area left by specified amount of pixels, if possible.

void scrollRightPct ( float  percent)

Scrolls the area right by specified percentage (ranging [0, 1]), if possible.

void scrollRightPx ( UINT32  pixels)

Scrolls the area right by specified amount of pixels, if possible.

void scrollUpPct ( float  percent)

Scrolls the area up by specified percentage (ranging [0, 1]), if possible.

void scrollUpPx ( UINT32  pixels)

Scrolls the area up by specified amount of pixels, if possible.

void updateClippedBounds ( )
overrideprotectedvirtual

Called whenever element clipped bounds need to be recalculated.

(for example when width, height or clip rectangles changes).

Reimplemented from GUIElement.

Member Data Documentation

const UINT32 ScrollBarWidth
static

Number of pixels the scroll bar will occupy when active.

This is width for vertical scrollbar, and height for horizontal scrollbar.