User Interface Editor – Arma 3

From Bohemia Interactive Community
Revision as of 18:37, 14 June 2021 by Lou Montana (talk | contribs) (Add Columns template usage + KeyboardShortcut usage)
Jump to navigation Jump to search

The User Interface editor can be launched from the Debug Console -> "GUI Editor" button.

Tutorial

The following tutorial gives an introduction to the GUI Editor in Arma. The content of the GUI Tutorial is assumed to be known.

Access

The GUI Editor can be opened via the debug console in the escape menu. The button "GUI Editor" opens the user interface. If you don't see the debug console make sure that you have access to it.

The Grid

The position of your UI is determined by screen coordinates. The default grid that is selected in the GUI Editor does not work. Therefore we will have to replace it. Open the grid settings with CTRL+G. You should see a UI where you can edit the values for X, Y, Area W, etc.. Enter the values according to the following table:

ⓘ
When using these values the UI will be fixed to the center of the screen. If you want to have your UI appear somewhere else you need to know which values to use instead.
The GUI Editor also does not support mixed position macros (at least not with horrendous effort). In this case you will need to understand screen coordinates and edit them in your config by hand.
X (safezoneX + (safezoneW - ((safezoneW / safezoneH) min 1.2))/2)
Y (safezoneY + (safezoneH - (((safezoneW / safezoneH) min 1.2) / 1.2))/2)
Area W ((safezoneW / safezoneH) min 1.2)
Area H (((safezoneW / safezoneH) min 1.2) / 1.2)
Segment W (((safezoneW / safezoneH) min 1.2) / 40)
Segment H ((((safezoneW / safezoneH) min 1.2) / 1.2) / 25)
Variable GUI_GRID_CENTER
⚠
These settings are not permanent! If you close the GUI Editor you will have to reenter them.

Handling controls

You can create a control by right clicking on free space. A list of available control types will appear.

Name Explanation
<Comment> This is not a control. Probably meant for documentation?
IGUIBack Deprecated.
RscButton Can be clicked on. Functionality is added via UIEH.
RscButtonMenu Arma 3's default menu button. Used in menus like the escape menu. Is more customizable than RscButton.
RscButtonMenuCancel Closes the UI with exit code 2.
RscButtonMenuOK Closes the UI with exit code 1.
RscCheckbox Control with two possible states: checked and unchecked.
RscCombo Dropdown menu.
RscControlsGroup Container for other controls to group them together.
RscEdit User editable text field.
RscFrame Decorative frame.
RscListbox A list of texts and/or optionally pictures.
RscPicture Can display an image.
RscShortcutButton Deprecated.
RscShortcutButtonMain Deprecated.
RscSlider A slider that can be dragged left to right. A more modern version is the CT_XSLIDER.
RscStructuredText Supports structured text formatting.
RscText Very simple control. Can be used for backgrounds and text labels.
RscTextCheckbox Similar to RscCheckbox has two states but displays two different texts instead.

Selecting one and confirming with OK will add this control to the screen. Some controls might appear with no background visible (RscText, RscControlsGroup). In this case you can hold enter to highlight all controls. To edit the control afterwards, right click on it to open a window where you can set the following attributes:

Attribute Explanation
Class The class name of the control which will be used in the export later on.
Text The text that is visible on supported controls.
Position An array of numbers or strings in the format [x, y, w, h].
Text color The color of the text. colorText[] in the config. Format [Red, Green, Blue, Alpha (Transparency)].
Background color The color of the background. Same format as Text Color.
Active color The color of the control when it is focused. Applicable to all interactable controls such as buttons.
Tooltip Text that is displayed in a small box at the cursor position when hovering over the control.
Text size The font size in screen coordinates. See the size/sizeEx attribute.
Position type One of absolute, safeZone, GUI_GRID (or whatever you set as your variable name) or a controls group. Used to switch to this grid for this control. Using "ControlGroup: 1234" means relative to the control group as a child control.

You can move controls around by holding left mouse button and moving your mouse. Resizing is possible by holding ALT and dragging a corner of the control to the desired size.

Saving

⚠
Your progress can only be copied to the clipboard and is therefore not permanent until you save it to a file yourself!

Press CTRL+S to open the Save dialog. Give your dialog a title. You have the option to export the dialog with different formats. The formats "GUI Editor" and "Config (controls as class)" are the most important ones.

