Arma: GUI Configuration

From Bohemia Interactive Community
(Redirected from Dialog Control)
Jump to navigation Jump to search

Overview

Dialogs are one way to provide custom graphical user interface in your missions and allow interaction with the player as well 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).


Terminology

GUI
Graphical User Interface - Allows user interaction with the software through graphical controls like buttons, lists and so on.
UI
User Interface - Allows the user to interact with the software through a console application.
IGUI
Integrated Graphical User Interface - A term usually encountered when talking about vanilla menus in Arma 3.

User Interface Types

Dialog

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

Display

  • Can be created upon an existing display. Parent display will be hidden.
  • Player movement is not blocked by display, if it has not been blocked by its parent display already.
Generally speaking, dialogs and displays are identical. They are only differentiated by the way they are created (createDisplay, createDialog).

HUD

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 or class 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 or class Contains class names of all foreground controls associated to this dialog.
objects Array or class List of all DialogControls-Objects type controls

Example Config

Show Example Config


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 to close a dialog:


HUDs

HUDs are defined 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

Show Example Config


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.

Special (button) IDCs (according to \a3\ui_f\hpp\defineResincl.inc):

  • 1: OK (closes display when clicked upon, raises exit code 1 in the onUnload UIEH)
  • 2: Cancel (closes display when clicked upon, raises exit code 2 in the onUnload UIEH)
  • 3: Auto cancel
  • 4: Abort
  • 5: Restart
  • 6: User button
  • 7: Exit to main

While the purposes of idcs 3 to 7 remain unknown, it is advisable to give all of your controls larger numbers, eg. 100.

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 is 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 Arma 3 logo black.png1.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

A property to enable or disable a control does not exist (because of implementation issues). However, there is a simple workaround based on the onLoad UI Event Handler that can be used to disable a control in the config:

onLoad = "(_this # 0) ctrlEnable false;";

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

Show Example Config


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";


Control Type Definitions

All definitions can be retrieved with "Default" call BIS_fnc_exportGUIBaseClasses;.
Show Control Type Definitions


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 Remark
TR_SHOWROOT 1 0x01 When this style is applied, all entries even with path [] can be collapsed. Use unkown.
TR_AUTOCOLLAPSE 2 0x02 Use unknown

Control Style Definitions

All definitions can be retrieved with "Default" call BIS_fnc_exportGUIBaseClasses;.
Show Control Style Definitions


Positioning

A detailed description of how you can achieve proper GUI placement can be found on the Arma 3: GUI Coordinates page.

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 re-declare all attributes for every class definition.

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

View the dedicated inheritance page for more information.

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 is not applicable). It can also make your code more readable sometimes.

Example Config

Show Example Config


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.

User Interface Event Handlers

User Interface Event Handlers are a key component of any Arma 3 GUI. See User Interface Event Handlers.


Scripting

There are several functions and commands to edit your dialog after its creation. These functions and commands can be found here:


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.


GUI References

It is sometimes a good idea so see how others created their GUIs. Here is a list of a few resources:

Tips for creating GUIs

  • Functionality
  • Layout
  • Style
  • Behaviour
  • Customizability


Tutorials


See Also