This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Basics
Rendering
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
Animations-Related Classes
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
VR-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials

Unigine::UserInterface Class

Header: #include <UnigineUserInterface.h>

The class is used to work with widgets that are created by loading a UI file.

Usage Examples#

The examples below show:

  • Loading a UserInterface from the *.ui file and accessing the widgets it stores.
  • Adding callbacks to these widgets.
  • Managing the UserInterface lifetime.

Managing Lifetime by the World#

The UserInterface is created on loading the world. When you reload or exit the world, or close the Engine window, the UserInterface is deleted.

AppWorldLogic.cpp

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

#include <UnigineUserInterface.h>

using namespace Unigine;

// EventConnections class instance to manage event subscriptions
EventConnections econn;

void on_group_remove(const WidgetPtr &group)
{
	Log::message("world group removed\n");
}

int AppWorldLogic::init()
{

	// world user interface
	UserInterfacePtr ui = UserInterface::create(Gui::getCurrent(), "user_interface.ui");
	ui->setLifetime(Widget::LIFETIME_WORLD);

	auto main_group = checked_ptr_cast<WidgetGroupBox>(ui->getWidget(ui->findWidget("main_group")));
	main_group->setText("World User Interface");
	main_group->getEventRemove().connect(econn, on_group_remove);
	WindowManager::getMainWindow()->addChild(main_group, Gui::ALIGN_EXPAND);

	return 1;
}

int AppWorldLogic::shutdown()
{
	// removing all event subscriptions
	econn.disconnectAll();

	return 1;
}

Managing Lifetime by the Window#

The UserInterface is created in a separate window. When you close the window, the UserInterface is deleted as its lifetime is managed by this window. The console shows whether the window and UserInterface are deleted or not, whether the remove event is fired, and the message from the remove event handler (if it is).

After closing, the window can be re-created by pressing T.

AppSystemLogic.cpp

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

#include <UnigineUserInterface.h>

using namespace Unigine;

// EventConnections class instance to manage event subscriptions
EventConnections econnections;

EngineWindowViewportPtr window;

UserInterfacePtr ui;
WidgetGroupBoxPtr main_group;

bool group_remove_handler = false;

void on_window_group_remove()
{
	Log::message("window group removed\n");
	group_remove_handler = true;
}

void create_window()
{

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

	// window user interface
	ui = UserInterface::create(window->getGui(), "user_interface.ui");
	ui->setLifetime(Widget::LIFETIME_WINDOW);

	main_group = checked_ptr_cast<WidgetGroupBox>(ui->getWidget(engine_ui->findWidget("main_group")));
	main_group->setText("Window User Interface");
	main_group->getEventRemove().connect(econnections, on_window_group_remove);
	window->addChild(main_group, Gui::ALIGN_EXPAND);

}

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, group deleted: %d, ui deleted: %d, group remove handler %d\n",
		window.isDeleted(), main_group.isDeleted(), ui.isDeleted(), group_remove_handler);
	

	return 1;
}

int AppSystemLogic::shutdown()
{
	// removing all event subscriptions
	econnections.disconnectAll();

	return 1;
}

Managing Lifetime by the Engine#

The lifetime of the UserInterface is managed by the Engine, so it is deleted on Engine shutdown. A Gui instance is set manually via the setGui() method.

The console shows whether the window and UserInterface are deleted or not, whether the remove event is fired, and the message from the remove event handler (if it is). After closing, the window can be re-created by pressing T.

AppSystemLogic.cpp

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

#include <UnigineUserInterface.h>

using namespace Unigine;

// EventConnections class instance to manage event subscriptions
EventConnections econnections;

EngineWindowViewportPtr engine_window;

UserInterfacePtr engine_ui;
WidgetGroupBoxPtr engine_main_group;

bool engine_group_remove_handler = false;

void on_engine_group_remove(const WidgetPtr &group)
{
	Log::message("engine group removed\n");
	engine_group_remove_handler = true;
}

void create_engine_window()
{

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

	engine_ui->setGui(engine_window->getGui());
	engine_window->addChild(engine_main_group, Gui::ALIGN_EXPAND);

}

int AppSystemLogic::init()
{

	// engine user interface
	engine_ui = UserInterface::create(Gui::getCurrent(), "user_interface.ui");
	engine_ui->setLifetime(Widget::LIFETIME_ENGINE);

	engine_main_group = checked_ptr_cast<WidgetGroupBox>(engine_ui->getWidget(ui->findWidget("main_group")));
	engine_main_group->setText("Engine User Interface");
	engine_main_group->getEventRemove().connect(econnections, on_engine_group_remove);

	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 group deleted: %d, engine ui deleted: %d, engine group remove handler %d\n",
		engine_window.isDeleted(), engine_main_group.isDeleted(), engine_ui.isDeleted(), engine_group_remove_handler);

	return 1;
}

