This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Materials and Shaders
Rebuilding the Engine 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
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Unigine::Widget Class

Header: #include <UnigineWidgets.h>

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.

AppWorldLogic.cpp

Source code (C++)
#include "AppWorldLogic.h"
#include <UnigineWidgets.h>

using namespace Unigine;

void on_button_click()
{
	Log::message("world button click\n");
}

int AppWorldLogic::init()
{
	// create a single widget
	WidgetButtonPtr button = WidgetButton::create("BUTTON");
	// add a callback for the button
	button->addCallback(Gui::CLICKED, MakeCallback(on_button_click));
	// add the button to WindowManager
	WindowManager::getMainWindow()->addChild(button);

	// create a hierarchy of widgets
	WidgetHBoxPtr hbox = WidgetHBox::create();
	hbox->setBackground(1);
	hbox->setBackgroundColor(Math::vec4_white);
	WindowManager::getMainWindow()->addChild(hbox, Gui::ALIGN_EXPAND);

	WidgetGroupBoxPtr group = WidgetGroupBox::create();
	group->setBackground(1);
	group->setText("Widgets Hierarchy");
	hbox->addChild(group);

	group->addChild(WidgetLabel::create("hierarchy_label_0"));
	group->addChild(WidgetLabel::create("hierarchy_label_1"));

	return 1;
}

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.

AppWorldLogic.cpp

Source code (C++)
#include "AppWorldLogic.h"
#include <UnigineWidgets.h>

using namespace Unigine;

void on_button_click()
{
	Log::message("world button click\n");
}

void on_button_remove()
{
	Log::message("world button removed\n");
}

void on_hbox_remove()
{
	Log::message("world hbox hierarchy removed\n");
}

int AppWorldLogic::init()
{

	// single world widget
	WidgetButtonPtr button = WidgetButton::create("WORLD_BUTTON");
	button->setLifetime(Widget::LIFETIME_WORLD);
	button->addCallback(Gui::CLICKED, MakeCallback(on_button_click));
	button->addCallback(Gui::REMOVE, MakeCallback(on_button_remove));
	WindowManager::getMainWindow()->addChild(button);

	// world hierarchy
	WidgetHBoxPtr hbox = WidgetHBox::create();
	hbox->setLifetime(Widget::LIFETIME_WORLD);
	hbox->addCallback(Gui::REMOVE, MakeCallback(on_hbox_remove));
	hbox->setBackground(1);
	hbox->setBackgroundColor(Math::vec4_red);
	WindowManager::getMainWindow()->addChild(hbox, Gui::ALIGN_EXPAND);

	WidgetGroupBoxPtr group = WidgetGroupBox::create();
	group->setBackground(1);
	group->setText("World Hierarchy");
	hbox->addChild(group);

	group->addChild(WidgetLabel::create("hierarchy_world_label_0"));
	group->addChild(WidgetLabel::create("hierarchy_world_label_1"));

	return 1;
}
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.

AppSystemLogic.cpp

Source code (C++)
#include "AppSystemLogic.h"
#include <UnigineWidgets.h>

using namespace Unigine;

EngineWindowViewportPtr window;

WidgetButtonPtr button;
WidgetHBoxPtr hbox;

bool button_remove_callback = false;
bool hbox_remove_callback = false;

void on_window_button_click()
{
	Log::message("window button click\n");
}

void on_window_button_remove()
{
	Log::message("window button removed\n");
	button_remove_callback = true;
}

void on_window_hbox_remove()
{
	Log::message("window hbox hierarchy removed\n");
	hbox_remove_callback = true;
}

void create_window()
{

	button_remove_callback = false;
	hbox_remove_callback = false;

	window = EngineWindowViewport::create("Test", 512, 256, EngineWindow::FLAGS_SHOWN);

	// single window widget
	button = WidgetButton::create("WINDOW_BUTTON");
	button->setLifetime(Widget::LIFETIME_WINDOW);
	button->addCallback(Gui::CLICKED, MakeCallback(on_window_button_click));
	button->addCallback(Gui::REMOVE, MakeCallback(on_window_button_remove));
	window->addChild(button);

	// window hierarchy
	hbox = WidgetHBox::create();
	hbox->setLifetime(Widget::LIFETIME_WINDOW);
	hbox->addCallback(Gui::REMOVE, MakeCallback(on_window_hbox_remove));
	hbox->setBackground(1);
	hbox->setBackgroundColor(Math::vec4_red);
	window->addChild(hbox, Gui::ALIGN_EXPAND);

	WidgetGroupBoxPtr group = WidgetGroupBox::create();
	group->setBackground(1);
	group->setText("Window Hierarchy");
	hbox->addChild(group);

	group->addChild(WidgetLabel::create("hierarchy_window_label_0"));
	group->addChild(WidgetLabel::create("hierarchy_window_label_1"));

}

