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

engine.gui Functions

This set of functions is used to manipulate the system 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 new dictionary with localized interface strings. Dictionaries cannot be modified in run-time.

Arguments

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

Return value

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

void engine.gui.clearDictionaries ()

Clears all 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.

int engine.gui.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 engine.gui.getChild (int child)

Returns a child widget with a given number.

Arguments

  • int child - Child widget number.

Return value

Required widget.

vec4 engine.gui.getColor ()

Returns the color of the global color multiplier.

Return value

Color multiplier.

Widget engine.gui.getFocus ()

Returns the widget currently in focus.

Return value

Focused widget.

int engine.gui.getHeight ()

Returns the current screen height.

Return value

Current screen height in pixels.

int engine.gui.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 key codes or one of the APP_KEY_* pre-defined variables.

Return value

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

variable engine.gui.getKeyPressCallback ()

Returns the name of the callback function, which is invoked when a key (localized) or a key combination (for example, SHIFT + key for upper-case letters or SHIFT + number for special symbols) is pressed.

Return value

Name of the callback function.

int engine.gui.getMouseButton ()

Returns the mouse button, which input is received.

Return value

APP_BUTTON_LEFT or APP_BUTTON_RIGHT or APP_BUTTON_MIDDLE.

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.

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.

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 in the GUI.

Return value

Number of widgets.

int engine.gui.getNumChilds ()

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

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.

mat4 engine.gui.getTransform ()

Returns the global GUI transformation matrix.

Return value

Transformation matrix.

int engine.gui.getWidth ()

Returns the current screen width.

Return value

Current screen width in pixels.

int engine.gui.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 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.

int engine.gui.isEnabled ()

Returns a value indicating if a widget is disabled.

Return value

1 if the widget is enabled; otherwise, 0.

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.isMouseEnabled ()

Returns a value indicating if the mouse is rendered.

Return value

1 if the mouse is enabled; otherwise, 0.

int engine.gui.isToolTipEnabled ()

Returns a value indicating if tooltips are available or not.

Return value

1 if tooltips are enabled; otherwise, 0.

vec4 engine.gui.parseColor (string color)

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

Arguments

  • string color - Color string in the Web format.

Return value

Color value in vec4.

void engine.gui.removeChild (Widget child)

Removes a given widget from the GUI.

Arguments

  • Widget child - Child widget to remove.

void engine.gui.removeFocus ()

Removes focus.

void engine.gui.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 engine.gui.saveDictionary (string name, string language = 0)

Saves the current dictionary on disk. This function can be used to save the currently loaded dictionary into another file.

Arguments

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

Return value

Returns 1 if the dictionary is saved successfully; 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 - Multiplier color.

void engine.gui.setEnabled (int enable)

Sets a value indicating if a widget should be disabled.

Arguments

  • int enable - 1 to enable the widget; 0 to disable.

int engine.gui.setFont (string name)

Changes the font used in the system GUI.

Arguments

  • string name - Path to the font file.

Return value

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

void engine.gui.setHidden (int hidden)

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

Arguments

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

void engine.gui.setKeyPressCallback (variable function)

Sets a callback function, which is invoked each time a key (localized) or a combination of keys (for example, SHIFT + key for upper-case letters or SHIFT + number for special symbols) is pressed. The function should have one argument of the int type for passing the pressed key to it (either a standard ASCII key code or one of APP_KEY_* variables).
  • The callback function should return 0 for control to be handled further (automatically update control state, etc.) In this case, the callback does not interfere with controls handling.
  • If the function returns 1, the control stops to be handled once the callback function is executed.
Notice

Unlike this function, engine.controls.setKeyPressCallback() detects standard keys from QWERTY layout (non-localized, lower-case).

You can use both functions to detect the whole range of input keys. engine.gui.setKeyPressCallback() will be called prior to the engine.controls.setKeyPressCallback().

Arguments

  • variable function - Name of the callback function.

Examples

Source code (UnigineScript)
// Implement a callback function that takes key as an argument.
int key_pressed_callback_func(int key) {
// Your callback code
return 0;
}

// Set the callback on pressing the key.
engine.gui.setKeyPressCallback("key_pressed_callback_func");

void engine.gui.setMouseButton (int button)

Sets a mouse button, which input should be received.

Arguments

void engine.gui.setMouseCursor (int cursor)

Sets a mouse pointer to display.

Arguments

void engine.gui.setMouseEnabled (int enable)

Enables or disables rendering of the mouse cursor.

Arguments

  • int enable - 1 to enable the mouse cursor; otherwise, 0.

void engine.gui.setMouseGrab (int mode)

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

Arguments

  • int mode - 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.

int engine.gui.setResource (string name)

Changes the resource skin file used in the system 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 GUI skin used in the system GUI.

Arguments

  • string name - Path to the skin file (an RC file and textures).

Return value

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

void engine.gui.setToolTipEnabled (int enabled)

Sets a value indicating whether tooltips are available or not.

Arguments

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

void engine.gui.setToolTip (int x, int y, string str)

Sets a tooltip.

Arguments

  • int x - X coordinate of the tooltip position.
  • int y - Y coordinate of the tooltip position.
  • string str - Tooltip text.

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.

Return value

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

string engine.gui.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 localization dictionary; otherwise, the source string.
Last update: 2017-07-03