Documentation/Articles/Overview of User Interface Editor
From NeoAxis 3D Engine Wiki
|Language:||English • Russian||Status:||Approved|
The User Interface Editor is designed to let you create and customize interface elements, such as text boxes, buttons, scrollbars, menus, etc.
In addition to the editor functionnaly description, you will find two tutorials:
NeoAxis has a set of base gui classes for elements of user interfaces:
- ProfilingToolWindow — Window Profiling Tool
You will find the description of each class below.
Each class is based on the Control class and inherits its properties.
The settings of this class are divided in three groups: Background (Background), General (General) and Layout (Layout).
|BackColor||BackColor. Additional color that is multiplied with texture color. If this parameter is set to "0 0 0 0", texture color is not changed. If you want to change texture color, remember to change the last value (alpha) to > 0.|
|BackTextureCoord||BackTextureCoord. Defines texture offset. Values are in the range of 0 to 1. Values are set in texture proportion.|
|BackTextureFiltering||Turns on or off back texture filtering. You can choose between Point (Point) and Linear (Linear) filtering.|
|BackTextureTile||Turns on or off back texture tiling.|
|ColorMultiplier||The control's color. Here you can change the control's color, including any text color if needed. Use color multiplier for mixing.|
|CopyTextFromParent||Turns on or off copy text from parent. If this parameter is set to True you will have the same text on all textboxes that belong to this control. If this parameter is set to False, you can use a different text.|
|Enable||Enable/Disable. If this parameter is set to False, this control will be in disabled state and will not take any input.|
|MouseCover||Turns on or off mouse cover. If this parameter is turned on mouse input don't reach the objects that are below the active window.|
|Name||Here you can assign a unique name for your control.|
|Text||Text, which appears on the control (if it has a textbox).|
|TopMost||Turns on or off to most for the control. If this parameter is set to True, this control will always stay on top.|
|Visible||Visiblity. If this parameter is set to False, the control will be invisible.|
|Anchor||Anchor. Allows to bind this component to adjacent components. You can select one or several positions for the anchor. You can as well leave the control without anchor.|
|HorizontalAlign||Sets the horizontal alignment. You can align to (Left), (Center) or (Right).|
|LockEditorResizing||Lock / unlock editor resizing. If this parameter is set to True, resizing will be locked and you will not be able to change the size of this component.|
|Position||Position. Allows to set the position of the component. Reference points can be set proportionally (from 0 to 1) to the (Parent) element or the (Screen), proportionally to screen resolution (ScreenByResolution). Reference points can also be set in absolute terms by choosing Pixel. Position setting is described more in depth in this article.|
|Size||Size. Allows to resize the component. Reference points can be set proportionally (from 0 to 1) to the (Parent) element or the (Screen), proportionally to screen resolution (ScreenByResolution). Reference points can also be set in absolute terms by choosing Pixel. Position setting is described more in depth in this article.|
|VerticalAlign||Sets the vertical alignment. You can align to (Top), (Center) or (Bottom).|
Button can have five different states:
- Default Control
- Over Control
- Push Control
- Active Control
- Disable Control
You can assign a control to each of these states (such as a TextBox so the button has text displayed). Usually, a TextBox is assigned to a control, which indicates the background and text of the button.
Here are the specific properties of the Button.
|Active||Turns on or off Active state of the button. If this parameter is set to True, the button will be in Active state permanently.|
|ClickMask||Mask the clickable area of the button (hit area). Here you can load a black and white mask that defines the clickable area of the button. This is used for nonsquare buttons.|
|ClickMaskTextureCoord||Texture coordinates of the mask clickable area.|
|SoundClick||Allows you to assign a sound that is played when the button is clicked.|
|SoundMouseOut||Allows you to assign a sound that is played when the mouse cursor leaves the button area (leaves the hit area).|
|SoundMouseOver||Allows you to assign a sound that is played when the mouse cursor enters the button area (enters the hit area).|
CheckBox works almost like a button but allows you to assign two different looks for each state (CheckBox checked and unchecked) and switch back and forth by mouse click. Each state represents a button with its own button-specific properties.
Find CheckBox specific properties in CheckBox.
|Checked||Check or uncheck the CheckBox. If this parameter is set to True, the CheckBox will be checked by default.|
ComboBox is a button that can be expanded to a list, from which you can select a value.
Here are the ComboBox specific properties.
|TextIfNoSelection||Text, which is displayed, if the value is not selected in the ComboBox.|
EditBox allows you to input a text during run-time. For example, in the application, the user can enter his name in the edit box.
Here are the EditBox specific properties.
|MaxCharacterCount||Defines the maximum number of characters that the EditBox can accept.|
A ListBox holds a number of values, and one of them can be selected. Contrary to ComboBox, in a ListBox, the values are visible all the time.
Here are the specific properties of a ListBox.
|AlwaysShowScrollBar||Turns on or off "always show" for the scrollbar. If this parameter is set to True, the scrollbar will always be shown. If this parameter is set to False, the scrollbar will be shown only when all the elements doesn't fit into the ListBox.|
|ClipRectangleBorders||Clip rectangle borders. Allows you to clip text at the borders of the list box. Reference points can be set proportionally (from 0 to 1) to (Parent) element or (Screen), proportionally to the resolution (ScreenByResolution). Clip can also be set in absolute terms, for this choose Pixel.|
|HideSelectionWhenDisabled||Hide or unhide selection, when the element is disabled. If this parameter is set to True, the selection is disabled when the element is disabled.|
|SelectedIndex||Selected index. Defines which value is selected by default. First value is numbered 0.|
ProfilingToolWindow doesn't have any specific properties to set.
SceneBox is an interface element which displays a three-dimensional scene. A SceneBox can consist of the following objects:
Specific properties of the SceneBox are divided into the following categories: Camera, Objects, RenderTarget and RenderingOptions.
|CameraFixedUp||Vector, which indicates FixedUp direction of the camera.|
|CameraFov||Camera field of view in degrees.|
|CameraLookAt||Point, at which the camera looks.|
|CameraNearFarClipDistance||A pair of values which determines the distance to the nearest and furthest clip area. Objects, situated close to the nearest or behind the furthest clip area, are not drawn.|
|CameraPosition||Camera position in space.|
|Objects||SceneBox objects. You can find detailed discription of SceneBox objects porperties below.|
|ShowMainSceneObjects||Turns on or off display of main scene objects.|
|AllowFXAACompositor||Turns on or off the FXAA effect.|
|AllowHDRCompositor||Turns on or off the HDR effect.|
|AutoMipmaps||Turns on or off the use of mipmaps for textures.|
|AutoUpdate||Turns on or off auto scene update.|
|DetectResolutionOnScreen||Turns on or off auto resolution detection of texture, in order to display it on screen with pixel by pixel accuracy.|
|Resolution||Texture scene resolution in pixel.|
|UseHDRTexture||Turns on or off the use of HDR texture.|
|AmbientLight||Ambient light color.|
|MaterialScheme||Material scheme during scene rendering.|
|ShadowsEnabled||Turns on or off the shadows.|
Scene object properties
Scene objects have two common groups of properties: General and Transform.
|Visible||Enable/Disable the display of the object. If it's set to True, the object will be visible.|
|Position||Object position on the map.|
|Rotation||Object rotation. Rotation angles are given in degrees.|
Special properties of SceneBoxMesh.
|CastDynamicShadows||Enable/Disable shadow casting for the 3D model.|
|MeshName||Mesh file name.|
|OverrideMaterial||Define material. If a material is selected, it's applied to the mesh. If the field is blank, the mesh's materials are used.|
Special properties of SceneBoxParticle (particle system).
|ParticleName||Particle system file name.|
Special properties of SceneBoxLight (light source).
|AttenuationFar||Light source maximal distance. Can only be used for Spot and Point light sources.|
|AttenuationNear||The maximal distance at which the light will have it's maximum value. Then it will start to fade out. Can only be used for Spot and Point light sources.|
|AttenuationPower||Source fading force. Can only be used for Spot and Point light sources.|
|CastShadows||Enable/Disable source shadows casting.|
|CustomShaderParameter||A special parameter for creators which allows to pass a target value to the shader.|
|DiffuseColor||Light source diffuse color.|
|DiffusePower||Source brightness multiplier.|
|FFPAttenuationConstant||Constant fading coefficient used during rendering on fixed pipeline mode (for very old video cards).|
|FFPAttenuationLinear||linear fading coefficient used during rendering on fixed pipeline mode (for very old video cards).|
|FFPAttenuationQuadric||squared fading coefficient used during rendering on fixed pipeline mode (for very old video cards).|
|LightType||Light source types. Three types of light source can be used: spotlight (Spot), point light (Point), directional light source (Directional).|
|SpecularColor||Light source specular color.|
|SpecularPower||Specular brightness multiplier.|
|SpotlightFalloff||Light fading coefficient from inner to outer cone. The higher the value is, the more gradual the fading will be. This parameter can only be used for Spot sources.|
|SpotlightInnerAngle||Inner cone angle. This parameter determines the degree of light concentration near the center. The difference will be noticiable only when SpotlightFalloff parameter is set higher than the minimal value. This parameter can only be used for Spot sources.|
|SpotlightOuterAngle||Outer cone angle. This parameter can only be used for Spot sources.|
SceneBoxHelper type (auxiliary object) doesn't have any special properties.
Has a slider (button) which is used to set the control's current value. Value is a number from the defined value range. ScrollBar can be used to scroll text that doesn't fit its window or to adjust sound volume.
Find ScrollBar specific properties in Scroll Bar:
|Value||Starting value of the scrollbar. It depends on what values are defined in ValueRange field.|
|ValueRange||Defines the minimum and maximum value that the scrollbar can have.|
|Vertical||Turns on or off vertical and horizontal type of scrollbar. Set this parameter to True for vertical type and set to False vor horizontal.|
TabControl allows control over multiple tabs. Usually buttons are used for switching between them. In one TabControl it is possible to use up to 20 pages. Each page, in its turn, can contain all types of controls.
Find specific properties of TabControl in: Tab Control:
|PageButtonsOffset||Sets the offset for buttons placed on this control. Reference points can be set in proportion (from 0 to 1) in relation to (Parent) element or (Screen), in proportion to resolution (ScreenByResolution). As well page buttons offset can be set in absolute terms, for this choose Pixel.|
|PageButtonsPosition||Sets the buttons position on this control. Reference points can be set in proportion (from 0 to 1) in relation to (Parent) element or (Screen), in proportion to resolution (ScreenByResolution). As well page buttons position can be set in absolute terms, for this choose Pixel.|
|SelectedIndex||Sets which tab is selected by default. First value of selected index is numbered 0.|
Textbox can hold a single or multiline text with optional wrapping.
TextBox specific properties are divided into following categories: Text Box, Text Shadow, Word Wrap:
|AutoSize||Enable/Disable element size automatic determination. If set to True the textbox will only be as big as the text inside it.|
|ClipRectangle||This property allows to cut off the element sides during rendering.|
|Font||Select a font that will be used in this textbox. You can only choose from precompiled fonts. Refer to Overview of Font Definition Editor for instructions.|
|SupportLocalization||Enable/Disable localization assistance. If set to True you will be able to replace the text in this textbox with a translation in another language.|
|TextHorizontalAlign||Text horizontal alignment. Here you can set the horizontal alignment of text in the textbox. Choose from Left, Center or Right.|
|TextOffset||Text offset. Can be set in different values: Parent(owner element proportional), ScreenByResolution (screen resolution proportional), Pixel (in pixels on the screen).|
|TextVerticalAlign||Text vertical alignment. Here you can set the vertical alignment of text in the textbox. Choose from Top (align top), Center (align center) or Bottom (align bottom).|
|Shadow||Enable/Disable text shadow. Set to True if you want your text to have shadow.|
|ShadowColor||Text shadow color.|
|ShadowOffset||Shadow offset. Can be set in different values: Parent(owner element proportional), ScreenByResolution (screen resolution proportional), Pixel (in pixels on the screen).|
|AlignByWidth||Enable/Disable the alignment of the text by width.|
|VerticalTextIndention||Vertical text indentions. Determines spacings between text lines.|
|WordWrap||Enable/Disable words wrap.|
Allows video playback. VideoBox specific properties are located in Video category.
|Filename||Video file name.|
|Loop||Enable/Disable steady playing. If set to True the video will play again after it's finished.|
|Pause||If set to True the videoplayback will be paused.|
SDK Pre-Made Controls
There are many pre-made controls available in /Data/Gui/Controls/ folder. Here are the most important ones:
|File Name||Base class||Description||Screenshot|
|DefaultButton.gui||Button||Button can be pressed and can detect the following states: Default (sometimes called RollOut), Over (or RollOver), Push (or Press), Active, Disable.|
|DefaultCheckBox.gui||CheckBox||CheckBox works a bit like a button, but can also have two appearances - checked and unchecked. It will switch from one to the other after it is pressed.|
|DefaultCheckedListBox.gui||CheckBox list||Array of checkboxes that allow multiple selection.|
|DefaultComboBox.gui||ComboBox||ComboBox — is list that expands upon being clicked. Then a value from the list can be selected.|
|DefaultEditBox.gui||EditBox||A place for entering text. Holds one line of text and will not wrap it.|
|DefaultEditBox_WordWrap.gui||EditBox||This control can hold a multiline text and wraps it automatically.|
|DefaultHScrollBar.gui||ScrollBar||A slider that allows you to scroll windows and define a value in a certain range. Scrolls from left to right.|
|DefaultListBox.gui||ListBox||A list of selectable values, of which one can be selected at a time. Unlike the ComboBox, ListBox has all values visible.|
|DefaultVScrollBar.gui||ScrollBar||A slider that allows you to scroll windows and define a value in a certain range.|
|DefaultWindow.gui||Control||Window has a title box and can hold other controls.|
|SamallCheckBox.gui||CheckBox||A little check box. Reduced analogue of DefaultCheckBox.gui.|
.gui files are like containers for user interface and control elements storage. GUI-files can be built from other GUI-files. DefaultWindow (a standart window)is often used in the user interface base. You can find a lot of GUI-files examples in the "Data\GUI" folder.
Creating the GUI-file
To create a new GUI-file, right-click on the folder in the Resources editor window, select New and then Graphic User Interface.
You will need to select a name for the GUI-file in the pop up window as well as set a base class or Gui-file and press the Next button. User interface or control elements inherits the properties of the base class or the other GUI-file. You can save the time having a chance to select the finished pattern and to set its parameters.
To edit the GUI-file, as usual, right-click on it and select Edit in the context menu. You can also simply double click on it.
In the Control Hierarchy (control elements hierarchy) window you can see the control element structure - all the elements and their hierarchy. Select the element to see or edit its properties in the Properties window.
To add a control element, choose the element, in which the new one will be located, and right-click on the window working area. In the context menu, select Create New Control (create a new control element). You can do the same operation in the Control Hierarchy window.
Then in New Control (a new control element) window, select the class or GUI-file which will be added and press the OK button. After finishing the GUI-file editing, you should save it using the Save button on the main panel.
Position and Size Properties
All controls have a Layout properties section, in which you will find the Position and Size properties. Values can be used the following way for these properties: Parent (in proportion to parent element); Screen (in proportion to screen); ScreenByResolution (in proportion to screen resolution); Pixel (in pixel on screen). It is worth to take into account vertical and horizontal alignment of the element, because this influences the position.
Parent (proportionally to the parent element)
This type of reference takes as reference point it's parent, that is - the element that it belongs to. You can see what element is the parent of the current element in the Control Hierarchy window:
In this example element A is the parent of element B, and element B — is the parent of element C.
If you set Parent reference point, it will be referenced proportionaly to the parent element. For example - if you want the object to be twice smaller in width than it's parent, the value must be set to 0.5.
If you set Parent reference point for a root object which doesn't have a Parent in the current structure, it will be referenced by the object on which it is placed. For example - if you create a Button with position type Parent and then use it in a UI Model and place it inside a window, the button's position will be referenced by that window.
Screen (proportionally to the screen)
Here, the reference point is the screen, represented by the green border which is only visible when you are in Edit mode.
In this case, values are set in proportion. Upper left corner is (0, 0), and lower right corner is — (1, 1). If you set your object's position to (Screen 0.5 0.5), its upper left corner will be positioned exactly in the center of the screen.
ScreenByResolution (proportionally to screen resolution)
In this type of position reference, size values are given in virtual pixels. Screen height is always 768 virtual pixels. Screen width depends on window size, but proportionality coefficient is always 1:1.
This type is convenient, because proportions of elements remain the same to all proportions of screen resoluton, that is not possible with Screen type of reference, because when using it, the elements change the width depending on whether you use standard or wide-format monitor.
Pixel (in pixels on the screen)
With this type the element position and size should be set in pixels.
To get the access to the interface editor settings, open the Options window from main panel or through the Tools -> Options menu. In the appeared window choose the GUI tab.
The interface editor settings are divided in two groups: General and Test Mode.
|Background Color||Background color of the working window.|
|Grid Color||Grid color.|
|Grid Step||Grip step. The higher the value, the biggest is the distance between the grid lines. All the controls elements are connected with these grid lines.|
|Show Grid||Turns on or off the grid display. If this parameter is set to True, the grid is shown.|
|Scaling In Test Mode||Turns on or off elements scaling in test mode.|
Tutorial — Menu creation
In this section you can read a step-by-step tutorial about creating a GUI-file similar to MainMenuWindow.gui (the main menu window) that can be found in the Data/Gui folder. Our menu will contain a title, the text, an exit button, a run the game button, and an image.
Creating the GUI-file
We will start this tutorial by creating a GUI-file for our menu. To do that, right-click on the GUI folder in the Resources window, choose New in the context menu, and then choose Graphic User Interface.
In the open window, set the name for a new GUI-file, e.g. Menu. Then select a base GUI-file for the menu. It is suitable to use DefaultWindow.gui (a standard window) as a base element because a window with the title should be created. To finish the GUI-file creation, press the Next button.
Now let's do the window setting. Open the file which has just been created to edit it. Right-click on it and select Edit in context menu.
Now you will need to modify some of the window's parameter. To do this, press on it in working area or check the GUI\Menu.gui element checkbox in the Control Hierarchy window.
Set the title (Menu) as the Text field in the Properties window. You should also set the window size around 480 per 400 virtual pixels.ScaleByResolution will be used for this element. You can read more about Position and Size properties and about the use of support elements here.
Let's adding an element to the window.
To add the element to the window, select it in the Control Hierarchy window and right-click on it to call the context menu. You can do the same in the working area. Then choose the Create New Control in context menu.
We will first add a text box to the window. To do that, select the TextBox class in the New Control (new element) window. You can find it in the Classes group.
Now that the text box has been added and selected in the hierarchy element window, we will edit it. You should change the text box size to make it more suitable. (text box fill the full space by default). In the Size propertie group, choose the ScaleByResolution support element with the value (480 30). You can move the text box using your mouse. Change it's position so the Position property will become equals to (ScaleByResolution 0 40). Finally, in the Text field, enter the text "Press "Start" to run the game".
Next, we will add an image to the window. Again select the window by right-clicking on it and choose Create New Control in the context menu. Then select Control (control element) class in the New Control window. After the element is added, select the point BackTexture (background texture) in the properties and press the "..." button.
In the resource selection window you have just opened, choose the texture you will want to use. For this tutorial, select the NeoAxis_256x256.png file, which is located in GUI\Textures.
Now you only need to change the image location. First, set the image size to (ScaleByResolution 256 256). Then, justify the image to the center of the window. To do this, set the Center value in HorizontalAlign and VerticalAlign properties.
Now you should add two buttons to the window. Let's do the same operations you did to add the image. In the New Control window, select the file DefaultButton.gui (a standard button), which is located in the "Data\GUI\Controls" folder. Put the buttons at the bottom of the window by moving them in the working area using your mouse. Set the value of Text in the properties: one button will be Start and the other Exit.
When you are done with the window creation, save the GUI-file. To do that, press the button with the floppy disk icon on the main panel or choose Save in the File menu.
You can see the user interface in the resource editor. To do this, press the Test button located in the Properties window.
Press Stop button to end the Testing Mode and get back to Edit Mode.
In this tutorial, you have learnt to create a window using a finished pattern, filled it with elements and worked with most used elements such as Text boxes and Buttons. You have also learnt how to add images to the window.
Tutorial — inset control element
In this tutorial you will learn how to work with property pages control element - TabControl. The example of use the insets control element is a property window Game.exe. The page or inset is a hierarchy of any control elements.
Creating a window with insets control element
Let's begin to create the GUI-file with inset control element. Right'click on GUI folder in Resource Editor and select New -> Graphic User Interface in context menu.
Set the name of GUI-file in open window: SampleTabControlWindow. To put the inset control element to the window when it will be prepeared, select the base object type: DefaultWindow.gui. Then press the Next button.
Now you need to open the created GUI-file to edit it. To do this, right-click on it and select Edit from the context menu.
Then you should put the inset control element to the standart window, which was selected as a base object. But this window should be prepeared. Select it at the Control Hierarchy window or in the working area and set some parameters. Firstly, let's change the title, entering "Sample Tab Control Window" (in the Text slot). Secondly, you should change the window size, entering ScaleByResolution 600 410 (in Size slot).
Now let's add the inset control element to the window. Right-click on the window in working area or on Control Hierarchy window. In open contex menu select the Create New Control point. In New Control window set the TabControl class at the Classes group and press the OK button. Select the insets control element and put it into inside part of the window. Now the insets control element is created, but it is nescessary to add some pages and buttons to it for editing it.
Creating a page
Now create two insets. The first will contain a send messages form, and the second an image. Both insets will be based on the simple control element (Control).
Let's add the first inset. Select the inset control element, right-click on it and select Create New Control in the context menu. In New Control window, set the class of the element - Control class from Classes group. Then in Parent Control Slot list select Page 0 (zero page) and press OK.
Set the size in the page properties - (ScaleByResolution 356 356). Then put the inset at the first part of the window (you will use the space on the left for buttons to switch the pages). Also, enter the inset's title in the Text slot - Feedback. This title will be used for text boxes on insets switch buttons in future.
Fill the inset with following elements:
- text box (TextBox class) with "Message:". Align the text left (TextHorizontalAlign property with Left value) and (ScaleByResolution 340 30) size,
- text box with text shifting (DefaultEditBox_WordWrap.gui file), with "Your text here..." text (your text is here) and (ScaleByResolution 340 230) size,
- (DefaultButton.gui file) button, with Send text and (ScaleByResolution 340 30) size..
Every time you want to add a new element, you will need to select the element which is used as inset 0, call the context menu and press the Create New Control button. Let's put the elements like as shown in the image below.
Again select the insets control element and add a new page. In the New Control window you, select the Control class again, and now set Page 1 in the Parent Control Slot list. The created inset will have the same size as the first inset - (ScaleByResolution 356 356), and it will be located at the same place. You should however set a different background texture for Page 1 so it doesn't look like the previous page. To do that, select the inset and press the "..." button in the the BackTexture slot.
In the resource choosing window, select the NeoAxis_256x256.png file, which is located in "Data\GUI\Textures.
Again enter the text in the suitable slot. Give the name Logo to the inset.
To switch from one inset to another in editing mode, you should enter the number of the inset (beginning with 0) in SelectedIndex slot of insets control element. In the end, you will be able to switch between insets from code. You can also do it the following way: set the buttons to switch between insets in the resource editor.
Standard buttons to switch the insets control elements can be set the following way:
- a pattern-element of a button should be set,
- the location of the buttons and space between them should be set,
- the text of the inset is used as the button title.
Let's set the standard shift buttons. Use the standard button as a pattern. Select the insets control element and add a new element to it. In New Control window, select the DefaultButton.gui file, and choose the PageButton from the ParentSlotControl list.
Now let's put the buttons on the left side of the window. To do that, choose the insets control element. Firstly select the position of the shift buttons (PageButtonsPosition property) - (ScaleByResolution 10 20). Then set the space between buttons (PageButtonsPosition property)equals to (ScaleByResolution 0 40).
Finishing the creation of insets control elements
After creating the insets, filling them with the necessary elements, and placing the shift buttons in the correct places, you should save the GUI-file. To do that, press the button with the image of a floppy disk in the main panel or use the menu File -> Save.
You can see how the insets control element works in the editor. To do that, press the Test button located at the bottom of the properties window.
Switching the insets using standard buttons can aslo work in testing mode. To go to the second inset (Page 1) press the Logo button.
To get back to the edit mode press the Stop button at the bottom of the properties window.
In this tutorial you have learnt how to create a window with insets control elements, how to add insets to it and set the standard buttons to switch between the pages.