int AppSystemLogic::init()
{	

	create_window();

	return 1;
}

int AppSystemLogic::update()
{

	if (Input::isKeyDown(Input::KEY_T) && window.isDeleted())
		create_window();

	Log::message("window deleted: %d, button deleted: %d, hbox deleted: %d, button remove callback: %d, hbox remove callback: %d\n",
		window.isDeleted(), button.isDeleted(), hbox.isDeleted(), button_remove_callback, hbox_remove_callback);

	return 1;
}
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.

AppSystemLogic.cpp

Source code (C++)
#include "AppSystemLogic.h"
#include <UnigineWidgets.h>

using namespace Unigine;

EngineWindowViewportPtr engine_window;

WidgetButtonPtr engine_button;
WidgetHBoxPtr engine_hbox;

bool engine_button_remove_callback = false;
bool engine_hbox_remove_callback = false;

void on_engine_button_click()
{
	Log::message("engine button click\n");
}

void on_engine_button_remove()
{
	Log::message("engine button removed\n");
	engine_button_remove_callback = true;
}

void on_engine_hbox_remove()
{
	Log::message("engine hbox hierarchy removed\n");
	engine_hbox_remove_callback = true;
}

void create_engine_window()
{

	engine_window = EngineWindowViewport::create("Test", 512, 256, EngineWindow::FLAGS_SHOWN);

	engine_window->addChild(engine_button);
	engine_window->addChild(engine_hbox, Gui::ALIGN_EXPAND);

}

int AppSystemLogic::init()
{	

	engine_button_remove_callback = false;
	engine_hbox_remove_callback = false;

	// single engine widget
	engine_button = WidgetButton::create("ENGINE_BUTTON");
	engine_button->setLifetime(Widget::LIFETIME_ENGINE);
	engine_button->addCallback(Gui::CLICKED, MakeCallback(on_engine_button_click));
	engine_button->addCallback(Gui::REMOVE, MakeCallback(on_engine_button_remove));

	// engine hierarchy
	engine_hbox = WidgetHBox::create();
	engine_hbox->setLifetime(Widget::LIFETIME_ENGINE);
	engine_hbox->addCallback(Gui::REMOVE, MakeCallback(on_engine_hbox_remove));
	engine_hbox->setBackground(1);
	engine_hbox->setBackgroundColor(Math::vec4_red);

	WidgetGroupBoxPtr engine_group = WidgetGroupBox::create();
	engine_group->setBackground(1);
	engine_group->setText("Engine Hierarchy");
	engine_hbox->addChild(engine_group);

	engine_group->addChild(WidgetLabel::create("hierarchy_engine_label_0"));
	engine_group->addChild(WidgetLabel::create("hierarchy_engine_label_1"));

	create_engine_window();

	return 1;
}

int AppSystemLogic::update()
{

	if (Input::isKeyDown(Input::KEY_T) && engine_window.isDeleted())
		create_engine_window();

	Log::message("engine window deleted: %d, engine button deleted: %d, engine hbox deleted: %d, engine button remove callback: %d, engine hbox remove callback: %d\n",
		engine_window.isDeleted(), engine_button.isDeleted(), engine_hbox.isDeleted(), engine_button_remove_callback, engine_hbox_remove_callback);

	return 1;
}

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

Enums

TYPE#

