Unigine::UserInterface Class

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;

void on_group_remove()
{
	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->addCallback(Gui::REMOVE, MakeCallback(on_group_remove));
	WindowManager::getMainWindow()->addChild(main_group, Gui::ALIGN_EXPAND);

	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 callback is fired, and the message from the remove callback (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;

EngineWindowViewportPtr window;

UserInterfacePtr ui;
WidgetGroupBoxPtr main_group;

bool group_remove_callback = false;

void on_window_group_remove()
{
	Log::message("window group removed\n");
	group_remove_callback = 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->addCallback(Gui::REMOVE, MakeCallback(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 callback %d\n",
		window.isDeleted(), main_group.isDeleted(), ui.isDeleted(), group_remove_callback);
	

	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 callback is fired, and the message from the remove callback (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;

EngineWindowViewportPtr engine_window;

UserInterfacePtr engine_ui;
WidgetGroupBoxPtr engine_main_group;

bool engine_group_remove_callback = false;

void on_engine_group_remove()
{
	Log::message("engine group removed\n");
	engine_group_remove_callback = 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->addCallback(Gui::REMOVE, MakeCallback(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 callback %d\n",
		engine_window.isDeleted(), engine_main_group.isDeleted(), engine_ui.isDeleted(), engine_group_remove_callback);

	return 1;
}

Методы:

Имя	Описание View: Sort by:
*create*	UserInterface constructor.
getNumWidgets	Returns the number of associated widgets.
setLifetime	Sets the lifetime management type for the UserInterface.
getLifetime	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).
getCallback	Returns the number of a given callback function.
addCallback	Adds a callback function of the specified type for the widget with the specified name.
removeCallback	Removes the specified callback from the list of callbacks of the specified type added for the widget with the given name.
clearCallbacks	Clears all callbacks of the specified type added for the widget with the given name.
getCallbackInstanceData	Returns the callback instance data.
getCallbackName	Returns the name of a given callback function.
getCallbackStringData	Returns the callback string data.
getCallbackVariableData	Returns the callback variable data.
getCallbackWidgetData	Returns the callback widget data.
getNumCallbacks	Returns the total number of callbacks for a given widget.
getWidget	Returns pointer to the widget with a given number.
getWidgetExport	Returns a value indicating if a given widget is exported into a script.
getWidgetName	Returns widget name by its number.
getWidgetNext	Returns the name of the widget, which will be focused next.
findWidget	Searches a widget by its name.
updateWidgets	Updates all widgets belonging to the user interface.
setGui	Sets a new Gui instance to be used for the UserInterface.
getGui	Returns a Gui instance for the UserInterface.

UserInterface Class

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.

void * addCallback ( const char * name, Gui::CALLBACK_INDEX callback, Unigine::CallbackBase * func ) #

Adds a callback function of the specified type for the widget with the specified name.The signature of the callback function must be as follows:

Source code (C++)

void callback_function_name();

Arguments

const char * name - Widget name.
Gui::CALLBACK_INDEX 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 ( const char * name, Gui::CALLBACK_INDEX callback, Unigine::CallbackBase1< Ptr<Widget> > * func ) #

Adds a callback function of the specified type for the widget with the specified name.The signature of the callback function must be as follows:

Source code (C++)

void callback_function_name(WidgetPtr widget);

Arguments

const char * name - Widget name.
Gui::CALLBACK_INDEX 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 ( const char * name, Gui::CALLBACK_INDEX callback, Unigine::CallbackBase2< Ptr<Widget>, Ptr<Widget> > * func ) #

Adds a callback function of the specified type for the widget with the specified name.The signature of the callback function must be as follows:

Source code (C++)

void callback_function_name(WidgetPtr widget1, WidgetPtr widget2);

Arguments

const char * name - Widget name.
Gui::CALLBACK_INDEX 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 ( const char * name, Gui::CALLBACK_INDEX callback, Unigine::CallbackBase3< Ptr<Widget>, Ptr<Widget>, int > * func ) #

Adds a callback function of the specified type for the widget with the specified name.The signature of the callback function must be as follows:

Source code (C++)

void callback_function_name(WidgetPtr widget1, WidgetPtr widget2, int arg3);

Arguments

const char * name - Widget name.
Gui::CALLBACK_INDEX 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 ( const char * name, Gui::CALLBACK_INDEX callback, void * id ) #

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

Arguments

const char * name - Widget name.
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 ( const char * name, Gui::CALLBACK_INDEX callback ) #

Clears all callbacks of the specified type added for the widget with the given name.

Arguments

const char * name - Widget name.
Gui::CALLBACK_INDEX callback - Callback type number. One of the callbacks defined in the Gui class (for example, CLICK, SHOW, HIDE, etc).

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 pointer to the widget with a given number.

Arguments

int num - Widget number.

Return value

Pointer to the widget with the given number.

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 lifetime

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

NoticeLifetime 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: 23.06.2023

Помогите сделать статью лучше

Была ли эта статья полезной?

Сообщить о проблеме в этой статье

(или выберите слово/фразу и нажмите Ctrl+Enter

Unigine::UserInterface Class

In This Article:

Usage Examples#

Managing Lifetime by the World#

Managing Lifetime by the Window#

Managing Lifetime by the Engine#

See Also#

Методы:

UserInterface Class

Members

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

Arguments

int getCallback ( int num, int callback ) const#

Arguments

Return value

void * addCallback ( const char * name, Gui::CALLBACK_INDEX callback, Unigine::CallbackBase * func ) #

Arguments

Return value

void * addCallback ( const char * name, Gui::CALLBACK_INDEX callback, Unigine::CallbackBase1< Ptr<Widget> > * func ) #

Arguments

Return value

void * addCallback ( const char * name, Gui::CALLBACK_INDEX callback, Unigine::CallbackBase2< Ptr<Widget>, Ptr<Widget> > * func ) #

Arguments

Return value

void * addCallback ( const char * name, Gui::CALLBACK_INDEX callback, Unigine::CallbackBase3< Ptr<Widget>, Ptr<Widget>, int > * func ) #

Arguments

Return value

bool removeCallback ( const char * name, Gui::CALLBACK_INDEX callback, void * id ) #

Arguments

Return value

void clearCallbacks ( const char * name, Gui::CALLBACK_INDEX callback ) #

Arguments

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

Arguments

Return value

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

Arguments

Return value

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

Arguments

Return value

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

Arguments

Return value

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

Arguments

Return value

int getNumCallbacks ( int num ) const#

Arguments

Return value

int getNumWidgets ( ) const#

Return value

Ptr<Widget> getWidget ( int num ) const#

Arguments

Return value

int getWidgetExport ( int num ) const#

Arguments

Return value

const char * getWidgetName ( int num ) const#

Arguments

Return value

const char * getWidgetNext ( int num ) const#

Arguments

Return value

int findWidget ( const char * name ) const#

Arguments

Return value

void updateWidgets ( ) const#

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

Arguments

Ptr<Gui> getGui ( ) const#

Return value

void setLifetime ( Widget::LIFETIME lifetime ) #

Arguments

Widget::LIFETIME getLifetime ( ) const#