Arma: GUI Configuration

Template:SideTOC Dialogs are one way to provide custom graphical user interface in your missions and allow interaction with the player aswell as they are able to run code. They are defined as classes in the missionConfigFile (description.ext), campaignConfigFile (Campaign Description.ext) or configFile (config.cpp).

• 

  Custom Briefing Editor

• 

  Teamswitch GUI

• 

  Dynamic Groups GUI

Terminology

GUI
Graphical User Interface which let's the user interact with the software through graphical controls like buttons, lists and so on.

UI
User Interface which let's the user interact with the software through a console application

IGUI
Integrated Graphical User Interface, usually used when talking about vanilla menus in Arma 3.

User Interface Types

Dialog

• Can be created upon an existing display. Parent display will be hidden.

• • Player movement is blocked by dialog
  • Commands: createDialog, closeDialog, allControls, dialog 7erra (talk)

Display

• Can be created upon an existing display. Parent display will be hidden.
• Player movement is not blocked by display, if it hasn't been blocked by its parent display already.
  • Commands: createDisplay, closeDisplay, allControls, allDisplays

ⓘ

Generally speaking, dialogs and displays are identical. They are only differentiated by the way they are created (createDisplay, createDialog).

7erra (talk): displayParent is only available for createDisplay displays, createDisplay will return the display while createDialog will only return success flag. dialog will return false for displays created with createDisplay.

HUD

• Is created in a new, or already existing layer. The user can not interact with it. Usually used to show information, like stamina, ammunition and so on.
  • Commands: allCutLayers, titleRsc, cutText, cutObj, cutFadeOut, setTitleEffect, allActiveTitleEffects

ⓘ

Some of the commands have different effects. Please check the command's biki page for detailed information.

Display and Dialog

Displays and dialogs are defined in the config file. They are usually used to simplify user interactions, through controls like buttons, list boxes and so on.

Properties

Name	Type	Remark
idd	Integer	The unique ID number of this dialog. Used with findDisplay to find the display. Can be -1 if no access is required from within a script.
access	Integer	0 - ReadAndWrite - this is the default case where properties can still be added or overridden. 1 - ReadAndCreate - this only allows creating new properties. 2 - ReadOnly - this does not allow to do anything in deriving classes. 3 - ReadOnlyVerified - this does not allow to do anything either in deriving classes, and a CRC check will be performed.
movingEnable	Boolean	Specifies whether the dialog can be moved or not (if enabled one of the dialogs controls should have the moving property set to 1 so it becomes the "handle" the dialog can be moved with). Doesn't seem to matter in Arma 3
enableSimulation	Boolean	Specifies whether the game continues while the dialog is shown or not.
onLoad	String	Expression executed when the dialog is opened. See User Interface Event Handlers
onUnload	String	Expression executed when the dialog is closed. See User Interface Event Handlers
controlsBackground	Array	Contains class names of all background controls associated to this dialog. The sequence in which the controls are listed will decide their z-index (i.e. the last ones will on top of the first ones).
controls	Array	Contains class names of all foreground controls associated to this dialog.
objects	Array

• Example Config:

class DefaultDialog 
{
  idd = -1;
  access = 0;
  movingEnable = true;		
  onLoad  = "hint str _this";
  onUnload  = "hint str _this";	
  enableSimulation = false;		
  controlsBackground[] = 
  { 
    //Background controls;
  };
  controls[] = 
  { 
   //Controls;
  };
  objects[] = 
  { 
    //Objects
  };				
};

Opening a display or dialog

There are two ways of creating a display or dialog. One can either use createDialog or createDisplay command.

Closing a display or dialog

There are several ways how a dialog can be closed.

• by pressing the Escape-key
• by using closeDialog
• by using closeDisplay
• when the user presses a button with IDC 0, 1 or 2

HUDs

HUDs are define in the class RscTitles, unlike displays or dialogs which are root classes in the config file. Additionally, their properties are different.

Properties

Name	Type	Remark
idd	Integer	The unique ID number of this HUD. Used with findDisplay to find the display. Can be -1 if no access is required from within a script.
fadeIn	Integer	Duration of fade in effect when opening in seconds.
fadeOut	Integer	Duration of fade out effect when closing in seconds.
duration	Integer	Duration the HUD is displayed after opening in seconds. Use a very large number to have it always open.
onLoad	String	Expression executed when the dialog is opened. See User Interface Event Handlers
onUnload	String	Expression executed when the dialog is closed. See User Interface Event Handlers
controls	Array	Contains class names of all foreground controls associated to this dialog.