NameDescription
WIDGET_VBOX = 0Vertical box. See also: WidgetVBox.
WIDGET_HBOX = 1Horizontal box. See also: WidgetHBox.
WIDGET_GRID_BOX = 2Grid box. See also: WidgetGridBox.
WIDGET_VPANED = 3Vertical box that allows resizing of its children. See also: WidgetVPaned.
WIDGET_HPANED = 4Horizontal box that allows resizing of its children. See also: WidgetHPaned.
WIDGET_LABEL = 5Text label. See also: WidgetLabel.
WIDGET_BUTTON = 6Simple button. See also: WidgetButton.
WIDGET_EDIT_LINE = 7Text field. See also: WidgetEditline.
WIDGET_EDIT_TEXT = 8Multiline text field. See also: WidgetEdittext.
WIDGET_CHECK_BOX = 9Checkbox. See also: WidgetCheckbox.
WIDGET_COMBO_BOX = 10Combobox. See also: WidgetCombobox.
WIDGET_CANVAS = 11Canvas widget for drawing text, lines and polygons. See also: WidgetCanvas.
WIDGET_GROUP_BOX = 12Group box. See also: WidgetGroupBox.
WIDGET_LIST_BOX = 13List box. See also: WidgetListBox.
WIDGET_TREE_BOX = 14Tree box. See also: WidgetTreeBox.
WIDGET_TAB_BOX = 15Tabbed box. See also: WidgetTabBox.
WIDGET_SCROLL = 16A scrollbar: horizontal or vertical one. See also: WidgetScroll.
WIDGET_SCROLL_BOX = 17Box with scrolling. See also: WidgetScrollBox.
WIDGET_SPACER = 18Spacer: horizontal or vertical one. See also: WidgetSpacer.
WIDGET_SLIDER = 19A slider: horizontal or vertical one. See also: WidgetSlider.
WIDGET_SPIN_BOX = 20Spinbox. See also: WidgetSpinBox.
WIDGET_SPIN_BOX_DOUBLE = 21Spinbox with double values. See also: WidgetSpinBoxDouble.
WIDGET_ICON = 22Icon. See also: WidgetIcon.
WIDGET_SPRITE = 23Sprite. See also: WidgetSprite.
WIDGET_SPRITE_VIDEO = 24Video Sprite. See also: WidgetSpriteVideo.
WIDGET_SPRITE_SHADER = 25Shader Sprite. See also: WidgetSpriteShader.
WIDGET_SPRITE_VIEWPORT = 26Viewport Sprite. See also: WidgetSpriteViewport.
WIDGET_SPRITE_NODE = 27Node Sprite. See also: WidgetSpriteNode.
WIDGET_MENU_BAR = 28Menu bar. See also: WidgetMenuBar.
WIDGET_MENU_BOX = 29Menu. See also: WidgetMenuBox.
WIDGET_WINDOW = 30Window. See also: WidgetWindow.
WIDGET_DIALOG = 31Dialog window. See also: WidgetDialog.
WIDGET_DIALOG_MESSAGE = 32Message Dialog. See also: WidgetDialogMessage.
WIDGET_DIALOG_FILE = 33File Dialog. See also: WidgetDialogFile.
WIDGET_DIALOG_COLOR = 34Color Dialog. See also: WidgetDialogColor.
WIDGET_DIALOG_IMAGE = 35Image Dialog. See also: WidgetDialogImage.
WIDGET_MANIPULATOR = 36Manipulator widget. See also: WidgetManipulator.
WIDGET_MANIPULATOR_TRANSLATOR = 37Translator Manipulator. See also: WidgetManipulatorTranslator.
WIDGET_MANIPULATOR_ROTATOR = 38Rotator Manipulator. See also: WidgetManipulatorRotator.
WIDGET_MANIPULATOR_SCALER = 39Scaler Manipulator. See also: WidgetManipulatorScaler.
WIDGET_EXTERN = 40External widget.
WIDGET_ENGINE = 41Engine-specific widget (manipulator). See also: WidgetManipulator.
WIDGET_HIT_TEST_AREA = 42Hit-Test Area. See also: WidgetHitTestArea.
NUM_WIDGETS = 43Total number of widget types.

LIFETIME#

NameDescription
LIFETIME_WORLD = 0Lifetime of the widget or user interface is managed by the world. The widget/user interface will be deleted automatically on closing the world.
LIFETIME_WINDOW = 1Lifetime of the widget or user interface is managed by the window. The widget/user interface will be deleted automatically on deleting the window.
LIFETIME_ENGINE = 2Lifetime of the widget or user interface is managed by the Engine. The widget/user interface will be deleted automatically on Engine shutdown.
Notice
When using this lifetime management type, the GUI instance can be empty for the widget: it will be assigned automatically when adding the widget to a window. For a user interface, the Gui instance must be set via the setGui() method.
LIFETIME_MANUAL = 3Lifetime of the widget or user interface is managed by the user. The widget/user interface should be deleted manually.
Notice
When using this lifetime management type, the GUI instance can be empty for the widget: it will be assigned automatically when adding the widget to a window. For a user interface, the Gui instance must be set via the setGui() method.

