Container for Graphical User Interface (GUI) widgets. More...

#include <GuiContainer.h>

Public Types
using	Ptr = std::shared_ptr< GuiContainer >
	Shared gui container pointer. More...

Public Member Functions
	GuiContainer ()
	Construct the gui. More...

	GuiContainer (priv::RenderTarget &window)
	Construct the gui and set the target on which the gui should be drawn. More...

	GuiContainer (const GuiContainer &)=delete
	Copy constructor. More...

GuiContainer &	operator= (const GuiContainer &)=delete
	Assignment operator. More...

	GuiContainer (GuiContainer &&) noexcept
	Move constructor. More...

GuiContainer &	operator= (GuiContainer &&) noexcept
	Move assignment operator. More...

void	setAbsoluteViewport (const FloatRect &viewport)
	Set the part of the window the gui will render on. More...

void	setRelativeViewport (const FloatRect &viewport)
	Set the part of the window the gui will render on as a ratio relative to the window size. More...

FloatRect	getViewport () const
	Get the part of the window the gui renders. More...

void	setAbsoluteView (const FloatRect &view)
	Set the part of the gui that will be used to fill the viewport. More...

void	setRelativeView (const FloatRect &view)
	Set the part of the gui that is used to fill the viewport. More...

FloatRect	getView () const
	Get the part of the gui that is used to fill the viewport. More...

void	setTextSize (unsigned int size)
	Set the character size of all existing and future child widgets. More...

unsigned int	getTextSize () const
	Get the text size of all existing and future child widgets. More...

void	setTarget (priv::RenderTarget &window)

bool	isTargetSet () const
	Check if the target on which the gui should be drawn is set or not. More...

void	setTabKeyUsageEnabled (bool enabled)
	Enable tab usage. More...

bool	isTabKeyUsageEnabled () const
	Check if tab key usage is enabled or not. More...

void	draw ()
	Draw all the widgets that were added to the gui. More...

void	setFont (const std::string &filename)
	Change the global font. More...

void	setOpacity (float opacity)
	Set the opacity of all widgets. More...

float	getOpacity () const
	Get the opacity of all the widgets. More...

void	setMouseCursor (CursorType cursorType)
	Change the mouse cursor that gets shown. More...

void	restoreMouseCursor ()
	Restores the mouse cursor to the way it was prior to setMouseCursor. More...

void	requestMouseCursor (CursorType cursorType)
	Change the mouse cursor that is shown. More...

Widget *	addWidget (Widget::Ptr widget, const std::string &name="")
	Add a widget to the gui. More...

template<typename T >
T *	addWidget (Widget::Ptr widget, const std::string &name="")
	Add a widget to the gui. More...

Widget *	getWidget (const std::string &name) const
	Get a pointer to a widget in the gui. More...

template<class T >
T *	getWidget (const std::string &name) const
	Get a pointer to a widget in the gui. More...

bool	removeWidget (const std::string &widget)
	Remove a widget from the gui. More...

void	removeAllWidgets ()
	Remove all widgets from the gui. More...

Widget *	getFocusedWidget () const
	Get the currently focused widget inside the container. More...

Widget *	getFocusedLeaf () const
	Get the currently focused widget inside the container. More...

Widget *	getWidgetAtPosition (Vector2f pos) const
	Get a widget at a given position. More...

Widget *	getWidgetBelowMouseCursor (Vector2f mousePos) const
	Get the widget below the mouse cursor. More...

bool	focusNextWidget (bool recursive=true)
	Focus the next widget in the gui. More...

bool	focusPreviousWidget (bool recursive=true)
	Focus the previous widget in the gui. More...

void	unfocusAllWidgets ()
	Unfocus all widgets in the container. More...

void	moveWidgetToFront (const Widget *widget)
	Place a widget before all other widgets to the front. More...

void	moveWidgetToBack (const Widget *widget)
	Place a widget behind all other widgets. More...

size_t	moveWidgetForward (const Widget *widget)
	Place a widget one step forward in the z-order. More...

size_t	moveWidgetBackward (const Widget *widget)
	Place a widget one step backwards in the z-order. More...

void	moveWidgetToFront (const std::string &widget)
	Place a widget before all other widgets to the front. More...

