Arma: GUI Configuration: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Some wiki formatting)
 
(184 intermediate revisions by 18 users not shown)
Line 1: Line 1:
== Introduction ==
{{TOC|side}}
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|code]]. They are defined as classes in the [[Description.ext|missionConfigFile]] ([[Description.ext|description.ext]]), [[campaignConfigFile]] ([[Campaign Description.ext]]) or [[configFile]] ([[config.cpp]]).
<gallery mode="nolines" class="center" widths=150px>
A3_GUI_Example_1.jpg|Custom Briefing Editor
A3_GUI_Example_2.jpg|Teamswitch GUI
A3_GUI_Example_3.jpg|Dynamic Groups GUI
</gallery>


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|code]]. They are defined as classes in the [[Description.ext|description.ext]] file.


'''Notice:''' If you change your description.ext file while the mission is still open in the editor, you will have to reload or resave the mission before the changes will take effect.  This behaviour is due to the fact the mission editor only reads the description.ext file during save/load.
=== Terminology ===


'''Warning:''' If there are syntactic errors in your description.ext file (e.g. incorrect spelling of keywords), then the game will simply return to desktop while processing the file, stating the nature and location of the error that caused it.
; GUI
: Graphical User Interface - Allows user interaction with the software through graphical controls like buttons, lists and so on.


Most of these definitions work with numeric constants, which are presented in [[#Constants|the following section]]. For readability purposes you should consider favoring them instead of the actual integers.
; UI
: User Interface - Allows the user to interact with the software through a console application.


* Positions and dimensions (x, y, w, h) aswell as font sizes are '''relative''' to the screen (and '''not''' pixel values), normally ranging from 0.0 to 1.0; 0.0 means 0% of the screen width (e.g. the left side of the screen in the context of x or y, or 0% length in the context of width and height). This makes font sizes usually a very small number (~0.02). This percentage is only based on the standard 4:3 screen area.  A dialog will look the same for all users, regardless of their monitor's aspect ratio, as long as their aspect ratio is set correctly for their monitor in the display options panel. This is only likely to be a problem, should you be intentionally trying to fill the whole screen with a dialog and the user has a non-4:3 monitor.  In all other situations, this behaviour is likely to be to your benefit, as you don't have to worry about users with different setups.  Keep this in mind.  You can set your positions and dimension outside of 0-1 if you wish. For the most part though, it's not recommended as parts of your dialog will be drawn outside the standard 4:3 screen area.  This means the majority of users could not access the items outside this area.  One practical application for that though, is that it lets you make a solid background that blocks out the screen for all users regardless of their monitor's screen aspect ratio.  This can be done by setting a panel's position and dimensions to "X = -1; Y = -1; W = 3; h = 3".
; IGUI
* Colors are usually defined in the following convention: <tt>{ Red, Green, Blue, Alpha }</tt>, each ranging from 0.0 to 1.0 as well. To easily convert from the more standard 0-255 range, simply divide the 255 based number by 255.
: Integrated Graphical User Interface - A term usually encountered when talking about vanilla menus in {{arma3}}.
* Sounds are usually defined in the following convention: <tt>{ "file.ogg", volume, pitch }</tt>, Volume ranges from 0.0 to 1.0.  Pitch is a floating point number ranging from 0.0 to 4.0.  2.0 doubles the pitch (makes it higher), 0.5 halfs the pitch (makes it deeper) and 1.0 is normal.  


<!-- I have no idea. Someone please correct the sound convention. -->


You can find a complete list of scripting related GUI functions in [[:Category:Command Group: GUI Control]].
== User Interface Types ==


===Dialogs and Displays===
=== Dialog ===


In theory, there is no difference.
* Can be created upon an existing display. Parent display will be hidden.


This document attempts to cover the genre of controls (idc's), dialogs (idd's), and displays (also idd's). It attempts to apply the same consistency as one (currently) finds in mission description.ext's, as well as configs. Specifically, config.cpp's relating to the so-called 'user ui'.
** Player movement is blocked by dialog
** '''Commands:''' [[createDialog]], [[closeDialog]], [[allControls]], [[dialog]]


This document must be inaccurate because *everything* config-dialogs/displays/controls is at the whim of engine revisions and which flavor pizza was eaten on Friday night.
=== Display ===


The token names used for color (purely as an example) are currently not only inconsistent across controls, they are subject to whim. Any addition to the engine's capabilities (with new control types) will (if history is the judge) produce new token names, that do exactly same as different names in other controls. color[]=, colorText[]= ActiveColor[]=ShadowColo[]= (an engine typo) =ColorActive[]=FrenchFries[]=..... all meaning the same thing (and NOT meaning the same thing, depending on the control's type)
* 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.
** '''Commands:''' [[createDisplay]], [[closeDisplay]], [[allControls]], [[allDisplays]]


Unfortunately, the current state of play with Arrowhead engine (and all engines prior) is that the entire caboodle is arbitrary. In terms of ui.config.cpp, most controls and most displays are hard-wired to the engine.  
{{Feature|informative|Generally speaking, dialogs and displays are identical. They are only differentiated by the way they are created ([[createDisplay]], [[createDialog]]).}}


For config.cpp's, one of the hardest animals to deal with is the fixed-in-concrete classname definitions, aligned with matching fixed-in-concrete idd's.
=== HUD ===


Purely as an example
* 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]]