GUI Editor

This format can be imported to the GUI Editor from the clipboard if you want to change the GUI at a later point. To import, copy the content between the comments (/* and */) to the cliboard and press CTRL+O while in the GUI Editor.

Indent

Indent means how many tabs to put before each line. Usually the controls of a dialog have and indent of 2 and RscTitle dialogs need an indent of 3. Not very important though.

IDC

The idc of the control can be given as a number or as a macro. In the latter case it is also necessary to use the "Config macro" output.

Text

Plain means literally just the text. Localized can be used for translating the controls' texts with a stringtable.

Example output
/* #Wygopu
$[
	1.063,
	["RscDisplayTestDialog",[["(safezoneX + (safezoneW - ((safezoneW / safezoneH) min 1.2))/2)","(safezoneY + (safezoneH - (((safezoneW / safezoneH) min 1.2) / 1.2))/2)","((safezoneW / safezoneH) min 1.2)","(((safezoneW / safezoneH) min 1.2) / 1.2)"],"(((safezoneW / safezoneH) min 1.2) / 40)","((((safezoneW / safezoneH) min 1.2) / 1.2) / 25)","GUI_GRID_CENTER"],0,0,0],
	[1000,"",[2,"",["4 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X","4 * GUI_GRID_CENTER_H + GUI_GRID_CENTER_Y","31 * GUI_GRID_CENTER_W","18 * GUI_GRID_CENTER_H"],[-1,-1,-1,-1],[0,0,0,0.8],[-1,-1,-1,-1],"","-1"],[]],
	[1001,"",[2,"Test Dialog",["4 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X","2.5 * GUI_GRID_CENTER_H + GUI_GRID_CENTER_Y","31 * GUI_GRID_CENTER_W","1 * GUI_GRID_CENTER_H"],[-1,-1,-1,-1],[0,1,0,0.8],[-1,-1,-1,-1],"","-1"],[]],
	[1100,"",[2,"Informative text...",["4.5 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X","4.5 * GUI_GRID_CENTER_H + GUI_GRID_CENTER_Y","30 * GUI_GRID_CENTER_W","17 * GUI_GRID_CENTER_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],"","-1"],[]],
	[2600,"",[2,"",["4 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X","22.5 * GUI_GRID_CENTER_H + GUI_GRID_CENTER_Y","8.5 * GUI_GRID_CENTER_W","1 * GUI_GRID_CENTER_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],"","-1"],[]],
	[2700,"",[2,"",["26.5 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X","22.5 * GUI_GRID_CENTER_H + GUI_GRID_CENTER_Y","8.5 * GUI_GRID_CENTER_W","1 * GUI_GRID_CENTER_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],"","-1"],[]]
]
*/

Config (controls as class)

This format is used in your display's controls class. It has to be pasted between the brackets of the controls class: 

class RscDisplayTestDialog
{
	idd = -1;
	class Controls
	{
		/* CLASS OUTPUT GOES HERE */
	};
};
Example output
////////////////////////////////////////////////////////
// GUI EDITOR OUTPUT START (by Terra, v1.063, #Lupile)
////////////////////////////////////////////////////////

class RscText_1000: RscText
{
	idc = 1000;
	x = 4 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X;
	y = 4 * GUI_GRID_CENTER_H + GUI_GRID_CENTER_Y;
	w = 31 * GUI_GRID_CENTER_W;
	h = 18 * GUI_GRID_CENTER_H;
	colorBackground[] = {0,0,0,0.8};
};
class RscText_1001: RscText
{
	idc = 1001;
	text = "Test Dialog"; //--- ToDo: Localize;
	x = 4 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X;
	y = 2.5 * GUI_GRID_CENTER_H + GUI_GRID_CENTER_Y;
	w = 31 * GUI_GRID_CENTER_W;
	h = 1 * GUI_GRID_CENTER_H;
	colorBackground[] = {0,1,0,0.8};
};
class RscStructuredText_1100: RscStructuredText
{
	idc = 1100;
	text = "Informative text..."; //--- ToDo: Localize;
	x = 4.5 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X;
	y = 4.5 * GUI_GRID_CENTER_H + GUI_GRID_CENTER_Y;
	w = 30 * GUI_GRID_CENTER_W;
	h = 17 * GUI_GRID_CENTER_H;
};
class RscButtonMenuOK_2600: RscButtonMenuOK
{
	x = 4 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X;
	y = 22.5 * GUI_GRID_CENTER_H + GUI_GRID_CENTER_Y;
	w = 8.5 * GUI_GRID_CENTER_W;
	h = 1 * GUI_GRID_CENTER_H;
};
class RscButtonMenuCancel_2700: RscButtonMenuCancel
{
	x = 26.5 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X;
	y = 22.5 * GUI_GRID_CENTER_H + GUI_GRID_CENTER_Y;
	w = 8.5 * GUI_GRID_CENTER_W;
	h = 1 * GUI_GRID_CENTER_H;
};
////////////////////////////////////////////////////////
// GUI EDITOR OUTPUT END
////////////////////////////////////////////////////////