void	moveWidgetToBack (const std::string &widget)
	Place a widget behind all other widgets. More...

size_t	moveWidgetForward (const std::string &widget)
	Place a widget one step forward in the z-order. More...

size_t	moveWidgetBackward (const std::string &widget)
	Place a widget one step backwards in the z-order. More...

void	handleEvent (Event event)

void	update (Time deltaTime)

	~GuiContainer ()
	Destructor. More...

Detailed Description

Container for Graphical User Interface (GUI) widgets.

This class is a container for all UI widgets. In order for a widget to receive events, updates and be rendered, it must exist in the gui container either directly (explicit addition) or indirectly (added to a container widget which is then added to the gui container)

This class is not meant to be instantiated directly, use ime::Scene::getGui or ime::Engine::getGui

Definition at line 56 of file GuiContainer.h.

Member Typedef Documentation

◆ Ptr

using ime::ui::GuiContainer::Ptr = std::shared_ptr<GuiContainer>

Shared gui container pointer.

Definition at line 58 of file GuiContainer.h.

Constructor & Destructor Documentation

◆ GuiContainer() [1/4]

ime::ui::GuiContainer::GuiContainer ( )

Construct the gui.

Warning: When constructed with this constructor, setTarget must be called before the gui container is used

See also: setTarget

◆ GuiContainer() [2/4]

ime::ui::GuiContainer::GuiContainer ( priv::RenderTarget & window )

explicit

Construct the gui and set the target on which the gui should be drawn.

Parameters

window Render target that will be used by the gui

This constructor will set the target therefore there is no need to call setTarget

See also: setTarget

◆ GuiContainer() [3/4]

ime::ui::GuiContainer::GuiContainer ( const GuiContainer & )

delete

Copy constructor.

◆ GuiContainer() [4/4]

ime::ui::GuiContainer::GuiContainer ( GuiContainer && )

noexcept

Move constructor.

◆ ~GuiContainer()

ime::ui::GuiContainer::~GuiContainer ( )

Destructor.

Member Function Documentation

◆ addWidget() [1/2]

Widget * ime::ui::GuiContainer::addWidget	(	Widget::Ptr	widget,
		const std::string &	name = `""`
	)

Add a widget to the gui.

Parameters

widget	The widget to be added
name	Unique name of the widget

Returns: Pointer to the widget if it was added to the container or nullptr if the container already has a widget with the same name as the specified widget name

The name parameter is kept for compatibility with v2.2.x and prior. Starting with v2.3.0, use ime::ui::Widget::setName

Warning: The name of the widget must not contain whitespaces

◆ addWidget() [2/2]

template<typename T >

T * ime::ui::GuiContainer::addWidget	(	Widget::Ptr	widget,
		const std::string &	name = `""`
	)

inline

Add a widget to the gui.

Parameters

widget	The widget to be added
name	Unique name of the widget

Returns: Pointer to the widget if it was added to the container or a premature program exit if a widget with the same name as name already exist in the container

The name parameter is kept for compatibility with v2.2.x and prior. Starting with v2.3.0, use ime::ui::Widget::setName

This function that will return the widget pointer already casted to the desired type:

using ime::ui;
// Here the type of lblGreeting is deduced to Widget*
auto* lblGreeting = gui.addWidget(Label::create("Hi there"));
 
// Here the type of lblGreeting is deduced to Label*
auto* lblGreeting = gui.addWidget<Label>(Label::create("Hi there"));

Warning: This function will return a nullptr if the argument widget is not convertible to T. In addition name must be unique

Definition at line 348 of file GuiContainer.h.

◆ draw()

void ime::ui::GuiContainer::draw ( )

Draw all the widgets that were added to the gui.

◆ focusNextWidget()

bool ime::ui::GuiContainer::focusNextWidget ( bool recursive = true )

Focus the next widget in the gui.

Parameters

recursive Set true to focus next widget when the currently focused widget is a container or false to focus the sibling of that container

Returns: True if the next widget was focused, otherwise false

◆ focusPreviousWidget()

bool ime::ui::GuiContainer::focusPreviousWidget ( bool recursive = true )

Focus the previous widget in the gui.

Parameters

