TGUI  0.9-beta
tgui::GuiBase Class Referenceabstract

Base class for the Gui. More...

#include <TGUI/GuiBase.hpp>

Public Member Functions

void setAbsoluteViewport (const FloatRect &viewport)
 Sets the part of the screen to which the gui will render in pixels. More...
 
void setRelativeViewport (const FloatRect &viewport)
 Sets the part of the screen to which the gui will render as a ratio relative to the window size. More...
 
RelFloatRect getViewport () const
 Returns to which part of the screen the gui will render. More...
 
void setAbsoluteView (const FloatRect &view)
 Sets the part of the gui that will be used to fill the viewport in pixels. More...
 
void setRelativeView (const FloatRect &view)
 Sets the part of the gui that will be used to fill the viewport. More...
 
RelFloatRect getView () const
 Returns the part of the gui that will be used to fill the viewport. More...
 
bool handleEvent (Event event)
 Passes the event to the widgets. More...
 
void setTabKeyUsageEnabled (bool enabled)
 When the tab key usage is enabled, pressing tab will focus another widget.
 
bool isTabKeyUsageEnabled () const
 Returns whether the tab key usage is enabled (if so, pressing tab will focus another widget)
 
virtual void draw ()=0
 Draws all the widgets that were added to the gui.
 
RootContainer::Ptr getContainer () const
 Returns the internal container of the Gui. More...
 
void setFont (const Font &font)
 Changes the global font. More...
 
Font getFont () const
 Returns the global font for this gui. More...
 
const std::vector< Widget::Ptr > & getWidgets () const
 Returns a list of all the widgets. More...
 
void add (const Widget::Ptr &widgetPtr, const String &widgetName="")
 Adds a widget to the container. More...
 
Widget::Ptr get (const String &widgetName) const
 Returns a pointer to an earlier created widget. More...
 
template<class T >
T::Ptr get (const String &widgetName) const
 Returns a pointer to an earlier created widget. More...
 
bool remove (const Widget::Ptr &widget)
 Removes a single widget that was added to the container. More...
 
void removeAllWidgets ()
 Removes all widgets that were added to the container.
 
Widget::Ptr getFocusedChild () const
 Returns the child widget that is focused inside this container. More...
 
Widget::Ptr getFocusedLeaf () const
 Returns the leaf child widget that is focused inside this container. More...
 
Widget::Ptr getWidgetAtPosition (Vector2f pos) const
 Returns the leaf child widget that is located at the given position. More...
 
Widget::Ptr getWidgetBelowMouseCursor (Vector2i mousePos) const
 Returns the leaf child widget below the mouse. More...
 
bool focusNextWidget (bool recursive=true)
 Focuses the next widget in the gui. More...
 
bool focusPreviousWidget (bool recursive=true)
 Focuses the previous widget in the gui. More...
 
void unfocusAllWidgets ()
 Unfocus all the widgets.
 
void moveWidgetToFront (const Widget::Ptr &widget)
 Places a widget before all other widgets, to the front of the z-order. More...
 
void moveWidgetToBack (const Widget::Ptr &widget)
 Places a widget behind all other widgets, to the back of the z-order. More...
 
std::size_t moveWidgetForward (const Widget::Ptr &widget)
 Places a widget one step forward in the z-order. More...
 
std::size_t moveWidgetBackward (const Widget::Ptr &widget)
 Places a widget one step backward in the z-order. More...
 
void setOpacity (float opacity)
 Changes the opacity of all widgets. More...
 
float getOpacity () const
 Returns the opacity of all the widgets. More...
 
void setTextSize (unsigned int size)
 Changes the character size of all existing and future child widgets. More...
 
