Unigine.UserInterface Class
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.
WidgetLifetimeWorld.cs
Source code (C#)
void on_group_remove()
{
Log.Message("world group removed\n");
}
private void Init()
{
// world user interface
UserInterface ui = new UserInterface(Gui.GetCurrent(), "user_interface.ui");
ui.Lifetime = Widget.LIFETIME.WORLD;
WidgetGroupBox main_group = (WidgetGroupBox)ui.GetWidget(ui.FindWidget("main_group"));
main_group.Text = "World User Interface";
main_group.AddCallback(Gui.CALLBACK_INDEX.REMOVE, on_group_remove);
WindowManager.MainWindow.AddChild(main_group, Gui.ALIGN_EXPAND);
}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.
WidgetLifetimeWorld.cs
Source code (C#)
public EngineWindow window;
public UserInterface ui;
public WidgetGroupBox main_group;
bool group_remove_callback = false;
void on_window_group_remove()
{
Log.Message("window group removed\n");
group_remove_callback = true;
}
public void create_window()
{
window = new EngineWindow("Test", 512, 256, (int)EngineWindow.FLAGS.SHOWN);
// window user interface
ui = new UserInterface(window.Gui, "user_interface.ui");
ui.Lifetime = Widget.LIFETIME.WINDOW;
main_group = (WidgetGroupBox)ui.GetWidget(ui.FindWidget("main_group"));
main_group.Text = "Window User Interface";
main_group.AddCallback(Gui.CALLBACK_INDEX.REMOVE, on_window_group_remove);
window.AddChild(main_group, Gui.ALIGN_EXPAND);
}
private void Init()
{
create_window();
}
private void Update()
{
if (Input.IsKeyDown(Input.KEY.T) && window.IsDeleted)
create_window();
Log.Message("window deleted: {0}, group deleted: {1}, ui deleted: {2}, group remove callback {3}\n",
window.IsDeleted, main_group.IsDeleted, ui.IsDeleted, group_remove_callback);
}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.
WidgetLifetimeEngine.cs
Source code (C#)
EngineWindow engine_window;
UserInterface engine_ui;
WidgetGroupBox 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 = new EngineWindow("Test", 512, 256, (int)EngineWindow.FLAGS.SHOWN);
engine_ui.Gui = engine_window.Gui;
engine_window.AddChild(engine_main_group, Gui.ALIGN_EXPAND);
}
private void Init()
{
// engine user interface
engine_ui = new UserInterface(Gui.Current, "user_interface.ui");
engine_ui.Lifetime = Widget.LIFETIME.ENGINE;
engine_main_group = (WidgetGroupBox)engine_ui.GetWidget(engine_ui.FindWidget("main_group"));
engine_main_group.Text = "Engine User Interface";
engine_main_group.AddCallback(Gui.CALLBACK_INDEX.REMOVE, on_engine_group_remove);
create_engine_window();
}
private void Update()
{
if (Input.IsKeyDown(Input.KEY.T) && engine_window.IsDeleted)
create_engine_window();
Log.Message("engine window deleted: {0},engine group deleted: {1}, engine ui deleted: {2}, engine group remove callback {3}\n",
engine_window.IsDeleted, engine_main_group.IsDeleted, engine_ui.IsDeleted, engine_group_remove_callback);
}See Also#
- C++ API sample <UnigineSDK>/source/samples/Api/Widgets/UserInterface
- C# API sample <UnigineSDK>/source/csharp/samples/Api/Widgets/UserInterface
UserInterface Class
Properties
int NumWidgets#
The number of associated widgets.
Gui Gui#
The Gui instance currently used for the UserInterface.
Widget.LIFETIME Lifetime#
The
Members
UserInterface ( Gui gui, string name, string prefix = 0 ) #
UserInterface constructor.Arguments
- Gui gui - GUI smart pointer.
- string name - User interface name.
- string prefix - Names prefix.
int GetCallback ( int num, int callback ) #
Returns the number of a given callback function.Arguments
- int num - Widget number.
- int callback
Return value
Callback number.IntPtr addCallback ( string name, Gui.CALLBACK_INDEX callback, Callback0Delegate 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
- string name - Widget name.
- Gui.CALLBACK_INDEX callback
- Callback0Delegate func - Callback function with the following signature: void Callback0Delegate()
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.IntPtr addCallback ( string name, Gui.CALLBACK_INDEX callback, Callback1Delegate 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(Widget widget);Arguments
- string name - Widget name.
- Gui.CALLBACK_INDEX callback
- Callback1Delegate func - Callback function with the following signature: void Callback1Delegate(Widget widget)
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.IntPtr addCallback ( string name, Gui.CALLBACK_INDEX callback, Call2backDelegate 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(Widget widget1, Widget widget2);Arguments
- string name - Widget name.
- Gui.CALLBACK_INDEX callback
- Call2backDelegate func - Callback function with the following signature: void Callback2Delegate(Widget widget1, Widget widget2)
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.IntPtr addCallback ( string name, Gui.CALLBACK_INDEX callback, Callback3Delegate 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(Widget widget1, Widget widget2, int arg3);Arguments
- string name - Widget name.
- Gui.CALLBACK_INDEX callback
- Callback3Delegate func - Callback function with the following signature: void Callback3Delegate(Widget widget1, Widget widget2, int arg3)
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 ( string name, Gui.CALLBACK_INDEX callback, IntPtr id ) #
Removes the specified callback from the list of callbacks of the specified type added for the widget with the given name.Arguments
- string name - Widget name.
- Gui.CALLBACK_INDEX callback
- IntPtr id - Callback ID obtained when adding it.
Return value
True if the callback with the given ID was removed successfully; otherwise false.void clearCallbacks ( string name, Gui.CALLBACK_INDEX callback ) #
Clears all callbacks of the specified type added for the widget with the given name.Arguments
- string name - Widget name.
- Gui.CALLBACK_INDEX callback
string GetCallbackInstanceData ( int num, Gui.CALLBACK_INDEX callback ) #
Returns the callback instance data.Arguments
- int num - Widget number.
- Gui.CALLBACK_INDEX callback
Return value
Callback instance data.string GetCallbackName ( int num, Gui.CALLBACK_INDEX callback ) #
Returns the name of a given callback function.Arguments
- int num - Widget number.
- Gui.CALLBACK_INDEX callback
Return value
Callback function name.string GetCallbackStringData ( int num, Gui.CALLBACK_INDEX callback ) #
Returns the callback string data.Arguments
- int num - Widget number.
- Gui.CALLBACK_INDEX callback
Return value
Callback string data.string GetCallbackVariableData ( int num, Gui.CALLBACK_INDEX callback ) #
Returns the callback variable data.Arguments
- int num - Widget number.
- Gui.CALLBACK_INDEX callback
Return value
Callback variable data.Widget GetCallbackWidgetData ( int num, Gui.CALLBACK_INDEX callback ) #
Returns the callback widget data.Arguments
- int num - Widget number.
- Gui.CALLBACK_INDEX callback
Return value
Widget data.int GetNumCallbacks ( int num ) #
Returns the total number of callbacks for a given widget.Arguments
- int num - Widget number.
Return value
Number of callbacks.Widget GetWidget ( int num ) #
Returns pointer to the widget with a given number.Arguments
- int num - Widget ID.
Return value
Pointer to the widget with the given number.int GetWidgetExport ( int num ) #
Returns a value indicating if a given widget is exported into a script.Arguments
- int num - Widget ID.
Return value
Returns 1 if the widget is exported; otherwise, 0.string GetWidgetName ( int num ) #
Returns widget name by its number.Arguments
- int num - Widget ID.
Return value
Widget name.string GetWidgetNext ( int num ) #
Returns the name of the widget, which will be focused next.Arguments
- int num - Widget number.
Return value
Next Widget name.int FindWidget ( string name ) #
Searches a widget by its name.Arguments
- string name - Widget name.
Return value
Returns the number of the widget if exists; otherwise, -1.void UpdateWidgets ( ) #
Updates all widgets belonging to the user interface. This function should be called, for example, after change of the interface language.void SetGui ( Gui gui ) #
Sets a new Gui instance to be used for the UserInterface.Arguments
Gui GetGui ( ) #
Returns a Gui instance for the UserInterface.Return value
Gui instance currently used for the UserInterface.Last update:
2022-12-14
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)