Members


bool isCallback ( int callback ) const#

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 ( Gui::CALLBACK_INDEX 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

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 ( Gui::CALLBACK_INDEX 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);
sender — the widget that caused the callback function to be called, i.e. the one on which the action took place (e.g. a button, that was clicked).

Arguments

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 ( Gui::CALLBACK_INDEX 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);
  • sender — the widget that caused the callback function to be called, i.e. the one on which the action took place (e.g. a button, that was clicked).
  • pointer — this parameter is used to identify a target widget of a Drag-and-Drop operation. You can find an example in the widgets/sprite_03 UnigineScript sample included in the SDK.

Arguments

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 ( Gui::CALLBACK_INDEX 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);
  • sender — the widget that caused the callback function to be called, i.e. the one on which the action took place (e.g. a button, that was clicked).
  • pointer — this parameter is used to identify a target widget of a Drag-and-Drop operation. You can find an example in the widgets/sprite_03 UnigineScript sample included in the SDK.
  • data — this parameter is used for getting mouse or keyboard button state, when a widget is clicked or pressed (callbacks: CLICKED, PRESSED, KEY_PRESSED).

Arguments

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 ( Gui::CALLBACK_INDEX callback, void * id ) #

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

Arguments

  • Gui::CALLBACK_INDEX 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 ( Gui::CALLBACK_INDEX callback ) #

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

Arguments

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

Assigns a hot key combination to a given callback function.

Arguments

  • Gui::CALLBACK_INDEX callback - Callback number: one of the Gui:: Enumeration (for example, SHOW, HIDE, etc).
  • unsigned int key - ASCII key code: one of the Input::KEY_* values.
  • int ctrl - CTRL key modifier.
  • int alt - ALT key modifier.
  • int shift - SHIFT key modifier.

bool getCallbackAccel ( Gui::CALLBACK_INDEX callback, unsigned int & key, int & ctrl, int & alt, int & shift ) const#

Gets the current hot key combination for a given callback function.

Arguments

  • Gui::CALLBACK_INDEX 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 ) const#

Checks if the given key in combination with CTRL, ALT, or/and SHIFT buttons is assigned as a widget callback.

Arguments

  • unsigned int key - ASCII key code: one of the Input::KEY_* values.
  • 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 ( Gui::CALLBACK_INDEX callback, bool enabled ) #

Enables or disables a given callback function.

Arguments

  • Gui::CALLBACK_INDEX callback - Callback number: one of the Gui:: Enumeration (for example, SHOW, HIDE, etc).
  • bool enabled - true to enable the callback, false to disable it.

int isCallbackEnabled ( Gui::CALLBACK_INDEX callback ) const#

Returns a value indicating if a given callback is enabled.

Arguments

Return value

1 if callback is enabled; otherwise, 0.

Ptr<Widget> getChild ( int num ) const#

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

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

Arguments

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

Return value

1 if the widget in question 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 ( ) const#

Returns user data associated with the widget.

Return value

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

void setEnabled ( bool enabled ) #

Enables or disables the widget.

Arguments

  • bool enabled - true to enable the widget, false to disable it.

bool isEnabled ( ) const#

Returns a value indicating if the widget is enabled.

Return value

Returns true if the widget is enabled; otherwise, false.

void setFlags ( int flags ) #

Sets widget flags.

Arguments

  • int flags - flags.

int getFlags ( ) const#

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

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

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

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

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

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