• Example Config:

#include "\a3\ui_f\hpp\definecommongrids.inc"
class RscTitles
{
  class RscInfoText
  {
      idd = 3100;
      fadein = 0;
      fadeout = 0;
      duration = 1e+011;
      onLoad = "uinamespace setvariable ['BIS_InfoText',_this select 0]";
      onUnLoad = "uinamespace setvariable ['BIS_InfoText',nil]";
      class Controls
      {
          class InfoText
          {
              idc = 3101;
              style = "0x01 + 0x10 + 0x200 + 0x100";
              font = "RobotoCondensedBold";
              x = "(profilenamespace getvariable [""IGUI_GRID_MISSION_X"",(safezoneX + safezoneW - 21 * (GUI_GRID_WAbs / 40))])";
              y = "(profilenamespace getvariable [""IGUI_GRID_MISSION_Y"",(safezoneY + safezoneH - 10.5 * (GUI_GRID_HAbs / 25))])";
              w = "20 * (GUI_GRID_WAbs / 40)";
              h = "5 * ((GUI_GRID_WAbs / 1.2) / 25)";
              colorText[] = {1,1,1,1};
              colorBackground[] = {0,0,0,0};
              text = "";
              lineSpacing = 1;
              sizeEx = 0.045;
              fixedWidth = 1;
              deletable = 0;
              fade = 0;
              access = 0;
              type = 0;
              shadow = 1;
              colorShadow[] = {0,0,0,0.5};
              tooltipColorText[] = {1,1,1,1};
              tooltipColorBox[] = {1,1,1,1};
              tooltipColorShade[] = {0,0,0,0.65};
          };
      };
  };
};

Controls

Controls are used to allow the player to interact with the GUI. Controls range from simple rectangles to 3D objects. Like dialogs, displays and HUDs, controls can have a unique ID to access them from within scripts. The classname of controls have to be unique.

What properties a control needs is defined by its type property. However most controls share a set of properties described in the following sections. For control specific properties visit the corresponding pages.

Common Properties

Name	Type	Remark
idc	Integer	The unique ID number of this control. Can be -1 if you don't require access to the control itself from within a script
moving	Boolean	Whether the dialog will be moved if this control is dragged (may require "movingEnable" to be 1 in the dialog. In Arma 3 works regardless). Another way of allowing moving of the dialog is to have control of style ST_TITLE_BAR
type	Integer	See Control Types
style	Integer	See Control Styles. style = "0x400+0x02+0x10";
x/y/w/h	Number	The position and size of the control in fractions of screen size.
sizeEx	Number	The font size of text in fractions of screen size. Behaves similar to h property. For some controls it's named size.
font	String	The font to use. See the list of available fonts for possible values.
colorText	Array	Text color
colorBackground	Array	Background color
text	String	The text or picture to display.
shadow	Integer	Can be applied to most controls (0 = no shadow, 1 = drop shadow with soft edges, 2 = stroke).
tooltip	String	Text to display in a tooltip when control is moused over. A tooltip can be added to any control type except CT_STATIC and CT_STRUCTURED_TEXT. Note: As of -wrong parameter ("a3") defined!-[[:Category:Introduced with a3 version 1.48|1.48]], most controls now support tooltips. A linebreak can be created by adding \n.
tooltipColorShade	Array	Tooltip background color
tooltipColorText	Array	Tooltip text color
tooltipColorBox	Array	Tooltip border color

Attributes Class

Name	Type	Remark
font	String	Available Fonts
color	HTML color	HTML Color Codes
align	String	"center", "left", "right"
shadow	Integer	0 = no shadow, 1 = drop shadow with soft edges, 2 = stroke

AttributesImage Class

Name	Type	Remark
font	String	Available Fonts (Optional)
color	HTML color	HTML Color Codes
align	String	"center", "left", "Right" (optional)

• Example Config:

