Getting Started
Migrating to UNIGINE 2.0
C++ API Migration
UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
Plugins Library
High-Level Systems
Samples
Usage Examples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins

Gui Class

This base class is used to create a GUI. Different types of GUI widgets can be either added to one of the following:

  • To the system GUI (Unigine user interface) that is rendered on top of application window.
  • To the GUI object positioned in the world. In this case, any postprocessing filter can be applied.
Default values returned by the following methods can be overridden via RC files defining a custom GUI.

See Also

Gui Class

Members


void addChild (Widget widget, int flags = 0)

Adds a given widget to the GUI.

Arguments

  • Widget widget - Widget to add.
  • int flags - One of the GUI_ALIGN_* pre-defined variables. This is an optional parameter.

int addDictionary (string name, string language = 0)

Adds a dictionary with required localization. Dictionaries cannot be changed in real-time.

Arguments

  • string name - Path to a dictionary file.
  • string language - Name of the dictionary language.

Return value

1 if the dictionary is added successfully; otherwise, 0.

void clearDictionaries ()

Unloads all loaded dictionaries.

int clearTexture (string name)

Clears the specified GUI texture file cache.

Arguments

  • string name - Name of the texture.

Return value

1 if the texture is successfully cleared; otherwise, 0.

int getActivity ()

Returns a value indicating if any widget in the GUI is in focus.

Return value

1 if any widget is focused; otherwise, 0.

Widget getChild (int widget)

Returns a child widget with a given number.

Arguments

  • int widget - Widget number.

Return value

Required widget.

vec4 getColor ()

Returns the color of the global color multiplier.

Return value

Multiplier color.

float getDefaultAlpha ()

Returns the standard alpha value of a widget.

Return value

Alpha value.

vec4 getDefaultColor ()

Returns the standard font color of a widget.

Return value

Font color.

int getDefaultSize ()

Returns the standard font size of a widget.

Return value

Font size.

float getDisabledAlpha ()

Returns the alpha value of a disabled widget.

Return value

Alpha value.

vec4 getDisabledColor ()

Returns the font color of a disabled widget.

Return value

Font color.

float getExposeSpeed ()

Returns the duration of animation played when a widget appears.

Return value

Duration in cycles per second.

float getFadeInSpeed ()

Returns the duration of fade-in animation played when a widget gets focused.

Return value

Duration in cycles per second.

float getFadeOutSpeed ()

Returns the duration of fade-out animation played when a widget loses focused.

Return value

Duration in cycles per second.

Widget getFocus ()

Returns the widget currently in focus.

Return value

Focused widget.

float getFocusedAlpha ()

Returns the alpha value of a focused widget.

Return value

Alpha value.

vec4 getFocusedColor ()

Returns the font color of a focused widget.

Return value

Font color.

int getHeight ()

Returns the height of the whole GUI on the screen. The default is 768 pixels.

Return value

Height in pixels.

int getKeyActivity (int key)

Checks if a given key already has a special purpose for the widget in focus.

Arguments

  • int key - One of the standard ASCII control codes or one of the APP_KEY_* pre-defined variables.

Return value

1 if the key cannot be used; otherwise, 0.

int getMouseButton ()

Returns the mouse button, which input is received.

Return value

APP_BUTTON_LEFT or APP_BUTTON_RIGHT or APP_BUTTON_MIDDLE .

int getMouseCursor ()

Returns the type of mouse pointer currently displayed.

Return value

One of the GUI_CURSOR_* pre-defined variables.

int getMouseDX ()

Returns the difference between the previous position of the mouse pointer and the current one along the x-axis.

Return value

Difference along the x-axis.

int getMouseDY ()

Returns the difference between the previous position of the mouse pointer and the current one along the y-axis.

Return value

Difference along the y-axis.

int getMouseGrab ()

Returns a value indicating if the mouse pointer is bound to the GUI.

Return value

1 if the mouse pointer cannot leave the GUI; otherwise, 0.

WidgetSprite getMouseSprite ()

