UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Rendering-Related Classes

Unigine::Widget Class

Header: #include <UnigineWidgets.h>

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

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 - Callback number: one of the Gui:: Enumeration (for example, SHOW, HIDE, etc).

Return value

true if at least one callback of the specified type is set for the widget; otherwise, false.

void * addCallback ( int callback, Unigine::CallbackBase * func ) #

Adds a callback function of the specified type for the widget.The signature of the callback function must be as follows:
Source code (C++)
void callback_function_name();

Arguments

  • int callback - Callback type number. One of the callbacks defined in the Gui class (for example, CLICK, SHOW, HIDE, etc).
  • Unigine::CallbackBase * func - Callback pointer.

Return value

ID of the last added callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

void * addCallback ( int callback, Unigine::CallbackBase1< Ptr<Widget> > * func ) #

Adds a callback function of the specified type for the widget.The signature of the callback function must be as follows:
Source code (C++)
void callback_function_name(WidgetPtr sender);

Arguments

  • int callback - Callback type number. One of the callbacks defined in the Gui class (for example, CLICK, SHOW, HIDE, etc).
  • Unigine::CallbackBase1< Ptr<Widget> > * func - Callback pointer.

Return value

ID of the last added callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

void * addCallback ( int callback, Unigine::CallbackBase2< Ptr<Widget>, Ptr<Widget> > * func ) #

Adds a callback function of the specified type for the widget.The signature of the callback function must be as follows:
Source code (C++)
void callback_function_name(WidgetPtr sender, WidgetPtr pointer);

Arguments

  • int callback - Callback type number. One of the callbacks defined in the Gui class (for example, CLICK, SHOW, HIDE, etc).
  • Unigine::CallbackBase2< Ptr<Widget>, Ptr<Widget> > * func - Callback pointer.

Return value

ID of the last added callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

void * addCallback ( int callback, Unigine::CallbackBase3< Ptr<Widget>, Ptr<Widget>, int > * func ) #

Adds a callback function of the specified type for the widget.The signature of the callback function must be as follows:
Source code (C++)
void callback_function_name(WidgetPtr sender, WidgetPtr pointer, int data);

Arguments

  • int callback - Callback type number. One of the callbacks defined in the Gui class (for example, CLICK, SHOW, HIDE, etc).
  • Unigine::CallbackBase3< Ptr<Widget>, Ptr<Widget>, int > * func - Callback pointer.

Return value

ID of the last added callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

bool removeCallback ( int callback, void * id ) #

Removes the specified callback from the list of callbacks of the specified type added for the widget.

Arguments

  • int callback - Callback type number. One of the callbacks defined in the Gui class (for example, CLICK, SHOW, HIDE, etc).
  • void * id - Callback ID obtained when adding it.

Return value

True if the callback with the given ID was removed successfully; otherwise false.

void clearCallbacks ( int callback ) #

Clears all callbacks of the specified type added for the widget.

Arguments

  • int callback - Callback type number. One of the callbacks defined in the Gui class (for example, CLICK, SHOW, HIDE, etc).

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

Assigns a hot key combination to 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.

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

true if the specified callback type exists; otherwise, false.

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 - Callback number: one of the Gui:: Enumeration (for example, SHOW, HIDE, etc).
  • 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 - Callback number: one of the Gui:: Enumeration (for example, SHOW, HIDE, etc).

Return value

Returns 1 if the callback is disabled; otherwise, 0.

Ptr<Widget> getChild ( int num ) #

Returns the widget child by its number.

Arguments

  • int num - Number of the child widget.

Return value

Pointer to the child widget.

int isChild ( const Ptr<Widget> & w ) #

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

Arguments

  • const Ptr<Widget> & w - Widget to check.

Return value

Returns 1 if the given widget is a child; otherwise, 0.

void setData ( const char * data ) #

Sets user data associated with the widget.

Arguments

  • const char * data - string data. Data can be an xml formatted string.

const char * getData ( ) #

Returns user data associated with the widget.

Return value

User string data. Data can be an xml formatted string.

void setEnabled ( int enabled ) #

Enables or disables the widget.

Arguments

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

int isEnabled ( ) #

Returns a value indicating if the widget is enabled.

Return value