#include "\a3\ui_f\hpp\definecommongrids.inc"
class RscButton
{
    deletable = 0;
    fade = 0;
    access = 0;
    type = 1;
    text = "";
    colorText[] = {1,1,1,1};
    colorDisabled[] = {1,1,1,0.25};
    colorBackground[] = {0,0,0,0.5};
    colorBackgroundDisabled[] = {0,0,0,0.5};
    colorBackgroundActive[] = {0,0,0,1};
    colorFocused[] = {0,0,0,1};
    colorShadow[] = {0,0,0,0};
    colorBorder[] = {0,0,0,1};
    soundEnter[] = {"\A3\ui_f\data\sound\RscButton\soundEnter",0.09,1};
    soundPush[] = {"\A3\ui_f\data\sound\RscButton\soundPush",0.09,1};
    soundClick[] = {"\A3\ui_f\data\sound\RscButton\soundClick",0.09,1};
    soundEscape[] = {"\A3\ui_f\data\sound\RscButton\soundEscape",0.09,1};
    idc = -1;
    style = 2;
    x = 0;
    y = 0;
    w = 0.095589;
    h = 0.039216;
    shadow = 2;
    font = "RobotoCondensed";
    sizeEx = "GUI_GRID_HAbs / 25";
    url = "";
    offsetX = 0;
    offsetY = 0;
    offsetPressedX = 0;
    offsetPressedY = 0;
    borderSize = 0;
};

Control Types

The type property of controls defines what type of control they are. For example an edit box has the type 2. There is an ingame dialog with examples of how the control types look and act like: createDialog "RscTestControlTypes";

Define	Decimal	Hexadecimal	Remark	Define	Decimal	Hexadecimal	Remark
CT_STATIC	0	0x00		CT_XLISTBOX	42	0x2A
CT_BUTTON	1	0x01		CT_XSLIDER	43	0x2B
CT_EDIT	2	0x02		CT_XCOMBO	44	0x2C
CT_SLIDER	3	0x03		CT_ANIMATED_TEXTURE	45	0x2D
CT_COMBO	4	0x04		CT_MENU	46	0x2E	Arma 3 (EDEN)
CT_LISTBOX	5	0x05		CT_MENU_STRIP	47	0x2F	Arma 3 (EDEN)
CT_TOOLBOX	6	0x06		CT_CHECKBOX	77	0x4D	Arma 3
CT_CHECKBOXES	7	0x07		CT_OBJECT	80	0x50
CT_PROGRESS	8	0x08		CT_OBJECT_ZOOM	81	0x51
CT_HTML	9	0x09		CT_OBJECT_CONTAINER	82	0x52
CT_STATIC_SKEW	10	0x0A		CT_OBJECT_CONT_ANIM	83	0x53
CT_ACTIVETEXT	11	0x0B		CT_LINEBREAK	98	0x62
CT_TREE	12	0x0C		CT_USER	99	0x63
CT_STRUCTURED_TEXT	13	0x0D		CT_MAP	100	0x64
CT_CONTEXT_MENU	14	0x0E		CT_MAP_MAIN	101	0x65
CT_CONTROLS_GROUP	15	0x0F		CT_LISTNBOX	102	0x66
CT_SHORTCUTBUTTON	16	0x10		CT_ITEMSLOT	103	0x67
CT_HITZONES	17	0x11		CT_LISTNBOX_CHECKABLE	104	0x68
CT_VEHICLETOGGLES	18	0x12		CT_VEHICLE_DIRECTION	105	0x69
CT_CONTROLS_TABLE	19	0x13
CT_XKEYDESC	40	0x28
CT_XBUTTON	41	0x29

• Control Types Defines:

All defines can be retrieved by executing "Default" call BIS_fnc_exportGUIBaseClasses;