Returns the custom mouse pointer currently in use.

Return value

Sprite with a custom mouse pointer or NULL (0), if the standard mouse pointer is used.

int getMouseX ()

Returns the current x-coordinate of the mouse pointer in the coordinate system of the application window.

Return value

X-coordinate of the mouse pointer.

int getMouseY ()

Returns the current y-coordinate of the mouse pointer in the coordinate system of the application window.

Return value

Y-coordinate of the mouse pointer.

int getNumChildren ()

Returns the number of widgets belonging to the GUI.

Return value

Number of widgets.

int getNumChilds ()

Returns the number of widgets belonging to the GUI.
Warning
The function is deprecated. It is provided to keep your code working until the next release. Please, replace it with getNumChildren().

Return value

Number of widgets.

Widget getOverlappedFocus ()

Returns the widget under the currently focused widget.

Return value

Widget under the focused widget.

Widget getPermanentFocus ()

Returns a widget that is always in focus.

Return value

Widget always in focus.

float getToolTipAlpha ()

Returns the alpha value of a tooltip.

Return value

Alpha value.

vec4 getToolTipColor ()

Returns the font color of a tooltip.

Return value

Font color.

int getToolTipHeight (string tooltip)

Returns a height of the given tooltip.
Notice
Height of a single-line tooltip is equal to 21 pixels.

Arguments

  • string tooltip - A tooltip text.

Return value

Height of the given tooltip (in pixels).

Examples

By using this function, you can check the height of the tooltip with the given text before adding it to a GUI instance:

Source code (UnigineScript)
Gui gui = engine.getGui();

gui.getToolTipHeight("Tooltip of the GUI instance");
gui.setToolTip(100,100,"Tooltip of the GUI instance");
						
The function will return 21.

int getToolTipSize ()

Returns the font size of a tooltip.

Return value

Font size.

string getToolTipText ()

Returns a text of a tooltip that is currently displayed.

Return value

Text of the tooltip.

Examples

If you set a tooltip for a button, you can get the text of the tooltip as follows:

Source code (UnigineScript)
Gui gui = engine.getGui();
		
WidgetButton button = new WidgetButton(gui,"Button");
button.setPosition(168,168);
gui.addChild(button,GUI_ALIGN_OVERLAP);
button.setToolTip("This is a tooltip for the button");

log.message("Button tooltip: %s\n",button.getGui().getToolTipText());
						
The following text will be printed in the console when the tooltip appears:
Output
Button tooltip: This is a tooltip for the button
						

float getToolTipTime ()

Returns the delay before tooltip appearing.

Return value

Delay in cycles per second.

int getToolTipWidth ()

Returns the current width of the tooltip.

Return value

Width of the tooltip.

int getToolTipWidth (string tooltip)

Returns the width of the given tooltip.

Arguments

  • string tooltip - A tooltip text.

Return value

Width of the tooltip that contains the given text (in pixels).

Examples

By using this function, you can check the width of the tooltip with the given text before adding it to the GUI:

Source code (UnigineScript)
gui.getToolTipWidth("Tooltip of a menu item"); 
						

int getToolTipX ()

Returns the tooltip position along the X axis.

Return value

X coordinate of the tooltip.

int getToolTipY ()

Returns the tooltip position along the Y axis.

Return value

Y coordinate of the tooltip.

mat4 getTransform ()

Returns the global GUI transformation matrix.

Return value

Transformation matrix.

float getTransparentAlpha ()

Returns the alpha value of a transparent widget. A widget is transparent, if it uses blending.

Return value

Alpha value.

vec4 getTransparentColor ()

Returns the font color of a transparent widget. A widget is transparent, if it uses blending.

Return value

Font color of a transparent widget.

int getWidth ()

Returns the width of the whole GUI on the screen.

Return value

Screen width in pixels.

int hasTranslation (string str)

Returns a value indicating if there is translation for a given string in the localization dictionary.

Arguments

  • string str - String to check.

Return value

1 if there is translation for the given string; otherwise, 0.

int isChild (Widget widget)

