UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
Plugins Library
High-Level Systems
Samples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Content Creation
Materials
Unigine Material Library
Tutorials

Widget Class

This base class is used to create graphical user interface widgets of different types.

Widget Class

Members


void addAttach (Widget widget, string format = 0, int multiplier = 1, int flags = 0)

Attaches a given widget to the current one. When applied to checkboxes, converts them into a group of radio buttons. A horizontal/vertical slider can be attached to a label or a text field. The text field can be attached to any of the sliders.

Arguments

  • Widget widget - Widget to attach.
  • string format = 0 - Format string for values entered into the attached widget. If none specified, "%d" is implied. This is an optional parameter.
  • int multiplier = 1 - Multiplier used to scale values provided by the attached widget. This is an optional parameter.
  • int flags = 0 - One of the GUI_ATTACH_* pre-defined variables. This is an optional parameter.

void addChild (Widget widget, int flags = 0)

Adds a child widget.

Arguments

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

void arrange ()

Rearranges the widget and its children to lay them out neatly. This function forces to recalculate widget size and allows to get updated GUI layout data in the current frame. If this function is not called, widget modifications made in the current update() will be available only in the next frame (i.e. with one-frame lag), as GUI is calculated and rendered after the script update() function has been executed.

Widget getChild (int widget)

Returns a child widget with a given number.

Arguments

  • int widget - Widget number.

Return value

Required widget.

string getData ()

Returns a string associated with the widget.

Return value

Associated string.

int getFlags ()

Returns the set flags that control widget position on the screen.

Return value

GUI_* variables:
  • GUI_ALIGN_CENTER = 1 << 0
  • GUI_ALIGN_LEFT = 1 << 1
  • GUI_ALIGN_RIGHT = 1 << 2
  • GUI_ALIGN_TOP = 1 << 3
  • GUI_ALIGN_BOTTOM = 1 << 4
  • GUI_ALIGN_EXPAND = 1 << 5
  • GUI_ALIGN_OVERLAP = 1 << 6
  • GUI_ALIGN_BACKGROUND = 1 << 7
  • GUI_ALIGN_FIXED = 1 << 8

vec4 getFontColor ()

Returns the color of the font used by the widget.

Return value

Font color.

int getFontHOffset ()

Returns the horizontal offset of the font, used by the widget.

Return value

Horizontal offset value, pixels.

int getFontHSpacing ()

Returns the spacing (in pixels) between widget characters.

Return value

Horizontal spacing value.

int getFontOutline ()

Returns a value indicating if widget text is rendered casting a shadow. Positive or negative values determine the distance in pixels used to offset the font outline.

Return value

Positive value if outline is offset in the bottom-right corner direction. Negative value if outline is offset in the top-left corner direction. 0 if font is not outlined.

int getFontPermanent ()

Returns a flag indicating if color of the widget text is not changed even when it is disabled (non active), transparent (enabled option on non-active window), or widget loses focus.

Return value

1 if it does not change; otherwise, 0.

int getFontRich ()

Returns a value indicating if rich text formatting is used.

Return value

1 if rich text formatting is used; otherwise, 0.

int getFontSize ()

Returns the size of the font used by the widget.

Return value

Font size.

int getFontVOffset ()

Returns the vertical offset of the font, used by the widget.

Return value

vertical offset value, pixels.

int getFontVSpacing ()

Returns the spacing (in pixels) between widget text lines.

Return value

Vertical spacing value.

int getFontWrap ()

Returns a value indicating if text wrapping to widget width is enabled.

Return value

1 if text wrapping is enabled; otherwise, 0.

Gui getGui ()

Returns a Gui instance that currently renders the widget. (This function can be used if the widget is created and used in two different GUIs, for example, in case of the Interface plugin.) It can be called only by root widgets. For child widgets, see getParentGui().

Return value

The current GUI instance used for the widget.

int getHeight ()

Returns the height of the widget.
Notice
You may need to call arrange() first, if you have added a new widget and want to get its height in the same frame. Otherwise, zero will be returned.

Return value

Height in pixels.

int getKeyActivity (int key)

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

Arguments

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

Return value

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

int getMouseCursor ()

Returns the type of mouse pointer displayed over a widget.