Returns 1 if the widget is disabled; otherwise, 0.

void setFlags ( int flags ) #

Sets widget flags.

Arguments

  • int flags - flags.

int getFlags ( ) #

Returns widget flags.

Return value

Widget flags: one of the Gui:: Enumeration with ALIGN_* prefixes. This is an optional parameter.

void setFocus ( ) #

Sets focus on the widget.

int isFocused ( ) #

Returns a value indicating if the widget is in focus.

Return value

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

void setFont ( const char * name ) #

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

Arguments

  • const char * name - Path to the font file (*.ttf).

void setFontColor ( const Math::vec4 & color ) #

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

Arguments

  • const Math::vec4 & color - Font color.

Math::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 in pixels.

int getFontHOffset ( ) #

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

Return value

Horizontal offset value in pixels.

void setFontHSpacing ( int hspacing ) #

Sets the spacing (in pixels) between widget text characters.

Arguments

  • int hspacing - Horizontal spacing value.

int getFontHSpacing ( ) #

Returns the spacing (in pixels) between widget text 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. 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.

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 (for example, when the widget becomes non-active or 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 (for example, when the widget becomes non-active or loses focus).

Return value

1 if color of the widget text is not changed; otherwise, 0.

void setFontRich ( int rich ) #

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

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 font size that will be used to render text on the widget.

Arguments

  • int size - Font size in pixels.

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. The default is 0.

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.

Ptr<Gui> getGui ( ) #

Returns the Gui smart pointer.

Return value

Gui smart pointer.

void setHeight ( int height ) #

Sets minimal height of the widget in pixels.

Arguments

  • int height - Widget minimal height. If a negative value is provided, the 0 will be used instead.

int getHeight ( ) #

Returns the current widget height in pixels.

Return value

Widget height in pixels.

void setHidden ( int hidden ) #

Hides or shows the widget.

Arguments

  • int hidden - 1 to show the widget, 0 to hide it.

int isHidden ( ) #

Returns a value indicating if the widget is hidden.

Return value

Return 1 if the widget is hidden; otherwise, 0.

void * getInterface ( ) #

Returns an interface pointer.

Return value

Interface pointer.

int getIntersection ( int x, int y ) #

Check the intersection with widget bounds.

Arguments

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

Return value

Returns 1 if the input coordinate 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 - ASCII key code: one of the 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.

Arguments

  • int cursor - Mouse pointer. See the list of available pointers with CURSOR_* prefixes in the article on Gui class functions.

int getMouseCursor ( ) #

Returns the current mouse pointer.

Return value

Mouse pointer. One of the available pointers with CURSOR_* prefixes described in the article on Gui class functions.

int getMouseX ( ) #

Returns the X coordinate of the mouse pointer position on the screen.

Return value

X coordinate of the mouse pointer position.

int getMouseY ( ) #

Returns the Y coordinate of the mouse pointer position on the screen.

Return value

Y coordinate of the mouse pointer position.

void setNextFocus ( const Ptr<Widget> & focus ) #

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

Arguments

  • const Ptr<Widget> & focus - Next widget.

Ptr<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 child widgets.

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 Gui::addChild() function with the Gui::ALIGN_OVERLAP flag specified (hould not be Gui::ALIGN_FIXED).
Source code (C++)
Unigine::Vector<Unigine::WidgetSpritePtr> sprites;

int AppWorldLogic::init()
{
	// create 3 squares with different colors
	for (int i = 0; i < 3; i++)
	{
		WidgetSpritePtr &sprite = sprites.append();
		sprite = WidgetSprite::create(Gui::get(), "white.dds");
		sprite->setPosition(i * 40 + 50, i * 40 + 50);
		sprite->setWidth(100);
		sprite->setHeight(100);
		Gui::get()->addChild(sprite->getWidget(), Gui::ALIGN_OVERLAP);
	}

	sprites[0]->setColor(vec4(1, 0.3f, 0.3f, 1));
	sprites[1]->setColor(vec4(0.3f, 1, 0.3f, 1));
	sprites[2]->setColor(vec4(0.3f, 0.3f, 1, 1));

	return 1;
}

int AppWorldLogic::update()
{
	// press space key to random reorder squares
	if (App::get()->clearKeyState(' '))
	{
		for (int i = 0; i < 3; i++)
		{
			sprites[i]->setOrder(Game::get()->getRandomInt(0, 10));
			
			Gui::get()->removeChild(sprites[i]->getWidget());
			Gui::get()->addChild(sprites[i]->getWidget());

			Log::message("%d ", sprites[i]->getOrder());
		}
		Log::message("\n");
	}
	return 1;
}

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

int isOwner ( ) #

Returns the owner flag. If the pointer is the owner, on its deletion the widget also will be deleted. Use grab() and release() functions to change ownership.

Return value

1 if the pointer is the owner; otherwise, 0.

void setParent ( const Ptr<Widget> & parent ) #

Sets a parent widget for the current one.

Arguments

  • const Ptr<Widget> & parent - Parent widget to set.

Ptr<Widget> getParent ( ) #

Returns the pointer to the parent widget.

Return value

Parent widget smart pointer.

Ptr<Gui> getParentGui ( ) #

Returns the parent Gui smart pointer.

Return value

Parent Gui smart pointer.

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

Return value

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 ( const char * str, int reset = 0 ) #

Sets a tooltip used for the widget.

Arguments

  • const char * str - Tooltip text.
  • int reset - 1 to recalculate a tooltip position under the mouse cursor; otherwise, 0 (by default).

const char * getToolTip ( ) #

Returns the widget tooltip text.

Return value

Tooltip text.

int getType ( ) #

Returns a type of the widget.

Return value

Widget type identifier.

const char * getTypeName ( ) #

Returns a name of the widget type.

Return value

Widget type name.

Ptr<Widget> getWidget ( ) #

Returns a widget pointer.

Return value

Widget pointer.

void setWidth ( int width ) #

Sets minimal width of the widget in pixels.

Arguments

  • int width - Widget minimal width. If a negative value is provided, the 0 will be used instead.

int getWidth ( ) #

Returns the current widget width in pixels.

Return value

Widget width in pixels.

void addAttach ( const Ptr<Widget> & w, const char * 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

  • const Ptr<Widget> & w - Widget to attach.
  • const char * format - Format string or 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 - Attachment flags: one of the Gui:: Enumeration with ATTACH_* prefixes. This is an optional parameter.

void addChild ( const Ptr<Widget> & w, int flags = 0 ) #

Adds a child to the widget.

Arguments

  • const Ptr<Widget> & w - Widget smart pointer.
  • int flags - Widget flags: one of the Gui:: Enumeration with ALIGN_* prefixes. This is an optional parameter.

void arrange ( ) #

Rearranges the widget size.

void grab ( ) #

Sets the owner flag to 1 for the widget pointer. The widget should not be handled by the class after this function is called

void raise ( const Ptr<Widget> & w ) #

Brings a given widget to the top.
Notice
Works only for widgets added to GUI via the Gui::addChild() function with the Gui::ALIGN_OVERLAP flag specified (hould not be Gui::ALIGN_FIXED).

Arguments

  • const Ptr<Widget> & w - Widget to be brought up.

void release ( ) #

Releases the Widget (sets the owner flag to 0 for the pointer). The Widget should be handled by the class after this function is called

void removeAttach ( const Ptr<Widget> & w ) #

Detaches a given widget from the current one.

Arguments

  • const Ptr<Widget> & w - Widget to detach.

void removeChild ( const Ptr<Widget> & w ) #

Removes a child widget from the list of children of the current widget.

Arguments

  • const Ptr<Widget> & w - Child widget smart pointer.

void removeFocus ( ) #

Removes focus from the widget.

void replaceChild ( const Ptr<Widget> & w, const Ptr<Widget> & old_w, int flags = 0 ) #

Replaces a child widget from the list of children with another one.

Arguments

  • const Ptr<Widget> & w - New child widget smart pointer.
  • const Ptr<Widget> & old_w - Child widget to replace.
  • int flags - Widget flags: one of the Gui:: Enumeration with ALIGN_* prefixes. This is an optional parameter.

void runCallback ( int callback ) #

Runs a given callback function.

Arguments

  • int callback - Callback number: one of the Gui:: Enumeration (for example, SHOW, HIDE, etc).
Last update: 2019-11-28