recursive Set true to focus next widget when the currently focused widget is a container or false to focus the sibling of that container

Returns: True if the next widget was focused, otherwise false

◆ getFocusedLeaf()

Widget * ime::ui::GuiContainer::getFocusedLeaf ( ) const

Get the currently focused widget inside the container.

Returns: Pointer to the focused child widget or a nullptr if none of the widgets are currently focused

Note: Unlike getFocusedWidget which returns a pointer to a container when the focused widget is a child of another container within the container, this function will always return the focused widget regardless of whether its a direct child of the container or not

See also: getFocusedWidget

◆ getFocusedWidget()

Widget * ime::ui::GuiContainer::getFocusedWidget ( ) const

Get the currently focused widget inside the container.

Returns: Pointer to the focused child widget or a nullptr if none of the widgets are currently focused

Note: Unlike getFocusedWidget which returns a pointer to a container when the focused widget is a child of another container within the container, this function will always return the focused widget regardless of whether its a direct child of the container or not

See also: getFocusedWidget

◆ getOpacity()

float ime::ui::GuiContainer::getOpacity ( ) const

Get the opacity of all the widgets.

Returns: The opacity of all the widgets in the range [0, 1]

◆ getTextSize()

unsigned int ime::ui::GuiContainer::getTextSize ( ) const

Get the text size of all existing and future child widgets.

Returns: The text size of all existing and future child widgets

◆ getView()

FloatRect ime::ui::GuiContainer::getView ( ) const

Get the part of the gui that is used to fill the viewport.

Returns: The part of the gui that fills the viewport

By default, the view will have the same size as the viewport

See also: setViewPort and setRelativeViewPort

◆ getViewport()

FloatRect ime::ui::GuiContainer::getViewport ( ) const

Get the part of the window the gui renders.

Returns: Rect of the window to which the gui will draw

See also: setViewPort and setRelativeViewPort

◆ getWidget() [1/2]

Widget * ime::ui::GuiContainer::getWidget ( const std::string & name ) const

Get a pointer to a widget in the gui.

Parameters

name	Name of the widget to retrieve

Returns: Pointer to the specified widget or a nullptr if the gui does not have a widget with the specified name

The gui will first search for widgets that are direct children of it, but when none of the child widgets match the given name, a recursive search will be performed

◆ getWidget() [2/2]

template<class T >

T * ime::ui::GuiContainer::getWidget ( const std::string & name ) const

inline

Get a pointer to a widget in the gui.

Parameters

name	Name of the widget to retrieve

Returns: Pointer to the specified widget or a nullptr if the gui does not have a widget with the specified name or T is invalid

Note: The pointer will already be casted to the desired type (T)

Definition at line 374 of file GuiContainer.h.

◆ getWidgetAtPosition()

Widget * ime::ui::GuiContainer::getWidgetAtPosition ( Vector2f pos ) const

Get a widget at a given position.

Parameters

pos	The position of the widget relative to the gui view

Returns: Pointer to the widget at the specified position or a nullptr if there is no widget at that position

◆ getWidgetBelowMouseCursor()

Widget * ime::ui::GuiContainer::getWidgetBelowMouseCursor ( Vector2f mousePos ) const

Get the widget below the mouse cursor.

Parameters

mousePos The position of the mouse cursor in pixel coordinates relative to the window

Returns: Widget below the mouse or a nullptr if the mouse isn't on top of any widgets

◆ isTabKeyUsageEnabled()

bool ime::ui::GuiContainer::isTabKeyUsageEnabled ( ) const

Check if tab key usage is enabled or not.

Returns: True if it is enabled, otherwise false

◆ isTargetSet()

bool ime::ui::GuiContainer::isTargetSet ( ) const

Check if the target on which the gui should be drawn is set or not.

Returns: True if the target is set, otherwise false

◆ moveWidgetBackward() [1/2]

size_t ime::ui::GuiContainer::moveWidgetBackward ( const std::string & widget )

Place a widget one step backwards in the z-order.

Parameters

widget The widget that should be moved one step backward

Returns: New index in the widgets list (one higher than the old index or the same if the widget was already in front),

◆ moveWidgetBackward() [2/2]