Return value

One of the GUI_CURSOR_* pre-defined variables.

int getMouseX ()

Returns the x-coordinate of the mouse pointer position on the screen.

Return value

X-coordinate of the mouse pointer in widget coordinates.

int getMouseY ()

Returns the y-coordinate of the mouse pointer position on the screen.

Return value

Y-coordinate of the mouse pointer in widget coordinates.

Widget getNextFocus ()

Returns a widget which will be focused next if the user presses TAB.

Return value

Next widget.

int getNumChilds ()

Returns the number of children of the current widget.

Return value

Number of child widgets.

int getOrder ()

Returns Z-order of the current widget.

Return value

Z-order of the widget, integer.

Gui getParentGui ()

If a widget is child of another widget, returns a Gui instance that currently renders the widget's parent. (This function can be used if the widget is created and used in two different GUIs, for example, in case of the Interface plugin.)

Return value

The current GUI instance used for the widget's parent.

Widget getParent ()

Returns reference to the parent widget.

Return value

Reference to the parent widget.

int getPositionX ()

Returns the x-coordinate of the widget position relative to its parent.

Return value

X-coordinate of the upper left corner of the widget.

int getPositionY ()

Returns the y-coordinate of the widget position relative to its parent.

Return value

Y-coordinate of the upper left corner of the widget.

int getScreenPositionX ()

Returns the screen position of the widget (its top left corner) on the screen along the X axis.

Return value

Screen position along the X-axis in pixels.

int getScreenPositionY ()

Returns the screen position of the widget (its top left corner) on the screen along the Y axis.

Return value

Screen position along the Y-axis in pixels.

string getToolTip ()

Returns the widget tooltip.

Return value

Displayed tooltip.

string getTypeName ()

Returns the name of the widget type.

Return value

Type name.

int getType ()

Returns the type of the widget.

Return value

One of the WIDGET_* pre-defined variables.

int getWidth ()

Returns the width of the widget.
Notice
You may need to call arrange() first, if you have added a new widget and want to get its width in the same frame. Otherwise, zero will be returned.

Return value

Width in pixels.

int isCallbackAccel (int key, int ctrl, int alt, int shift)

Checks if the a given key in combination with CTRL, ALT or/and SHIFT buttons is assigned as a widget callback.

Arguments

  • int key - One of the standard ASCII keycodes or one of the APP_KEY_* pre-defined variables.
  • int ctrl - 1 if the CTRL key modifier is used; otherwise, 0.
  • int alt - 1 if the ALT key modifier is used; otherwise, 0.
  • int shift - 1 if the SHIFT key modifier is used; otherwise, 0.

Return value

1 if it is used in combinations; otherwise, 0.

int isCallbackEnabled (int callback)

Returns a value indicating if a given callback is enabled.

Arguments

  • int callback - One of the callbacks defined in the Gui class.

Return value

1 if callback is enabled; otherwise, 0.

int isChild (Widget widget)

Checks if a given widget is a child of the current one.

Arguments

  • Widget widget - Widget to check.

Return value

1 if the widget in question is a child; otherwise, 0.

int isEnabled ()

Returns a value indicating if the user can interact with the widget. The default is 1.

Return value

1 if the widget is enabled; otherwise, 0.

int isFocused ()

Returns a value indicating if the widget is currently in focus.

Return value

1 if the widget is in focus; otherwise, 0.

int isHidden ()

Returns a value indicating if the widget is rendered. When a widget is hidden, space occupied by it is left empty, and other widgets are not re-arranged.

Return value

1 if the widget is not rendered; otherwise, 0.

void raise (Widget widget)

Brings a given widget to the top.

Arguments

  • Widget widget - Widget to raise.

void removeAttach (Widget widget)

Detaches a given widget from the current one.

Arguments

  • Widget widget - Widget to detach.

void removeChild (Widget widget)

Removes a child widget from the current one.

Arguments

  • Widget widget - Child widget.

void removeFocus ()

Removes focus from the widget.

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

Replaces one child widget with another.

Arguments

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

void runCallback (int callback)

Runs a given callback function.

Arguments

  • int callback - One of the callbacks defined in the Gui class.

