User Interface Editor – Arma 3

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Some wiki formatting)
m (Text replacement - "{{Feature|Warning|" to "{{Feature|warning|")
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{TOC|side}}
{{TOC|side}}
The User Interface editor can be launched from the [[Mission Editor: Debug Console (Arma 3)|Debug Console]] -> "GUI Editor" button.
The User Interface editor can be launched from the [[Arma 3: Debug Console|Debug Console]] -> "GUI Editor" button.
 


== Tutorial ==
== Tutorial ==
The following tutorial gives an introduction to the GUI Editor in Arma. The content of the [[GUI Tutorial]] is assumed to be known.
The following tutorial gives an introduction to the GUI Editor in Arma. The content of the [[GUI Tutorial]] is assumed to be known.
=== Access ===
=== 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 [[Arma_3:_Debug_Console#Access|access]] to it.
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 [[Arma_3:_Debug_Console#Access|access]] to it.


=== The Grid ===
=== The Grid ===
The position of your UI is determined by [[Arma_3:_GUI_Coordinates|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:
 
{{Feature|Informative|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 [[Arma_3:_GUI_Coordinates#Using_the_grids_in_the_GUI_Editor|which values to use instead]].<br>
The position of your UI is determined by [[Arma_3:_GUI_Coordinates|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 {{Controls|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:
{{Feature|informative|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 [[Arma_3:_GUI_Coordinates#Using_the_grids_in_the_GUI_Editor|which values to use instead]].<br>
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.}}
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.}}


{| class="wikitable"
{| class="wikitable"
|-
|-
| X || (safezoneX + (safezoneW - ((safezoneW / safezoneH) min 1.2))/2)
| X || <sqf>(safeZoneX + (safeZoneW - ((safeZoneW / safeZoneH) min 1.2)) / 2)</sqf>
|-
|-
| Y || (safezoneY + (safezoneH - (((safezoneW / safezoneH) min 1.2) / 1.2))/2)
| Y || <sqf>(safeZoneY + (safeZoneH - (((safeZoneW / safeZoneH) min 1.2) / 1.2)) / 2)</sqf>
|-
|-
| Area W || ((safezoneW / safezoneH) min 1.2)
| Area W || <sqf>((safeZoneW / safeZoneH) min 1.2)</sqf>
|-
|-
| Area H || (((safezoneW / safezoneH) min 1.2) / 1.2)
| Area H || <sqf>(((safeZoneW / safeZoneH) min 1.2) / 1.2)</sqf>
|-
|-
| Segment W || (((safezoneW / safezoneH) min 1.2) / 40)
| Segment W || <sqf>(((safeZoneW / safeZoneH) min 1.2) / 40)</sqf>
|-
|-
| Segment H || ((((safezoneW / safezoneH) min 1.2) / 1.2) / 25)
| Segment H || <sqf>((((safeZoneW / safeZoneH) min 1.2) / 1.2) / 25)</sqf>
|-
|-
| Variable || GUI_GRID_CENTER
| Variable || <sqf>GUI_GRID_CENTER</sqf>
|}
|}


{{Feature|important|These settings are not permanent! If you close the GUI Editor you will have to reenter them.}}
{{Feature|important|These settings are not permanent! If you close the GUI Editor you will have to enter them again.}}
 
=== Handling Controls ===


=== Handling controls ===
You can create a control by right clicking on free space. A list of available control types will appear.
You can create a control by right clicking on free space. A list of available control types will appear.
{| class="wikitable"
{| class="wikitable"
Line 43: Line 49:
| [[CT_BUTTON|RscButton]] || Can be clicked on. Functionality is added via [[User_Interface_Event_Handlers|UIEH]].
| [[CT_BUTTON|RscButton]] || Can be clicked on. Functionality is added via [[User_Interface_Event_Handlers|UIEH]].
|-
|-
| [[CT_SHORTCUTBUTTON|RscButtonMenu]] || Arma 3's default menu button. Used in menus like the escape menu. Is more customizable than RscButton.
| [[CT_SHORTCUTBUTTON|RscButtonMenu]] || {{arma3}}'s default menu button. Used in menus like the escape menu. Is more customizable than RscButton.
|-
|-
| RscButtonMenuCancel || Closes the UI with [[User_Interface_Event_Handlers#onUnload|exit code 2]].
| RscButtonMenuCancel || Closes the UI with [[User_Interface_Event_Handlers#onUnload|exit code 2]].
Line 77: Line 83:


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:
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:
{| class="wikitable"
{| class="wikitable"
|-
|-
Line 87: Line 94:
| Position || An [[Array|array]] of numbers or strings in the format {{hl|[x, y, w, h]}}.
| Position || An [[Array|array]] of numbers or strings in the format {{hl|[x, y, w, h]}}.
|-
|-
| Text color || The color of the text. <syntaxhighlight lang="cpp" inline>colorText[]</sqf> in the config. Format {{hl|[Red, Green, Blue, Alpha (Transparency)]}}.
| Text color || The color of the text. <syntaxhighlight lang="cpp" inline>colorText[]</syntaxhighlight> in the config. Format {{hl|[Red, Green, Blue, Alpha (Transparency)]}}.
|-
|-
| Background color || The color of the background. Same format as Text Color.
| Background color || The color of the background. Same format as Text Color.
Line 104: Line 111:
=== Saving ===
=== Saving ===
{{Feature|important|Your progress can only be copied to the clipboard and is therefore not permanent until you save it to a file yourself!}}
{{Feature|important|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.
Press {{Controls|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 ====
==== 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.
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 {{Controls|Ctrl|O}} while in the GUI Editor.
 
===== Indent =====
===== 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.
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 =====
===== 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.
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 =====
===== Text =====
Plain means literally just the text. Localized can be used for translating the controls' texts with a [[stringtable]].
Plain means literally just the text. Localized can be used for translating the controls' texts with a [[stringtable]].


===== Example output =====
===== Example Output =====
<pre>/* #Wygopu
<pre>/* #Wygopu
$[
$[
1.063,
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],
["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"],[]],
[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"],[]],
[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"],[]],
Line 140: Line 151:
</syntaxhighlight>
</syntaxhighlight>


===== Example output =====
===== Example Output =====
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
////////////////////////////////////////////////////////
////////////////////////////////////////////////////////
Line 146: Line 157:
////////////////////////////////////////////////////////
////////////////////////////////////////////////////////


class RscText_1000: RscText
class RscText_1000 : RscText
{
{
idc = 1000;
idc = 1000;
Line 155: Line 166:
colorBackground[] = {0,0,0,0.8};
colorBackground[] = {0,0,0,0.8};
};
};
class RscText_1001: RscText
class RscText_1001 : RscText
{
{
idc = 1001;
idc = 1001;
Line 165: Line 176:
colorBackground[] = {0,1,0,0.8};
colorBackground[] = {0,1,0,0.8};
};
};
class RscStructuredText_1100: RscStructuredText
class RscStructuredText_1100 : RscStructuredText
{
{
idc = 1100;
idc = 1100;
Line 174: Line 185:
h = 17 * GUI_GRID_CENTER_H;
h = 17 * GUI_GRID_CENTER_H;
};
};
class RscButtonMenuOK_2600: RscButtonMenuOK
class RscButtonMenuOK_2600 : RscButtonMenuOK
{
{
x = 4 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X;
x = 4 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X;
Line 181: Line 192:
h = 1 * GUI_GRID_CENTER_H;
h = 1 * GUI_GRID_CENTER_H;
};
};
class RscButtonMenuCancel_2700: RscButtonMenuCancel
class RscButtonMenuCancel_2700 : RscButtonMenuCancel
{
{
x = 26.5 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X;
x = 26.5 * GUI_GRID_CENTER_W + GUI_GRID_CENTER_X;
Line 197: Line 208:


==== Grid Macros ====
==== 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.
This will export the values that you set with the {{Controls|Ctrl|G}} dialog as macros. Paste them into the config before you use them the first time.


==== Parent Classes ====
==== Parent Classes ====
Line 204: Line 215:
==== Stringtable ====
==== Stringtable ====
Output to be used in the stringtable. Not really necessary and probably better to do it by hand.
Output to be used in the stringtable. Not really necessary and probably better to do it by hand.
===== Example output =====
===== Example output =====
<code>//--- RscDisplayTestDialog
//--- RscDisplayTestDialog
language, original
language, original
RscDisplayTestDialog_RscText_1001, "Test Dialog"
RscDisplayTestDialog_RscText_1001, "Test Dialog"
RscDisplayTestDialog_RscStructuredText_1100, "STR_INFO"</code>
RscDisplayTestDialog_RscStructuredText_1100, "STR_INFO"
 


== Controls ==
== Controls ==
=== LMB===
 
=== LMB ===
 
* '''Click and hold over GUI element''' - Move element
* '''Click and hold over GUI element''' - Move element
* {{Controls|Ctrl}} - Disable aligning to grid
* {{Controls|Ctrl}} - Disable aligning to grid
Line 217: Line 232:


=== RMB ===
=== RMB ===
* '''Click on GUI element''' - Modify element parameters
* '''Click on GUI element''' - Modify element parameters
* {{Controls|Ctrl}} '''+ Click on GUI element''' - Modify custom element parameters (changes won't be visible)
* {{Controls|Ctrl}} '''+ Click on GUI element''' - Modify custom element parameters (changes won't be visible)
Line 222: Line 238:


=== Key Shortcuts ===
=== Key Shortcuts ===
{{Columns|2|
{{Columns|2|
* {{Controls|H}} / {{Controls|F1}} - Help
* {{Controls|H}} / {{Controls|F1}} - Help
Line 248: Line 265:
}}
}}


=== Position types ===
=== Position Types ===
 
Following variants determine in what format the element position will be saved
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.
* '''Absolute''' - Absolute position, remains same no matter what UI size or aspect ratio is.
Line 254: Line 272:
* '''Grid''' - Coordinates are multipliers of grid size
* '''Grid''' - Coordinates are multipliers of grid size
* '''Control Group''' - Elements are aligned to given RscControlGroup and share their position type
* '''Control Group''' - Elements are aligned to given RscControlGroup and share their position type
{{Feature|Warning|The current GUI_GRID setting does not work. A fix can be found [[Arma_3:_GUI_Coordinates#Using_the_grids_in_the_GUI_Editor|here]].}}
{{Feature|warning|The current GUI_GRID setting does not work. A fix can be found [[Arma_3:_GUI_Coordinates#Using_the_grids_in_the_GUI_Editor|here]].}}
 


== Export ==
== Export ==
=== Editor format ===
 
=== Editor Format ===
 
{{Controls|Ctrl|S}}
{{Controls|Ctrl|S}}


Starts with dollar symbol ($). When you copy this format to clipboard, it can be loaded in editor using {{Controls|Ctrl|O}}
Starts with dollar symbol ($). When you copy this format to clipboard, it can be loaded in editor using {{Controls|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],""],[]]]
  $[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) ===


=== Editor format (multi-line) ===
{{Controls|Ctrl|Alt|S}}
{{Controls|Ctrl|Alt|S}}


Line 270: Line 292:
  $[
  $[
  1.043,
  1.043,
  [["safezoneX","safezoneY","safezoneW","safezoneH"],"safezoneW / 32","safezoneH / 20","GUI_GRID"],
  [["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],""],[]],
  [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;"]],
  [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;"]],
Line 279: Line 301:
  */
  */


=== Config format ===
=== Config Format ===
 
Ready to be included into config or description file.<br>
Ready to be included into config or description file.<br>
{{Controls|Ctrl|Shift|S}}
{{Controls|Ctrl|Shift|S}}
Line 288: Line 311:
////////////////////////////////////////////////////////
////////////////////////////////////////////////////////


class RscText_1000: RscText
class RscText_1000 : RscText
{
{
     idc = 1000;
     idc = 1000;
Line 297: Line 320:
     h = 1 * GUI_GRID_H;
     h = 1 * GUI_GRID_H;
};
};
class MyListbox: RscListbox
class MyListbox : RscListbox
{
{
     idc = CUSTOM_IDC; //--- Custom params are listed first and are divided by one empty line from generated params
     idc = CUSTOM_IDC; //--- Custom params are listed first and are divided by one empty line from generated params
Line 306: Line 329:
     h = 15 * GUI_GRID_H;
     h = 15 * GUI_GRID_H;
};
};
class RscShortcutButton_1700: RscShortcutButton
class RscShortcutButton_1700 : RscShortcutButton
{
{
     idc = 1700;
     idc = 1700;
     text = $STR_DISP_CANCEL;
     text = "$STR_DISP_CANCEL";
     x = 1 * GUI_GRID_W + GUI_GRID_X;
     x = 1 * GUI_GRID_W + GUI_GRID_X;
     y = 18 * GUI_GRID_H + GUI_GRID_Y;
     y = 18 * GUI_GRID_H + GUI_GRID_Y;
Line 315: Line 338:
     h = 1 * GUI_GRID_H;
     h = 1 * GUI_GRID_H;
};
};
class Group: RscControlsGroup
class Group : RscControlsGroup
{
{
     idc = 2300;
     idc = 2300;
Line 324: Line 347:
     class controls
     class controls
     {
     {
         class GroupText: RscText
         class GroupText : RscText
         {
         {
             idc = 1001;
             idc = 1001;
Line 338: Line 361:
////////////////////////////////////////////////////////
////////////////////////////////////////////////////////
</syntaxhighlight>
</syntaxhighlight>


== Import ==
== Import ==
{{Controls|Ctrl|I}}
{{Controls|Ctrl|I}}
*Sometimes one has to do more changes, even after the user interface was considered done.
* Sometimes one has to do more changes, even after the user interface was considered done.


'''Example'''
'''Example'''
Line 348: Line 373:
[[File:Arm3_UI_Editor_Import_Config_Result.jpg|250px]]
[[File:Arm3_UI_Editor_Import_Config_Result.jpg|250px]]


== Known issues ==
 
== Known Issues ==
 
* When changing element from any position type to controls group type, its position is not updated correctly.
* 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.
** 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.
** If you cannot se the element (it's position is now outside of screen), press {{Controls|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.
* Game sometimes freezes when you're working on layout with controls groups and open ({{Controls|Ctrl|O}}) another one with different control groups. Press {{Controls|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.
* 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
* Script error when using the undo functionality

Latest revision as of 00:25, 2 February 2024

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 enter them again.

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

  • H / F1 - Help
  • G - Show/hide grid
  • Ctrl + G - Modify grid parameters
  • Alt + G - Create grid on element under cursor
  • ⇧ Shift + G - Toggle between Absolute and Safezone grid
  • Ctrl + N - Add a new element
  • Del - Delete a current element
  • Ctrl + C - Copy a current element
  • Ctrl + X - Cut a current element
  • Ctrl + V - Paste a copied element
  • Ctrl + Z - Undo
  • Ctrl + ⇧ Shift + Z - Redo
  • Ctrl + L - Display list of all elements, change order and lock/unlock
  • Ctrl + S - Export to GUI editor format
  • Ctrl + Alt + S - Export to GUI editor format with linebreaks
  • Ctrl + ⇧ Shift + S - Export to a config format
  • Ctrl + ⇧ Shift + S + (1-9) - Export to a config format (class controls variant) with given number of tabs (1-9)
  • Ctrl + Alt + ⇧ Shift + S - Export to a config format (controls[]= variant) with given number of tabs (1-9)
  • Ctrl + O - Import from GUI editor format
  • Ctrl + I - Import from config
  • Ctrl + P - Export parent classes
  • Ctrl + ⇧ Shift + P - Export grid macros
  • Space - Highlights all elements (including invisible ones)

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=352129"