Widget Class

List of Functions:

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 - Format string for values entered into the attached widget. If none specified, "%d" is implied. This is an optional parameter.
int multiplier - Multiplier used to scale values provided by the attached widget. This is an optional parameter.
int flags - 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 - 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 getIntersection (int x, int y)

Searches for the intersection with widget bounds for the given point.

Arguments

int x - Local X coordinate.
int y - Local Y coordinate.

Return value

Returns 1 if the input point is inside the widget; otherwise, 0.

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 getNumChildren ()

Returns the number of children of the current widget.

Return value

Number of child widgets.

int getNumChilds ()

Returns the number of children of the current widget.

Warning

The function is deprecated. It is provided to keep your code working until the next release. Please, replace it with getNumChildren().

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 isCallback (int callback)

Checks if the given callback is set for the widget.

Arguments

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

Return value

1 is the callback is set for the widget; 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.

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