Checks if a given widget belongs to the GUI.

Arguments

  • Widget widget - Widget to check.

Return value

1 if the widget belongs to the GUI; otherwise, 0.

int isDisabledEnabled ()

Returns a value indicating if a widget can be rendered as disabled (i.e. change its color accordingly), when necessary.

Return value

1 if the widget can be rendered as disabled; otherwise, 0.

int isEnabled ()

Returns a value indicating if a widget is disabled.

Return value

1 if the widget is enabled; otherwise, 0.

int isFocusedEnabled ()

Returns a value indicating if a widget can be rendered as focused on (i.e. change its color accordingly), when necessary.

Return value

1 if the widget can be rendered as focused on; otherwise, 0.

int isFocusedPermanent ()

Returns a value indicating if the permanent color of the focused widget is changed.

Return value

1 if the font color is overridden with the global GUI focused color; 0 if the font color is unchanged.

int isHidden ()

Returns a value indicating if a widget is rendered visible.

Return value

1 if the widget is rendered; otherwise, 0.

int isMouseEnabled ()

Returns a value indicating if the mouse cursor is rendered or not.

Return value

1 if the mouse is rendered; otherwise, 0.

int isToolTipEnabled ()

Returns a value indicating if the tooltip is enabled.

Return value

1 if the tooltip is enabled; otherwise, 0.

int isTransparentEnabled ()

Returns a value indicating if a widget can be rendered as transparent (i.e. change its color accordingly), when necessary. For example, it can indicate whether the drop-down list of combobox is transparent or not.

Return value

1 if the widget can be rendered as transparent; otherwise, 0.

vec4 parseColor (string str)

