engine.gui Functions
The scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScript (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.
Creates 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.
Gui Class
Members
engine.gui.getCurrent ( ) #
Returns the current GUI instance.Return value
Current GUI instance.int engine.gui.isActive ( ) #
Returns a value indicating if any widget in the GUI is in focus.Return value
1 if any widget is focused; otherwise, 0.Widget engine.gui.getChild ( int num ) #
Returns a child widget with a given number.Arguments
- int num - Widget number.
Return value
Required widget.int engine.gui.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.void engine.gui.setColor ( vec4 color ) #
Sets a color for the global color multiplier. The default is equivalent to #ffffff (white).Arguments
- vec4 color - Color multiplier.
vec4 engine.gui.getColor ( ) #
Returns the color of the global color multiplier.Return value
Color multiplier.void engine.gui.setDefaultAlpha ( float alpha ) #
Sets a standard alpha value for widgets.Arguments
- float alpha - Alpha value. 0 means completely transparent.
float engine.gui.getDefaultAlpha ( ) #
Returns the standard alpha value of a widget.Return value
Alpha value.void engine.gui.setDefaultColor ( vec4 color ) #
Sets a standard font color for widgets. The default is equivalent to #ddddff (blue-white).Arguments
- vec4 color - Font color.
vec4 engine.gui.getDefaultColor ( ) #
Returns the standard font color of a widget.Return value
Font color.void engine.gui.setDefaultSize ( int size ) #
Sets a standard font size for widgets.Arguments
- int size - Font size.
int engine.gui.getDefaultSize ( ) #
Returns the standard font size of a widget.Return value
Font size.void engine.gui.setDisabledAlpha ( float alpha ) #
Sets an alpha value for disabled widgets.Arguments
- float alpha - Alpha value. 0 means completely transparent.
float engine.gui.getDisabledAlpha ( ) #
Returns the alpha value of a disabled widget.Return value
Alpha value.void engine.gui.setDisabledColor ( vec4 color ) #
Sets a font color for disabled widgets. The default is equivalent to #869caa (light bluish).Arguments
- vec4 color - Font color.
vec4 engine.gui.getDisabledColor ( ) #
Returns the font color of a disabled widget.Return value
Font color.void engine.gui.setDisabledEnabled ( int enabled ) #
Sets a value indicating if a widget can be rendered as disabled (i.e. change its color accordingly), when necessary.Arguments
- int enabled - Positive value if the widget can be rendered as disabled; otherwise, 0.
int engine.gui.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.void engine.gui.setEnabled ( int enabled ) #
Sets a value indicating if a widget should be disabled.Arguments
- int enabled - Positive integer to enable the widget; 0 to disable.
int engine.gui.isEnabled ( ) #
Returns a value indicating if a widget is disabled.Return value
1 if the widget is enabled; otherwise, 0.void engine.gui.setExposeSpeed ( float speed ) #
Sets a duration of animation played when the widget appears.Arguments
- float speed - Duration in cycles per second, for example, 6 means that the duration is a 1/6 of a second.
float engine.gui.getExposeSpeed ( ) #
Returns the duration of animation played when a widget appears.Return value
Duration in cycles per second.void engine.gui.setFadeInSpeed ( float speed ) #
Sets a duration of fade-in animation played when the widget gets focused.Arguments
- float speed - Duration in cycles per second, for example, 8 means that the duration is a 1/8 of a second.
float engine.gui.getFadeInSpeed ( ) #
Returns the duration of fade-in animation played when a widget gets focused.Return value
Duration in cycles per second.void engine.gui.setFadeOutSpeed ( float speed ) #
Sets a duration of fade-out animation played when the widget loses focus.Arguments
- float speed - Duration in cycles per second, for example, 4 means that the duration is a 1/4 of a second.
float engine.gui.getFadeOutSpeed ( ) #
Returns the duration of fade-out animation played when a widget loses focus.Return value
Duration in cycles per second.Widget engine.gui.getFocus ( ) #
Returns the widget currently in focus.Return value
Focused widget.void engine.gui.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.
float engine.gui.getFocusedAlpha ( ) #
Returns the alpha value of a focused widget.Return value
Alpha value.void engine.gui.setFocusedColor ( vec4 color ) #
Sets an font color for focused widgets. The default is equivalent to #ffffff (white).Arguments
- vec4 color - Font color.
vec4 engine.gui.getFocusedColor ( ) #
Returns the font color of a focused widget.Return value
Font color.void engine.gui.setFocusedEnabled ( int enabled ) #
Sets a value indicating if a widget can be rendered as focused on (i.e. change its color accordingly), when necessary.Arguments
- int enabled - Positive value if the widget can be rendered as focused on; otherwise, 0.
int engine.gui.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.void engine.gui.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 engine.gui.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 engine.gui.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.int engine.gui.getHeight ( ) #
Returns the height of the whole GUI on the screen. The default is 768 pixels.Return value
Height in pixels.void engine.gui.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.
int engine.gui.isHidden ( ) #
Returns a value indicating if a widget is rendered visible.Return value
1 if the widget is rendered; otherwise, 0.int engine.gui.getKeyActivity ( unsigned int key ) #
Checks if a given key already has a special purpose for the widget in focus.Arguments
- unsigned int key - One of the standard ASCII control codes or one of the KEY_* pre-defined variables.
Return value
1 if the key cannot be used; otherwise, 0.void engine.gui.setMouseButtons ( int buttons ) #
Sets mouse button(s), whose input should be received.Arguments
- int buttons - INPUT_MOUSE_BUTTON_LEFT or INPUT_MOUSE_BUTTON_RIGHT, or INPUT_MOUSE_BUTTON_MIDDLE.
int engine.gui.getMouseButtons ( ) #
Returns mouse button(s), whose input is received.Return value
INPUT_MOUSE_BUTTON_LEFT or INPUT_MOUSE_BUTTON_RIGHT, or INPUT_MOUSE_BUTTON_MIDDLE.void engine.gui.setMouseCursor ( int cursor ) #
Sets a mouse pointer to display.Arguments
- int cursor - One of the GUI_CURSOR_* pre-defined variables.
int engine.gui.getMouseCursor ( ) #
Returns the type of mouse pointer currently displayed.Return value
One of the GUI_CURSOR_* pre-defined variables.int engine.gui.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 engine.gui.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.void engine.gui.setMouseEnabled ( int enabled ) #
Sets a value indicating if the mouse cursor is rendered or not.Arguments
- int enabled - Positive value to enable rendering of the mouse; otherwise, 0.
int engine.gui.isMouseEnabled ( ) #
Returns a value indicating if the mouse cursor is rendered or not.Return value
1 if the mouse is rendered; otherwise, 0.void engine.gui.setMouseGrab ( int grab ) #
Sets a value indicating if the mouse pointer is bound to the GUI.Arguments
- int grab - Positive integer, if the mouse pointer cannot leave the GUI; otherwise, 0.
int engine.gui.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.void engine.gui.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.
WidgetSprite engine.gui.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 engine.gui.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 engine.gui.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 engine.gui.getNumChildren ( ) #
Returns the number of widgets belonging to the GUI.Return value
Number of widgets.Widget engine.gui.getOverlappedFocus ( ) #
Returns the widget under the currently focused widget.Return value
Widget under the focused widget.Widget engine.gui.getPermanentFocus ( ) #
Returns a widget that is always in focus.Return value
Widget always in focus.int engine.gui.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 engine.gui.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 engine.gui.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 engine.gui.setToolTipAlpha ( float alpha ) #
Sets an alpha value for tooltips. The default is 0.95 (translucent).Arguments
- float alpha - Alpha value. 0 means completely transparent.
float engine.gui.getToolTipAlpha ( ) #
Returns the alpha value of a tooltip.Return value
Alpha value.void engine.gui.setToolTipColor ( vec4 color ) #
Sets a font color for tooltips. The default is equivalent to #000000 (black).Arguments
- vec4 color - Font color.
vec4 engine.gui.getToolTipColor ( ) #
Returns the font color of a tooltip.Return value
Font color.void engine.gui.setToolTipEnabled ( int enabled ) #
Sets a value indicating whether the tooltip is enabled or not.Arguments
- int enabled - 1 to enable the tooltip; otherwise, 0.
int engine.gui.isToolTipEnabled ( ) #
Returns a value indicating if the tooltip is enabled.Return value
1 if the tooltip is enabled; otherwise, 0.int engine.gui.getToolTipHeight ( string str ) #
Returns a height of the given tooltip.Height of a single-line tooltip is equal to 21 pixels.
Arguments
- string str - A tooltip text.
Return value
Height of the given tooltip (in pixels).void engine.gui.setToolTipSize ( int size ) #
Sets a font size for widgets.Arguments
- int size - Font size.
int engine.gui.getToolTipSize ( ) #
Returns the font size of a tooltip.Return value
Font size.void engine.gui.setToolTipText ( string text ) #
Sets a new text for the tooltip.Arguments
- string text - Text for the tooltip to be set.
string engine.gui.getToolTipText ( ) #
Returns the text of the currently displayed tooltip.Return value
Text of the GUI tooltip.void engine.gui.setToolTipTime ( float time ) #
Sets a delay before tooltip appearance.Arguments
- float time - Delay in cycles per second.
float engine.gui.getToolTipTime ( ) #
Returns the delay before tooltip appearing.Return value
Delay in cycles per second.void engine.gui.setToolTipWidth ( int width ) #
Sets the width for the tooltip.Arguments
- int width - New tooltip width.
int engine.gui.getToolTipWidth ( string str ) #
Returns the current width of the tooltip.Arguments
- string str - A tooltip text.
Return value
Width of the tooltip.int engine.gui.getToolTipWidth ( ) #
Returns the current width of the tooltip.Return value
Width of the tooltip.void engine.gui.setToolTipX ( int tooltipx ) #
Sets the ToolTip position along the X axis.Arguments
- int tooltipx - New X coordinate of the ToolTip to be set.
int engine.gui.getToolTipX ( ) #
Returns the ToolTip position along the X axis.Return value
X coordinate of the ToolTip.void engine.gui.setToolTipY ( int tooltipy ) #
Sets the ToolTip position along the Y axis.Arguments
- int tooltipy - New Y coordinate of the ToolTip to be set.
int engine.gui.getToolTipY ( ) #
Returns the ToolTip position along the Y axis.Return value
Y coordinate of the ToolTip.void engine.gui.setTransform ( mat4 transform ) #
Sets the global GUI transformation matrix. This 2D matrix can be tilted, rotated, moved or modified in many ways in 3D space.Arguments
- mat4 transform - Transformation matrix.
mat4 engine.gui.getTransform ( ) #
Returns the global GUI transformation matrix.Return value
GUI transformation matrix.void engine.gui.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.
float engine.gui.getTransparentAlpha ( ) #
Returns the alpha value of a transparent widget. A widget is transparent, if it uses blending.Return value
Alpha value.void engine.gui.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.
vec4 engine.gui.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.void engine.gui.setTransparentEnabled ( int enabled ) #
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 enabled - Positive value if the widget can be rendered as transparent; otherwise, 0.
int engine.gui.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.int engine.gui.getWidth ( ) #
Returns the width of the whole GUI on the screen.Return value
Screen width in pixels.WidgetVBox engine.gui.getVBox ( ) #
Returns the root widget of the GUI (WidgetVBox).Return value
The root widget of the GUI.void engine.gui.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 engine.gui.addDictionary ( string name, string language = 0 ) #
Adds a dictionary with required localization. Dictionaries cannot be changed in real-time.Arguments
- string name - Path to the dictionary file.
- string language - Name of the dictionary language.
Return value
1 if the dictionary is added successfully; otherwise, 0.void engine.gui.clearDictionaries ( ) #
Unloads all loaded dictionaries.int engine.gui.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.Gui engine.gui.create ( string name = 0 ) #
GUI constructor.Arguments
- string name - GUI skin name.
Return value
Pointer to the created GUI.int engine.gui.hasTranslation ( string arg1 ) #
Returns a value indicating if there is translation for a given string in the localization dictionary.Arguments
- string arg1 - String to check.
Return value
1 if there is translation for the given string; otherwise, 0.vec4 engine.gui.parseColor ( string str ) #
Converts a 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 value as a vec4 vector (R, G, B, A).void engine.gui.removeChild ( Widget widget ) #
Removes the specified widget from the GUI.Arguments
- Widget widget - Child widget to be removed.
void engine.gui.removeFocus ( ) #
Removes the current focus.void engine.gui.render ( ) #
Renders the GUI.void engine.gui.render ( int custom_mouse_buttons ) #
Renders the GUI.Arguments
- int custom_mouse_buttons - Pressed mouse button.
void engine.gui.replaceChild ( Widget widget, Widget old_widget, int flags = 0 ) #
Replaces a given widget in the GUI with another widget.Arguments
- Widget widget - Replacement widget.
- Widget old_widget - Widget to be replaced.
- int flags - One of the GUI_ALIGN_* pre-defined variables. This is an optional parameter.
int engine.gui.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.string engine.gui.translate ( string str ) #
Returns the source string translated using the dictionary.Arguments
- string str - String to translate (source).
Return value
Target (translated) string if it is found in the localization dictionary; otherwise, the source string.int engine.gui.isRenderingBootScreen ( ) #
Returns a value indicating if the GUI currently renders the boot screen.Return value
1 if the GUI currently renders the boot screen; otherwise, 0.int engine.gui.isRenderingSplashScreen ( ) #
Returns a value indicating if the GUI currently renders the splash screen.Return value
1 if the GUI currently renders the splash screen; otherwise, 0.int engine.gui.isRenderingLoadingScreen ( ) #
Returns a value indicating if the GUI currently renders the loading screen.Return value
1 if the GUI currently renders the loading screen; otherwise, 0.void engine.gui.focusGained ( ) #
The focus is set on the GUI object.void engine.gui.focusLost ( ) #
The focus is removed from the GUI.int engine.gui.isHover ( int global_pos_x, int global_pos_y ) #
Returns a value indicating if the cursor is hovering over the GUI object.Arguments
- int global_pos_x - The X coordinate of the cursor in global coordinates.
- int global_pos_y - The Y coordinate of the cursor in global coordinates.
Return value
1 if the cursor is hovering over the GUI object; otherwise, 0.Widget engine.gui.getWidgetIntersection ( int global_pos_x, int global_pos_y ) #
Returns the intersected widget that is visually perceptible (not empty, not transparent).Arguments
- int global_pos_x - The X coordinate of the cursor in global coordinates.
- int global_pos_y - The Y coordinate of the cursor in global coordinates.
Return value
The intersected widget that is visually perceptible.Widget engine.gui.getUnderCursorWidget ( ) #
Returns the visually perceptible widget, over which the cursor is currently hovering.Return value
The widget, over which the cursor is currently hovering.Gui engine.gui.getFocusGui ( ) #
Returns the GUI object that is currently in focus.Return value
The GUI object currently in focus.Gui engine.gui.getGuiIntersection ( int global_pos_x, int global_pos_y ) #
Returns the intersected GUI object.This method takes Z-ordering into consideration: if the GUI object is overlapped by any other window, the method returns null.
Arguments
- int global_pos_x - The X coordinate of the intersection point in global coordinates.
- int global_pos_y - The Y coordinate of the intersection point in global coordinates.
Return value
The intersected GUI object.Gui engine.gui.getUnderCursorGui ( ) #
Returns the GUI object that is currently under cursor.If case of dragging or resizing a window, this method returns null. To receive the intersected GUI in such a case, use getGuiIntersection().
Return value
GUI object currently under cursor.void engine.gui.getWorldGuiInstances ( Vector<Gui>& ret_instances ) #
Returns all GUI instances that are available in the scene hierarchy and rendered as world objects.Arguments
- Vector<Gui>& ret_instances - All GUI instances that are available in the scene hierarchy and rendered as world objects.
void engine.gui.setSize ( ivec2 size ) #
Sets the GUI object size.Arguments
- ivec2 size - GUI object size (width and height).
ivec2 engine.gui.getSize ( ) #
Returns the GUI object size.Return value
GUI object size (width and height).void engine.gui.setPosition ( ivec2 position ) #
Sets the GUI object position (top left corner) in screen coordinates.Arguments
- ivec2 position - GUI object position.
ivec2 engine.gui.getPosition ( ) #
Sets the GUI object position (top left corner) in screen coordinates.Return value
GUI object position.void engine.gui.setWinHandle ( long handle ) #
Sets the engine handle of the window.Arguments
- long handle - The window handle.
long engine.gui.getWinHandle ( ) #
Returns the engine handle of the window.Return value
The window handle.void engine.gui.setWorldObject ( int val ) #
Sets the value indicating if the GUI object is available in the hierarchy and rendered as a world object.Arguments
- int val - 1 if the GUI object should be available in the hierarchy and rendered as a world object; 0 if it should have the window handle.
int engine.gui.isWorldObject ( ) #
Returns the value indicating if the GUI object is available in the hierarchy and rendered as a world object.Return value
1 if the GUI object is available in the hierarchy and rendered as a world object; 0 if it has the window handle.void engine.gui.setMouseShow ( int show ) #
Sets the value indicating if the OS mouse pointer should be displayed.Arguments
- int show - 1 if the OS mouse pointer should be displayed; 0 if the application cursor is used only.
int engine.gui.isMouseShow ( ) #
Returns the value indicating if the OS mouse pointer should be displayed.Return value
1 if the OS mouse pointer is displayed; 0 if the application cursor is used only.int engine.gui.getMouseWheel ( ) #
Returns the current mouse scroll value. Negative values correspond to scrolling downwards; positive values correspond to scrolling upwards; the value is zero when the mouse wheel is not scrolled.Return value
The mouse scroll value in the [-1;1] range.int engine.gui.getAndClearMouseWheel ( ) #
Returns the mouse scroll value and clears the mouse scroll state info.Return value
The mouse scroll value in the [-1;1] range.void engine.gui.forceSetMouseWheel ( int value ) #
Sets the mouse scroll value.Arguments
- int value - The mouse scroll value in the [-1;1] range.
int engine.gui.getMouseWheelHorizontal ( ) #
Returns the current horizontal mouse scroll value.Return value
The horizontal mouse scroll value in the [-1;1] range.int engine.gui.getAndClearMouseWheelHorizontal ( ) #
Returns the mouse horizontal scroll value and clears the mouse scroll state info.Return value
The horizontal mouse scroll value in the [-1;1] range.void engine.gui.forceSetMouseWheelHorizontal ( int value ) #
Sets the mouse vertical scroll value.Arguments
- int value - The horizontal mouse scroll value in the [-1;1] range.
int engine.gui.isUnderCursor ( ) #
Returns the value indicating if the GUI object is under cursor.Return value
1 if the GUI object is under cursor; otherwise, 0.int engine.gui.getKey ( int key ) #
Returns the value indicating if the specified key is pressed.Arguments
- int key - One of the standard ASCII control codes or one of the KEY_* pre-defined variables.
Return value
1 if the key is pressed; otherwise, 0.int engine.gui.getAndClearKey ( int key ) #
Returns the value indicating if the specified key is pressed and clears the key state info.Arguments
- int key - One of the standard ASCII control codes or one of the KEY_* pre-defined variables.
Return value
1 if the key is pressed; otherwise, 0.Last update:
2023-02-17
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)