#define CT_STATIC				  0
#define CT_BUTTON				  1
#define CT_EDIT					  2
#define CT_SLIDER				  3
#define CT_COMBO				  4
#define CT_LISTBOX				  5
#define CT_TOOLBOX				  6
#define CT_CHECKBOXES			  7
#define CT_PROGRESS				  8
#define CT_HTML					  9
#define CT_STATIC_SKEW			 10
#define CT_ACTIVETEXT			 11
#define CT_TREE					 12
#define CT_STRUCTURED_TEXT		 13
#define CT_CONTEXT_MENU			 14
#define CT_CONTROLS_GROUP		 15
#define CT_SHORTCUTBUTTON		 16
#define CT_HITZONES				 17
#define CT_VEHICLETOGGLES		 18
#define CT_CONTROLS_TABLE		 19
#define CT_XKEYDESC				 40
#define CT_XBUTTON				 41
#define CT_XLISTBOX				 42
#define CT_XSLIDER				 43
#define CT_XCOMBO				 44
#define CT_ANIMATED_TEXTURE		 45
#define CT_MENU					 46
#define CT_MENU_STRIP			 47
#define CT_CHECKBOX				 77
#define CT_OBJECT				 80
#define CT_OBJECT_ZOOM			 81
#define CT_OBJECT_CONTAINER		 82
#define CT_OBJECT_CONT_ANIM		 83
#define CT_LINEBREAK			 98
#define CT_USER					 99
#define CT_MAP					100
#define CT_MAP_MAIN				101
#define CT_LISTNBOX				102
#define CT_ITEMSLOT				103
#define CT_LISTNBOX_CHECKABLE	104
#define CT_VEHICLE_DIRECTION	105

Control Styles

To further customize controls there are several different styles for each control type available.

To get an idea of how the styles look like you can create the following dialog: createDialog "RscTestControlStyles";

⚠

Note that drawing of vertical text is not supported and any attempt to use ST_UP, ST_DOWN, ST_VCENTER is likely to result in the following .rpt spam:
Obsolete, sizeH and sizeW calculation missing
In addition, ST_UP, ST_DOWN, ST_VCENTER are stand alone styles and should not be mixed with any other styles

Define	Decimal	Hexadecimal	Remark
ST_LEFT	0	0x00	Default, text left aligned
ST_RIGHT	1	0x01	Modifier, adding this to another style will force text to be aligned to the right
ST_CENTER	2	0x02	Modifier, adding this to another style will force text to be centered
ST_DOWN	4	0x04	Vertical text alignment (See the note above)
ST_UP	8	0x08	Vertical text alignment (See the note above)
ST_VCENTER	12	0x0C	Vertical text alignment, same as ST_DOWN + ST_UP (See the note above)
ST_SINGLE	0	0x00	Plain single line box without a border
ST_MULTI	16	0x10	Plain multiple line box with a slight border. To remove border add 512 (+ ST_NO_RECT) to the style (style 528, 529 and 530 are therefore border-less). Additional parameter lineSpacing is required for this style. lineSpacing = 1; is normal line spacing. Any \n character in the text string will be interpreted as new line.
ST_TITLE_BAR	32	0x20	Plain single line box with semi-transparent background and somewhat embossed border. When this style is used, the dialog containing control becomes draggable by this control
ST_PICTURE	48	0x30	Border-less picture box. Text string is treated as a path to a texture. Alignment has no effect. The texture is stretched to fit the box by default. To force original aspect ratio add 2048 (+ ST_KEEP_ASPECT_RATIO) to the style. Background is ignored, colorText controls texture colour and opacity
ST_FRAME	64	0x40	Legend like frame without background with text showing over the frame edge. Alignment has no effect. colorText defines both text and frame colour
ST_BACKGROUND	80	0x50	Single line box with always black opaque background and thick raised beveled border
ST_GROUP_BOX	96	0x60	Single line box with delicate semi-transparent background and slight border. Only text colour can be controlled
ST_GROUP_BOX2	112	0x70	Plain single line box, same as ST_SINGLE, only with a slight border similar to ST_MULTI box border
ST_HUD_BACKGROUND	128	0x80	Sets special texture for corners. It was used for rounded corners in OFP, Arma and Arma 2. In Arma 3, square corners are used everywhere, so the texture is adapted to the unified style, but the technology is not removed. In Arma 3 it looks the same as normal ST_SINGLE. Corner textures are defined in configFile >> "CfgInGameUI" >> "imageCornerElement" (can be set only globally for the whole game, not per control)”
ST_TILE_PICTURE	144	0x90	The picture is tiled according to tileH and tileW values. To force tiled picture to keep aspect ratio of original image, add 2048 (+ ST_KEEP_ASPECT_RATIO) to the style.
ST_WITH_RECT	160	0xA0	Single line box frame, similar to ST_FRAME box. The text however is displayed inside the frame. Frame and text colour are set with colorText
ST_LINE	176	0xB0	Diagonal line going from left top corner to bottom right corner. To control line direction, width w and height h parameters of the box could be negative. Line and text colour are set with colorText
ST_UPPERCASE	192	0xC0	Forces control text to upper case
ST_LOWERCASE	208	0xD0	Forces control text to lower case
ST_ADDITIONAL_INFO	3840	0x0F00	ST_SHADOW + ST_NO_RECT + SL_HORZ + ST_KEEP_ASPECT_RATIO
ST_SHADOW	256	0x0100
ST_NO_RECT	512	0x0200	This style works for CT_STATIC in conjunction with ST_MULTI
ST_KEEP_ASPECT_RATIO	2048	0x0800	When used with image or texture, stops it from stretching to fit the control
ST_TITLE	34	0x22	ST_TITLE_BAR + ST_CENTER