size_t ime::ui::GuiContainer::moveWidgetBackward ( const Widget * widget )

Place a widget one step backwards in the z-order.

Parameters

widget The widget that should be moved one step backward

Returns: New index in the widgets list (one higher than the old index or the same if the widget was already in front),

◆ moveWidgetForward() [1/2]

size_t ime::ui::GuiContainer::moveWidgetForward ( const std::string & widget )

Place a widget one step forward in the z-order.

Parameters

widget The widget that should be moved one step forward

Returns: New index in the widgets list (one higher than the old index or the same if the widget was already in front),

◆ moveWidgetForward() [2/2]

size_t ime::ui::GuiContainer::moveWidgetForward ( const Widget * widget )

Place a widget one step forward in the z-order.

Parameters

widget The widget that should be moved one step forward

Returns: New index in the widgets list (one higher than the old index or the same if the widget was already in front),

◆ moveWidgetToBack() [1/2]

void ime::ui::GuiContainer::moveWidgetToBack ( const std::string & widget )

Place a widget behind all other widgets.

Parameters

widget The widget to be moved to the back

◆ moveWidgetToBack() [2/2]

void ime::ui::GuiContainer::moveWidgetToBack ( const Widget * widget )

Place a widget behind all other widgets.

Parameters

widget The widget to be moved to the back

◆ moveWidgetToFront() [1/2]

void ime::ui::GuiContainer::moveWidgetToFront ( const std::string & widget )

Place a widget before all other widgets to the front.

Parameters

widget The widget to be moved to the front

◆ moveWidgetToFront() [2/2]

void ime::ui::GuiContainer::moveWidgetToFront ( const Widget * widget )

Place a widget before all other widgets to the front.

Parameters

widget The widget to be moved to the front

◆ operator=() [1/2]

GuiContainer & ime::ui::GuiContainer::operator= ( const GuiContainer & )

delete

Assignment operator.

◆ operator=() [2/2]

GuiContainer & ime::ui::GuiContainer::operator= ( GuiContainer && )

noexcept

Move assignment operator.

◆ removeAllWidgets()

void ime::ui::GuiContainer::removeAllWidgets ( )

Remove all widgets from the gui.

◆ removeWidget()

bool ime::ui::GuiContainer::removeWidget ( const std::string & widget )

Remove a widget from the gui.

Parameters

widget Name of the widget to be removed from the gui

Returns: True if the widget was removed or false if the widget does not exist in the gui

◆ requestMouseCursor()

void ime::ui::GuiContainer::requestMouseCursor ( CursorType cursorType )

Change the mouse cursor that is shown.

Parameters

cursorType The cursor to show

This function is used by widgets to set the mouse cursor when the mouse enters or leaves a widget. If you want to choose a cursor that doesnt changed when moving the mouse, then use setMouseCursor. If the cursor is already set using the setMouseCursor function then this function wont be able to change the cursor. When the mouse cursor is restored restoreMouseCursor, then the mouse cursor will be changed to what was last requested here

See also: setMouseCursor and restoreMouseCursor

◆ restoreMouseCursor()

void ime::ui::GuiContainer::restoreMouseCursor ( )

Restores the mouse cursor to the way it was prior to setMouseCursor.

The mouse cursor is changeable only if there are no active mouse cursor changes

See also: setMouseCursor

◆ setAbsoluteView()

void ime::ui::GuiContainer::setAbsoluteView ( const FloatRect & view )

Set the part of the gui that will be used to fill the viewport.

Parameters

view

Example code to use the contents of the gui container from top-left (200,100) to bottom-right (600, 400) and stretch it to fill the viewport (which equals the entire window by default):

gui.setAbsoluteView({200, 100, 400, 300});

◆ setAbsoluteViewport()

void ime::ui::GuiContainer::setAbsoluteViewport ( const FloatRect & viewport )

Set the part of the window the gui will render on.

Parameters

viewport Rect of the window to which the gui should draw

Example code to render the gui on only the right side of an 800x600 window:

gui.setAbsoluteViewport({400, 0, 400, 600});

By default, the gui fills the entire window

See also: setRelativeViewPort

◆ setFont()

void ime::ui::GuiContainer::setFont ( const std::string & filename )

