R3vo/Sandbox – User
m (→Dialogs) |
|||
Line 110: | Line 110: | ||
== HUDs (RscTitles) == | == HUDs (RscTitles) == | ||
RscTitles is the class in which HUDs need to be defined. Once your HUD is defined there you can use cutRsc to open it. | RscTitles is the class in which HUDs need to be defined. Once your HUD is defined there you can use cutRsc to open it. | ||
*'''Example''' | |||
<syntaxhighlight lang="cpp">class RscTitles | <spoiler><syntaxhighlight lang="cpp">class RscTitles | ||
{ | { | ||
class RscInfoText | class RscInfoText | ||
Line 150: | Line 151: | ||
}; | }; | ||
}; | }; | ||
};</syntaxhighlight> | };</syntaxhighlight></spoiler> | ||
=== Creating dialogs === | === Creating dialogs === |
Revision as of 08:57, 4 August 2019
Introduction
Dialogs are one way to provide custom graphical user interface in your missions and allow interaction with the player aswell as they are able to run code. They are defined as classes in the missionConfigFile (description.ext), campaignConfigFile (Campaign Description.ext) or configFile (config.cpp).
Difference between dialogs and HUDs
- Dialogs: Displays that interact with the player through controls. While dialogs are opened player can not move.
- Commands: createDialog, closeDialog, createDisplay, closeDisplay
- HUDs: Displays that print information about the game (amount of ammo, stance,...). HUDs do not interfere with the player's movement.
- Commands: cutRsc
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 file or externalized to separate hpp-files, which are included in the description.ext file using the #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 for details. For simplicity we won't apply this practice in the following code examples.
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 |
|
movingEnable | Boolean | Specifies whether the dialog can be moved or not (if enabled one of the dialogs controls should have the moving property set to 1 so it becomes the "handle" the dialog can be moved with). Doesn't seem to matter in Arma 3 |
enableSimulation | Boolean | Specifies whether the game continues while the dialog is shown or not. |
onLoad | String | Expression executed when the dialog is opened. See User Interface Event Handlers |
onUnload | String | Expression executed when the dialog is closed. See User Interface Event Handlers |
controlsBackground | Array | Contains class names of all background controls associated to this dialog. The sequence in which the controls are listed will decide their z-index (i.e. the last ones will on top of the first ones). |
controls | Array | Contains class names of all foreground controls associated to this dialog. |
objects | Array |
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.
- Example 1:
#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;
};
};
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. In the Eden editor it's enough to save the mission via CTRL + S (Default). This will precompile the description.ext.
HUDs (RscTitles)
RscTitles is the class in which HUDs need to be defined. Once your HUD is defined there you can use cutRsc to open it.
- Example
class RscTitles
{
class RscInfoText
{
idd = 3100; //ID Display. Unique identifier
fadein = 0; //Duration of fade in effect when opening in seconds
fadeout = 0; //Duration of fade out effect when closing in seconds
duration = 1e+011; //Duration the HUD is displayed after opening in seconds. Use a very large number to have it always open
onLoad = "uinamespace setvariable ['BIS_InfoText',_this select 0]"; //Code called when the HUD is created
onUnLoad = "uinamespace setvariable ['BIS_InfoText',nil]"; //Code called when the HUD is destroyed/closed
class Controls
{
class InfoText
{
idc = 3101;
style = "0x01 + 0x10 + 0x200 + 0x100";
font = "RobotoCondensedBold";
x = "(profilenamespace getvariable [""IGUI_GRID_MISSION_X"", (safezoneX + safezoneW - 21 * ( ((safezoneW / safezoneH) min 1.2) / 40))])";
y = "(profilenamespace getvariable [""IGUI_GRID_MISSION_Y"", (safezoneY + safezoneH - 10.5 * ( ( ((safezoneW / safezoneH) min 1.2) / 1.2) / 25))])";
w = "(20 * ( ((safezoneW / safezoneH) min 1.2) / 40))";
h = "(5 * ( ( ((safezoneW / safezoneH) min 1.2) / 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};
};
};
};
};
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:
_ok = createDialog "MyHelloWorldDialog";
waitUntil { !dialog }; // hit ESC to close it
hint "Dialog closed.";
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 false and wait statements with a !dialog condition will end.
- Example - close by action
class CloseButton : RscButton {
/* … */
type = CT_BUTTON;
text = "Close";
action = "closeDialog 0";
}
- Example - close by external request
closeDialog 0;
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 GUI functions.
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:
Common properties | |||
---|---|---|---|
Name | Type | Remark | |
idc | integer | the unique ID number of this control. can be -1 if you don't require access to the control itself from within a script | |
moving | boolean | whether the dialog will be moved if this control is dragged (may require "movingEnable" to be 1 in the dialog. In Arma 3 works regardless). Another way of allowing moving of the dialog is to have control of style ST_TITLE_BAR | |
type | integer CT_TYPES | ||
style | integer CT_STYLES | can be combinatorial: style = "0x400+0x02+0x10"; | |
x/y/w/h | float | the position and size of the control in fractions of screen size. | |
sizeEx | float | the font size of text (0..1) | |
font | string | the font to use. See the list of available fonts for possible values | |
colorText | color array | text color | |
colorBackground | color array | background color | |
text | string or texture | the text or picture to display | |
shadow | 0,1 or 2 | 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 v1.48 (approx), most controls now support tooltips. | |
tooltipColorShade | color array | Tooltip background color | |
tooltipColorText | color array | Tooltip text color | |
tooltipColorBox | color array | Tooltip border color | |
autocomplete | string | Option for entry fields (e.g. RscEdit) to activate autocompletion. For known script commands and functions use autocomplete = "scripting". | |
url | string | 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, opens the link in the default browser set by the OS. |
Attributes class
Properties | ||
---|---|---|
Name | Type | Remark |
font | string | |
color | HTML color | |
align | string | center, left, etc |
shadow | integer | not image class |
AttributesImage class
Properties | ||
---|---|---|
Name | Type | Remark |
font | string | optional |
color | HTML color | |
align | string | center, left, etc optional |
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 for details.
CONTROL TYPES
There is an ingame dialog with examples of how the control types look and act like:
createDialog "RscTestControlTypes";
Define | Decimal | Hexadecimal | Remark |
---|---|---|---|
CT_STATIC | 0 | 0x00 | |
CT_BUTTON | 1 | 0x01 | |
CT_EDIT | 2 | 0x02 | |
CT_SLIDER | 3 | 0x03 | |
CT_COMBO | 4 | 0x04 | |
CT_LISTBOX | 5 | 0x05 | |
CT_TOOLBOX | 6 | 0x06 | |
CT_CHECKBOXES | 7 | 0x07 | |
CT_PROGRESS | 8 | 0x08 | |
CT_HTML | 9 | 0x09 | |
CT_STATIC_SKEW | 10 | 0x0A | |
CT_ACTIVETEXT | 11 | 0x0B | |
CT_TREE | 12 | 0x0C | |
CT_STRUCTURED_TEXT | 13 | 0x0D | |
CT_CONTEXT_MENU | 14 | 0x0E | |
CT_CONTROLS_GROUP | 15 | 0x0F | |
CT_SHORTCUTBUTTON | 16 | 0x10 | |
CT_HITZONES | 17 | 0x11 | |
CT_VEHICLETOGGLES | 18 | 0x12 | |
CT_CONTROLS_TABLE | 19 | 0x13 | |
CT_XKEYDESC | 40 | 0x28 | |
CT_XBUTTON | 41 | 0x29 | |
CT_XLISTBOX | 42 | 0x2A | |
CT_XSLIDER | 43 | 0x2B | |
CT_XCOMBO | 44 | 0x2C | |
CT_ANIMATED_TEXTURE | 45 | 0x2D | |
CT_MENU | 46 | 0x2E | Arma 3 (EDEN) |
CT_MENU_STRIP | 47 | 0x2F | Arma 3 (EDEN) |
CT_CHECKBOX | 77 | 0x4D | Arma 3 |
CT_OBJECT | 80 | 0x50 | |
CT_OBJECT_ZOOM | 81 | 0x51 | |
CT_OBJECT_CONTAINER | 82 | 0x52 | |
CT_OBJECT_CONT_ANIM | 83 | 0x53 | |
CT_LINEBREAK | 98 | 0x62 | |
CT_USER | 99 | 0x63 | |
CT_MAP | 100 | 0x64 | |
CT_MAP_MAIN | 101 | 0x65 | |
CT_LISTNBOX | 102 | 0x66 | |
CT_ITEMSLOT | 103 | 0x67 | |
CT_LISTNBOX_CHECKABLE | 104 | 0x68 | |
CT_VEHICLE_DIRECTION | 105 | 0x69 |
Control Types Defines
All defines can be retrieved by executing
"Default" call BIS_fnc_exportGUIBaseClasses;
#define CT_STATIC 0
#define CT_BUTTON 1
#define CT_EDIT 2
#define CT_SLIDER 3
#define CT_COMBO 4
#define CT_LISTBOX 5
#define CT_TOOLBOX 6
#define CT_CHECKBOXES 7
#define CT_PROGRESS 8
#define CT_HTML 9
#define CT_STATIC_SKEW 10
#define CT_ACTIVETEXT 11
#define CT_TREE 12
#define CT_STRUCTURED_TEXT 13
#define CT_CONTEXT_MENU 14
#define CT_CONTROLS_GROUP 15
#define CT_SHORTCUTBUTTON 16
#define CT_HITZONES 17
#define CT_VEHICLETOGGLES 18
#define CT_CONTROLS_TABLE 19
#define CT_XKEYDESC 40
#define CT_XBUTTON 41
#define CT_XLISTBOX 42
#define CT_XSLIDER 43
#define CT_XCOMBO 44
#define CT_ANIMATED_TEXTURE 45
#define CT_MENU 46
#define CT_MENU_STRIP 47
#define CT_CHECKBOX 77
#define CT_OBJECT 80
#define CT_OBJECT_ZOOM 81
#define CT_OBJECT_CONTAINER 82
#define CT_OBJECT_CONT_ANIM 83
#define CT_LINEBREAK 98
#define CT_USER 99
#define CT_MAP 100
#define CT_MAP_MAIN 101
#define CT_LISTNBOX 102
#define CT_ITEMSLOT 103
#define CT_LISTNBOX_CHECKABLE 104
#define CT_VEHICLE_DIRECTION 105
CONTROL STYLES
Common Controls Styles
To get an idea of how the styles look like you can create the following dialog:
createDialog "RscTestControlStyles";
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 |
CT_SLIDER Specific Styles
Define | Decimal | Hexadecimal | Remark |
---|---|---|---|
SL_VERT | 0 | 0x00 | |
SL_HORZ | 1024 | 0x0400 | |
SL_TEXTURES | 16 | 0x10 |
CT_PROGRESS Specific Styles
Define | Decimal | Hexadecimal | Remark |
---|---|---|---|
ST_VERTICAL | 1 | 0x01 | |
ST_HORIZONTAL | 0 | 0x00 |
CT_LISTBOX Specific Styles
Define | Decimal | Hexadecimal | Remark |
---|---|---|---|
LB_TEXTURES | 16 | 0x10 | |
LB_MULTI | 32 | 0x20 | Makes CT_LISTBOX multi-selectable (see also lbSetCurSel, lbCurSel, lbSetSelected, lbSelection) |
CT_TREE Specific Styles
Define | Decimal | Hexadecimal | Remark |
---|---|---|---|
TR_SHOWROOT | 1 | 0x01 | |
TR_AUTOCOLLAPSE | 2 | 0x02 |
Control Styles Defines
All defines can be retrieved by executing
"Default" call BIS_fnc_exportGUIBaseClasses;
#define ST_LEFT 0x00
#define ST_RIGHT 0x01
#define ST_CENTER 0x02
#define ST_DOWN 0x04
#define ST_UP 0x08
#define ST_VCENTER 0x0C
#define ST_SINGLE 0x00
#define ST_MULTI 0x10
#define ST_TITLE_BAR 0x20
#define ST_PICTURE 0x30
#define ST_FRAME 0x40
#define ST_BACKGROUND 0x50
#define ST_GROUP_BOX 0x60
#define ST_GROUP_BOX2 0x70
#define ST_HUD_BACKGROUND 0x80
#define ST_TILE_PICTURE 0x90
#define ST_WITH_RECT 0xA0
#define ST_LINE 0xB0
#define ST_UPPERCASE 0xC0
#define ST_LOWERCASE 0xD0
#define ST_ADDITIONAL_INFO 0x0F00
#define ST_SHADOW 0x0100
#define ST_NO_RECT 0x0200
#define ST_KEEP_ASPECT_RATIO 0x0800
#define ST_TITLE ST_TITLE_BAR + ST_CENTER
#define SL_VERT 0
#define SL_HORZ 0x400
#define SL_TEXTURES 0x10
#define ST_VERTICAL 0x01
#define ST_HORIZONTAL 0
#define LB_TEXTURES 0x10
#define LB_MULTI 0x20
#define TR_SHOWROOT 1
#define TR_AUTOCOLLAPSE 2
UI Eventhandlers
A reference list of User Interface Event Handlers.
Best practice
Inheritance
Using inheritance can reduce your dialog class definitions significantly by standardising common attributes in base classes and just changing unique attributes in derived classes. There is no need to redeclare all attributes for each class definition.
- Example:
class RscText // Base definition used for inheritance
{
type = CT_STATIC;
idc = -1;
style = ST_LEFT;
colorBackground[] = {0, 0, 0, 1};
colorText[] = {1, 1, 1, 1};
font = FontM;
sizeEx = 0.04;
h = 0.04;
text = "";
};
class My_BlueText : RscText // My_BlueText inherits all attributes from RscText defined above, thus only x,w & colorText need to be changed
{
colorText[] = {0, 0, 1, 1};
x = 0.1;
w = 0.4;
};
class My_Dialog
{
//…
controls[] = {
My_Text_1,
My_Text_2
};
class My_Text_1 : My_BlueText // My_Text_1 inherits all attribute from My_BlueText, therefore only text & y attributes have to be changed
{
text = "Line 1";
y = 0.2;
};
class My_Text_2 : My_BlueText
{
text = "Line 2";
y = 0.25;
};
};
Preprocessor instructions
Note that you can also add your own preprocessor instructions for commonly used data, eg. for colors, to save yourself the hassle of writing it in several different places and then adapt each of them if you want to change them afterwards (especially if class inheritance isn't applicable). Also it can make your code look more readable sometimes.
- Example:
#define COLOR_LIGHTBROWN { 0.776, 0.749, 0.658, 1 }
#define COLOR_HALF_BLACK { 0, 0, 0, 0.5 }
#define COLOR_TRANSPARENT { 0, 0, 0, 0 }
// …
class MyDialog {
idd = -1;
movingEnable = 1;
objects[] = {};
controlsBackground[] = { MyDialogBackground };
controls[] = { MyDialogText };
class MyDialogBackground : RscText {
colorBackground[] = COLOR_HALF_BLACK;
x = 0.7; y = 0.1;
w = 0.25; h = 0.15;
};
class MyDialogText : RscText {
style = ST_MULTI;
colorBackground[] = COLOR_TRANSPARENT;
colorText[] = COLOR_LIGHTBROWN;
text = "No power in the 'Verse can stop me.";
lineSpacing = 1;
x = 0.71; y = 0.11;
w = 0.23; h = 0.13;
};
};