int AppSystemLogic::shutdown()
{
	// removing all event subscriptions
	econnections.disconnectAll();

	return 1;
}

See Also#

  • C++ API sample <UnigineSDK>/source/samples/Api/Widgets/UserInterface
  • C# API sample <UnigineSDK>/source/csharp/samples/Api/Widgets/UserInterface

UserInterface Class

Enums

EVENT_TYPE#

NameDescription
EVENT_SHOW = 0
EVENT_HIDE = 1
EVENT_FOCUS_IN = 2
EVENT_FOCUS_OUT = 3
EVENT_CHANGED = 4
EVENT_CLICKED = 5
EVENT_DOUBLE_CLICKED = 6
EVENT_PRESSED = 7
EVENT_RELEASED = 8
EVENT_KEY_PRESSED = 9
EVENT_TEXT_PRESSED = 10
EVENT_ENTER = 11
EVENT_LEAVE = 12
EVENT_DRAG_MOVE = 13
EVENT_DRAG_DROP = 14
EVENT_REMOVE = 15
NUM_EVENTS = 16

Members


static UserInterfacePtr create ( const Ptr<Gui> & gui, const char * name, const char * prefix = 0 ) #

UserInterface constructor.

Arguments

  • const Ptr<Gui> & gui - GUI smart pointer.
  • const char * name - User interface name.
  • const char * prefix - Names prefix.

int getCallback ( int num, int callback ) const#

Returns the number of a given callback function.

Arguments

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

Return value

Callback number.

const char * getCallbackInstanceData ( int num, Gui::CALLBACK_INDEX callback ) const#

Returns the callback instance data.

Arguments

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

Return value

Callback instance data.

const char * getCallbackName ( int num, Gui::CALLBACK_INDEX callback ) const#

Returns the name of a given callback function.

Arguments

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

Return value

Callback function name.

const char * getCallbackStringData ( int num, Gui::CALLBACK_INDEX callback ) const#

Returns the callback string data.

Arguments

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

Return value

Callback string data.

const char * getCallbackVariableData ( int num, Gui::CALLBACK_INDEX callback ) const#

Returns the callback variable data.

Arguments

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

Return value

Callback variable data.

Ptr<Widget> getCallbackWidgetData ( int num, Gui::CALLBACK_INDEX callback ) const#

Returns the callback widget data.

Arguments

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

Return value

Widget data.

int getNumCallbacks ( int num ) const#

Returns the total number of callbacks for a given widget.

Arguments

  • int num - Widget number.

Return value

Number of callbacks.

int getNumWidgets ( ) const#

Returns the number of associated widgets.

Return value

Number of associated widgets.

Ptr<Widget> getWidget ( int num ) const#

Returns a widget with the given ID.

Arguments

  • int num - Widget number.

Return value

Pointer to the widget with the given number.

Ptr<Widget> getWidgetByName ( const char * name ) const#

Returns a widget with the given name.

Arguments

  • const char * name - Widget name.

Return value

Widget with the given ID.

int getWidgetExport ( int num ) const#

Returns a value indicating if a given widget is exported into a script.

Arguments

  • int num - Widget number.

Return value

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

const char * getWidgetName ( int num ) const#

Returns widget name by its number.

Arguments

  • int num - Widget number.

Return value

Widget name.

const char * getWidgetNext ( int num ) const#

Returns the name of the widget, which will be focused next.

Arguments

  • int num - Current widget number.

Return value

Next Widget name.

int findWidget ( const char * name ) const#

Searches a widget by its name.

Arguments

  • const char * name - Widget name.

Return value

Returns the number of the widget if exists; otherwise, -1.

void updateWidgets ( ) const#

Updates all widgets belonging to the user interface. This function should be called, for example, after change of the interface language.

void setGui ( const Ptr<Gui> & gui ) #

Sets a new Gui instance to be used for the UserInterface.

Arguments

  • const Ptr<Gui> & gui - Gui instance to be used for the UserInterface.

Ptr<Gui> getGui ( ) const#

Returns a Gui instance for the UserInterface.

Return value

Gui instance currently used for the UserInterface.

void setLifetime ( Widget::LIFETIME lifetime ) #

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

Arguments

Widget::LIFETIME getLifetime ( ) const#

Returns the lifetime management type for the root of the UserInterface, or for the UserInterface itself (if it is not a child for another UserInterface).
Notice
Lifetime of each UserInterface in the hierarchy is defined by it's root. Thus, lifetime management type set for a child UserInterface that differs from the one set for the root is ignored.
Last update: 2024-08-01
Build: ()