Change the global font.

Parameters

filename Filename of the new global font

Exceptions

FileNotFoundException if the font cannot be found on the disk

◆ setMouseCursor()

void ime::ui::GuiContainer::setMouseCursor ( CursorType cursorType )

Change the mouse cursor that gets shown.

Parameters

cursorType The mouse cursor to show

Warning: The mouse cursor must be restored for every call to this function. If the cursor is not restored then it can no longer be changed by widgets. If this function is called multiple times, the cursors are stacked and restoring the cursors will only pop the last added cursor from the stack

Note: This function can also be used to prevent widgets from changing the mouse cursor by setting the cursor of choice and restoring it once widgets are allowed to change the cursor

See also: restoreMouseCursor

◆ setOpacity()

void ime::ui::GuiContainer::setOpacity ( float opacity )

Set the opacity of all widgets.

Parameters

opacity The new opacity of the widgets in the range [0, 1]

O means completely transparent whilst 1 means fully opaque. The default opacity for all widgets is 1

◆ setRelativeView()

void ime::ui::GuiContainer::setRelativeView ( const FloatRect & view )

Set the part of the gui that is used to fill the viewport.

Parameters

view	Rect of the gui that will be stretched to fill the viewport relative to the viewport size

The default view is (0, 0, 1, 1) so that no scaling happens when the viewport is changed

Example code to zoom in on the gui and display everything at 2x the size:

gui.setRelativeView({0, 0, 0.5f, 0.5f});

See also: setViewPort

◆ setRelativeViewport()

void ime::ui::GuiContainer::setRelativeViewport ( const FloatRect & viewport )

Set the part of the window the gui will render on as a ratio relative to the window size.

Parameters

viewport Rect of the window to which the gui should draw relative to the window size

Example code to render the gui on only the right side of window:

gui.setRelativeViewport({0.5f, 0, 0.5f, 1});

The default viewport is (0, 0, 1, 1) so that the gui fills the entire window

See also: setViewPort

◆ setTabKeyUsageEnabled()

void ime::ui::GuiContainer::setTabKeyUsageEnabled ( bool enabled )

Enable tab usage.

Parameters

enabled True to enable tab usage or false to disable it

When the tab key usage is enabled, pressing tab will focus another widget

◆ setTextSize()

void ime::ui::GuiContainer::setTextSize ( unsigned int size )

Set the character size of all existing and future child widgets.

Parameters

size	The new character size

◆ unfocusAllWidgets()

void ime::ui::GuiContainer::unfocusAllWidgets ( )

Unfocus all widgets in the container.

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

GuiContainer.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Ptr

Constructor & Destructor Documentation

◆ GuiContainer() [1/4]

◆ GuiContainer() [2/4]

◆ GuiContainer() [3/4]

◆ GuiContainer() [4/4]

◆ ~GuiContainer()

Member Function Documentation

◆ addWidget() [1/2]

◆ addWidget() [2/2]

◆ draw()

◆ focusNextWidget()

◆ focusPreviousWidget()

◆ getFocusedLeaf()

◆ getFocusedWidget()

◆ getOpacity()

◆ getTextSize()

◆ getView()

◆ getViewport()

◆ getWidget() [1/2]

◆ getWidget() [2/2]

◆ getWidgetAtPosition()

◆ getWidgetBelowMouseCursor()

◆ isTabKeyUsageEnabled()

◆ isTargetSet()

◆ moveWidgetBackward() [1/2]

◆ moveWidgetBackward() [2/2]

◆ moveWidgetForward() [1/2]

◆ moveWidgetForward() [2/2]

◆ moveWidgetToBack() [1/2]

◆ moveWidgetToBack() [2/2]

◆ moveWidgetToFront() [1/2]

◆ moveWidgetToFront() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ removeAllWidgets()

◆ removeWidget()

◆ requestMouseCursor()

◆ restoreMouseCursor()

◆ setAbsoluteView()

◆ setAbsoluteViewport()

◆ setFont()

◆ setMouseCursor()

◆ setOpacity()

◆ setRelativeView()

◆ setRelativeViewport()

◆ setTabKeyUsageEnabled()

◆ setTextSize()

◆ unfocusAllWidgets()