Usage Example

This article describes a simple example of how to create Unigine native GUI by using User interface (UI) files.

Use a plain text editor to create a *.ui file that describes the GUI of your project. Then describe all of the required containers, widgets and their layout:

<?xml version="1.0" encoding="utf-8"?>
<ui version="1.0">	
	<window name="window" export="1" width="250" height="150" sizeable="1" enabled="1" space_y="10">
		<text align="left">Language</text>
		<align align="left">
			<label><text>Choose the language:</text></label>
			<checkbox name="radiobutton_0" export="1" checked="1">
				<text>English</text>
			</checkbox>
			<checkbox name="radiobutton_1" export="1">
				<attach>radiobutton_0</attach>
				<text>Chinese</text>
			</checkbox>
		</align>				
		<button>
			<text>Apply</text>
			<callback type="clicked">translation</callback>
		</button>
	</window>
</ui>
				

To set the callback for the widget, simply define callback as a child tag and set the required value for its type parameter. Also the callback function must be defined in the script.

To support several languages in your project, create all of the necessary dictionaries in the project folder. Each dictionary file corresponds to one of supported languages:

• English-English dictionary, which is required to switch from the other language.
  Source code (XML)

  <?xml version="1.0" encoding="utf-8"?>
  <dictionary version="1.00">
  	<msg>
  		<src>Apply</src>
  		<tr>Apply</tr>
  	</msg>
  	<msg>
  		<src>Choose the language</src>
  		<tr>Choose the language</tr>
  	</msg>
  	<msg>
  		<src>Chinese</src>
  		<tr>Chinese</tr>
  	</msg>
  	<msg>
  		<src>English</src>
  		<tr>English</tr>
  	</msg>
  	<msg>
  		<src>Language</src>
  		<tr>Language</tr>
  	</msg>
  </dictionary>				
  					

  You can also create an empty dictionary instead of the English-English dictionary. In this case, if you will load this dictionary via engine.gui.addDictionary(), the text defined in your UI file will be displayed.
  Source code (XML)

  <?xml version="1.0" encoding="utf-8"?>
  <dictionary version="1.00">
  </dictionary>
  					

• English-Chinese dictionary:
  Source code (XML)

  <?xml version="1.0" encoding="utf-8"?>
  <dictionary version="1.00">
  	<msg>
  		<src>Apply</src>
  		<tr>申请</tr>
  	</msg>
  	<msg>
  		<src>Choose the language:</src>
  		<tr>选择语言</tr>
  	</msg>
  	<msg>
  		<src>Chinese</src>
  		<tr>汉语</tr>
  	</msg>
  	<msg>
  		<src>English</src>
  		<tr>English</tr>
  	</msg>
  	<msg>
  		<src>Language</src>
  		<tr>语</tr>
  	</msg>
  </dictionary>
  					

  To be shown correctly, the Chinese font file (for example, font_ch.ttf) should be added to the project folder and loaded when it is necessary.

When the *.ui file is created, the GUI is described and all of the necessary dictionaries and fonts are added to the project, you need to add a script logic.

1. Declare the root widget, its children (if necessary) and User interface as global variables in the script:
   Source code (UnigineScript)

   WidgetWindow window; // root widget
   WidgetComboBox radiobutton_0; // the first radiobutton
   WidgetComboBox radiobutton_1; // the second radiobutton
   UserInterface ui; // user interface
   						

   Notice

   The name of each variable must match the name of the widget defined in the UI file.
2. Load User interface by using the UserInterface() constructor:
   Source code (UnigineScript)

   int init(){
       new UserInterface(engine.getGui(),"my_project/my_project.ui");
   	
   	return 1;
   }
   						

3. Create an object of the GUI class and add the root widget to be rendered in the GUI interface via Gui::addChild():
   Source code (UnigineScript)

   int init(){
       new UserInterface(engine.getGui(),"my_project/my_project.ui");
   	
   	Gui gui = engine.getGui();
   	gui.addChild(window,GUI_ALIGN_CENTER);
   	
   	return 1;
   }
   						

   To set the root widget alignment via scripting, define one of the GUI_ALIGN_* pre-defined variables as the second argument of the addChild() function.
4. Define callback function that loads the chosen dictionary via engine.gui.addDictionary() (if necessary) and applies the language changes via updateWidgets():
   Source code (UnigineScript)

   void translation(){
   	if (radiobutton_0.isChecked()){
   		// load English-English or empty dictionary and set the default font
   		engine.gui.addDictionary("my_project/locale/scrollbox.en"); 
   		engine.gui.setFont("core/gui/font.ttf");
   	}
   	else {
   		// load English-Chinese dictionary
   		engine.gui.addDictionary("my_project/locale/scrollbox.ch");
   		// set the Chinese font for correct characters displaying
   		engine.gui.setFont("my_project/gui/font_ch.ttf"); 
   	}
   	ui.updateWidgets();
   }
   						

The script logic, described in the example, allows switching between English and Chinese:

The first radiobutton was checked.	The second radiobutton was checked.