Widget Class
Warning
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.
This base class is used to create graphical user interface widgets of different types. The Widget class doesn't provide creating of a widget: you can create the required widget by using a constructor of the corresponding class inherited from the Widget class.
Widgets can be used separately or form a hierarchy.
Working with Widgets#
The example below demonstrates how to create a single widget, a hierarchy of widgets, and subscribe for a widget's event.
Lifetime of Widgets#
By default each new widget's lifetime matches the lifetime of the Engine (i.e. the widget shall be deleted on Engine shutdown). But you can choose widget's lifetime to be managed:
- By a separate window — in this case the widget is deleted automatically on deleting the window.
- By the world — in this case the widget is deleted when the world is closed.
- Manually — in this case the widget should be deleted manually.
The examples below show how the different lifetime management types work.
Managing Lifetime by the World#
In this example, the widgets appear on loading the world. When you reload or exit the world, or close the Engine window, the widgets are deleted as their lifetime is managed by the world. The corresponding messages will be shown in the console.
Managing Lifetime by the Window#
In this example, widgets appear in a separate window. When you close the window, the widgets are deleted as their lifetime is managed by this window. The console shows the following information:
- Whether the window, button and hbox hierarchy are deleted or not.
- Whether the remove callbacks are fired or not.
- Messages from the remove callbacks.
After closing, the window can be re-created by pressing T.
Managing Lifetime by the Engine#
Widgets are created on Engine initialization, and then added to a separate window. The console shows the following information:
- Whether the window, button and hbox hierarchy are deleted or not.
- Whether the remove callbacks are fired or not.
- Messages from the remove callbacks.
If you close the window, it will be deleted and the information in the console will change. All the other widgets are deleted only on Engine shutdown, as their lifetime is managed by the Engine.
If the separate window is closed, press T to re-create it.
See Also#
- Widgets sample set in CPP Samples suite
- Widgets sample in C# Component Samples suite
- A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/widgets/ folder
Widget Class
Members
int getNumChildren() const#
Returns the current
Return value
Current number of child widgets.void setFontWrap ( int wrap ) #
Sets a new value indicating if text wrapping to widget width is enabled.
Arguments
- int wrap - The value of 1 for text wrapping; otherwise, 0.
int getFontWrap() const#
Returns the current value indicating if text wrapping to widget width is enabled.
Return value
Current value of 1 for text wrapping; otherwise, 0.void setFontRich ( int rich ) #
Sets a new value indicating if rich text formatting is used.
Arguments
- int rich - The value of 1 for rich text formatting; otherwise, 0.
int getFontRich() const#
Returns the current value indicating if rich text formatting is used.
Return value
Current value of 1 for rich text formatting; otherwise, 0.void setFontOutline ( int outline ) #
Sets a new 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.
Arguments
- int outline - The 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 getFontOutline() const#
Returns the current 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
Current 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.void setFontVOffset ( int voffset ) #
Sets a new
Arguments
- int voffset - The vertical offset value, in pixels.
int getFontVOffset() const#
Returns the current
Return value
Current vertical offset value, in pixels.void setFontHOffset ( int hoffset ) #
Sets a new
Arguments
- int hoffset - The horizontal offset value, in pixels.
int getFontHOffset() const#
Returns the current
Return value
Current horizontal offset value, in pixels.void setFontVSpacing ( int vspacing ) #
Sets a new spacing (in pixels) between widget text lines.
Arguments
- int vspacing - The vertical spacing value, in pixels.
int getFontVSpacing() const#
Returns the current spacing (in pixels) between widget text lines.
Return value
Current vertical spacing value, in pixels.void setFontHSpacing ( int hspacing ) #
Sets a new
Arguments
- int hspacing - The horizontal spacing value, in pixels.
int getFontHSpacing() const#
Returns the current
Return value
Current horizontal spacing value, in pixels.void setFontPermanent ( int permanent ) #
Sets a new
Arguments
- int permanent - The value of 1 to keep the text color unchanged; 0 to change it.
int getFontPermanent() const#
Returns the current
Return value
Current value of 1 to keep the text color unchanged; 0 to change it.void setFontColor ( vec4 color ) #
Sets a new color of the font used by the widget.
Arguments
- vec4 color - The font color.
vec4 getFontColor() const#
Returns the current color of the font used by the widget.
Return value
Current font color.void setFontSize ( int size ) #
Sets a new size of the font used by the widget.
Arguments
- int size - The Font size in pixels.
int getFontSize() const#
Returns the current size of the font used by the widget.
Return value
Current Font size in pixels.void setMouseCursor ( int cursor ) #
Sets a new
Arguments
- int cursor - The mouse pointer, one of the CURSOR_* pre-defined variables.
int getMouseCursor() const#
Returns the current
Return value
Current mouse pointer, one of the CURSOR_* pre-defined variables.int getMouseY() const#
Returns the current Y coordinate of the mouse pointer position in the widget's local space.
Return value
Current Y coordinate of the mouse pointer position in the widget's local space.int getMouseX() const#
Returns the current X coordinate of the mouse pointer position in the widget's local space.
Return value
Current X coordinate of the mouse pointer position in the widget's local space.void setHeight ( int height ) #
Sets a new
Arguments
- int height - The widget minimal height, in pixels. If a negative value is provided, the value of 0 will be used instead.
int getHeight() const#
Returns the current
Return value
Current widget minimal height, in pixels. If a negative value is provided, the value of 0 will be used instead.void setWidth ( int width ) #
Sets a new
Arguments
- int width - The widget minimal width, in pixels. If a negative value is provided, the value of 0 will be used instead.
int getWidth() const#
Returns the current
Return value
Current widget minimal width, in pixels. If a negative value is provided, the value of 0 will be used instead.int getScreenPositionY() const#
Returns the current screen position of the widget (its top left corner) on the screen along the y axis.
Return value
Current screen position along the Y axis in pixels.int getScreenPositionX() const#
Returns the current screen position of the widget (its top left corner) on the screen along the x axis.
Return value
Current screen position along the X axis in pixels.void setPositionY ( int y ) #
Sets a new Y coordinate of the widget position relative to its parent.
Arguments
- int y - The Y coordinate of the widget position relative to its parent.
int getPositionY() const#
Returns the current Y coordinate of the widget position relative to its parent.
Return value
Current Y coordinate of the widget position relative to its parent.void setPositionX ( int x ) #
Sets a new X coordinate of the widget position relative to its parent.
Arguments
- int x - The X coordinate of the widget position relative to its parent.
int getPositionX() const#
Returns the current X coordinate of the widget position relative to its parent.
Return value
Current X coordinate of the widget position relative to its parent.void setNextFocus ( Widget focus ) #
Sets a new widget which will be focused next if the user presses TAB.
Arguments
- Widget focus - The widget which will be focused next if the user presses TAB.
Widget getNextFocus() const#
Returns the current widget which will be focused next if the user presses TAB.
Return value
Current widget which will be focused next if the user presses TAB.void setData ( string data ) #
Sets a new
Arguments
- string data - The
string getData() const#
Returns the current
Return value
Currentvoid setOrder ( int order ) #
Sets a new
Arguments
- int order - The rendering order (z-order) for the widget, in the range [-128;127]. (126 for the Profiler, 127 for the Console).
int getOrder() const#
Returns the current
Return value
Current rendering order (z-order) for the widget, in the range [-128;127]. (126 for the Profiler, 127 for the Console).void setHidden ( ) #
Sets a new
Arguments
- hidden - The the hidden status for the widget
isHidden() const#
Returns the current
Return value
Current the hidden status for the widgetvoid setEnabled ( ) #
Sets a new
Arguments
- enabled - The the enabled (interactable) status for the widget
isEnabled() const#
Returns the current
Return value
Current the enabled (interactable) status for the widgetvoid setIntersectionEnabled ( ) #
Sets a new value indicating if intersection detection is enabled for the widget.
Arguments
- enabled - The intersection detection for the widget
isIntersectionEnabled() const#
Returns the current value indicating if intersection detection is enabled for the widget.
Return value
Current intersection detection for the widgetvoid setFlags ( int flags ) #
Sets a new
Arguments
- int flags - The widget flags, ALIGN_* pre-defined variables.
int getFlags() const#
Returns the current
Return value
Current widget flags, ALIGN_* pre-defined variables.void setParent ( Widget parent ) #
Sets a new
Arguments
- Widget parent - The parent widget.
Widget getParent() const#
Returns the current
Return value
Current parent widget.Gui getParentGui() const#
Returns the current Gui instance that currently renders the widget's parent, if the widget has a 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
Current GUI instance used for the widget's parent.Gui getGui() const#
Returns the current
Return value
Current GUI instance used for the widget.string getTypeName() const#
Returns the current
Return value
Current name of the widget type.getType() const#
Returns the current
Return value
Current type of the widget.bool isLayout() const#
Returns the current value indicating if the widget is a layout.
Return value
true if the widget is a layout; otherwise false.bool isFixed() const#
Returns the current value indicating if the widget is fixed.
Return value
true if the widget is fixed; otherwise false.bool isBackground() const#
Returns the current value indicating if the widget is a background one.
Return value
true if the widget is a background one; otherwise false.bool isOverlapped() const#
Returns the current value indicating if the widget is overlapped.
Return value
true if the widget is overlapped; otherwise false.bool isExpanded() const#
Returns the current value indicating if the widget is expanded.
Return value
true if the widget is expanded; otherwise false.void setLifetime ( ) #
Sets a new lifetime management type for the root of the widget, or for the widget itself (if it is not a child for another widget).
Notice
Lifetime of each widget in the hierarchy is defined by its root. Thus, lifetime management type set for a child widget that differs from the one set for the root is ignored.
Arguments
- lifetime - The lifetime management type.
getLifetime() const#
Returns the current lifetime management type for the root of the widget, or for the widget itself (if it is not a child for another widget).
Notice
Lifetime of each widget in the hierarchy is defined by its root. Thus, lifetime management type set for a child widget that differs from the one set for the root is ignored.
Return value
Current lifetime management type.float getDpiScale() const#
Returns the current DPI scale applied to the widget.
Return value
Current DPI scale applied to the widget.int getRenderHeight() const#
Returns the current widget frame height in pixels.
Return value
Current widget frame height in pixels.int getRenderWidth() const#
Returns the current widget frame width in pixels.
Return value
Current widget frame width in pixels.getEventRemove() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventDragDrop() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventDragMove() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventLeave() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventEnter() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventTextPressed() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventKeyPressed() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventReleased() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventPressed() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventDoubleClicked() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventClicked() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventChanged() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventFocusOut() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventFocusIn() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventHide() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.getEventShow() const#
The event handler signature is as follows: myhandler()Usage Example
Source code
Return value
Event reference.Widget getChild ( int num ) #
Returns a child widget with a given number.Arguments
- int num - Widget number.
Return value
Required widget.int isChild ( Widget w ) #
Checks if a given widget is a child of the current one.Arguments
- Widget w - Widget to check.
Return value
1 if the widget in question is a child; otherwise, 0.void setFocus ( ) #
Make the widget focused.int isFocused ( ) #
Returns a value indicating if the widget is currently in focus.Return value
1 if the widget is in focus; otherwise, 0.void setFont ( string name ) #
Sets a font that will be used to render text on this widget.Arguments
- string name - Font name.
int getIntersection ( int local_pos_x, int local_pos_y ) #
Checks for an intersection with the widget's bounds for the given point.Arguments
- int local_pos_x - Local X coordinate.
- int local_pos_y - Local Y coordinate.
Return value
1 if the input coordinate is inside the widget; otherwise, 0.Widget getHierarchyIntersection ( int screen_pos_x, int screen_pos_y ) #
Checks for an intersection with a widget that belongs to the hierarchy of the current widget.Arguments
- int screen_pos_x - The X coordinate of the screen position.
- int screen_pos_y - The Y coordinate of the screen position.
Return value
Widget the intersection with which is found.int getKeyActivity ( unsigned int key ) #
Checks if a given key already has a special purpose for the widget.Arguments
- unsigned int key - One of the standard ASCII keycodes or one of the INPUT_KEY_*pre-defined variables.
Return value
1 if the key cannot be used; otherwise, 0.void setPermanentFocus ( ) #
Sets permanent focus on the widget (it means that the widget is always in focus).void setPosition ( int x, int y ) #
Sets a position of the widget relative to its parent.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 str, int reset = 0 ) #
Sets a tooltip for the widget.Arguments
- string str - Tooltip text.
- int reset - 1 to recalculate a tooltip location if the mouse cursor was relocated; otherwise — 0(by default).
string getToolTip ( ) #
Returns the widget's tooltip text.Return value
Tooltip text.void addAttach ( Widget w, 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 w - Widget to attach.
- string format - Format string for values entered into the attached widget. If none specified, "%d" is implied. This is an optional parameter.
- int multiplier - Multiplier value, which is used to scale values provided by the attached widget. This is an optional parameter.
- int flags - One of the ATTACH_* pre-defined variables. This is an optional parameter.
void addChild ( Widget w, int flags = 0 ) #
Adds a child to the widget.Arguments
- Widget w - Child widget.
- int flags - One of the 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.void raise ( Widget w ) #
Brings a given widget to the top.Notice
Works only for widgets added to GUI via the addChild() function with the GUI_ALIGN_OVERLAP flag specified (should not be GUI_ALIGN_FIXED).
Arguments
- Widget w - Widget to be brought up.
void removeAttach ( Widget w ) #
Detaches a given widget from the current one.Arguments
- Widget w - Widget to detach.
void removeChild ( Widget w ) #
Removes a child widget from the list of the widget's children.Arguments
- Widget w - Child widget.
void removeFocus ( ) #
Removes focus from the widget.void replaceChild ( Widget w, Widget old_w, int flags = 0 ) #
Replaces one child widget with another.Arguments
- Widget w - Replacement widget.
- Widget old_w - Widget to be replaced.
- int flags - One of the ALIGN_* pre-defined variables. This is an optional parameter.
int getLifetimeSelf ( ) #
Returns the lifetime management type set for the widget.Notice
Lifetime of each widget in the hierarchy is defined by it's root. Setting lifetime management type for a child widget different from the one set for the root has no effect.
ivec2 getTextRenderSize ( const char * OUT_text ) #
Returns the size (in pixels) of the specified text string rendered on the screen with taking into account all text output settings such as dpi, font size and style.Arguments
- const char * OUT_text - Text string.NoticeThis output buffer is to be filled by the Engine as a result of executing the method.
Return value
Text size in pixels.void runEventShow ( ) #
Emulates the Show event.void runEventHide ( ) #
Emulates the Hide event.void runEventFocusIn ( ) #
Emulates the FocusIn event.void runEventFocusOut ( ) #
Emulates the FocusOut event.void runEventChanged ( ) #
Emulates the Changed event.void runEventClicked ( int mouse_buttons ) #
Emulates the Clicked event.Arguments
- int mouse_buttons - Mouse button. One of the MOUSE_BUTTON values.
void runEventDoubleClicked ( ) #
Emulates the DoubleClicked event.void runEventPressed ( int mouse_buttons ) #
Emulates the Pressed event.Arguments
- int mouse_buttons - Mouse button. One of the MOUSE_BUTTON values.
void runEventReleased ( int mouse_buttons ) #
Emulates the Released event.Arguments
- int mouse_buttons - Mouse button. One of the MOUSE_BUTTON values.
void runEventKeyPressed ( int key ) #
Emulates the KeyPressed event.Arguments
- int key - Key scan code.
void runEventTextPressed ( unsigned int code ) #
Emulates the TextPressed event.Arguments
- unsigned int code - Vistual key.
void runEventEnter ( ) #
Emulates the Enter event.void runEventLeave ( ) #
Emulates the Leave event.void runEventDragMove ( Widget pointer ) #
Emulates the DragMove event.Arguments
- Widget pointer - Underlying widget.
void runEventDragDrop ( Widget pointer ) #
Emulates the DragDrop event.Arguments
- Widget pointer - Target widget.
Last update:
2024-03-25
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)