Returns a value 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 color of the widget text does not change; 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 ( ) const#

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

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

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

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

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

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

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 ( bool 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

  • bool hidden - true to hide the widget, false to render it.

bool isHidden ( ) const#

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

true if the widget is hidden; otherwise, false.

bool getIntersection ( int local_pos_x, int local_pos_y ) const#

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

true if the input coordinate is inside the widget; otherwise, false.

Ptr<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 ( bool enabled ) #

Sets a value indicating if intersection detection is enabled for the widget.

Arguments

  • bool enabled - true to enable intersection detection for the widget, false — to disable it.

bool isIntersectionEnabled ( ) const#

Returns a value indicating if intersection detection is enabled for the widget.

Return value

true if intersection detection is enabled for the widget; otherwise, false.

int getKeyActivity ( unsigned int key ) const#

Checks if a given key already has a special purpose for the widget.

Arguments

  • unsigned int key - ASCII key code: one of the Input::KEY_* values.

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 - Mouse pointer. See the list of available pointers with CURSOR_* prefixes in the article on Gui class functions.

int getMouseCursor ( ) const#

Returns the type of mouse pointer displayed over a widget.

Return value

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

int getMouseX ( ) const#

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

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

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

Return value

Next widget.

int getNumChildren ( ) const#

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 Gui::addChild() function with the Gui::ALIGN_OVERLAP flag specified (should 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, 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::clearKeyState(' '))
	{
		for (int i = 0; i < 3; i++)
		{
			sprites[i]->setOrder(Game::getRandomInt(0, 10));
			
			Gui::get()->removeChild(sprites[i]);
			Gui::get()->addChild(sprites[i]);

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

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 ( const Ptr<Widget> & parent ) #

Sets a parent widget for the current one.

Arguments

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

Ptr<Widget> getParent ( ) const#

Returns the pointer to the parent widget.

Return value

Parent widget smart pointer.

Ptr<Gui> getParentGui ( ) const#

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

Returns the X coordinate of the widget position relative to its parent.

Return value

The relative X coordinate.

int getPositionY ( ) const#

Returns the Y coordinate of the widget position relative to its parent.

Return value

Relative Y coordinate.

int getScreenPositionX ( ) const#

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

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 for the widget.

Arguments

  • const char * str - Tooltip text.
  • int reset - 1 to recalculate a tooltip location if the mouse cursor was relocated; otherwise — 0(by default).

const char * getToolTip ( ) const#

Returns the widget's tooltip text.

Return value

Tooltip text.

Widget::TYPE getType ( ) const#

Returns the type of the widget.

Return value

Widget type identifier.

const char * getTypeName ( ) const#

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

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 ( 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 - Child widget.
  • int flags - Widget flags: one of the Gui:: Enumeration with ALIGN_* prefixes. 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 ( 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 (should not be Gui::ALIGN_FIXED).

Arguments

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

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 the widget's children.

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 one child widget with another.

Arguments

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

void runCallback ( int callback ) const#

Runs a given callback function.

Arguments

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

bool isExpanded ( ) const#

Returns a value indicating if the widget is expanded.

Return value

true if the widget is expanded; otherwise, false.

bool isOverlapped ( ) const#

Returns a value indicating if the widget is overlapped.

Return value

true if the widget is overlapped; otherwise, false.

bool isBackground ( ) const#

Returns a value indicating if the widget is a background one.

Return value

true if the widget a background one; otherwise, false.

bool isFixed ( ) const#

Returns a value indicating if the widget is fixed.

Return value

true if the widget is fixed; otherwise, false.

bool isLayout ( ) const#

Returns a value indicating if the widget is of a type that is responsible for the layout.

Return value

true if the widget is a layout; otherwise, false.

Widget::LIFETIME getLifetimeSelf ( ) const#

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 ( Widget::LIFETIME lifetime ) #

Sets the lifetime management type for the widget. By default, the LIFETIME_ENGINE type is used.

Arguments

Widget::LIFETIME getLifetime ( ) const#

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 its root. Thus, lifetime management type set for a child widget that differs from the one set for the root is ignored.

Return value

Lifetime management type.

int getRenderWidth ( ) const#

Returns the widget frame width in pixels.

Return value

The widget frame width in pixels.

int getRenderHeight ( ) const#

Returns the widget frame height in pixels.

Return value

The widget frame height in pixels.

float getDpiScale ( ) const#

Returns the current DPI scale applied to the widget.

Return value

The current DPI scale applied to the widget.

int toRenderSize ( int unit_size ) #

Transforms the unit value to the pixel value.

Arguments

  • int unit_size - Size in units.

Return value

Size in pixels.

int toUnitSize ( int render_size ) #

Transforms the pixel value to the unit value.

Arguments

  • int render_size - Size in pixels.

Return value

Size in units.

Math::ivec2 toRenderSize ( const Math::ivec2 & unit_size ) #

Transforms the unit value to the pixel value.

Arguments

  • const Math::ivec2 & unit_size - Size in units.

Return value

Size in pixels.

Math::ivec2 toUnitSize ( const Math::ivec2 & render_size ) #

Transforms the pixel value to the unit value.

Arguments

  • const Math::ivec2 & render_size - Size in pixels.

Return value

Size in units.
Last update: 2023-06-23
Build: ()