unsigned int getTextSize () const
 Returns the character size for future child widgets (and for existing widgets where the size wasn't changed) More...
 
void loadWidgetsFromFile (const String &filename, bool replaceExisting=true)
 Loads the child widgets from a text file. More...
 
void saveWidgetsToFile (const String &filename)
 Saves the child widgets to a text file. More...
 
void loadWidgetsFromStream (std::stringstream &stream, bool replaceExisting=true)
 Loads the child widgets from a string stream. More...
 
void loadWidgetsFromStream (std::stringstream &&stream, bool replaceExisting=true)
 Loads the child widgets from a string stream. More...
 
void saveWidgetsToStream (std::stringstream &stream) const
 Saves this the child widgets to a text file. More...
 
void setOverrideMouseCursor (Cursor::Type type)
 Overrides which cursor gets shown. More...
 
void restoreOverrideMouseCursor ()
 Undoes the effect of the last call to setOverrideCursor. More...
 
void requestMouseCursor (Cursor::Type type)
 Function that is used by widgets to change the mouse cursor. More...
 
void setDrawingUpdatesTime (bool drawUpdatesTime)
 Sets whether drawing the gui will automatically update the internal clock or whether the user does it manually. More...
 
bool updateTime ()
 Updates the internal clock (for timers, animations and blinking edit cursors) More...
 

Public Attributes

SignalFloatRect onViewChange = {"ViewChanged"}
 The view was changed. Optional parameter: new view rectangle.
 

Detailed Description

Base class for the Gui.

Member Function Documentation

◆ add()

void tgui::GuiBase::add ( const Widget::Ptr widgetPtr,
const String widgetName = "" 
)

Adds a widget to the container.

Parameters
widgetPtrPointer to the widget you would like to add
widgetNameIf you want to access the widget later then you must do this with this name
Warning
The widget name should not contain whitespace

◆ focusNextWidget()

bool tgui::GuiBase::focusNextWidget ( bool  recursive = true)

Focuses the next widget in the gui.

Parameters
recursiveIf the focused widget is a container, should the next widget inside it be focused instead of focusing the sibling of the container?
Returns
Whether a new widget was focused

◆ focusPreviousWidget()

bool tgui::GuiBase::focusPreviousWidget ( bool  recursive = true)

Focuses the previous widget in the gui.

Parameters
recursiveIf the focused widget is a container, should the next widget inside it be focused instead of focusing the sibling of the container?
Returns
Whether a new widget was focused

◆ get() [1/2]

Widget::Ptr tgui::GuiBase::get ( const String widgetName) const

Returns a pointer to an earlier created widget.

Parameters
widgetNameThe name that was given to the widget when it was added to the container
Returns
Pointer to the earlier created widget

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.

Warning
This function will return nullptr when an unknown widget name was passed

◆ get() [2/2]

template<class T >
T::Ptr tgui::GuiBase::get ( const String widgetName) const
inline

Returns a pointer to an earlier created widget.

Parameters
widgetNameThe name that was given to the widget when it was added to the container
Returns
Pointer to the earlier created widget. The pointer will already be casted to the desired type

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.

Warning
This function will return nullptr when an unknown widget name was passed

◆ getContainer()

RootContainer::Ptr tgui::GuiBase::getContainer ( ) const

Returns the internal container of the Gui.

This could be useful when having a function that should accept both the gui and e.g. a child window as parameter.

Warning
Not all functions in the Container class make sense for the Gui (which is the reason that the Gui does not inherit from Container), so calling some functions (e.g. setSize) on the container will have no effect.
Returns
Reference to the internal Container class

◆ getFocusedChild()

Widget::Ptr tgui::GuiBase::getFocusedChild ( ) const

Returns the child widget that is focused inside this container.

Returns
Focused child widget or nullptr if none of the widgets are currently focused

If the focused widget is a container then a pointer to that container is returned. If you want to know which widget is focused inside that container (recursively) then you should use the getFocusedLeaf() function.

◆ getFocusedLeaf()

Widget::Ptr tgui::GuiBase::getFocusedLeaf ( ) const

Returns the leaf child widget that is focused inside this container.

Returns
Focused leaf child widget or nullptr if none of the widgets are currently focused

If the focused widget is a container then the getFocusedLeaf() is recursively called on that container. If you want to limit the search to only direct children of this container then you should use the getFocusedChild() function.

◆ getFont()

Font tgui::GuiBase::getFont ( ) const

Returns the global font for this gui.

Returns
Font for widgets in the gui

◆ getOpacity()

float tgui::GuiBase::getOpacity ( ) const

Returns the opacity of all the widgets.

Returns
The opacity of the widgets. 0 means completely transparent, while 1 (default) means fully opaque

◆ getTextSize()

unsigned int tgui::GuiBase::getTextSize ( ) const

Returns the character size for future child widgets (and for existing widgets where the size wasn't changed)

Returns
The current text size or 0 when no size was explicitly set in this gui

◆ getView()

RelFloatRect tgui::GuiBase::getView ( ) const

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

Returns

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

◆ getViewport()

RelFloatRect tgui::GuiBase::getViewport ( ) const

Returns to which part of the screen the gui will render.

Returns
Rect of the window to which the gui will draw

By default the viewport will fill the entire screen.

◆ getWidgetAtPosition()

Widget::Ptr tgui::GuiBase::getWidgetAtPosition ( Vector2f  pos) const

Returns the leaf child widget that is located at the given position.

Parameters
posThe location where the widget will be searched, relative to the gui view
Returns
Widget at the queried position, or nullptr when there is no widget at that location
See also
getWidgetBelowMouseCursor

◆ getWidgetBelowMouseCursor()

Widget::Ptr tgui::GuiBase::getWidgetBelowMouseCursor ( Vector2i  mousePos) const

Returns the leaf child widget below the mouse.

Parameters
mousePosPosition of the mouse, in pixel coordinates, relative the the window
Returns
Widget below the mouse, or nullptr when the mouse isn't on top of any widgets
See also
getWidgetAtPosition

◆ getWidgets()

const std::vector<Widget::Ptr>& tgui::GuiBase::getWidgets ( ) const

Returns a list of all the widgets.

Returns
Vector of all widget pointers

◆ handleEvent()

bool tgui::GuiBase::handleEvent ( Event  event)

Passes the event to the widgets.

Parameters
eventThe event that was polled from the window
Returns
Has the event been consumed? When this function returns false, then the event was ignored by all widgets.

◆ loadWidgetsFromFile()

void tgui::GuiBase::loadWidgetsFromFile ( const String filename,
bool  replaceExisting = true 
)

Loads the child widgets from a text file.

Parameters
filenameFilename of the widget file
replaceExistingRemove existing widgets first if there are any

◆ loadWidgetsFromStream() [1/2]

void tgui::GuiBase::loadWidgetsFromStream ( std::stringstream &&  stream,
bool  replaceExisting = true 
)

Loads the child widgets from a string stream.

Parameters
streamstringstream that contains the widget file
replaceExistingRemove existing widgets first if there are any

◆ loadWidgetsFromStream() [2/2]

void tgui::GuiBase::loadWidgetsFromStream ( std::stringstream &  stream,
bool  replaceExisting = true 
)

Loads the child widgets from a string stream.

Parameters
streamstringstream that contains the widget file
replaceExistingRemove existing widgets first if there are any

◆ moveWidgetBackward()

std::size_t tgui::GuiBase::moveWidgetBackward ( const Widget::Ptr widget)

Places a widget one step backward in the z-order.

Parameters
widgetThe widget that should be moved one step backward
Returns
New index in the widgets list (one lower than the old index or the same if the widget was already at back), or getWidgets().size() if the widget was never added to this container.
See also
moveWidgetToBack

◆ moveWidgetForward()

std::size_t tgui::GuiBase::moveWidgetForward ( const Widget::Ptr widget)

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

Parameters
widgetThe 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), or getWidgets().size() if the widget was never added to this container.
See also
moveWidgetToFront

◆ moveWidgetToBack()

void tgui::GuiBase::moveWidgetToBack ( const Widget::Ptr widget)

Places a widget behind all other widgets, to the back of the z-order.

Parameters
widgetThe widget that should be moved to the back

◆ moveWidgetToFront()

void tgui::GuiBase::moveWidgetToFront ( const Widget::Ptr widget)

Places a widget before all other widgets, to the front of the z-order.

Parameters
widgetThe widget that should be moved to the front

◆ remove()

bool tgui::GuiBase::remove ( const Widget::Ptr widget)

Removes a single widget that was added to the container.

Parameters
widgetPointer to the widget to remove

◆ requestMouseCursor()

void tgui::GuiBase::requestMouseCursor ( Cursor::Type  type)

Function that is used by widgets to change the mouse cursor.

Parameters
typeThe requested cursor

This function is used to change the mouse cursor when the mouse enters or leaves a widget. If you want to choose a cursor that doesn't get changed when moving the mouse then use setOverrideMouseCursor. If an override cursor is already set then this function won't be able to change the cursor. When all overrides are removed with restoreOverrideMouseCursor then the mouse cursor will be changed to what was last requested here.

◆ restoreOverrideMouseCursor()

void tgui::GuiBase::restoreOverrideMouseCursor ( )

Undoes the effect of the last call to setOverrideCursor.

This function has to be called for each call to setOverrideCursor. If the stack of overriden cursors becomes empty then widgets will be able to change the cursor again.

◆ saveWidgetsToFile()

void tgui::GuiBase::saveWidgetsToFile ( const String filename)

Saves the child widgets to a text file.

Parameters
filenameFilename of the widget file

◆ saveWidgetsToStream()

void tgui::GuiBase::saveWidgetsToStream ( std::stringstream &  stream) const

Saves this the child widgets to a text file.

Parameters
streamstringstream to which the widget file will be added

◆ setAbsoluteView()

void tgui::GuiBase::setAbsoluteView ( const FloatRect view)

Sets the part of the gui that will be used to fill the viewport in pixels.

Parameters
viewRect of the gui that will be stretched to fill the viewport

No stretching will occur when the view has the same size as the viewport (default).

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

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

◆ setAbsoluteViewport()

void tgui::GuiBase::setAbsoluteViewport ( const FloatRect viewport)

Sets the part of the screen to which the gui will render in pixels.

Parameters
viewportRect 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});