Control Specific Styles

CT_LISTBOX Specific Styles

Define	Decimal	Hexadecimal	Remark
LB_TEXTURES	16	0x10
LB_MULTI	32	0x20	Makes CT_LISTBOX multi-selectable

CT_PROGRESS Specific Styles

Define	Decimal	Hexadecimal
ST_VERTICAL	1	0x01
ST_HORIZONTAL	0	0x00

CT_SLIDER Specific Styles

Define	Decimal	Hexadecimal
SL_VERT	0	0x00
SL_HORZ	1024	0x0400
SL_TEXTURES	16	0x10

CT_TREE Specific Styles

Define	Decimal	Hexadecimal
TR_SHOWROOT	1	0x01
TR_AUTOCOLLAPSE	2	0x02

• Control Styles Definitions:

All defines can be retrieved by executing "Default" call BIS_fnc_exportGUIBaseClasses;

#define ST_LEFT					0x00
#define ST_RIGHT				0x01
#define ST_CENTER				0x02
#define ST_DOWN					0x04
#define ST_UP					0x08
#define ST_VCENTER				0x0C
#define ST_SINGLE				0x00
#define ST_MULTI				0x10
#define ST_TITLE_BAR			0x20
#define ST_PICTURE				0x30
#define ST_FRAME				0x40
#define ST_BACKGROUND			0x50
#define ST_GROUP_BOX			0x60
#define ST_GROUP_BOX2			0x70
#define ST_HUD_BACKGROUND		0x80
#define ST_TILE_PICTURE			0x90
#define ST_WITH_RECT			0xA0
#define ST_LINE					0xB0
#define ST_UPPERCASE			0xC0
#define ST_LOWERCASE			0xD0
#define ST_ADDITIONAL_INFO		0x0F00
#define ST_SHADOW				0x0100
#define ST_NO_RECT				0x0200
#define ST_KEEP_ASPECT_RATIO	0x0800
#define ST_TITLE				ST_TITLE_BAR + ST_CENTER
#define SL_VERT					0
#define SL_HORZ					0x400
#define SL_TEXTURES				0x10
#define ST_VERTICAL				0x01
#define ST_HORIZONTAL			0
#define LB_TEXTURES				0x10
#define LB_MULTI				0x20
#define TR_SHOWROOT				1
#define TR_AUTOCOLLAPSE			2

Positioning

The position has to fulfill the following goals:

• Scale properly with interface size set by the user
• Work on all common aspect ratios and resolutions. See common aspect ratios and resolutions in 2020.

Template:wip //Some description, common issues/problems, best practices

• Arma_3_GUI_Coordinates
• Arma 3 Pixel Grid System
• SafeZone

7erra (talk): Remind user that not everyone has the same settings as him. Best practice is to create the UI with the following settings (even if they look like s*it): UI size: Very Large, Ratio: 4:3 (actually 5:4 but no one uses that one). Here is a graph I created which shows the resolutions used by Steam users:

Inheritance

Using inheritance can reduce your dialog class definitions significantly by standardising common attributes in base classes and just changing unique attributes in derived classes. There is no need to redeclare all attributes for each class definition.

ⓘ

Using inheritance can also make your GUI config hard to read for others.

• Example Config:

class RscText // Base definition used for inheritance
{
	type = CT_STATIC;
	idc = -1;
	style = ST_LEFT;
	colorBackground[] = {0, 0, 0, 1};
	colorText[] = {1, 1, 1, 1};
	font = FontM;
	sizeEx = 0.04;
	h = 0.04;
	text = "";
};

class My_BlueText : RscText // My_BlueText inherits all attributes from RscText defined above, thus only x,w & colorText need to be changed
{
	colorText[] = {0, 0, 1, 1};
	x = 0.1;
	w = 0.4;
};

class My_Dialog
{
	//…

	controls[] = {
		My_Text_1,
		My_Text_2
	};

	class My_Text_1 : My_BlueText // My_Text_1 inherits all attribute from My_BlueText, therefore only text & y attributes have to be changed
	{
		text = "Line 1";
		y = 0.2;
	};

	class My_Text_2 : My_BlueText
	{
		text = "Line 2";
		y = 0.25;
	};
};

Preprocessor instructions

Note that you can also add your own preprocessor instructions for commonly used data, eg. for colors, to save yourself the hassle of writing it in several different places and then adapt each of them if you want to change them afterwards (especially if class inheritance isn't applicable). Also it can make your code look more readable sometimes.

• Example Config:

#define COLOR_LIGHTBROWN { 0.776, 0.749, 0.658, 1 }
#define COLOR_HALF_BLACK { 0, 0, 0, 0.5 }
#define COLOR_TRANSPARENT { 0, 0, 0, 0 }

class MyDialog 
{
	idd = -1;
	movingEnable = 1;
	objects[] = {};
	controlsBackground[] = { MyDialogBackground };
	controls[] = { MyDialogText };

	class MyDialogBackground : RscText 
    {
		colorBackground[] = COLOR_HALF_BLACK;
		x = 0.7;  y = 0.1;
		w = 0.25; h = 0.15;
	};

	class MyDialogText : RscText 
    {
		style = ST_MULTI;
		colorBackground[] = COLOR_TRANSPARENT;
		colorText[] = COLOR_LIGHTBROWN;
		text = "No power in the 'Verse can stop me.";
		lineSpacing = 1;
		x = 0.71; y = 0.11;
		w = 0.23; h = 0.13;
	};
};

Useful includes

Arma 3 offers a wide range of useful files which can be included to get access to some helpful macros.

Include Code	Description / Content
#include "\a3\3DEN\UI\macros.inc"	Defines for Eden Editor like colors, text sizes custom pixel grid macros.
#include "\a3\3DEN\UI\macroexecs.inc"	Defines for Eden Editor to calculate text sizes etc.
#include "\a3\ui_f\hpp\definedikcodes.inc"	Useful when working with custom shortcuts. Contains defines for key codes.
#include "\a3\ui_f\hpp\definecommoncolors.inc"	Colors used in Arma 3, like background color set by the user.
#include "\a3\ui_f\hpp\definecommongrids.inc"	UI grids such as GUI_GRID and all its variants.
#include "\a3\ui_f\hpp\defineresincl.inc"	IDCs and IDDs of many Arma 3 UIs.

Eventhandlers

To give the dialog its functionality, one will have to use user interface eventhandlers (UIEH). This way you can assign actions to buttons, listboxes, etc.

• User Interface Event Handlers

Scripting

There are several commands to influence your dialog after its initial creation. These command are listed on the following pages:

• GUI Commands
• GUI Functions

Native Arma 3 GUIs

Arma 3 comes with a wide varity of various displays and dialogs. They can be found in:

• configFile usually with names like RscSomeDisplayName or DisplaySomeDisplayName

Additonally, Arma 3 offers some customizeable GUIs which can be accessed by scripts.

• BIS_fnc_3DENShowMessage
• BIS_fnc_guiMessage
• BIS_fnc_GUIhint
• hint, hintSilent, hintC

GUI References

Sometimes it's a good idea so see how others created their GUIs. Here's a list of a few resources:

• Terra's Editing Extentions
• A3ExtendedFunctionViewer
• A3UserInputMenus
• A3ColorPicker
• 3den Enhanced

Tips for creating GUIs

• Functionality
• Layout
• Style
• Behaviour
• Customizability
• ...

Misc

• Arma_3_IDD_List
• Arma 3 User Interface Editor