void setCallbackAccel (int callback, int key, int ctrl, int alt, int shift)

Assigns a key combination to a given callback function.

Arguments

  • int callback - One of the callbacks defined in the Gui class.
  • int key - One of the standard ASCII keycodes or one of the APP_KEY_* pre-defined variables.
  • int ctrl - 1 to use the CTRL key modifier, 0 not to use.
  • int alt - 1 to use the ALT key modifier, 0 not to use.
  • int shift - 1 to use the SHIFT key modifier, 0 not to use.

void setCallbackEnabled (int callback, int mode)

Enables or disables a given callback function.

Arguments

  • int callback - One of the callbacks defined in the Gui class.
  • int mode - 1 to enable the callback, 0 to disable it.

void setCallback (int callback, variable function, variable data_0, variable data_1, variable data_2, variable data_3)

Sets a function that will be called upon the specified GUI action. The passed function can take up to four arguments.

Arguments

  • int callback - Action callback flag (see GUI_* variables in the Gui class).
  • variable function - Function to be called.
  • variable data_0 - The argument to the function.
  • variable data_1 - The argument to the function.
  • variable data_2 - The argument to the function.
  • variable data_3 - The argument to the function.

void setData (string str)

Associates a custom string with a widget.

Arguments

  • string str - String to be associated

void setEnabled (int mode)

Sets a value indicating if the user can interact with the widget. The default is 1.

Arguments

  • int mode - 1 to enable the widget, 0 to disable it.

void setFlags (int flags)

Sets flags that control widget position on the screen.

Arguments

void setFocus ()

Make the widget focused.

void setFontColor (vec4 color)

Sets a color of the font used by the widget.

Arguments

  • vec4 color - Font color.

void setFontHOffset (int offset)

Sets the horizontal offset of the font, used by the widget.

Arguments

  • int offset - Horizontal offset value, pixels.

void setFontHSpacing (int spacing)

Sets the spacing (in pixels) between widget letters. The default is 0.

Arguments

  • int spacing - Horizontal spacing value.

void setFontOutline (int outline)

Sets a value indicating if widget text should be rendered casting a shadow. Positive or negative values set the distance in pixels to offset the font outline. The default is 0 (no outlining).

Arguments

  • int outline - Outline offset:
    • Positive values set offset in the bottom-right corner direction.
    • Negative values set offset in the top-left corner direction (the outline will overlap widget text).
    • 0 is not to use font outlining.

void setFontPermanent (int permanent)

Sets a flag to prevent color change for the widget text when it is disabled (non active), transparent (enabled option on non-active window), or widget loses focus.

Arguments

  • int permanent - 1 not to change text color; 0 to change it.

void setFontRich (int mode)

Sets a value indicating if rich text formatting should be used. The default is 0.

Arguments

  • int mode - 1 to use rich text formatting, 0 to use plain text formatting.

void setFontSize (int size)

Sets a size of the font used by the widget.

Arguments

  • int size - Font size.

void setFontVOffset (int offset)

Sets the vertical offset of the font, used by the widget.

Arguments

  • int offset - Vertical offset value, pixels.

void setFontVSpacing (int spacing)

Sets the spacing (in pixels) between widget text lines. The default is 0.

Arguments

  • int spacing - Vertical spacing value.

void setFontWrap (int mode)

Enables or disables text wrapping to widget width. The default is 0.

Arguments

  • int mode - 1 to enable text wrapping, 0 to disable it.

void setFont (string font)

Sets a font that will be used to render text on this widget.

Arguments

  • string font - Font name.

void setHeight (int height)

Sets height of the widget in pixels.
Notice
The widget cannot be smaller than its content (the texture, video, etc.). With setHeight() and setWidth() functions, it is only possible to make the widget bigger then the size of its content. For example, WidgetButton can be made bigger than its texture, but it cannot be made any smaller than the texture dimensions.

Arguments

  • int height - Height in pixels. If a negative value is provided, 0 will be used instead.

void setHidden (int mode)

Hides or shows the widget. When a widget is hidden, space occupied by it is left empty, and other widgets are not re-arranged. The default is 0.

Arguments

  • int mode - 1 to hide the widget, 0 to render it.

void setMouseCursor (int cursor)