◆ setDrawingUpdatesTime()

void tgui::GuiBase::setDrawingUpdatesTime ( bool  drawUpdatesTime)

Sets whether drawing the gui will automatically update the internal clock or whether the user does it manually.

Parameters
drawUpdatesTimeTrue if gui.draw() updates the clock (default), false if gui.updateTime() has to be called

◆ setFont()

void tgui::GuiBase::setFont ( const Font font)

Changes the global font.

Parameters
fontFont to use

◆ setOpacity()

void tgui::GuiBase::setOpacity ( float  opacity)

Changes the opacity of all widgets.

Parameters
opacityThe opacity of the widgets. 0 means completely transparent, while 1 (default) means fully opaque

◆ setOverrideMouseCursor()

void tgui::GuiBase::setOverrideMouseCursor ( Cursor::Type  type)

Overrides which cursor gets shown.

Parameters
typeWhich cursor to show
Warning
You must call restoreOverrideCursor() for every call to setOverrideCursor.

Until restoreOverrideCursor is called, the cursor will no longer be changed by widgets. If setOverrideCursor is called multiple times, the cursors are stacked and calling restoreOverrideCursor will only pop the last added cursor from the stack.

◆ setRelativeView()

void tgui::GuiBase::setRelativeView ( const FloatRect view)

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

Parameters
viewRect 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 even 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});

◆ setRelativeViewport()

void tgui::GuiBase::setRelativeViewport ( const FloatRect viewport)

Sets the part of the screen to which the gui will render as a ratio relative to the window size.

Parameters
viewportRect of the window to which the gui should draw, relative to the window size

The default viewport is set to (0, 0, 1, 1) so that it fills the entire window.

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

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

◆ setTextSize()

void tgui::GuiBase::setTextSize ( unsigned int  size)

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

Parameters
sizeThe new text size

The text size specified in this function overrides the global text size property. By default, the gui does not pass any text size to the widgets and the widgets will use the global text size as default value.

◆ updateTime()

bool tgui::GuiBase::updateTime ( )

Updates the internal clock (for timers, animations and blinking edit cursors)

Returns
True if the the contents of the screen changed, false if nothing changed

You do not need to call this function unless you set DrawingUpdatesTime to false (it is true by default).


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