Converts a given color string in the Web format(RRGGBB / #RRGGBB or RRGGBBAA / #RRGGBBAA) into its vec4 equivalent.

Arguments

  • string str - Color string in the Web format.

Return value

Color in vec4.

void removeChild (Widget widget)

Removes a given widget from the GUI.

Arguments

  • Widget widget - Widget to remove.

void removeFocus ()

Removes the current focus.

void replaceChild (Widget new, Widget old, int flags = 0)

Replaces a given widget in the GUI with another widget.

Arguments

  • Widget new - Replacement widget.
  • Widget old - Widget to be replaced.
  • int flags - One of the GUI_ALIGN_* pre-defined variables. This is an optional parameter.

int saveDictionary (string name, string language = 0)

Saves the dictionary with required localization. This function can be used to save the currently loaded dictionary into another file.

Arguments

  • string name - Path to a dictionary file.
  • string language - Name of the dictionary language.

Return value

1 if the dictionary is saved successfully; otherwise, 0.

void setColor (vec4 color)

Sets a color for the global color multiplier. The default is equivalent to #ffffff (white).

Arguments

  • vec4 color - Multiplier color.

void setDefaultAlpha (float alpha)

Sets a standard alpha value for widgets.

Arguments

  • float alpha - Alpha value. 0 means completely transparent.

void setDefaultColor (vec4 color)

Sets a standard font color for widgets. The default is equivalent to #ddddff (blue-white).

Arguments

  • vec4 color - Font color.

void setDefaultSize (int size)

Sets a standard font size for widgets.

Arguments

  • int size - Font size.

void setDisabledAlpha (float alpha)

Sets an alpha value for disabled widgets.

Arguments

  • float alpha - Alpha value. 0 means completely transparent.

void setDisabledColor (vec4 color)

Sets a font color for disabled widgets. The default is equivalent to #869caa (light bluish).

Arguments

  • vec4 color - Font color.

void setDisabledEnabled (int enable)

Sets a value indicating if a widget can be rendered as disabled (i.e. change its color accordingly), when necessary.

Arguments

  • int enable - Positive value if the widget can be rendered as disabled; otherwise, 0.

void setEnabled (int enable)

Sets a value indicating if a widget should be disabled.

Arguments

  • int enable - Positive integer to enable the widget; 0 to disable.

void setExposeSpeed (float duration)

Sets a duration of animation played when the widget appears.

Arguments

  • float duration - Duration in cycles per second, for example, 6 means that the duration is a 1/6 of a second.

void setFadeInSpeed (float duration)

Sets a duration of fade-in animation played when the widget gets focused.

Arguments

  • float duration - Duration in cycles per second, for example, 8 means that the duration is a 1/8 of a second.

void setFadeOutSpeed (float duration)

Sets a duration of fade-out animation played when the widget loses focused.

Arguments

  • float duration - Duration in cycles per second, for example, 4 means that the duration is a 1/4 of a second.

void setFocusedAlpha (float alpha)

Sets an alpha value for focused widgets. The default is 1 (completely opaque).

Arguments

  • float alpha - Alpha value. 0 means completely transparent.

void setFocusedColor (vec4 color)

Sets an font color for focused widgets. The default is equivalent to #ffffff (white).

Arguments

  • vec4 color - Font color.

void setFocusedEnabled (int enable)

Sets a value indicating if a widget can be rendered as focused on (i.e. change its color accordingly), when necessary.

Arguments

  • int enable - Positive value if the widget can be rendered as focused on; otherwise, 0.

void setFocusedPermanent (int permanent)

Changes the permanent color of the focused widget.

Arguments

  • int permanent - 1 - a font color is overridden with the global GUI focused color; 0 - a font color is unchanged.

int setFont (string name)

Changes the font used for widgets in the current GUI.

Arguments

  • string name - Path to the font file.

Return value

1 if the font is successfully changed; otherwise, 0.

void setHidden (int hidden)

Sets a value indicating if a widget should not be rendered.

Arguments

  • int hidden - Positive integer to render the widget; 0 not to render.

void setMouseButton (int button)

Sets a mouse button, which input should be received.

Arguments

void setMouseCursor (int cursor)

Sets a mouse pointer to display.

Arguments

  • int cursor - One of the GUI_CURSOR_* pre-defined variables.

void setMouseEnabled (int enable)

Sets a value indicating if the mouse cursor is rendered or not.

Arguments

  • int enable - Positive value to enable rendering of the mouse; otherwise, 0.

void setMouseGrab (int mode)

Sets a value indicating if the mouse pointer is bound to the GUI.

Arguments

  • int mode - Positive integer, if the mouse pointer cannot leave the GUI; otherwise, 0.

void setMouseSprite (WidgetSprite sprite)

Sets a custom mouse pointer.

Arguments

  • WidgetSprite sprite - Sprite with a custom mouse pointer or NULL (0) to fall back to the standard mouse pointer.

int setResource (string name)

Changes the resource file skin used for widgets in the current GUI.

Arguments

  • string name - Path to the *.rc file.

Return value

1 if the resource file is successfully changed; otherwise, 0.

int setSkin (string name)

Changes the skin used for widgets in the current GUI.

Arguments

  • string name - Path to the directory where the skin files are stored (an RC file and textures).

Return value

1 if the skin is successfully changed; otherwise, 0.

void setToolTipAlpha (float alpha)

Sets an alpha value for tooltips. The default is 0.95 (translucent).

Arguments

  • float alpha - Alpha value. 0 means completely transparent.

void setToolTipColor (vec4 color)

Sets a font color for tooltips. The default is equivalent to #000000 (black).

Arguments

  • vec4 color - Font color.

void setToolTipEnabled (int enabled)

Sets a value indicating whether the tooltip is enabled or not.

Arguments

  • int enabled - 1 to enable the tooltip; otherwise, 0.

void setToolTipSize (int size)

Sets a font size for widgets.

Arguments

  • int size - Font size.

void setToolTipTime (float delay)

Sets a delay before tooltip appearance.

Arguments

  • float delay - Delay in cycles per second.

void setToolTipWidth (int width)

Sets the width for the tooltip.

Arguments

  • int width - New tooltip width.

void setToolTip (int x, int y, string str)

Sets a tooltip to be displayed. The tooltip is positioned on the screen by its upper left corner. For the tooltip to be displayed, this function should be called each frame.

Arguments

  • int x - Screen position along the X axis.
  • int y - Screen position along the Y axis.
  • string str - Tooltip to display.

void setTransform ()

Sets the global GUI transformation matrix. This 2D matrix can be tilted, rotated, moved or modified in many ways in 3D space.

Return value

1 if the matrix is successfully set; otherwise, 0.

void setTransparentAlpha (float alpha)

Sets an alpha value for transparent widgets. A widget is transparent, if it uses blending. The default is 0.8 (translucent).

Arguments

  • float alpha - Alpha value. 0 means completely transparent.

void setTransparentColor (vec4 color)

Sets a font color for transparent widgets. A widget is transparent, if it uses blending. The default is equivalent to #869caa (light bluish).

Arguments

  • vec4 color - Font color.

void setTransparentEnabled (int enable)

Sets a value indicating if a widget can be rendered as transparent (i.e. change its color accordingly), when necessary. For example, this function allows to control whether the drop-down list of combobox is transparent or not.

Arguments

  • int enable - Positive value if the widget can be rendered as transparent; otherwise, 0.

string translate (string source)

Returns a localized variant of a given string.

Arguments

  • string source - Source string.

Return value

Target (translated) string, if it is found in the dictionary; otherwise, the source string.

int GUI_ALIGN_BACKGROUND

Description

Widget is always placed under other widgets. If clicken on, it does not pop up. Use this flag together with GUI_ALIGN_OVERLAP one.

int GUI_ALIGN_BOTTOM

Description

Widget is aligned to the bottom of its container.

int GUI_ALIGN_CENTER

Description

Widget is centered relative to its container.

int GUI_ALIGN_EXPAND

Description

Widget occupies all available space inside its container.

int GUI_ALIGN_FIXED

Description

Widget in focus stays on the background or on the foreground (depending on where it was created). This flag is valid only if GUI_ALIGN_OVERLAP is also set. Non-fixed overlapping windows can pop over the fixed ones, while the latter cannot do it.

int GUI_ALIGN_LEFT

Description

Widget is aligned to the left side of its container.

int GUI_ALIGN_OVERLAP

Description

Widget is rendered over other widgets, on the foreground (or over the contents of the parent container). Overlapping widgets are sorted between each other (i.e. pop up when focused on). This flag also makes the window movable.

int GUI_ALIGN_RIGHT

Description

Widget is aligned to the right side of its container.

int GUI_ALIGN_TOP

Description

Widget is aligned to the top of its container.

int GUI_ATTACH_LOG10

Description

Attached slider uses a logarithmic scale with the base ten.

int GUI_ATTACH_MAX_EXPAND

Description

Maximum value of the attached slider can be raised.

int GUI_ATTACH_MIN_EXPAND

Description

Minimum value of the attached slider can be lowered.

int GUI_BLEND_DEST_ALPHA

Description

Components of each widget color are multiplied by bA .

int GUI_BLEND_DEST_COLOR

Description

Components of each widget color are multiplied by these factors (per component): (bR, bG, bB, bA) .

int GUI_BLEND_NONE

Description

No blending is used for a widget.

int GUI_BLEND_ONE

Description

Components of each widget color are multiplied by one.

int GUI_BLEND_ONE_MINUS_DEST_ALPHA

Description

Components of each widget color are multiplied by 1- bA .

int GUI_BLEND_ONE_MINUS_DEST_COLOR

Description

Components of each widget color are multiplied by these factors (per component): (1 - bR, 1 - bG, 1 - bB, 1 - bA) .

int GUI_BLEND_ONE_MINUS_SRC_ALPHA

Description

Components of each widget color are multiplied by 1- wA .

int GUI_BLEND_ONE_MINUS_SRC_COLOR

Description

Components of each widget color are multiplied by these factors (per component): (1 - wR, 1 - wG, 1 - wB, 1 - wA) .

int GUI_BLEND_SRC_ALPHA

Description

Components of each widget color are multiplied by wA .

int GUI_BLEND_SRC_COLOR

Description

Components of each widget color are multiplied by these factors (per component): (wR, wG, wB, wA) .

int GUI_BLEND_ZERO

Description

Components of each widget color are multiplied by zero.

int GUI_BUFFER_ALL

Description

Mask that specifies all channels.

int GUI_BUFFER_ALPHA

Description

Mask that specifies the alpha channel.

int GUI_BUFFER_BLUE

Description

Mask that specifies the blue channel.

int GUI_BUFFER_GREEN

Description

Mask that specifies the green channel.

int GUI_BUFFER_RED

Description

Mask that specifies the red channel.

int GUI_CHANGED

Description

Callback is used when a widget has changed its state. Supported by the following widgets:

int GUI_CLICKED

Description

Callback is used when the mouse is clicked somewhere on a widget. Supported by the following widgets:

int GUI_CURSOR_ARROW

Description

Default arrow pointer is displayed.

int GUI_CURSOR_DND

Description

Pointer for a drag-and-drop operation is displayed.

int GUI_CURSOR_HEIGHT

Description

Pointer for vertical resizing is displayed.

int GUI_CURSOR_MOVE

Description

Pointer for move operation is displayed.

int GUI_CURSOR_NA

Description

Pointer indicating that an operation is not available is displayed.

int GUI_CURSOR_NESW

Description

Pointer for top-right / bottom-left resizing is displayed.

int GUI_CURSOR_NONE

Description

Mouse pointer is not displayed.

int GUI_CURSOR_NWSE

Description

Pointer for top-left / bottom-right resizing is displayed.

int GUI_CURSOR_ROTATE

Description

Pointer for rotation operation is displayed.

int GUI_CURSOR_SCALE

Description

Pointer for operation of object scaling is displayed.

int GUI_CURSOR_WIDTH

Description

Pointer for horizontal resizing is displayed.

int GUI_DOUBLE_CLICKED

Description

Callback is used when the mouse is double-clicked somewhere on a widget. Supported by the following widgets:

int GUI_DRAG_DROP

Description

Callback is used when a drag-and-drop operation is performed with a widget. Supported by all widgets. A callback can receive dragged widgets inside additional arguments. Clicked or pressed callbacks receive a mouse button or a key inside an additional callback argument.

int GUI_DRAG_MOVE

Description

Callback is used when a focused widget is moved.

int GUI_ENTER

Description

Callback is used when the mouse pointer enters a widget. Supported by all widgets.

int GUI_FOCUS_IN

Description

Callback is used when a widget is focused. Supported by all widgets.

int GUI_FOCUS_OUT

Description

Callback is used when a widget loses focus. Supported by all widgets.

int GUI_HIDE

Description

Callback is used when a widget is removed via Gui::removeChild(). Supported by all widgets.

int GUI_HORIZONTAL

Description

Widget has horizontal orientation.

int GUI_KEY_PRESSED

Description

Callback us used when a key is pressed while a widget is in focus. Supported by the following widgets:

int GUI_LEAVE

Description

Callback is used when the mouse pointer leaves a widget. Supported by all widgets.

int GUI_PRESSED

Description

Callback is used when a mouse button or ENTER (RETURN) is pressed, while the mouse pointer is somewhere on a widget. Supported by the following widgets:

int GUI_RELEASED

Description

Callback is used when the mouse was released after clicking somewhere on a widget.

int GUI_SHOW

Description

Callback is used when a widget is shown. Supported by all widgets.

int GUI_VALIDATOR_ANY

Description

Input control accepts any data.

int GUI_VALIDATOR_ASCII

Description

Input control accepts only ASCII based symbols.

int GUI_VALIDATOR_FLOAT

Description

Input control accepts only floating point data.

int GUI_VALIDATOR_INT

Description

Input control accepts only integer data.

int GUI_VALIDATOR_UINT

Description

Input control accepts only unsigned integer data.

int GUI_VERTICAL

Description

Widget has vertical orientation.
Last update: 2017-07-03