RscDisplaySelectIsland uses an idd of 51. Both are currently nuclear fallout shelters (hardened concrete). you can't change the name, you can't change the idd.
{{Feature|informative|Some of the commands have different effects. Please check the command's biki page for detailed information.}}


The engine is hard wired (with the equivalent of) createDisplay "RscDisplaySelectIsland" via various fixed-in-conrete idc's of other displays. There is no action, no eventhandler, no over-ride, which you can apply to this 'behavior'. Similarly, the engine reacts to that displays controls with hard-wired _display ctrlParent 'control' expecting the _display idd to be 51 to proceed any further. (in this case, open the editor and show the selected island's map)


There is nothing wrong with this approach. It has been the same since CWC. But, with the increasing abundance of official bis sqf scripts which specifically deal with and react to ui controls and displays (see \ca\ui\scripts). The burden of the engine dealing with this is becoming anachronistic and contrary to the flexibility that those scripts provide.
== Display and Dialog ==


In short:
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.
*The token names described here as general, have to be taken in context to the control/display they are used in. There can be no guarantee that they are the same for all controls, and no guarantee that they wont change. the bin\config.bin of the engine, is the ultimate umpire. It declares what this engine, expects.
*Any reference to eventHandlers and 'actions' are subject to the whim of the engine. It may, or may not, force-over-ride any action depending on display(idd) and it's control (idc)
*Any class definition may or may not be fixed in concrete. Some classnames are, some classnames are not. Which ones, depend on whether it's Monday afternoon.


== Constants ==
=== Properties ===


These are constants generally used to maintain a certain degree of readability. They represent integer values for use with ''type'' and ''style'' properties of controls. You can also define other constants, e.g. the font name.
{| class="wikitable sortable" Style = "Width: 100%"
 
<code><nowiki>// Control types
#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_SHORTCUT_BUTTON  16 // Arma 2 - textured button
 
#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_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_List_N_Box      102 // Arma 2 - N columns list box
 
 
// Static styles
#define ST_POS            0x0F
#define ST_HPOS          0x03
#define ST_VPOS          0x0C
#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_TYPE          0xF0
#define ST_SINGLE        0
#define ST_MULTI          16
#define ST_TITLE_BAR      32
#define ST_PICTURE        48
#define ST_FRAME          64
#define ST_BACKGROUND    80
#define ST_GROUP_BOX      96
#define ST_GROUP_BOX2    112
#define ST_HUD_BACKGROUND 128
#define ST_TILE_PICTURE  144
#define ST_WITH_RECT      160
#define ST_LINE          176
 
#define ST_SHADOW        0x100
#define ST_NO_RECT        0x200 // this style works for CT_STATIC in conjunction with ST_MULTI
#define ST_KEEP_ASPECT_RATIO  0x800
 
#define ST_TITLE          ST_TITLE_BAR + ST_CENTER
 
// Slider styles
#define SL_DIR            0x400
#define SL_VERT          0
#define SL_HORZ          0x400
 
#define SL_TEXTURES      0x10
 
// Listbox styles
#define LB_TEXTURES      0x10
#define LB_MULTI          0x20
 
#define FontM            "Zeppelin32"</nowiki></code>
 
'''Notice:''' All examples within this article use these constants. If you do not include them, or name them differently, these examples won't work as-is.
 
== Attributes ==
 
A list of all available attributes (properties) without explanation, originally posted by ColonelSandersLite, can be found [http://www.flashpoint1985.com/cgi-bin/ikonboard311/ikonboard.cgi?act=ST;f=71;t=64450;st=15 here]
 
== Dialogs ==
 
Dialogs are parent containers for the actual controls it contains. Their definition contains several properties on the controls it contains, how the dialog can be addressed, and whether or not the player is able to continue regular movement while the dialog is shown.
 
They can be defined in the [[Description.ext|description.ext]] file or externalized to separate hpp-files, which are included in the description.ext file using the [[PreProcessor_Commands#.23include|#include]] preprocessor directive. The latter method is generally a good idea to split a large description.ext file into several small chunks in order to keep track of what's where.
 
Most often, controls of a dialog are defined within the definition of the dialog itself, though it's a good practice to generalize common controls in a base definition in the global scope. See [[#Best practice|best practice]] for details. For simplicity we won't apply this practice in the following code examples.
 
 
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
! Name !! Type!! Remark
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|-
| '''idd'''
| '''idd'''
| integer
| Integer
| The unique ID number of this dialog. can be -1 if you don't require access to the dialog itself from within a script.
| 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'''
| '''movingEnable'''
| boolean
| [[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)
| 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 {{arma3}}
|-
|-
| '''enableSimulation'''
| '''enableSimulation'''
| boolean
| [[Boolean]]
| Specifies whether the game continues while the dialog is shown or not.
| 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#onLoad|User Interface Event Handlers]]
|-
| '''onUnload'''
| [[String]]
| Expression executed when the dialog is closed. See [[User_Interface_Event_Handlers#onUnload|User Interface Event Handlers]]
|-
|-
| '''controlsBackground'''
| '''controlsBackground'''
| array
| [[Array]] or class
| Contains class names of all background controls associated to this dialog.<br>
| Contains class names of all background controls associated to this dialog.<br>
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).
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'''
| '''controls'''
| array
| [[Array]] or class
| Contains class names of all foreground controls associated to this dialog.
| Contains class names of all foreground controls associated to this dialog.
|-
|-
| '''objects'''
| '''objects'''
| array
| [[Array]] or class
|
| List of all [[DialogControls-Objects]] type controls
|-
|}
|}<br clear="all">


=== Example Config ===


Setting the ''idd'' property to a non-negative (i.e. "useful") number is only required if you want to access the dialog itself via the [[findDisplay]] function. Accessing the dialog itself via the ''idd'' property though does not mean that you can implicitly access the controls within the dialog. For that you will have to rely on the control's ''idc'' properties. Hence, in most basic cases you won't need it and -1 should be sufficient.
<spoiler text="Show Example Config">
 
<syntaxhighlight lang="cpp">
It's also noteworthy for more advanced developers that there is a numeric property named '''''access''''' with the following possible values (and their named constants):
class DefaultDialog
* '''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.
This does not have any impact other than limiting what deriving classes are allowed to (re-)specify. Generally this is not required for dialogs or dialog controls and can be safely ignored.
 
Here's an example of a dialog that will only display ''Hello world'' in the top right corner of the screen. If you get confused by the ''MyHelloText'' class, just ignore it for the moment until you have read details on the definition of controls  in the following chapter, [[#Controls|Controls]].
 
* '''Example 1:'''
<code><nowiki>#define true 1
#define false 0
 
class MyHelloWorldDialog {
idd = -1;                      // set to -1, because we don't require a unique ID
movingEnable = true;          // the dialog can be moved with the mouse (see "moving" below)
enableSimulation = false;      // freeze the game
controlsBackground[] = { };    // no background controls needed
objects[] = { };              // no objects needed
controls[] = { MyHelloText };  // our "Hello world" text as seen below:
class MyHelloText {
idc = -1;              // set to -1, unneeded
moving = 1;            // left click (and hold) this control to move the dialog
                      // (requires "movingEnabled" to be 1, see above)
type = CT_STATIC;      // constant
style = ST_LEFT;      // constant
text = "Hello world";
font = FontM;
sizeEx = 0.023;
 
colorBackground[] = { 1, 1, 1, 0.3 };
colorText[] = { 0, 0, 0, 1 };
 
x = 0.8;
y = 0.1;
w = 0.2;
h = 0.05;
};
};</nowiki></code>
 
* '''Example 2:'''
The benefit of the following syntax is that you do not need to double list all of the control class names.
<code><nowiki>class RscText; // assume external declaration
 
class MyHelloWorldDialog {
idd = -1;
idd = -1;
movingEnable = 0;
access = 0;
class controlsBackground {  
movingEnable = true;
// define controls here
onLoad = "hint str _this";
onUnload  = "hint str _this";
enableSimulation = false;
class ControlsBackground
{
//Background controls
};
};
class objects {  
class Controls
// define controls here
{
//Controls
};
};
class controls {  
class Objects
// define controls here
{
//Objects
class MyHelloText: RscText {
idc = -1;
text = "Hello world";
x = 0.80;
y = 0.10;
w = 0.20;
h = 0.05;
};
};
};
};</nowiki></code>
};
 
</syntaxhighlight>
Once you have defined (or prototyped) dialogs you want to use, be sure to reload the mission in the editor if it is already running.
</spoiler>
 
=== Creating dialogs ===
 
Dialogs can then be created and shown using the [[createDialog]] function. If you do so by script and await a responsive action from the user, you might also want to wait until the user has closed the dialog by using a wait statement (e.g. [[waitUntil]]) in conjunction with the [[dialog]] function, if you intend to handle the dialog result within the same script.
 
* '''Example:'''
<code><nowiki>_ok = createDialog "MyHelloWorldDialog";
waitUntil { !dialog }; // hit ESC to close it
hint "Dialog closed.";</nowiki></code>
 
=== Closing dialogs ===


In most use cases a dialog "closes itself", ie. by invoking the [[closeDialog]] function in an ''action'' field. However dialogs don't necessarily have to close themselves, but can also be closed from the "outside" (ie. by scripts or triggers). Once closed, the [[dialog]] function returns <tt>false</tt> and wait statements with a <tt>!dialog</tt> condition will end.
=== Opening a display or dialog ===


* '''Example''' - close by action
There are two ways of creating a display or dialog. One can either use [[createDialog]] or [[createDisplay]] command.
<code><nowiki>class CloseButton : RscButton {
/* ... */
type = CT_BUTTON;
text = "Close";
action = "closeDialog 0";
}</nowiki></code>
* '''Example''' - close by external request
<code><nowiki>closeDialog 0</nowiki></code>
 
== Controls ==


Controls are the actual content of dialogs and can be anything, ranging from simple solid rectangles to a complex 3d object within a dialog. Like dialogs, controls can have a unique ID saved in the ''idc'' property to access them from within scripts using [[:Category:Command_Group:_GUI_Control|GUI functions]].
=== Closing a display or dialog ===


The type of the control is usually set in the ''type'' property. Different types allow or require a different set of properties. However most controls share a set of properties in addition to the properties described in the following sections:
There are several ways to close a dialog:
* Pressing {{Controls|Esc}}
* Clicking a button with IDC 0, 1 or 2
* [[closeDialog]]
* [[closeDisplay]]


{| border="1" align="left" cellpadding="3" cellspacing="0" |
==== Exit Codes ====
! colspan="3" bgcolor="#bbbbff" | Common properties
Exit codes are a way to determine in what way a display was closed. The [[User_Interface_Event_Handlers#onUnload|onUnload UIEH]] has the exit code as one of its parameters. This way you can handle different user decisions, eg. save a value if the user confirms it or discard changes when the user pressed a cancel button. Macros for the different exit codes can be found in {{hl|\a3\ui_f\hpp\defineResincl.inc}}:
<syntaxhighlight lang="cpp">
// Predefined controls
#define IDC_OK 1
#define IDC_CANCEL 2
#define IDC_AUTOCANCEL 3
#define IDC_ABORT 4
#define IDC_RESTART 5
#define IDC_USER_BUTTON 6
#define IDC_EXIT_TO_MAIN 7
</syntaxhighlight>
{| class="wikitable"
|-
|-
! bgcolor="#ddddff" | Name
! Exit Code !! Macro !! Comment
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|-
| '''idc'''
| 1 || IDC_OK || Dialog was closed with a positive outcome
| 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'''
| 2 || IDC_CANCEL || Dialog was closed with a negative outcome
| boolean
| whether the dialog will be moved if this control is dragged (requires "movingEnable" to be 1 in the dialog)
|-
|-
| '''type'''
| 3 || IDC_AUTOCANCEL || ?
| integer [[#Constants|CT_TYPES]]
|  
|-
|-
| '''style'''
| 4 || IDC_ABORT || When used on the mission display (Display #46) it simulates "Save and Exit" button from escape menu
| integer [[#Constants|CT_STYLES]]
| can be combinatorial: style = "0x400+0x02+0x10";
|-
|-
| '''x'''
| 5 || IDC_RESTART || ?
| float
| the offset from the left side of the window (0..1; 0.0 = left side; 1.0 = right side)
|-
|-
| '''y'''
| 6 || IDC_USER_BUTTON || ?
| float
| the offset from the top side of the window (0..1; 0.0 = left side; 1.0 = right side)
|-
|-
| '''w'''
| 7 || IDC_EXIT_TO_MAIN || ?
| float
|}
| the width of the control (0..1)
 
|-
== HUDs ==
| '''h'''
| float
| the height of the control (0..1)
|-
| '''sizeEx'''
| float
| the font size of text (0..1)
|-
| '''font'''
| string
| the font to use. See the list of [[Fonts#Available_Fonts|available fonts]] for possible values
|-
| '''colorText'''
| color array
| text color
|-
| '''colorBackground'''
| color array
| background color
|-
| '''text'''
| string
| the text to display initially
|-
|}<br clear="all">


To save space and effort, it is generally a good idea to make use of class polymorphism, i.e. deriving from very basic classes that already have some specific properties set. See the [[#Best_Practice|Best Practice]] chapter for details.
HUDs are defined in the class RscTitles, unlike displays or dialogs which are root classes in the config file. Additionally, their properties are different.
==GENERAL TEXT==
=== CT_STATIC=0 ===


Static controls represent exactly that: static data. Static means there is NO possible user interaction. CT_STATIC is primarily used for texts, dialog backgrounds, pictures (and video). The constant ''type'' property for these controls usually is <tt>CT_STATIC</tt>.
=== Properties ===


{| border="1" align="left" cellpadding="3" cellspacing="0" |
{| class="wikitable sortable" Style="Width: 100%"
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
! Name !! Type !! Remark
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|-
| '''autoplay'''
| '''idd'''
| boolean
| Integer
| video only
| 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.
|-
|-
| '''blinkingPeriod'''
| '''fadeIn'''
| float (Seconds)
| Integer
| Makes the text start transparent, go to full opacity and back to full transparent in the amount of time specified.
| Duration of fade in effect when opening in seconds.
|-
|-
| '''key'''
| '''fadeOut'''
| string
| Integer
| a possibly quite useless xbox value
| Duration of fade out effect when closing in seconds.
|-
|-
| '''loops'''
| '''duration'''
| integer
| Integer
| video only
| Duration the HUD is displayed after opening in seconds. Use a very large number to have it always open.
|-
|-
| '''lineSpacing'''
| '''onLoad'''
| float
| [[String]]
| line spacing. Required, if the style was set to <tt>ST_MULTI</tt>.
| Expression executed when the dialog is opened. See [[User_Interface_Event_Handlers#onLoad|User Interface Event Handlers]]
|-
|-
| '''fixedWidth'''
| '''onUnload'''
| boolean?
| [[String]]
|  
| Expression executed when the dialog is closed. See [[User_Interface_Event_Handlers#onUnload|User Interface Event Handlers]]
|-
|-
| '''shadow'''
| '''controls'''
| float
| [[Array]]
| optional shadow style: 0 = none (default), 1 = drop shadow, 2 = outline
| Contains class names of all foreground controls associated to this dialog.
|-
|}
|}<br clear="all">
 


==== Static Text ====
=== Example Config ===
[[Image:Dialog controls text.jpg|thumb||''Hello world'' text with semi-transparent background]]
Most often this type of control will be used to add text to dialogs. If you want the text to change dynamically while playing the mission, you should set the ''idc'' property to a positive number, which allows usage of the [[ctrlSetText]] function. Text alignment can be controlled using the ''style'' property and the <tt>ST_*</tt> constants.


By default, this will only display a '''single line''' (and cut the overflow); use <tt>ST_MULTI</tt> if you intend to use multiple lines. This also requires setting the property ''lineSpacing'', which indicates the relative space between lines; usually, you can set this to 1 for normal line spacing.
<spoiler text="Show Example Config">
<syntaxhighlight lang="cpp">
#include "\a3\ui_f\hpp\definecommongrids.inc"


* '''Example:'''
class RscTitles
<code><nowiki>
class RscText
{
{
access = 0;
class RscInfoText
type = CT_STATIC;
{
idc = -1;
idd = 3100;
style = ST_LEFT;
fadein = 0;
w = 0.1; h = 0.05;
fadeout = 0;
//x and y are not part of a global class since each rsctext will be positioned 'somewhere'
duration = 1e+011;
font = "TahomaB";
onLoad = "uinamespace setVariable ['BIS_InfoText',_this select 0]";
sizeEx = 0.04;
onUnLoad = "uinamespace setVariable ['BIS_InfoText', nil]";
colorBackground[] = {0,0,0,0};
class Controls
colorText[] = {1,1,1,1};
{
text = "";
class InfoText
fixedWidth = 0;
{
shadow = 0;
idc = 3101;
};
style = "0x01 + 0x10 + 0x200 + 0x100";
class dialog
font = "RobotoCondensedBold";
{
x = "(profileNamespace getVariable [""IGUI_GRID_MISSION_X"", (safezoneX + safezoneW - 21 * (GUI_GRID_WAbs / 40))])";
  class controls
y = "(profileNamespace getVariable [""IGUI_GRID_MISSION_Y"", (safezoneY + safezoneH - 10.5 * (GUI_GRID_HAbs / 25))])";
  {
w = "20 * (GUI_GRID_WAbs / 40)";
    class Background: RscText
h = "5 * ((GUI_GRID_WAbs / 1.2) / 25)";
    {
colorText[] = {1,1,1,1};
    text = "whatever";
colorBackground[] = {0,0,0,0};
    colorBackground[] = {0,0,0,1};
text = "";
    x = 0;   y = 0;  w = 1;  h = 1;
lineSpacing = 1;
    colorText[] = {0,0,0,0};
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};
};
};
};
};
};
</syntaxhighlight>
</spoiler>


</nowiki></code>


==== Static Background ====
== Controls ==
[[Image:Dialog controls background.jpg|thumb||Semi-transparent background]]
One can also use this control type to add solid background to dialogs by simply leaving the ''text'' property empty. This way, it will look like a regular rectangle.
 
* '''Example:'''
<code><nowiki>class MyRedBackgroundExample {
/* ... same as the text example, except for */
colorBackground[] = { 1, 0.1, 0.1, 0.8 };
text = "";
};</nowiki></code>
 
==== Static Pictures ====
Using specific style constants you can enhance your dialogs with pictures too. These pictures should reside in your mission folder as [[PAA File Format|paa]]-files. Then set your ''style'' property to <tt>ST_PICTURE</tt> (to display it once) or <tt>ST_TILE_PICTURE</tt> (to tile it) and use the ''text'' property to locate the paa image you want to use, relative to your addon or mission folder (''absolute paths cannot be used'').
 
[[Image:Dialog controls picture.jpg|thumb|100px|Dialog control showing a picture]]
* '''Example:'''
<code><nowiki>
class RscPicture
{
access = 0;
type = CT_STATIC;
idc = -1;
style = 48;//ST_PICTURE
colorBackground[] = {0,0,0,0};
colorText[] = {1,1,1,1};
font = "TahomaB";
sizeEx = 0;
lineSpacing = 0;
text = "";
fixedWidth = 0;
shadow = 0;
};
class dialog
{
class controls
{
  class Picture: RscPicture
  {
  text = "#(argb,8,8,3)color(1,1,1,1)";
  or
  text = "mypicture.paa";
  x = 0.46;
  y = 0.63;
  w = 0.08;
  h = 0.1;
  };
};
};
 
</nowiki></code>
 
====  Static Videos ====
[[Image:arma2oa_1.56.gif]]
 
All setings are same as for pictures, only source file must be of ''.OGV'' format. Two additional properties are available - ''autoplay'' (when 1, video starts automatically) and ''loops'' (defines how many times video will be played in loop).
 
For video encoding, you can use:
* ffmpeg2theora: http://www.v2v.cc/~j/ffmpeg2theora/download.html
* Theora Converter .NET: http://sourceforge.net/projects/theoraconverter/ (GUI for ffmpeg2theora)
 
* '''Example:'''
<code><nowiki>class MyVideoExample {
/* ... same as the picture example, with addition of */
text = "myVideo.ogv";
autoplay = 1;
loops = 10;
};</nowiki></code>


===CT_STRUCTURED_TEXT=13===
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.


The Structured Text control can display [[Structured Text]]. This is a separate [[Data Types|data type]] in Arma.
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.


Structured Text can not only hold some text values, it also can contain some attributes to format the text, as you can see in the example picture below.
=== Common Properties ===


You ''can'' contain a subclass '''Attributes''' to change the default attributes for your control. But the ''Attributes class'' and all of its attributes are optional and must not be specified.
{| class="wikitable" width="100%"
 
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
! Name
! bgcolor="#ddddff" | Type
! Type
! bgcolor="#ddddff" | Remark
! Remark
|-
|-
| '''Attributes'''
| '''idc'''
| class
| Integer
| see below
| The unique ID number of this control. Can be -1 if you don't require access to the control itself from within a script.<br>
Special (button) IDCs (according to \a3\ui_f\hpp\defineResincl.inc):
* 1: OK (closes display when clicked upon, raises exit code 1 in the [[User_Interface_Event_Handlers#onUnload|onUnload UIEH]])
* 2: Cancel (closes display when clicked upon, raises exit code 2 in the [[User_Interface_Event_Handlers#onUnload|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.
|-
|-
| '''ShowImage'''
| '''moving'''
| boolean
| [[Boolean]]
| found in an xbox dialog and probably quite useless
| Whether the dialog will be moved if this control is dragged (may require "movingEnable" to be 1 in the dialog. In {{arma3}} works regardless). Another way of allowing moving of the dialog is to have control of style ST_TITLE_BAR
|-
|-
|}<br clear="all">
| '''type'''
 
| Integer
 
| See [[#Control Types|Control Types]]
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="4" bgcolor="#bbbbff" | Optional SubClass Attributes Properties
|-
|-
! bgcolor="#ddddff" | Name
| '''style'''
! bgcolor="#ddddff" | Type
| Integer
! bgcolor="#ddddff" | Remark
| See [[#Control Styles|Control Styles]]. <syntaxhighlight lang="cpp" inline>style = "0x400+0x02+0x10";</syntaxhighlight>
! bgcolor="#ddddff" | Default Value
|-
|-
| '''font'''
| '''x/y/w/h'''
| string
| [[Number]]
| fontname to use
| The position and size of the control in fractions of screen size.
| "Zeppelin32"
|-
|-
| '''color'''
| '''sizeEx'''
| string
| [[Number]]
| text color defined in HMTL-like syntax.
| The font size of text in fractions of screen size. Behaves similar to '''h''' property. For some controls it is named '''size'''.
| "#ffffff"
|-
|-
| '''align'''
| '''font'''
| string
| [[String]]
| align of text. Values can be "left", "center" or "right"
| The font to use. See the list of [[Fonts#Available_Fonts|available fonts]] for possible values.
| "center"
|-
|-
| '''valign'''
| '''colorText'''
| string
| [[Array]]
| vertical align of text. Values can be "top", "middle", "bottom".
| Text color
| "middle"
|-
|-
| '''shadow'''
| '''colorBackground'''
| integer
| [[Array]]
| affects the shadow of the text.
| Background color
| 1 (true)
|-
| '''shadowColor'''
| string
| shadow color defined in HMTL-like syntax.
| "#000000"
|-
| '''size'''
| float
| Set the size of the text where 1 is the size value of parent class.
| 1
|-
|}<br clear="all">
 
The following example uses almost the same code as the controls shown in the example screenshot.
[[Image:ControlStructuredText.jpg|thumb|400px|A StructuredText control based on sample code]]
* '''Example:'''
<code><nowiki>class MyRscStructuredText {
  idc = -1;
  type = CT_STRUCTURED_TEXT;  // defined constant
  style = ST_LEFT;            // defined constant
  colorBackground[] = { 1, 1, 1, 1 };
  x = 0.1;
  y = 0.1;
  w = 0.3;
  h = 0.1;
  size = 0.018;
  text = "";
  class Attributes {
    font = "TahomaB";
    color = "#000000";
    align = "center";
    valign = "middle";
    shadow = false;
    shadowColor = "#ff0000";
    size = "1";
  };
};</nowiki></code>
* '''Helpful Script Commands:'''
'''[[ctrlSetStructuredText]], [[lineBreak]], [[parseText]], [[composeText]], [[image]]'''
 
===CT_HTML=9===
 
The HTML control is well known as the "notebook" in the Map-View of the game. It can display a text over more pages and can inherit links to other, own defined sections. It has some simple formatting possibilities. It also can display images.
 
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''align'''
| string
| "center"
|-
| '''cyclelinks'''
| boolean
|
|-
| '''filename'''
| string
| the html file to load into the control at startup
|-
|-
| '''text'''
| '''text'''
| string
| [[String]]
| the text the control should display. Leave it blank, if you set a '''filename'''
| The text '''or picture''' to display.
|-
|-
| '''colorBold'''
| '''shadow'''
| color array
| Integer
| color of '''bold''' text (between &lt;b&gt; and </b> tags)
| Can be applied to most controls (0 = no shadow, 1 = drop shadow with soft edges, 2 = stroke).
|-
|-
| '''colorLink'''
| '''tooltip'''
| color array
| [[String]]
| text color of links (between <a href="#Sectionname> and </a>)
| 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 {{GVI| arma3|1.48}}, most controls now support tooltips. A linebreak can be created by adding '''\n'''.
|-
|-
| '''colorLinkActive'''
| '''tooltipColorShade'''
| color array
| [[Array]]
| text color of the active link (normaly the fist on in page)
| Tooltip background color
|-
| '''colorPicture'''
| color array
| color of transparent part of image
|-
| '''colorPictureBorder'''
| color array
| color of the borader arround image
|-
| '''colorPictureLink'''
| color array
| color of transparent part of image within links
|-
| '''colorPictureSelected'''
| color array
| color of transparent part of image within active links
|-
|-
| '''tooltipColorText'''
| '''tooltipColorText'''
| color array
| [[Array]]
|
| Tooltip text color
|-
|-
| '''tooltipColorBox'''
| '''tooltipColorBox'''
| color array
| [[Array]]
|
| Tooltip border color
|-
|-
| '''tooltipColorShade'''
| '''autocomplete'''
| color array
| [[String]]
|
| (where applicable) Option for entry fields (e.g. RscEdit) to activate autocompletion. For known script commands and functions use autocomplete = "scripting".
|-
| '''prevPage'''
| string argb
| filename of image which is used as left arrow
|-
| '''nextPage'''
| string argb
| filename of image which is used as right arrow
|-
! colspan="3" bgcolor="#bbbbff" | Properties of subclass (H1-H6,P)
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''font'''
| string
| font to use for default text
|-
| '''fontBold'''
| string
| font to use within bold tags
|-
|-
| '''sizeEx'''
| '''url'''
| float
| [[String]]
| font size
| (where applicable) URL which will be opened when clicking on the control. Used on e.g. a button control. Does not utilize the Steam Overlay browser if enabled by default, opens the link in the default browser set by the OS.
|-
|-
|}<br clear="all">
| '''overlayMode'''
 
| [[Number]]
The following example uses almost the same code as the controls shown in the example screenshot.
| {{GVI|arma3|2.10}} (where applicable) 0 - opens URL in default browser; 1 - opens URL in Steam overlay id enabled, otherwise in default browser; 2 - opens URL in Steam overlay, shows error message box (with button to use default browser) if Steam overlay is disabled.
[[Image:HTMLControl.jpg|thumb|400px|A HTML control with some different formatted text and links]]
|}
* '''Example:'''
<code><nowiki>class MyRscHTML {
  idc = -1;
  type = CT_HTML; // defined constant (9)
  style = ST_LEFT; // defined constant (0)
 
  x = 0.1;
  y = 0.1;
  w = 0.6;
  h = 0.5;
 
  filename = "test.html";
  text="";
 
  colorBackground[] = {1,1,1,0.5};
  colorBold[] = {1, 0, 0, 1};
  colorLink[] = {0, 0, 1, 1};
  colorLinkActive[] = {1, 0, 0, 1};
  colorPicture[] = {1, 1, 1, 1};
  colorPictureBorder[] = {1, 0, 0, 1};
  colorPictureLink[] = {0, 0, 1, 1};
  colorPictureSelected[] = {0, 1, 0, 1};
  colorText[] = {0, 0, 0, 1};
 
  prevPage = "\ca\ui\data\arrow_left_ca.paa";
  nextPage = "\ca\ui\data\arrow_right_ca.paa";
class H1 {
font = "Zeppelin32";
fontBold = "Zeppelin33";
sizeEx = 0.02474;
};
class H2 {
font = "Zeppelin32";
fontBold = "Zeppelin33";
sizeEx = 0.0286458;
};
class H3 {
font = "Zeppelin32";
fontBold = "Zeppelin33";
sizeEx = 0.0286458;
};
class H4 {
font = "Zeppelin33Italic";
fontBold = "Zeppelin33";
sizeEx = 0.0208333;
};
class H5 {
font = "Zeppelin32";
fontBold = "Zeppelin33";
sizeEx = 0.0208333;
};
class H6 {
font = "Zeppelin32";
fontBold = "Zeppelin33";
sizeEx = 0.0208333;
};
class P {
font = "Zeppelin32";
fontBold = "Zeppelin33";
sizeEx = 0.0208333;
};
};</nowiki></code>
* '''Helpful Script Commands:'''
'''[[htmlLoad]]'''
 
== BUTTONS ==


Buttons are one way to add interactivity to your dialogs. Their corresponding ''type'' property is <tt>CT_BUTTON</tt>.
A property to enable or disable a control does not exist (because of implementation issues). However, there is a simple workaround based on the [[User_Interface_Event_Handlers#onLoad|onLoad]] UI Event Handler that can be used to disable a control in the config:
<syntaxhighlight lang="cpp">onLoad = "(_this # 0) ctrlEnable false;";</syntaxhighlight>


Buttons can have different states (see screenshot) and will render slightly different to give the user a visual feedback on the button's state:
=== Attributes Class ===
* '''Enabled''': the button has not been [[ctrlEnable|disabled]], it currently doesn't have any mouse or keyboard related focus
* '''Disabled''': the button has been explicitly disabled. It will not be clickable.
* '''Enabled''' + '''Focused''': As enabled; additionally it will have a small border of the color defined in the ''colorFocused'' property. This occurs when the button currently has focus (ie. is the default button or has been selected via the ''Tab'' key).
* '''Enabled''' + '''Active''': As enabled; additionally it will have a different background as specified in the ''colorBackgroundActive'' background. This occurs when the mouse is currently hovering over an unfocused button.
* '''Enabled''' + '''Active''' + '''Focused''': The combined result of the above two states. The mouse is currently hovering over the button in question and it has input focus.


Button can also have code attached to it in the ''action'' property. This code will be run when the button is clicked. Most often, you will have at least one button that closes the dialog via [[closeDialog]]. In this case you can provide ''0'' as the right-side parameter to close the currently open dialog.
{| class="wikitable" width="70%"
====CT_BUTTON=1====
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
! Name
! bgcolor="#ddddff" | Type
! Type
! bgcolor="#ddddff" | Remark
! Remark
|-
|-
| '''action'''
| '''font'''
| string
| [[String]]
| a statement that is executed when the button is not disabled and clicked
| [[FXY_File_Format#Available_Fonts|Available Fonts]]
|-
|-
| '''attributes'''
| '''color'''
| class
| HTML color
| Possibly an irrelevant xbox class
| {{Link|https://html-color-codes.info/|HTML Color Codes}}
|-
|-
| '''BorderSize'''
| '''align'''
| float
| [[String]]
| thickness of border
| "center", "left", "right"
|-
|-
| '''default'''
| '''shadow'''
| boolean
| Integer
| Whether or not this button is the dialog's initially selected button
| 0 = no shadow, 1 = drop shadow with soft edges, 2 = stroke
|-
|}
| '''colorDisabled'''
 
| color array
=== AttributesImage Class ===
| text color, if the control has been disabled via [[ctrlEnable]]
|-
| '''colorFocused'''
| color array
| color when control has received focus via tabbing or scripted methods
|-
| '''colorShadow'''
| color array
| the color of the shadow
|-
| '''colorBorder'''
| color array
| the color of the border, if any
|-
| '''borderSize'''
| float
| the width of the border
|-
| '''colorBackgroundActive'''
| color array
| color when control has received focus via mouse-over
|-
| '''colorBackgroundDisabled'''
| color array
| background color, if the control has disabled via [[ctrlEnable]]
|-
| '''offsetX'''
| float
| the relative X offset between the button and its shadow
|-
| '''offsetY'''
| float
| the relative Y offset between the button and its shadow
|-
| '''offsetPressedX'''
| float
| the relative X offset between the button and its shadow, when it's pressed
|-
| '''offsetPressedY'''
| float
| the relative Y offset between the button and its shadow, when it's pressed
|-
| '''soundEnter'''
| sound array
| the sound to play, when the cursor enters the button's bounds
|-
| '''soundPush'''
| sound array
| the sound to play, when the button has been pushed
|-
| '''soundClick'''
| sound array
| the sound to play, when the button is being released
|-
| '''soundEscape'''
| sound array
| the sound to play, when the button has been pushed and the mouse button is released when not over the control
|-
| '''size'''
| float
| possibly an irrelevant xbox dialog
|-
| '''tooltip'''
| string
| some help phrase when you hover over button
|-
|}<br clear="all">


=====Attributes class=====
{| class="wikitable" width="70%"
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
! Name
! bgcolor="#ddddff" | Type
! Type
! bgcolor="#ddddff" | Remark
! Remark
|-
|-
| '''font'''
| '''font'''
| string
| [[String]]
|
| [[FXY_File_Format#Available_Fonts|Available Fonts]] (Optional)
|-
|-
| '''shadow'''
| '''color'''
| integer
| HTML color
|
| {{Link|https://html-color-codes.info/|HTML Color Codes}}
|-
|-
| '''align'''
| '''align'''
| string
| [[String]]
| "center"
| "center", "left", "Right" (optional)
|-
| '''color'''
| color array
| "#000000"
|-
|-
|-
|}<br clear="all">
|}<br clear="all">
* '''Example:'''
<code><nowiki>
class RscButton
{
access = 0;
type = CT_BUTTON;
style = ST_LEFT;
x = 0; y = 0; w = 0.3; h = 0.1;
text = "";
font = "TahomaB";
sizeEx = 0.04;
colorText[] = {0,0,0,1};
colorDisabled[] = {0.3,0.3,0.3,1};
colorBackground[] = {0.6,0.6,0.6,1};
colorBackgroundDisabled[] = {0.6,0.6,0.6,1};
colorBackgroundActive[] = {1,0.5,0,1};
offsetX = 0.004;
offsetY = 0.004;
offsetPressedX = 0.002;
offsetPressedY = 0.002;
colorFocused[] = {0,0,0,1};
colorShadow[] = {0,0,0,1};
shadow = 0;
colorBorder[] = {0,0,0,1};
borderSize = 0.008;
soundEnter[] = {"",0.1,1};
soundPush[] = {"",0.1,1};
soundClick[] = {"",0.1,1};
soundEscape[] = {"",0.1,1};
};
class dialog
{
class controls
{
  class OK:rscButton
  {
    idc=1;// fixed engine constant
    x=y=w=y=whatever;
    text="OK"
    default=true;
  };
  class Cancel
  {
    idc=2; // fixed engine constant
    x=y=somewhere else
    default=false;
  };
  };
};


</nowiki></code>
=== Example Config ===


<spoiler text="Show Example Config">
<syntaxhighlight lang="cpp">
#include "\a3\ui_f\hpp\definecommongrids.inc"


The following example uses almost the same code as the buttons shown in the example screenshot.
class RscButton
[[Image:Dialog controls button.jpg|thumb|110px|The same button four times in different states]]
{
 
deletable = 0;
* '''Example:'''
fade = 0;
<code><nowiki>class MyButton {
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;
idc = -1;
type = CT_BUTTON;
style = 2;
style = ST_LEFT;
x = 0;
default = false;
y = 0;
font = FontM;
w = 0.095589;
sizeEx = 0.03;
h = 0.039216;
colorText[] = { 0, 0, 0, 1 };
shadow = 2;
colorFocused[] = { 1, 0, 0, 1 };   // border color for focused state
font = "RobotoCondensed";
colorDisabled[] = { 0, 0, 1, 0.7 };   // text color for disabled state
sizeEx = "GUI_GRID_HAbs / 25";
colorBackground[] = { 1, 1, 1, 0.8 };
url = "";
colorBackgroundDisabled[] = { 1, 1, 1, 0.5 };   // background color for disabled state
offsetX = 0;
colorBackgroundActive[] = { 1, 1, 1, 1 };   // background color for active state
offsetY = 0;
offsetX = 0.003;
offsetPressedX = 0;
offsetY = 0.003;
offsetPressedY = 0;
offsetPressedX = 0.002;
offsetPressedY = 0.002;
colorShadow[] = { 0, 0, 0, 0.5 };
colorBorder[] = { 0, 0, 0, 1 };
borderSize = 0;
borderSize = 0;
soundEnter[] = { "", 0, 1 };  // no sound
soundPush[] = { "buttonpushed.ogg", 0.1, 1 };
soundClick[] = { "", 0, 1 };  // no sound
soundEscape[] = { "", 0, 1 };  // no sound
x = 0.4; y = 0.475;
w = 0.2; h = 0.05;
text = "Close";
action = "closeDialog 0; hint ""Dialog closed. You are good to go now!""";
};</nowiki></code>
====CT_SHORTCUTBUTTON=16====
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''action'''
| string
|
|-
| '''Attributes'''
| class
|
|-
| '''AttributesImage'''
| class
|
|-
| '''animTextureNormal'''
| argb color array
|
|-
| '''animTextureDisabled'''
| argb color array
|
|-
| '''animTextureOver'''
| argb color array
|
|-
| '''animTextureFocused'''
| class
|
|-
| '''animTexturePressed'''
| argb color array
|
|-
| '''animTextureDefault'''
| argb color array
|
|-
| '''textureNoShortcut'''
| argb color array
|
|-
| '''color'''
| color array
|
|-
| '''color2'''
| color array
|
|-
| '''colorActiveBackground'''
| color array
|
|-
| '''colorBackground'''
| color array
|
|-
| '''colorBackground2'''
| color array
|
|-
| '''colorDisabled'''
| color array
|
|-
| '''default'''
| boolean
|
|-
| '''HitZone'''
| class
|
|-
| '''period'''
| float
|
|-
| '''periodFocus'''
| float
|
|-
| '''periodOver'''
| float
|
|-
| '''ShortcutPos'''
| class
|
|-
| '''shortcuts'''
| array
| key short cuts. often over-ridden/ignored by engine
|-
| '''Size'''
| float
| possibly a typo, used in conjunction with sizeEx
|-
| '''soundEnter'''
| sound array
|
|-
| '''soundPush'''
| sound array
|
|-
| '''soundClick'''
| sound array
|
|-
| '''soundEscape'''
| sound array
|
|-
| '''TextPos'''
| class
|
|-
|}<br clear="all">
* '''Example:'''
<code><nowiki>class RscShortcutButton
{
type = 16;
class HitZone
{
  left = 0.0;
  top = 0.0;
  right = 1.0;
  bottom = 1.0;
};
class ShortcutPos
{
  left = 0.005;
  top = 0.005;
  w = 0.0225;
  h = 0.03;
};
class TextPos
{
  left = 0.02;
  top = 0.005;
  right = 0.005;
  bottom = 0.005;
};
animTextureNormal = "#(argb,8,8,3)color(1,1,1,1)";
animTextureDisabled = "#(argb,8,8,3)color(0.3,0.3,0.3,1)";
animTextureOver = "#(argb,8,8,3)color(0.8,0.3,0,1)";
animTextureFocused = "#(argb,8,8,3)color(1,0.5,0,1)";
animTexturePressed = "#(argb,8,8,3)color(1,0,0,1)";
animTextureDefault = "#(argb,8,8,3)color(0,1,0,1)";
period = 0.1;
periodFocus = 0.4;
periodOver = 0.4;
shortcuts[] = {};
textureNoShortcut = "#(argb,8,8,3)color(0,0,0,0)";
color[] = {0,0,0,0.6};
color2[] = {0,0,0,1};
colorDisabled[] = {0,0,0,0.3};
colorBackground[] = {1,1,1,1};
colorBackground2[] = {1,1,1,0.5};
text = "";
size = 0.04;
class Attributes
{
  font = "TahomaB";
  color = "#000000";
  align = "left";
  shadow = 0;
};
};
};
</nowiki></code>
</syntaxhighlight>
 
</spoiler>
====CT_ACTIVETEXT=11====


The Active Text control behaves very similar to buttons. It shows up as regular text with the additional functionality that you can click and select it. The dialog's currently selected Active Text control will be underlined to indicate it's status. By default, the first Active Text control is selected. When the mouse cursor hovers over an instance of this control, it will show up in the color defined in the ''colorActive'' property.


'''Notice:''' This control doesn't render the usually common ''colorBackground'' property and ''colorText'' is replaced with ''color''.
== Control Types ==


{| border="1" align="left" cellpadding="3" cellspacing="0" |
The type property of controls defines what type of control they are. For example an edit box has the type 2.
! colspan="3" bgcolor="#bbbbff" | Properties
There is an ingame dialog with examples of how the control types look and act like:
|-
<sqf>createDialog "RscTestControlTypes";</sqf>
! bgcolor="#ddddff" | Name
{{Navbox/CT}}
! bgcolor="#ddddff" | Type
<!---
! bgcolor="#ddddff" | Remark
{| class="wikitable sortable" Style ="Width: 100%"
|-
! Define !! Decimal !! Hexadecimal !! Remark
| '''action'''
| string
| a statement that is executed when the control has been clicked
|-
| '''blinkingPeriod'''
| float (Seconds)
| Makes the text start transparent, go to full opacity and back to full transparent in the amount of time specified.
|-
|-
| '''color'''
| [[CT_STATIC]] || 0 || 0x00 ||  
| color array
| '''replaces ''colorText''''', standard text and underline color
|-
|-
| '''colorActive'''
| [[CT_BUTTON]] || 1 || 0x01 ||
| color array
| text and underline color whenever the mouse hovers over the control
|-
|-
| '''colorShade'''
| [[CT_EDIT]] || 2 || 0x02 ||
| color array
|  
|-
|-
| '''colorDisabled'''
| [[CT_SLIDER]] || 3 || 0x03 ||
| color array
|  
|-
|-
| <strike>'''colorBackground'''</strike>
| [[CT_COMBO]] || 4 || 0x04 ||
| <strike>color array</strike>
| '''not applicable'''
|-
|-
| '''default'''
| [[CT_LISTBOX]] || 5 || 0x05 ||
| boolean
| Whether or not this control is the dialog's initially selected active text
|-
|-
| '''pictureWidth/Height'''
| [[CT_TOOLBOX]] || 6 || 0x06 ||
| floats
|  
|-
|-
| '''sideDisabled'''
| [[CT_CHECKBOXES]] || 7 || 0x07 ||
| argb
|  
|-
|-
| '''sideToggle'''
| [[CT_PROGRESS]] || 8 || 0x08 ||  
| argb
|  
|-
|-
| '''textHeight'''
| [[CT_HTML]] || 9 || 0x09 ||
| float
|  
|-
|-
| '''soundEnter'''
| [[CT_STATIC_SKEW]] || 10 || 0x0A ||
| sound array
| the sound to play, when the cursor enters the button's bounds
|-
|-
| '''soundPush'''
| [[CT_ACTIVETEXT]] || 11|| 0x0B||
| sound array
| the sound to play, when the button has been pushed
|-
|-
| '''soundClick'''
| [[CT_TREE]] || 12 || 0x0C ||
| sound array
| the sound to play, when the button is being released
|-
|-
| '''soundEscape'''
| [[CT_STRUCTURED_TEXT]] || 13 || 0x0D ||
| sound array
| the sound to play, when the button has been pushed and the mouse button is released when not over the control.
|-
|-
|}<br clear="all">
| [[CT_CONTEXT_MENU]] || 14 || 0x0E ||
 
The following example uses almost the same code as the controls shown in the example screenshot.
[[Image:Dialog controls activetext.jpg|thumb|110px|Simple dialog with three Active Text controls]]
* '''Example:'''
<code><nowiki>class MyActiveText {
idc = -1;
type = CT_ACTIVETEXT;
style = ST_LEFT;
x = 0.75; y = 0.5;
w = 0.2; h = 0.035;
font = FontM;
sizeEx = 0.024;
color[] = { 1, 1, 1, 1 };
colorActive[] = { 1, 0.2, 0.2, 1 };
soundEnter[] = { "", 0, 1 };  // no sound
soundPush[] = { "", 0, 1 };
soundClick[] = { "", 0, 1 };
soundEscape[] = { "", 0, 1 };
action = "hint ""Good choice!""";
text = "Text";
default = true;
};</nowiki></code>
==EDIT BOX==
===CT_EDIT=2===
A text box allows the user to either enter text himself, or to select and copy its content.<br>
{| border="1" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
| [[CT_CONTROLS_GROUP]] || 15 || 0x0F ||
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|-
| '''autocomplete'''
| [[CT_SHORTCUTBUTTON]] || 16 || 0x10 ||
| string ("scripting")
| entered text will automatically be completed with matching command
|-
|-
| '''htmlControl'''
| [[CT_HITZONES]] || 17 || 0x11 ||
| boolean
| if used together with style=ST_MULTI, allows multi-line editable text fields.
|-
|-
| '''lineSpacing'''
| [[CT_VEHICLETOGGLES]] || 18 || 0x12 ||  
| float
| line spacing. Required, if the style was set to <tt>ST_MULTI</tt>.
|-
|-
| '''colorSelection'''
| [[CT_CONTROLS_TABLE]] || 19 || 0x13 ||
| color array
|  
|-
|-
| '''size'''
| [[CT_XKEYDESC]] || 40 || 0x28 ||
| float
| possibly a typo, perhaps irrelevant xbox control
|-
|-
|}<br clear="all">
| [[CT_XBUTTON]] || 41 || 0x29 ||
 
* '''Example:'''
<code><nowiki>
class RscEdit
{
access = 0;
type = CT_EDIT;
style = ST_LEFT;
x = 0;
y = 0;
h = 0.04;
w = 0.2;
colorBackground[] = {0,0,0,0};
colorText[] = {1,1,1,1};
colorSelection[] = {1,1,1,0.25};
font = "TahomaB";
sizeEx = 0.04;
autocomplete = "";
text = "";
size = 0.2;
shadow = 0;
};
class dialog
{
class controls
{
  class Value: RscEdit
  {
  idc = 120; // otherwise there's not much point
  x = 0.3025;
  y = 0.34;
  text = "whatever";
  autocomplete = "scripting";
  };
};
};
</nowiki></code>
 
==OBJECTS==
===CT_OBJECT=80===
===CT_OBJECT_CONTAINER=82===
{| border="1" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
| [[CT_XLISTBOX]] || 42 || 0x2A ||
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|-
| '''scale'''
| [[CT_XSLIDER]] || 43 || 0x2B ||
| float
|
|-
|-
| '''selectionArrow'''
| [[CT_XCOMBO]] || 44 || 0x2C ||
| float
|
|-
|-
| '''direction'''
| [[CT_ANIMATED_TEXTURE]] || 45 || 0x2D ||
| array
|
|-
|-
| '''up'''
| [[CT_MENU]] || 46 || 0x2E || {{arma3}} (EDEN)
| array
|
|-
|-
| '''shadow'''
| [[CT_MENU_STRIP]] || 47 || 0x2F || {{arma3}} (EDEN)
| integer
|
|-
|-
| '''model'''
| [[CT_CHECKBOX]] || 77 || 0x4D || {{arma3}}
| string
| path to p3d
|-
|-
| '''selectionDate1/2'''
| [[CT_OBJECT]] || 80 || 0x50 ||
| strings
|
|-
|-
| '''selectionDay'''
| [[CT_OBJECT_ZOOM]] || 81 || 0x51 ||
| string
|
|-
|-
| '''x/y/zBack'''
| [[CT_OBJECT_CONTAINER]] || 82 || 0x52 ||
| float
|
|-
|-
| '''inBack'''
| [[CT_OBJECT_CONT_ANIM]] || 83 || 0x53 ||
| boolean
|
|-
|-
| '''enableZoom'''
| [[CT_LINEBREAK]] || 98 || 0x62 ||
| boolean
|
|-
|-
| '''zoomDuration'''
| [[CT_USER]] || 99 || 0x63 ||
| float
|
|-
|-
| '''scale'''
| [[CT_MAP]] || 100 || 0x64 ||
| float
|
|-
|-
| '''waitForLoad'''
| [[CT_MAP_MAIN]] || 101 || 0x65 ||
| boolean
|
|-
|-
| '''Animations'''
| [[CT_LISTNBOX]] || 102 || 0x66 ||
| class
|
|-
|-
| '''Animations'''
| [[CT_ITEMSLOT]] || 103 || 0x67 ||
| class
| type 80 only
|-
|-
| '''Areas'''
| [[CT_LISTNBOX_CHECKABLE]] || 104 || 0x68 ||
| class
| type 82 only
|-
|-
|}<br clear="all">
| [[CT_VEHICLE_DIRECTION]] || 105 || 0x69 ||
* '''Example:'''
|}
<code><nowiki>
--->
class dialog
{
class objects
{
  class Watch/*: RscObject*/
  {
  access = 0;
  scale = 1.0;
  direction[] = {0,0,1};
  up[] = {0,1,0};
  shadow = 0;
  idc = 101;
  type = 80;
  model = "\core\watch\watch.p3d";
  selectionDate1 = "date1";
  selectionDate2 = "date2";
  selectionDay = "day";
  x = 0.7;
  xBack = 0.7;
  y = 0.12;
  yBack = 0.12;
  z = 0.22;
  zBack = 0.22;
  inBack = 0;
  enableZoom = 0;
  direction[] = {0,0,1};
  up[] = {0,1,0};
  zoomDuration = 1;
  scale = 0.7;
  waitForLoad = 0;
  class Animations
  {
    class WatchHour
    {
    type = "rotation";
    source = "clockHour";
    selection = "hodinova";
    axis = "osa";
    memory = 1;
    animPeriod = 0;
    angle0 = 0;
    angle1 = "rad 360";
    };
    class WatchMinute
    {
    type = "rotation";
    source = "clockMinute";
    selection = "minutova";
    axis = "osa";
    memory = 1;
    animPeriod = 0;
    angle0 = 0;
    angle1 = "rad 360";
    };
    class WatchSecond
    {
    type = "rotation";
    source = "clockSecond";
    selection = "vterinova";
    axis = "osa";
    memory = 1;
    animPeriod = 0;
    angle0 = 0;
    angle1 = "rad 360";
    };
  };
  };
};</nowiki></code>


===CT_OBJECT_ZOOM=81===
=== Control Type Definitions ===
All definitions can be retrieved with <sqf inline>"Default" call BIS_fnc_exportGUIBaseClasses;</sqf>.<br>
<spoiler text="Show Control Type Definitions">
<syntaxhighlight lang="cpp">
#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
</syntaxhighlight>
</spoiler>


{| border="1" cellpadding="3" cellspacing="0" |
== Control Styles ==
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''model'''
| string
| path to model
|-
| '''selectionArrow'''
| string
|
|-
| '''position'''
| array
|
|-
| '''direction'''
| array
|
|-
| '''up'''
| array
|
|-
| '''positionBack'''
| array
|
|-
| '''inBack'''
| integer
|
|-
| '''enableZoom'''
| boolean
|
|-
| '''zoomDuration'''
| float
|
|-
|}<br clear="all">
* '''Example:'''
<code><nowiki>class RscCompass: RscObject
{
idc = -1;
type = 81;
model = "\core\compass\compass.p3d";
selectionArrow = "arrow";
position[] = {0.026,0.047,0.2};
direction[] = {0,1,1};
up[] = {0,0,-1};
positionBack[] = {0.0749,-0.059,0.315};
inBack = 1;
enableZoom = 0;
zoomDuration = 0.5;
class Animations
{
  class Pointer
  {
  type = "rotation";
  source = "compassPointer";
  selection = "kompas";
  axis = "osa kompasu";
  memory = 1;
  animPeriod = 0;
  minValue = "rad -180";
  maxValue = "rad 180";
  angle0 = "rad -180";
  angle1 = "rad 180";
  };
  class Arrow
  {
  type = "rotation";
  source = "compassArrow";
  selection = "arrow";
  axis = "osa kompasu";
  memory = 1;
  animPeriod = 0;
  minValue = "rad -180";
  maxValue = "rad 180";
  angle0 = "rad -180";
  angle1 = "rad 180";
  };
  class Cover
  {
  type = "rotation";
  source = "compassCover";
  selection = "vicko";
  axis = "osa vicka";
  memory = 1;
  animPeriod = 0;
  angle0 = 0;
  angle1 = "rad -81";
  };
};
};</nowiki></code>


==OTHER==
To further customize controls there are several different styles for each control type available.<br>


===CT_LINEBREAK=98===
To get an idea of how the styles look like you can create the following dialog:
<sqf>createDialog "RscTestControlStyles";</sqf>


{| border="1" cellpadding="3" cellspacing="0" |
{{Feature | important | Note that drawing of vertical text is not supported and any attempt to use {{hl|ST_UP}}, {{hl|ST_DOWN}}, {{hl|ST_VCENTER}} is likely to result in the following ''.rpt'' spam:<br>{{hl|Obsolete, sizeH and sizeW calculation missing}}<br>In addition, {{hl|ST_UP}}, {{hl|ST_DOWN}}, {{hl|ST_VCENTER}} are stand alone styles and should not be mixed with any other styles}}
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|}<br clear="all">
* '''Example:'''
<code><nowiki>class RscLineBreak
{
idc = -1;
type = 98;
shadow = 0;
};</nowiki></code>


===CT_SLIDER=3===
{| class="wikitable" Style="Width: 100%"
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! Define !! Decimal !! Hexadecimal !! Remark
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
| ST_LEFT || 0 || 0x00 || Default, text left aligned
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''style'''
| integer
| generally 1024
|-
|-
| '''coloractive'''
| ST_RIGHT || 1 || 0x01 || Modifier, adding this to another style will force text to be aligned to the right
| color array
| color of the arrows.
|-
|-
| '''Title'''
| ST_CENTER || 2 || 0x02 || Modifier, adding this to another style will force text to be centered
| class
|
|-
|-
| '''Value'''
| ST_DOWN || 4 || 0x04 || Vertical text alignment (See the note above)
| class
|
|-
|-
|}<br clear="all">
| ST_UP || 8 || 0x08 || Vertical text alignment (See the note above)
 
====Title or Value class====
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
| ST_VCENTER || 12 || 0x0C || Vertical text alignment, same as ST_DOWN + ST_UP (See the note above)
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|-
| '''idc'''
| ST_SINGLE || 0 || 0x00 || Plain single line box without a border
| integer
|  
|-
|-
| '''colorBase'''
| 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.
| color array
|
|-
|-
| '''colorActive'''
| 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
| color array
|
|-
|-
|}<br clear="all">
| 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
 
===CT_XSLIDER=43===
 
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
| 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
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|-
| '''style'''
| ST_BACKGROUND || 80 || 0x50 || Single line box with always black opaque background and thick raised beveled border
| integer
|  
|-
|-
| '''coloractive'''
| ST_GROUP_BOX || 96 || 0x60 || Single line box with delicate semi-transparent background and slight border. Only text colour can be controlled
| color array
| color of the arrows.
|-
|-
| '''colorDisable'''
| ST_GROUP_BOX2 || 112 || 0x70 || Plain single line box, same as ST_SINGLE, only with a slight border similar to ST_MULTI box border
| color array
|  
|-
|-
| '''arrowEmpty'''
| ST_HUD_BACKGROUND || 128 || 0x80 || Sets special texture for corners. It was used for rounded corners in {{Name|ofp|short}}, {{Name|arma1|short}} and {{arma2}}. In {{arma3}}, square corners are used everywhere, so the texture is adapted to the unified style, but the technology is not removed. In {{arma3}} it looks the same as normal ST_SINGLE. Corner textures are defined in <sqf inline>configFile >> "CfgInGameUI" >> "imageCornerElement"</sqf> (can be set only globally for the whole game, not per control)
| color array
|
|-
|-
| '''arrowFull'''
| 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.
| color array
|
|-
|-
| '''border'''
| 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''
| color array
|
|-
|-
| '''thumb'''
| 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''
| color array
|
|-
|-
| '''vspacing'''
| ST_UPPERCASE || 192 || 0xC0 || Forces control text to upper case
| float
|
|-
|-
|}<br clear="all">
| ST_LOWERCASE || 208 || 0xD0 || Forces control text to lower case
 
 
'''Notice:'''
 
You can change the orientation of the slider with the '''style''' constants ''SL_HORZ'' and ''SL_VERT''.
[[Image:ControlSlider.JPG|thumb|200px|A Slider Control]]
* '''Example:'''
<code><nowiki>class MySlider {
    idc = -1;
    type = CT_SLIDER;
    style = SL_HORZ;
    x = 0.4;
    y = 0.2;
    w = 0.3;
    h = 0.025;
    color[] = { 1, 1, 1, 1 };
    coloractive[] = { 1, 0, 0, 0.5 };
    // This is an ctrlEventHandler to show you some response if you move the sliderpointer.
    onSliderPosChanged = "hint format[""%1"",_this];";
};</nowiki></code>
* '''Helpful Script Commands:'''
'''[[sliderPosition]], [[sliderRange]], [[sliderSetPosition]], [[sliderSetRange]], [[sliderSetSpeed]], [[sliderSpeed]]'''
 
===CT_COMBO Type=4===
see [[DialogControls-Combo]]
 
===LISTBOXES===
===Listboxes===
 
see [[DialogControls-ListBoxes]]
 
===CT_TOOLBOX Type=6===
 
see [[DialogControls-Toolbox]]
 
===CT_XKEYDESC=40===
 
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
| ST_ADDITIONAL_INFO || 3840 || 0x0F00 || ST_SHADOW + ST_NO_RECT + SL_HORZ + ST_KEEP_ASPECT_RATIO
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|-
| '''Attributes'''
| ST_SHADOW || 256 || 0x0100 ||
| class
|  
|-
|-
| '''AttributesImage'''
| ST_NO_RECT || 512 || 0x0200 || This style works for [[CT_STATIC]] in conjunction with ST_MULTI
| class
|  
|-
|-
| '''key'''
| ST_KEEP_ASPECT_RATIO || 2048 || 0x0800 || When used with image or texture, stops it from stretching to fit the control
| argb
| key = "0x00050000 + 1";
|-
|-
|}<br clear="all">
| ST_TITLE || 34 || 0x22 || ST_TITLE_BAR + ST_CENTER
 
|}
* '''Example:'''
<code><nowiki>class RscXKey
{
type = 40;
idc = -1;
style = ST_LEFT;
h = 0.06;
size = "( 21 / 408 )";
shadow = 0;
key = "0x00050000 + 1";
class Attributes
{
  font = "Zeppelin32";
  color = "#E5E5E5";
  align = "left";
};
class AttributesImage
{
  color = "#E5E5E5";
};
};</nowiki></code>
 
=== Checkboxes ===
The Checkboxes are a set of state change buttons, ordered by columns and rows. Unlike the Toolbox Control more than one button can become active.


{| border="1" align="left" cellpadding="3" cellspacing="0" |
=== Control Specific Styles ===
! colspan="3" bgcolor="#bbbbff" | Properties
==== [[CT_LISTBOX]] Specific Styles ====
{| class="wikitable" width="70%"
! Define !! Decimal !! Hexadecimal !! Remark
|-
|-
! bgcolor="#ddddff" | Name
| LB_TEXTURES || 16 || 0x10 ||
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|-
| '''idc'''
| LB_MULTI || 32 || 0x20 || Makes [[CT_LISTBOX]] multi-selectable
| integer
|}
| the unique ID number of this dialog. Can be -1 if you don't require access to the dialog itself from within a script.
 
==== [[CT_PROGRESS]] Specific Styles ====
{| class="wikitable" width="70%"
! Define !! Decimal !! Hexadecimal
|-
|-
| '''colorText'''
| ST_VERTICAL || 1 || 0x01
| color array
| color of the control text.
|-
|-
| '''color'''
| ST_HORIZONTAL || 0 || 0x00
| color array
|}
| color of border from selected entry, if other control has focus.
 
==== [[CT_SLIDER]] Specific Styles ====
{| class="wikitable" width="70%"
|-
|-
| '''colorTextSelect'''
! Define !! Decimal !! Hexadecimal
| color array
| color of text if selected
|-
|-
| '''colorSelect'''
| SL_VERT || 0 || 0x00
| color array
| color of border from selected entry.
|-
|-
| '''colorTextDisable'''
| SL_HORZ || 1024 || 0x0400
| color array
| color of control text, if control is disabled.
|-
|-
| '''colorDisable'''
| SL_TEXTURES || 16 || 0x10
| color array
|}
| seems nothing to change, but define it to avoid errors.
 
==== [[CT_TREE]] Specific Styles ====
{| class="wikitable" width="70%"
! Define !! Decimal !! Hexadecimal !! Remark
|-
|-
| '''font'''
| TR_SHOWROOT || 1 || 0x01 || When this style is applied, all entries even with path [] can be collapsed. Use unkown.
| float
| the font to use. See the list of [[Fonts#Available_Fonts|available fonts]] for possible values
|-
|-
| '''sizeEx'''
| TR_AUTOCOLLAPSE || 2 || 0x02 || Use unknown
| float
|}
| the font size of text (0 to 1)
 
|-
=== Control Style Definitions ===
| '''rows'''
All definitions can be retrieved with <sqf inline>"Default" call BIS_fnc_exportGUIBaseClasses;</sqf>.<br>
| integer
<spoiler text="Show Control Style Definitions">
| amount of rows to display
<syntaxhighlight lang="cpp">
|-
#define ST_LEFT 0x00
| '''columns'''
#define ST_RIGHT 0x01
| integer
#define ST_CENTER 0x02
| amount of columns to display
#define ST_DOWN 0x04
|-
#define ST_UP 0x08
| '''color'''
#define ST_VCENTER 0x0C
| color array
#define ST_SINGLE 0x00
| color of the control surrounding lines.
#define ST_MULTI 0x10
|-
#define ST_TITLE_BAR 0x20
| '''strings'''
#define ST_PICTURE 0x30
| string array
#define ST_FRAME 0x40
| text for each toolbox entry
#define ST_BACKGROUND 0x50
|-
#define ST_GROUP_BOX 0x60
|}<br clear="all">
#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
</syntaxhighlight>
</spoiler>


Checkboxes corresponding '''type''' property is ''CT_CHECKBOXES''.
== Positioning ==


[[Image:CheckboxesControl.jpg|thumb|200px|A Checkboxes Control from example code with a hint dialog from UI event handler]]
A detailed description of how you can achieve proper GUI placement can be found on the [[Arma 3: GUI Coordinates]] page.
* '''Example:'''
<code><nowiki>class MyRscCheckBoxes {
  idc = 200;
  type = CT_CHECKBOXES; // defined contant (7)
  style = ST_CENTER; // defined constat (0)
 
  x = 0.1;
  y = 0.18;
  w = 0.15;
  h = 0.15;
 
  colorText[] = {1, 0, 0, 1};
  color[] = {0, 1, 0, 1};  //seems nothing to change, but define to avaoid errors
  colorTextSelect[] = {0, 0.8, 0, 1};
  colorSelect[] = {0, 0, 0, 1};
  colorTextDisable[] = {0.4, 0.4, 0.4, 1};
  colorDisable[] = {0.4, 0.4, 0.4, 1};
 
  font = "Zeppelin32";
  sizeEx = 0.0208333;
 
  rows = 3;
  columns = 2;
  strings[] = {"Entry 1","Entry 2","Entry 3","Entry 4","Entry 5","Entry 6"};
 
  //Simple UI event handler to show response on clicks
  onCheckBoxesSelChanged = "hint format[""Checkbox change:\n%1\nEntry#: %2\nNewState: %3"",(_this select 0),(_this select 1),(_this select 2)];"
};
</nowiki></code>


'''Notice:'''
== Inheritance ==
As you see in the example image, the returned entry number from the ''onCheckBoxesSelChanged'' event handler starts at zero (0)! So if you have 6 toolbox entrys, the first is 0 and the last is 5!
'''Notice:'''
You must add this line : '''coloSelectedBg[] = {0, 0, 0, 0};''' (for setting the selected box color)


===CT_PROGRESS=8===
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.
see [[DialogControls-ProgressBar]]


===CT_ANIMATED_TEXTURE=45===
{{Feature|informative|Using inheritance can make your GUI config hard to read for others.}}
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''texture '''
| color array
|
|-
|}<br clear="all">


* '''Example:'''
View the [[Class Inheritance|dedicated inheritance page]] for more information.
<code><nowiki>class RscProgressNotFreeze
{
idc = -1;
type = 45;
style = 0;
shadow = 0;
x = 0;
y = 0;
w = 0.5;
h = 0.1;
texture = "#(argb,8,8,3)color(0,0,0,0)";
};</nowiki></code>
===CT_USER=99===
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''Scrollbar'''
| class
|
|-
| '''colorLines'''
| color array
|
|-
| '''colorBar'''
| color array
|
|-
| '''colorSelection'''
| color array
|
|-
|}<br clear="all">


* '''Example:'''
== Preprocessor instructions ==
<code><nowiki>  class TimeLines
  {
  type = 99;
  style = 0;
  idc = 102;
  shadow = 0;
  x = "0.03 + 0.02";
  y = 0.53;
  w = "0.90 - 0.04";
  h = 0.26;
  class Scrollbar{};
  font = "TahomaB";
  colorLines[] = {0,0,0,1};
  colorBackground[] = {1,1,1,1};
  colorBar[] = {0.8,0.8,0.8,1};
  colorSelection[] = {1,0,0,1};
  };</nowiki></code>


===CT_CONTEXT_MENU=14===
Note that you can also add your own [[PreProcessor_Commands|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.


{| border="1" align="left" cellpadding="3" cellspacing="0" |
=== Example Config ===
! colspan="3" bgcolor="#bbbbff" | Properties
<spoiler text="Show Example Config">
|-
<syntaxhighlight lang="cpp">
! bgcolor="#ddddff" | Name
#define COLOR_HALF_BLACK { 0, 0, 0, 0.5 }
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''colorBorder'''
| color array
|
|-
| '''colorChecked'''
| color array
|
|-
| '''colorBorder'''
| color array
|
|-
| '''colorSelectBackground'''
| color array
|
|-
| '''colorSeparator'''
| color array
|
|-
| '''colorEnabled'''
| color array
|
|-
| '''colorDisabled'''
| color array
|
|-
|}<br clear="all">


* '''Example:'''
class MyDialog
<code><nowiki>
class dialog
{
{
class controls
idd = -1;
{
movingEnable = 1;
  class Menu
objects[] = {};
  {
controlsBackground[] = { MyDialogBackground };
  type = 14;
  idc = 204;
  style = 0;
  x = 0;
  y = 0;
  w = 0;
  h = 0;
  colorBackground[] = {0.3,0.3,0.3,1};
  colorBorder[] = {1,1,1,1};
  colorSeparator[] = {1,1,1,1};
  colorSelectBackground[] = {1,1,1,0.3};
  colorChecked[] = {0,0,1,1};
  colorEnabled[] = {1,1,1,1};
  colorDisabled[] = {1,1,1,0.5};
  sizeEx = 0.025;
  font = "TahomaB";
  };
};
};</nowiki></code>


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


===CT_TREE=12===
=== Useful includes ===
Raedor has said, "Unfortunately one can only use RscTree hardcoded."  This strongly implies that RscTree is only available to BIS and not to the public.  The original post can be [http://www.mapfact.net/forum_arma/viewtopic.php?p=7504&sid=09dda9bd058705f71d489a657fd7f155 found here].


{| border="1" align="left" cellpadding="3" cellspacing="0" |
{{arma3}} offers a wide range of useful files which can be included to get access to some  helpful macros.
! colspan="3" bgcolor="#bbbbff" | Properties
{| class="wikitable"
|-
! bgcolor="#ddddff" | Name
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
| '''colorSelect'''
| color array
|
|-
|-
| '''colorBorder'''
! Include Code !! Description / Content
| color array
|
|-
|-
| '''colorArrow'''
| <syntaxhighlight lang="cpp">#include "\a3\3DEN\UI\macros.inc"</syntaxhighlight> || Defines for [[:Category:Eden Editor|Eden Editor]] like colors, text sizes custom pixel grid macros.
| color array
|  
|-
|-
| '''maxHistoryDelay '''
| <syntaxhighlight lang="cpp">#include "\a3\3DEN\UI\macroexecs.inc"</syntaxhighlight> || Defines for [[:Category:Eden Editor|Eden Editor]] to calculate text sizes etc.
| float
|  
|-
|-
|}<br clear="all">
| <syntaxhighlight lang="cpp">#include "\a3\ui_f\hpp\definedikcodes.inc"</syntaxhighlight> || Useful when working with custom shortcuts. Contains defines for key codes.
 
* '''Example:'''
<code><nowiki>class RscTree
{
access = 0;
type = 12;
style = 0;
colorBackground[] = {0.35,0.38,0.36,1};
colorSelect[] = {1,1,1,1};
colorText[] = {1,1,1,0.75};
colorBorder[] = {1,1,1,1};
colorArrow[] = {1,1,1,1};
font = "TahomaB";
sizeEx = 0.04;
maxHistoryDelay = 1.0;
shadow = 0;
};</nowiki></code>
 
===CT_CONTROLS_GROUP Type=15===
see [[DialogControls-ControlsGroup]]
 
=== Animated texture ===
{| border="1" align="left" cellpadding="3" cellspacing="0" |
! colspan="3" bgcolor="#bbbbff" | Properties
|-
|-
! bgcolor="#ddddff" | Name
| <syntaxhighlight lang="cpp">#include "\a3\ui_f\hpp\definecommoncolors.inc"</syntaxhighlight> || Colors used in {{arma3}}, like background color set by the user.
! bgcolor="#ddddff" | Type
! bgcolor="#ddddff" | Remark
|-
|-
| '''texture'''
| <syntaxhighlight lang="cpp">#include "\a3\ui_f\hpp\definecommongrids.inc"</syntaxhighlight> || UI grids such as GUI_GRID and all its variants.
| string
| Relative path to the file used for the texture from the mission folder
|-
|-
|}<br clear="all">
| <syntaxhighlight lang="cpp">#include "\a3\ui_f\hpp\defineresincl.inc"</syntaxhighlight> || IDCs and IDDs of many {{arma3}} UIs.
 
|}
This feature is still relatively undocumented and it is not clear how to produce anything except a non-animated, non-tiled image (even if the ST_TILE_PICTURE style is used).
 
===CT_MAP_MAIN=101===


'''see [[Dialog Control Map|dialog map and example]]'''
== User Interface Event Handlers ==


User Interface Event Handlers are a key component of any {{arma3}} GUI. See [[User Interface Event Handlers]].


== UI Eventhandlers ==


A reference list of [[User Interface Event Handlers]].
== Scripting ==


== Best practice ==
There are several functions and commands to edit your dialog after its creation. These functions and commands can be found here:
* [[:Category:Function_Group:_GUI|GUI Functions]]
* [[:Category:Command Group: GUI Control|GUI Commands]]


=== Inheritance ===
<!-- added by Dr_Eyeball. Example not tested. 11 May 2007. Modify it as you see fit, but don't forget this important topic. -->
<!-- Nasty person and Java developer that I am, I dared to move all opening braces at the end of the previous line to make it look more compact. Furthermore I removed some placeholders, because they didn't seem to be needed that much. I hope you don't mind. Also, I love to meddle... :) ~~~~ -->
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.


* '''Example:'''
== Native {{arma3}} GUIs ==
<code><nowiki>class RscText {
  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 {
{{arma3}} comes with a wide varity of various displays and dialogs. They can be found in:
  colorText[] = {0, 0, 1, 1};
* [[configFile]] usually with names like '''Rsc'''SomeDisplayName or '''Display'''SomeDisplayName
  x = 0.1;
  w = 0.4;
};


class My_Dialog {
Additonally, {{arma3}} offers some customizeable GUIs which can be accessed by scripts.
  //...
* [[BIS_fnc_3DENShowMessage]]
* [[BIS_fnc_guiMessage]]
* [[BIS_fnc_GUIhint]]
* [[hint]], [[hintSilent]], [[hintC]]


  controls[] = {
    My_Text_1,
    My_Text_2
  };


  class My_Text_1 : My_BlueText {
== GUI References ==
    text = "Line 1";
    y = 0.2; 
  };


  class My_Text_2 : My_BlueText {
It is sometimes a good idea so see how others created their GUIs. Here is a list of a few resources:
    text = "Line 2";
* {{Link|https://github.com/7erra/-Terra-s-Editing-Extensions/tree/master/TER_editing/gui|Terra's Editing Extensions}}
    y = 0.25; 
* {{Link|https://github.com/ConnorAU/A3ExtendedFunctionViewer|A3ExtendedFunctionViewer}}
  };
* {{Link|https://github.com/ConnorAU/A3UserInputMenus|A3UserInputMenus}}
};</nowiki></code>
* {{Link|https://github.com/ConnorAU/A3ColorPicker|A3ColorPicker}}
* {{Link|https://github.com/R3voA3/3den-Enhanced/tree/master/3denEnhanced/GUI|3den Enhanced}}


=== Preprocessor instructions ===
== Tips for creating GUIs ==
<!-- What is this? -->
* Functionality
* Layout
* Style
* Behaviour
* Customizability


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.
{{Wiki|stub}}


* '''Example:'''
<code><nowiki>#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 }


// ...
== Tutorials ==


class MyDialog {
* [[GUI Tutorial]]
idd = -1;
{{Wiki|stub}}
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 {
== See Also ==
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;
};
};</nowiki></code>


* [[Arma 3: IDD List]]
* [[Arma 3: User Interface Editor]]
* [[Arma 3: GUI Coordinates]]
* [[:Category:Function Group:_GUI|GUI Functions]]
* [[:Category:Command Group: GUI Control|GUI Commands]]
* [[User Interface Event Handlers]]
* [[Class Inheritance]]
* [[PreProcessor Commands]]


==Demo mission==
For VBS2 users, a demo mission is available [https://forums.bisimulations.com/viewtopic.php?p=21235#p21235 here].


[[Category: Dialogs]]
[[Category:GUI Topics|GUI Configuration]]

Latest revision as of 10:31, 19 April 2024

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).

  • Custom Briefing Editor

    Custom Briefing Editor

  • Teamswitch GUI

    Teamswitch GUI

  • Dynamic Groups GUI

    Dynamic Groups GUI


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

class DefaultDialog
{
	idd = -1;
	access = 0;
	movingEnable = true;
	onLoad = "hint str _this";
	onUnload  = "hint str _this";
	enableSimulation = false;
	class ControlsBackground
	{
		//Background controls
	};
	class Controls
	{
		//Controls
	};
	class 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 to close a dialog:

Exit Codes

Exit codes are a way to determine in what way a display was closed. The onUnload UIEH has the exit code as one of its parameters. This way you can handle different user decisions, eg. save a value if the user confirms it or discard changes when the user pressed a cancel button. Macros for the different exit codes can be found in \a3\ui_f\hpp\defineResincl.inc: 

// Predefined controls
#define IDC_OK				1
#define IDC_CANCEL			2
#define IDC_AUTOCANCEL		3
#define IDC_ABORT			4
#define IDC_RESTART			5
#define IDC_USER_BUTTON		6
#define IDC_EXIT_TO_MAIN	7
Exit Code Macro Comment
1 IDC_OK Dialog was closed with a positive outcome
2 IDC_CANCEL Dialog was closed with a negative outcome
3 IDC_AUTOCANCEL ?
4 IDC_ABORT When used on the mission display (Display #46) it simulates "Save and Exit" button from escape menu
5 IDC_RESTART ?
6 IDC_USER_BUTTON ?
7 IDC_EXIT_TO_MAIN ?

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

#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};
			};
		};
	};
};
↑ Back to spoiler's top


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
autocomplete String (where applicable) Option for entry fields (e.g. RscEdit) to activate autocompletion. For known script commands and functions use autocomplete = "scripting".
url String (where applicable) URL which will be opened when clicking on the control. Used on e.g. a button control. Does not utilize the Steam Overlay browser if enabled by default, opens the link in the default browser set by the OS.
overlayMode Number Arma 3 logo black.png2.10 (where applicable) 0 - opens URL in default browser; 1 - opens URL in Steam overlay id enabled, otherwise in default browser; 2 - opens URL in Steam overlay, shows error message box (with button to use default browser) if Steam overlay is disabled.

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

#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;
};
↑ Back to spoiler's top


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 Types / MACRO (TYPE VALUE)
Text/Image/Video

CT_STATIC (0) | CT_EDIT (2) | CT_HTML (9) | CT_STRUCTURED_TEXT (13)

Buttons

CT_BUTTON (1) | CT_ACTIVETEXT (11) | CT_SHORTCUTBUTTON (16) | CT_CHECKBOX (77) | CT_XBUTTON (41)

Lists

CT_COMBO (4) | CT_TOOLBOX (6) | CT_CHECKBOXES (7) | CT_TREE (12) | CT_CONTROLS_TABLE (19) | CT_XCOMBO (44) | CT_LISTBOX (5) | CT_LISTNBOX (102) | CT_LISTNBOX_CHECKABLE (104) | CT_XLISTBOX (45)

3D Objects

CT_OBJECT (80) | CT_OBJECT_ZOOM (81) | CT_OBJECT_CONTAINER (82) | CT_OBJECT_CONT_ANIM (83)

Maps

CT_MAP (100) | CT_MAP_MAIN (101)

Meta

CT_SLIDER (3) | CT_XSLIDER (43) | CT_PROGRESS (8) | CT_CONTROLS_GROUP (15) | CT_WEBBROWSER (106) | CT_EXTENSION (107)

Menu

CT_CONTEXT_MENU (14) | CT_MENU (46) | CT_MENU_STRIP (47)

Unknown

CT_STATIC_SKEW (10) | CT_HITZONES (17) | CT_VEHICLETOGGLES (18) | CT_XKEYDESC (40) | CT_ANIMATED_TEXTURE (45) | CT_LINEBREAK (98) | CT_USER (99) | CT_ITEMSLOT (103) | CT_VEHICLE_DIRECTION (105)


Control Type Definitions

All definitions can be retrieved with "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
↑ Back to spoiler's top

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

#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
↑ Back to spoiler's top

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

#define COLOR_HALF_BLACK { 0, 0, 0, 0.5 }

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

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

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
This article is a Stub. You can help BI Community Wiki by expanding it.


Tutorials

This article is a Stub. You can help BI Community Wiki by expanding it.


See Also

Retrieved from "https://community.bistudio.com/wiki?title=Arma:_GUI_Configuration&oldid=363772"