Sets a mouse pointer to display over a widget.

Arguments

void setNextFocus (Widget focus)

Sets a widget which will be focused next if the user presses TAB.

Arguments

  • Widget focus - Next widget.

void setOrder (int order)

Sets Z-order for the current widget. The higher the value, the higher the order of the widget implementation priority will be.

Arguments

  • int order - Order value, integer, can be up to 127. (126 for the Profiler, 127 for the Console).

void setParent (Widget parent)

Sets a parent widget for the current one.

Arguments

  • Widget parent - Widget to be set as a parent.

void setPermanentFocus ()

Make the widget always focused.

void setPosition (int x, int y)

Sets a position of the widget relative to its parent. The default is (0,0).

Arguments

  • int x - X-coordinate of the upper left corner of the widget.
  • int y - Y-coordinate of the upper left corner of the widget.

void setToolTip (string text, int reset)

Sets a tooltip for the widget.

Arguments

  • string text - Tooltip to display.
  • int reset - 1 to recalculate a tooltip location if the mouse cursor was relocated; otherwise - 0.

void setWidth (int width)

Sets width of the widget in pixels.
Notice
The widget cannot be smaller than its content (the texture, video, etc.). With setHeight() and setWidth() functions, it is only possible to make the widget bigger then the size of its content. For example, WidgetButton can be made bigger than its texture, but it cannot be made any smaller than the texture dimensions.

Arguments

  • int width - Width in pixels. If a negative value is provided, 0 will be used instead.

int WIDGET_BUTTON

Description

Simple button. See also: WidgetButton.

int WIDGET_CANVAS

Description

Canvas widget for drawing text, lines and polygons. See also: WidgetCanvas.

int WIDGET_CHECKBOX

Description

Checkbox. See also: WidgetCheckbox.

int WIDGET_COMBOBOX

Description

Combobox. See also: WidgetCombobox.

int WIDGET_DIALOG

Description

Dialog window. See also: WidgetDialog.

int WIDGET_EDITLINE

Description

Text field. See also: WidgetEditline.

int WIDGET_EDITTEXT

Description

Multiline text field. See also: WidgetEdittext.

int WIDGET_ENGINE

Description

Engine-specific widget (manipulator). See also: WidgetManipulator.

int WIDGET_EXTERN

Description

External widget.

int WIDGET_GRIDBOX

Description

Grid box. See also: WidgetGridBox.

int WIDGET_GROUPBOX

Description

Group box. See also: WidgetGroupBox.

int WIDGET_HBOX

Description

Horizontal box. See also: WidgetHBox.

int WIDGET_HPANED

Description

Horizontal box that allows resizing of its children. See also: WidgetHPaned.

int WIDGET_ICON

Description

Icon. See also: WidgetIcon.

int WIDGET_LABEL

Description

Text label. See also: WidgetLabel.

int WIDGET_LISTBOX

Description

List box. See also: WidgetListBox.

int WIDGET_MENUBAR

Description

Menu bar. See also: WidgetMenuBar.

int WIDGET_MENUBOX

Description

Menu. See also: WidgetMenuBox.

int WIDGET_SCROLL

Description

A scrollbar: horizontal or vertical one. See also: WidgetScroll.

int WIDGET_SCROLLBOX

Description

Box with scrolling. See also: WidgetScrollBox.

int WIDGET_SLIDER

Description

A slider: horizontal or vertical one. See also: WidgetSlider.

int WIDGET_SPACER

Description

Spacer: horizontal or vertical one. See also: WidgetSpacer.

int WIDGET_SPINBOX

Description

Spinbox. See also: WidgetSpinBox.

int WIDGET_SPRITE

Description

Sprite. See also: WidgetSprite.

int WIDGET_TABBOX

Description

Tabbed box. See also: WidgetTabBox.

int WIDGET_TREEBOX

Description

Tree box. See also: WidgetTreeBox.

int WIDGET_VBOX

Description

Vertical box. See also: WidgetVBox.

int WIDGET_VPANED

Description

Vertical box that allows resizing of its children. See also: WidgetVPaned.

int WIDGET_WINDOW

Description

Window. See also: WidgetWindow.
Last update: 2017-07-03