Widget Class

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

Widget Class

Members

---

void setCallback0(int callback, Callback0 func)

Arguments

• int callback
• Callback0 func

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.

void setCallback1(int callback, Callback1 func)

Arguments

• int callback
• Callback1 func

void setCallback2(int callback, Callback2 func)

Arguments

• int callback
• Callback2 func

void setCallback3(int callback, Callback3 func)

Arguments

• int callback
• Callback3 func

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 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 getCallbackAccel(int callback, unsigned int & key, int & ctrl, int & alt, int & shift)

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

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

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

int getFontVOffset()

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

Return value

vertical offset value, 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.

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.

void setHeight(int height)

Sets height of the widget in pixels.

Arguments

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

int getHeight()

Returns the height of the widget.

Return value

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 hide the widget, 0 to render it.

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 * getInterface()

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

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

Return value

Number of child widgets.

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

int getOrder()

Returns Z-order of the current widget.

Return value

Z-order of the widget, integer.

void setParent(Widget widget)

Sets a parent widget for the current one.

Arguments

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

Widget getParent()

Returns reference to the parent widget.

Return value

Reference to the parent widget.

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.

void setPermanentFocus()

Make the widget always focused.

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

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.

void setToolTip(string str, int reset = 0)

Sets a tooltip for the widget.

Arguments

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

string getToolTip()

Returns the widget tooltip.

Return value

Displayed tooltip.

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

Type name.

Widget getWidget()

Returns a widget pointer.

Return value

Widget pointer.

void setWidth(int width)

Sets width of the widget in pixels.

Arguments

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

int getWidth()

Returns the width of the widget.

Return value

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

Arguments

• Widget w - Widget to raise.

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

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