Config (controls as array)

Another format with which you can leave out the {{class Controls {... class. It is barely used and it is recommended to stick to the class format.

Grid Macros

This will export the values that you set with the CTRL+G dialog as macros. Paste them into the config before you use them the first time.

Parent Classes

This export will declare the base classes that are available in the GUI Editor from which you can inherit. It is probably a better option to use BIS_fnc_exportGUIBaseClasses instead.

Stringtable

Output to be used in the stringtable. Not really necessary and probably better to do it by hand.

Example output

//--- RscDisplayTestDialog language, original RscDisplayTestDialog_RscText_1001, "Test Dialog" RscDisplayTestDialog_RscStructuredText_1100, "STR_INFO"

Controls

LMB

  • Click and hold over GUI element - Move element
  • Ctrl - Disable aligning to grid
  • Alt - Modify size

RMB

  • Click on GUI element - Modify element parameters
  • Ctrl + Click on GUI element - Modify custom element parameters (changes won't be visible)
  • Click on free space - Add a new element

Key Shortcuts

-no columns content defined-

Position types

Following variants determine in what format the element position will be saved

  • Absolute - Absolute position, remains same no matter what UI size or aspect ratio is.
  • Safezone - GUI elements stretches based both on UI width and height. Result may differ on different aspect ratios.
  • Grid - Coordinates are multipliers of grid size
  • Control Group - Elements are aligned to given RscControlGroup and share their position type
⚠
The current GUI_GRID setting does not work. A fix can be found here.

Export

Editor format

Ctrl + S

Starts with dollar symbol ($). When you copy this format to clipboard, it can be loaded in editor using Ctrl + O 

$[1.043,[["safezoneX","safezoneY","safezoneW","safezoneH"],"safezoneW / 32","safezoneH / 20","GUI_GRID"],[1000,"",[2,"Hello World!",["1 * GUI_GRID_W + GUI_GRID_X","1 * GUI_GRID_H + GUI_GRID_Y","30 * GUI_GRID_W","1 * GUI_GRID_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],""],[]],[1500,"MyListbox",[2,"",["1.5 * GUI_GRID_W + GUI_GRID_X","2.5 * GUI_GRID_H + GUI_GRID_Y","9 * GUI_GRID_W","15 * GUI_GRID_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],""],["idc = CUSTOM_IDC;"]],[1700,"",[2,"$STR_DISP_CANCEL",["1 * GUI_GRID_W + GUI_GRID_X","18 * GUI_GRID_H + GUI_GRID_Y","10 * GUI_GRID_W","1 * GUI_GRID_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],""],[]],[2300,"Group",[2,"",["11.5 * GUI_GRID_W + GUI_GRID_X","2.5 * GUI_GRID_H + GUI_GRID_Y","19 * GUI_GRID_W","15 * GUI_GRID_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],""],[]],[-1001,"GroupText",[2300,"",["0 * GUI_GRID_W","0 * GUI_GRID_H","19 * GUI_GRID_W","15 * GUI_GRID_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],""],[]]]

Editor format (multi-line)

Ctrl + Alt + S 

/*
$[
	1.043,
	[["safezoneX","safezoneY","safezoneW","safezoneH"],"safezoneW / 32","safezoneH / 20","GUI_GRID"],
	[1000,"",[2,"Hello World!",["1 * GUI_GRID_W + GUI_GRID_X","1 * GUI_GRID_H + GUI_GRID_Y","30 * GUI_GRID_W","1 * GUI_GRID_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],""],[]],
	[1500,"MyListbox",[2,"",["1.5 * GUI_GRID_W + GUI_GRID_X","2.5 * GUI_GRID_H + GUI_GRID_Y","9 * GUI_GRID_W","15 * GUI_GRID_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],""],["idc = CUSTOM_IDC;"]],
	[1700,"",[2,"$STR_DISP_CANCEL",["1 * GUI_GRID_W + GUI_GRID_X","18 * GUI_GRID_H + GUI_GRID_Y","10 * GUI_GRID_W","1 * GUI_GRID_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],""],[]],
	[2300,"Group",[2,"",["11.5 * GUI_GRID_W + GUI_GRID_X","2.5 * GUI_GRID_H + GUI_GRID_Y","19 * GUI_GRID_W","15 * GUI_GRID_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],""],[]],
	[-1001,"GroupText",[2300,"",["0 * GUI_GRID_W","0 * GUI_GRID_H","19 * GUI_GRID_W","15 * GUI_GRID_H"],[-1,-1,-1,-1],[-1,-1,-1,-1],[-1,-1,-1,-1],""],[]]
]
*/

Config format

Ready to be included into config or description file.
Ctrl + ⇧ Shift + S 

//--- Header contains player's profile name and editor version
////////////////////////////////////////////////////////
// GUI EDITOR OUTPUT START (by Karel, v1.043)
////////////////////////////////////////////////////////

class RscText_1000: RscText
{
    idc = 1000;
    text = "Hello World!"; //--- ToDo: Localize; Plain text is automatically marked to be localized
    x = 1 * GUI_GRID_W + GUI_GRID_X;
    y = 1 * GUI_GRID_H + GUI_GRID_Y;
    w = 30 * GUI_GRID_W;
    h = 1 * GUI_GRID_H;
};
class MyListbox: RscListbox
{
    idc = CUSTOM_IDC; //--- Custom params are listed first and are divided by one empty line from generated params

    x = 1.5 * GUI_GRID_W + GUI_GRID_X;
    y = 2.5 * GUI_GRID_H + GUI_GRID_Y;
    w = 9 * GUI_GRID_W;
    h = 15 * GUI_GRID_H;
};
class RscShortcutButton_1700: RscShortcutButton
{
    idc = 1700;
    text = $STR_DISP_CANCEL;
    x = 1 * GUI_GRID_W + GUI_GRID_X;
    y = 18 * GUI_GRID_H + GUI_GRID_Y;
    w = 10 * GUI_GRID_W;
    h = 1 * GUI_GRID_H;
};
class Group: RscControlsGroup
{
    idc = 2300;
    x = 11.5 * GUI_GRID_W + GUI_GRID_X;
    y = 2.5 * GUI_GRID_H + GUI_GRID_Y;
    w = 19 * GUI_GRID_W;
    h = 15 * GUI_GRID_H;
    class controls
    {
        class GroupText: RscText
        {
            idc = 1001;
            x = 0 * GUI_GRID_W;
            y = 0 * GUI_GRID_H;
            w = 19 * GUI_GRID_W;
            h = 15 * GUI_GRID_H;
        };
    };
};
////////////////////////////////////////////////////////
// GUI EDITOR OUTPUT END
////////////////////////////////////////////////////////

Import

Ctrl + I

  • Sometimes one has to do more changes, even after the user interface was considered done.

Example

Arma3 UI Editor Import Config.jpg Arm3 UI Editor Import Config Result.jpg

Known issues

  • When changing element from any position type to controls group type, its position is not updated correctly.
    • Changed element usually changes it is position. Dragging and dropping it should fix it.
    • If you cannot se the element (it's position is now outside of screen), press Ctrl+L to open list of elements, edit the changed element and modify X and Y coordinates to 0.
  • Game sometimes freezes when you're working on layout with controls groups and open (Ctrl+O) another one with different control groups. Press Ctrl+N to clear current layout first or close and open whole editor.
  • Listboxes (in "Add Element" and "Element's List' menus) are somehow not clickable in the bottom part. To select items in this area, click anywhere on top and move down using direction keys or Page Up/Down.
  • Script error when using the undo functionality
  • Each type of control can only be created 99 times
  • When importing GUIs from config, the default GUI_GRID is used
Retrieved from "https://community.bistudio.com/wiki?title=Arma_3:_User_Interface_Editor&oldid=281680"