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 add a callback for the widget.
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 the separate window is closed, press T to re-create it.
See Also#
- A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/widgets/ folder
Widget Class
Members
bool isCallback ( int callback ) #
Returns a value indicating if there are any callbacks of the specified type set for the widget.Arguments
- int callback - One of the callbacks defined in the Gui class.
Return value
true if at least one callback of the specified type is set for the widget; otherwise, false.void setCallback ( int callback, Variable func ) #
Sets a callback function for the widget.Source code (UnigineScript)
WidgetEditText text = new WidgetEditText(gui,"Editable text...");
text.setCallback(GUI_KEY_PRESSED,"Text::text_key_pressed");Arguments
- int callback - Callback number. One of the callbacks defined in the Gui class.
- Variable func - Name or identifier of the callback function to be set with the following signature: void callback().
void setCallback ( int callback, Variable func, Variable arg0 ) #
Sets a callback function for the widget.Source code (UnigineScript)
void sprite_drag_move(WidgetSprite sprite) {
// ...
}
// ...
WidgetSprite sprite = new WidgetSprite(gui,fullPath("core/gui/gui_white.png"));
sprite.setCallback(GUI_DRAG_MOVE,functionid(sprite_drag_move),sprite);Arguments
- int callback - Callback number.
- Variable func - Name or identifier of the callback function to be set with the following signature: void callback(Variable arg0).
- Variable arg0 - First callback argument.
void setCallback ( int callback, Variable func, Variable arg0, Variable arg1 ) #
Sets a callback function for the widget.Arguments
- int callback - Callback number.
- Variable func - Name or identifier of the callback function to be set with the following signature: void callback(Variable arg0, Variable arg1).
- Variable arg0 - First callback argument.
- Variable arg1 - Second callback argument.
void setCallback ( int callback, Variable func, Variable arg0, Variable arg1, Variable arg2 ) #
Sets a callback function for the widget.Source code (UnigineScript)
void sprite_enter(WidgetSprite sprite,vec4 color,int id) {
engine.message("enter: %d\n",id);
sprite.setColor(vec4_one);
}
//...
WidgetSprite sprite = new WidgetSprite(gui,fullPath("core/gui/gui_white.png"));
sprite.setCallback(GUI_ENTER,functionid(sprite_enter),sprite,color,i);Arguments
- int callback - Callback number.
- Variable func - Name or identifier of the callback function to be set with the following signature: void callback(Variable arg0, Variable arg1, Variable arg2).
- Variable arg0 - First callback argument.
- Variable arg1 - Second callback argument.
- Variable arg2 - Third callback argument.
void setCallback ( int callback, Variable func, Variable arg0, Variable arg1, Variable arg2, Variable arg3 ) #
Sets a callback function for the widget.Arguments
- int callback - Callback number.
- Variable func - Name or identifier of the callback function to be set with the following signature: void callback(Variable arg0, Variable arg1, Variable arg2, Variable arg3).
- Variable arg0 - First callback argument.
- Variable arg1 - Second callback argument.
- Variable arg2 - Third callback argument.
- Variable arg3 - Fourth callback argument.
void setCallbackAccel ( int callback, unsigned 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.
- unsigned int key - One of the standard ASCII keycodes or one of the INPUT_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.
bool getCallbackAccel ( int callback, unsigned int & key, int & ctrl, int & alt, int & shift ) #
Gets the current hot key combination for a given callback function.Arguments
- int callback - Callback number: one of the Gui:: Enumeration (for example, SHOW, HIDE, etc).
- unsigned int & key - ASCII key code: one of the App:: Enumeration with KEY_* prefixes.
- int & ctrl - CTRL key modifier.
- int & alt - ALT key modifier.
- int & shift - SHIFT key modifier.
Return value
1 if the specified callback type exists; otherwise, 0.int isCallbackAccel ( unsigned int key, int ctrl, int alt, int shift ) #
Checks if the given key in combination with CTRL, ALT, or/and SHIFT buttons is assigned as a widget callback.Arguments
- unsigned int key - One of the standard ASCII keycodes or one of the INPUT_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.void setCallbackEnabled ( int callback, int enabled ) #
Enables or disables a given callback function.Arguments
- int callback - One of the callbacks defined in the Gui class.
- int enabled - 1 to enable the callback, 0 to disable it.
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.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 setData ( string data ) #
Associates a custom string with a widget.Arguments
- string data - String to be associated
string getData ( ) #
Returns a string associated with the widget.Return value
Associated string.void setEnabled ( int enabled ) #
Sets a value indicating if the user can interact with the widget.Arguments
- int enabled - 1 to enable the widget, 0 to disable it.
int isEnabled ( ) #
Returns a value indicating if the user can interact with the widget.Return value
1 if the widget is enabled; otherwise, 0.void setFlags ( int flags ) #
Sets flags that control widget position on the screen.Arguments
- int flags - ALIGN_* pre-defined variables.
int getFlags ( ) #
Returns the set flags that control widget position on the screen.Return value
GUI variables:- ALIGN_CENTER = 1 << 0
- ALIGN_LEFT = 1 << 1
- ALIGN_RIGHT = 1 << 2
- ALIGN_TOP = 1 << 3
- ALIGN_BOTTOM = 1 << 4
- ALIGN_EXPAND = 1 << 5
- ALIGN_OVERLAP = 1 << 6
- ALIGN_BACKGROUND = 1 << 7
- ALIGN_FIXED = 1 << 8
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.
void setFontColor ( vec4 color ) #
Sets a color of the font used by the widget.Arguments
- vec4 color - Font color.
vec4 getFontColor ( ) #
Returns the color of the font used by the widget.Return value
Font color.void setFontHOffset ( int hoffset ) #
Sets the horizontal offset of the font, used by the widget.Arguments
- int hoffset - Horizontal offset value, pixels.
int getFontHOffset ( ) #
Returns the horizontal offset of the font, used by the widget.Return value
Horizontal offset value, pixels.void setFontHSpacing ( int hspacing ) #
Sets the spacing (in pixels) between widget letters.Arguments
- int hspacing - Horizontal spacing value.
int getFontHSpacing ( ) #
Returns the spacing (in pixels) between widget characters.Return value
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.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.
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.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.
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.void setFontRich ( int rich ) #
Sets a value indicating if rich text formatting should be used.Arguments
- int rich - 1 to use rich text formatting, 0 to use plain text formatting.
int getFontRich ( ) #
Returns a value indicating if rich text formatting is used.Return value
1 if rich text formatting is used; otherwise, 0.void setFontSize ( int size ) #
Sets a size of the font used by the widget.Arguments
- int size - Font size.
int getFontSize ( ) #
Returns the size of the font used by the widget.Return value
Font size.void setFontVOffset ( int voffset ) #
Sets the vertical offset of the font used by the widget.Arguments
- int voffset - Vertical offset value, in pixels.
int getFontVOffset ( ) #
Returns the vertical offset of the font, used by the widget.Return value
Vertical offset value, in pixels.void setFontVSpacing ( int vspacing ) #
Sets the spacing (in pixels) between widget text lines.Arguments
- int vspacing - Vertical spacing value.
int getFontVSpacing ( ) #
Returns the spacing (in pixels) between widget text lines.Return value
Vertical spacing value.void setFontWrap ( int wrap ) #
Enables or disables text wrapping to widget width.Arguments
- int wrap - 1 to enable text wrapping, 0 to disable it. The default is 0.
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
Current GUI instance used for the widget.void setHeight ( int height ) #
Sets the minimal 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 - Widget's minimal height. If a negative value is provided, the 0 will be used instead.
int getHeight ( ) #
Returns the current widget height ,in pixels.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
Widget's height, in pixels.void setHidden ( int hidden ) #
Hides or shows the widget. When a widget is hidden, space occupied by it is left empty, and other widgets are not re-arranged.Arguments
- int hidden - 1 to show the widget, 0 to hide it.
int isHidden ( ) #
Returns a value indicating if the widget is hidden. 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 hidden; otherwise, 0.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.void setIntersectionEnabled ( int enabled ) #
Sets a value indicating if intersection detection is enabled for the widget.Arguments
- int enabled - 1 to enable intersection detection for the widget, 0 - to disable it.
int isIntersectionEnabled ( ) #
Returns a value indicating if intersection detection is enabled for the widget.Return value
1 if intersection detection is enabled for the widget; otherwise, 0.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 setMouseCursor ( int cursor ) #
Sets a mouse pointer to display over a widget.Arguments
- int cursor - One of the CURSOR_* pre-defined variables.
int getMouseCursor ( ) #
Returns the type of mouse pointer displayed over a widget.Return value
One of the CURSOR_* pre-defined variables.int getMouseX ( ) #
Returns the X coordinate of the mouse pointer position in the widget's local space.Return value
X coordinate of the mouse pointer position in the widget's local space.int getMouseY ( ) #
Returns the Y coordinate of the mouse pointer position in the widget's local space.Return value
Y coordinate of the mouse pointer position in the widget's local space.void setNextFocus ( Widget focus ) #
Sets a widget which will be focused next if the user presses TAB.Arguments
- Widget focus - Next widget.
Widget getNextFocus ( ) #
Returns a widget which will be focused next if the user presses TAB.Return value
Next widget.int getNumChildren ( ) #
Returns the number of children of the widget.Return value
Number of child widgets.void setOrder ( int order ) #
Sets rendering order (Z-order) for the widget. The higher the value, the higher the order of the widget will be.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
- int order - Rendering order (Z-order) of the widget, in the range [-128;127]. (126 for the Profiler, 127 for the Console).
int getOrder ( ) #
Returns rendering order (Z-order) for the widget.Return value
Rendering order (Z-order) of the widget, in the range [-128;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.
Widget getParent ( ) #
Returns reference to the parent widget.Return value
Parent widget.Gui getParentGui ( ) #
Returns a 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.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.
int getPositionX ( ) #
Returns the X coordinate of the widget position relative to its parent.Return value
The relative X coordinate.int getPositionY ( ) #
Returns the Y coordinate of the widget position relative to its parent.Return value
Relative Y coordinate.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.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.int getType ( ) #
Returns the type of the widget.Return value
One of the WIDGET_* pre-defined variables.string getTypeName ( ) #
Returns the name of the widget type.Return value
Widget type name.void setWidth ( int width ) #
Sets the minimal 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 - Widget's minimal width. If a negative value is provided, the 0 will be used instead.
int getWidth ( ) #
Returns the current widget width, in pixels.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
Widget width, in pixels.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.
void runCallback ( int callback ) #
Runs a given callback function.Arguments
- int callback - One of the callbacks defined in the Gui class.
int isExpanded ( ) #
Returns a value indicating if the widget is expanded.Return value
1 if the widget is expanded; otherwise, 0.int isOverlapped ( ) #
Returns a value indicating if the widget is overlapped.Return value
1 if the widget is overlapped; otherwise, 0.int isBackground ( ) #
Returns a value indicating if the widget is a background one.Return value
1 if the widget a background one; otherwise, 0.int isFixed ( ) #
Returns a value indicating if the widget is fixed.Return value
1 if the widget is fixed; otherwise, 0.int isLayout ( ) #
Returns a value indicating if the widget is of a type that is responsible for the layout.Return value
1 if the widget is a layout; otherwise, 0.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.
void setLifetime ( int lifetime ) #
Sets the lifetime management type for the widget. By default, the LIFETIME_ENGINE type is used.Arguments
- int lifetime - Lifetime management type.
int getLifetime ( ) #
Returns the 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 it's root. Thus, lifetime management type set for a child widget that differs from the one set for the root is ignored.
Last update:
2023-03-01
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)