7erra/Sandbox – User

From Bohemia Interactive Community
Jump to navigation Jump to search
m (7erra moved page GUI Tutorial to User:7erra/Sandbox over redirect: moving is not bueno)
(emptied page)
Line 1: Line 1:
{{WIP}}
<pre>
= Introduction =
                _.                              _______
This page will guide you through the first steps on how to create a UI in Arma 3. It will only go over the very basic stuff. For some more advanced usage you can try and look at how Arma 3 handles its UIs.
          __.--'  |            ____...,---'''''     .'''-.
<!-- TODO: check out [[Arma 3: GUI Framework]].-->
      _,-'        \ ____...--'''                     | '   '-._
== Terminology ==
    ,-'             |                                |  \      -.
Before we begin let us clear up some words and their meaning:
,-'               '                                 |  '       `\
{| class="wikitable"
|                   \                              .'    '   _,._/
|-
|                     \                              |     '  \
! Term
|                    \                             |      \ '
! Meaning
||                     \                            |        \<
|-
|\                      \                          |          \|
| UI
|'.                     \                          /           |
| '''U'''ser '''I'''nterface. What the player will see. Also: GUI ('''G'''raphical User Interface, IGUI (meaning not entierly clear, used for HUDs in Arma), display, dialog.
| |                      \                        |            '
|-
| '.                     |                 ____,..            \
| Dialog/Display
| |                      \__,...-----''''''      `.           |
| Generally speaking they are the same. There are a few tiny differences between these two terms which will be explained in [[#createDialog vs createDisplay vs cutRsc|this section]] later on.
|  '.                      \                          \          '
|-
|  |                      \                          `          \
| HUD
|  '                        \                          `          |
| '''H'''eads-'''u'''p-'''D'''isplay. A type of display for displaying information that does not interfere with the player's controls.
|    |                        \                          \          \
|-
|   '.                       '                          \          \
| UIEH
|     \                        \                          \      _,|
| '''U'''ser '''I'''nterface '''E'''vent '''H'''andler. Detects changes to the UI. Explained in [[#User Interface Event Handlers|this section]].
|     |                       \                          \ _,.--  |
|}
|     '.                       ,                      _,.-'      |
 
'      \                 _,.-''                __.,-''            |
= Config =
|      |             _.-'                _,.,--'                  |
You will need files for the following parts:
\        \        _.-'          __,.,--''                         |
* A config
'        `.   ,-'      __..---''                                  |
* Basic control classes
'        \ ,-'___..,--'                ____                        '
* A display config
  \        -'''                ____    / ___|                       .
 
  .       |             ___  / ___| | |                         ,
Your folder structure could look something like this:
    |       |   __  __  |_ _| \___ \  | |___                      |
<code>mission.World/
    '      |   | \/  | | |   ___) | \____|                     |
├── mission.sqm
    \      |   | |\/| | | | |____/                              |
├── description.ext
      \    |   | | | | |___|                                     |
├── UI/
      \    |   |_| |_|                                     __,.-''
│   ├── BaseControls.hpp
        \  |                                       __,..-''
│  ├── RscDisplayName.hpp
        \  |                              ___..--'''       [lf]
</code>
          \ |                    ___,.--''
 
          \|       ____...,--'''
If you are making a mod the description.ext will be called config.cpp and there is no mission.sqm. We will call the description.ext and config.cpp the main config to cover both.
            '_..,--''
 
</pre>
== Main Config Content ==
All display classes are defined in here. Since the config can get very long we will instead include the files in one another with the {{Inline code|#include}} [[PreProcessor_Commands#.23include|preprocessor]]:
<syntaxhighlight lang=cpp>#include "UI\BaseControls.hpp"
#include "UI\RscDisplayName.hpp"</syntaxhighlight>
 
== Parent Controls ==
Also known as base controls. They are the controls that we will be inheriting from. This means that we will copy the content of the parent class without having to rewrite every class. Each parent class has its own unique functionality or appearance determined by their attributes, for example the color of the background is determined by the {{Inline code|colorBackground}} attribute. If we inherit from this parent class then our dialog control will have the same background color as the parent class. The concept of class inheritance is explained [[Class_Inheritance|here]]. There are three ways to declare these base classes.
 
=== Export Classes Via BIS_fnc_exportGUIBaseClasses ===
Run this command from the debug console:
<code>["Default"] [[call]] [[BIS_fnc_exportGUIBaseClasses]];</code>
The result is copied to the clipboard. Paste it into BaseControls.hpp.
 
=== Import Classes Via import Keyword (Mission Only) ===
{{GVI|arma3|2.02}} You can use the base classes from the game config by using the [[import]] keyword:
<syntaxhighlight lang=cpp>import RscObject;
import RscText;
import RscFrame;
import RscLine;
import RscProgress;
import RscPicture;
import RscPictureKeepAspect;
import RscVideo;
import RscHTML;
import RscButton;
import RscShortcutButton;
import RscEdit;
import RscCombo;
import RscListBox;
import RscListNBox;
import RscXListBox;
import RscTree;
import RscSlider;
import RscXSliderH;
import RscActiveText;
import RscActivePicture;
import RscActivePictureKeepAspect;
import RscStructuredText;
import RscToolbox;
import RscControlsGroup;
import RscControlsGroupNoScrollbars;
import RscControlsGroupNoHScrollbars;
import RscControlsGroupNoVScrollbars;
import RscButtonTextOnly;
import RscButtonMenu;
import RscButtonMenuOK;
import RscButtonMenuCancel;
import RscButtonMenuSteam;
import RscMapControl;
import RscMapControlEmpty;
import RscCheckBox;</syntaxhighlight>
 
=== Declare Classes (Addon Only) ===
We have access to the classes from the game's config when we declare them beforehand.
<syntaxhighlight lang=cpp>class RscObject;
class RscText;
class RscFrame;
class RscLine;
class RscProgress;
class RscPicture;
class RscPictureKeepAspect;
class RscVideo;
class RscHTML;
class RscButton;
class RscShortcutButton;
class RscEdit;
class RscCombo;
class RscListBox;
class RscListNBox;
class RscXListBox;
class RscTree;
class RscSlider;
class RscXSliderH;
class RscActiveText;
class RscActivePicture;
class RscActivePictureKeepAspect;
class RscStructuredText;
class RscToolbox;
class RscControlsGroup;
class RscControlsGroupNoScrollbars;
class RscControlsGroupNoHScrollbars;
class RscControlsGroupNoVScrollbars;
class RscButtonTextOnly;
class RscButtonMenu;
class RscButtonMenuOK;
class RscButtonMenuCancel;
class RscButtonMenuSteam;
class RscMapControl;
class RscMapControlEmpty;
class RscCheckBox;</syntaxhighlight>
 
== Display Config ==
A display class looks like this:
<syntaxhighlight lang=cpp>class RscDisplayName
{
idd = 1234;
class ControlsBackground
{
};
class Controls
{
};
};</syntaxhighlight>
 
{{Inline code|RscDisplayName}} is the name of the display which will be used in the [[createDisplay]]/[[createDialog]] commands.<br>
{{Inline code|idd}} is the identification number for the display. It is used in the [[findDisplay]] command. It is mandatory to have it defined. If you don't intend to use the idd you can set it to -1.<br>
{{Inline code|ControlsBackground}} contains all controls that should stay in the background, for example the dark background of the display.<br>
{{Inline code|Controls}} contains all important controls, for example buttons.
 
=== Controls Config ===
The most common way to create a UI in Arma 3 is via the [[Arma 3: User Interface Editor]]. The BIKI page contains a tutorial on it too. You might also be interested in some of the external UI editors listed [https://forums.bohemia.net/forums/topic/226269-tools-utilities-compilation-list-for-arma3/ here].
 
A possible output from the GUI Editor might look like this:
<syntaxhighlight lang=cpp>class RscButton_1600: RscButton
{
idc = 1600;
x = GUI_GRID_CENTER_X + 0 * GUI_GRID_CENTER_W;
y = GUI_GRID_CENTER_Y + 0 * GUI_GRID_CENTER_H;
w = 40 * GUI_GRID_CENTER_W;
h = 25 * GUI_GRID_CENTER_H;
};</syntaxhighlight>
 
The {{Inline code|idc}} is the identification number for a control. It is used in the [[displayCtrl]] command and can be returned by the [[ctrlIDC]] command.<br>
{{Inline code|x}} and {{Inline code|y}} determine the position of the control. {{Inline code|w}} and {{Inline code|h}} determine the size. These numbers are given in [[Arma 3: GUI Coordinates|screen coordinates]]. They are somewhat complicated so read about them on the linked page. In the example the {{Inline code|GUI_GRID_CENTER_X/Y/W/H}} macro is used to keep the UI in the middle of the screen on all possible screen resolutions and UI sizes.<br>
Apart from the editable attributes in the GUI Editor there are even more. Which exactly depends on the {{Inline code|type}} of the control. Here is an overview over all available control types (CTs).
{{Navbox/CT}}
 
== HUDs ==
A Head-Up-Display is just another type of display in Arma 3. All of the above applies to them too. The differences are:
* The player will be able to move and look around while the display is open but can not interact with it.
* The display class has to be listed as part of the RscTitles class:
<syntaxhighlight lang=cpp>#include "UI\BaseControls.hpp"
class RscTitles
{
#include "UI\RscMyHUD.hpp"
};</syntaxhighlight>
* The display class needs the {{Inline code|duration}} attribute. It determines how long the display will stay on screen. You can choose a large number to make it stay "forever", for example 10^6 (scientific notation: 1e+6) seconds.
<syntaxhighlight lang=cpp>class RscMyHUD
{
idd = -1;
duration = 1e+6;
{...</syntaxhighlight>
* The commands for controlling the display are also different:
** HUDs are created with [[cutRsc]].
** [[findDisplay]] does not work on RscTitles displays. Save the display as a variable to [[uiNamespace]] instead. You can get the display with the following code:
<code>[[uiNamespace]] [[getVariable]] ["RscMyHUD", [[displayNull]]];</code>
<br>
<syntaxhighlight lang=cpp>class RscMyHUD
{
idd = -1;
onLoad = "uiNamespace setVariable ['RscMyHUD', _this select 0];";
duration = 1e+6;
class Controls
{...</syntaxhighlight>
 
= Scripting =
To bring your dialog to life you will need to know how to influence it with sqf commands. A list of all available UI related commands can be found [[:Category:Command_Group:_GUI_Control|here]]. A list of GUI related functions can be found [[:Category:Function_Group:_GUI|here]]. Some control types have special commands such as [[lbAdd]] to add an item to a listbox. A list of commands that are related to the control type can be found on the control type's BIKI page.<br>
== createDialog vs createDisplay vs cutRsc ==
[[createDialog]], [[createDisplay]] and [[cutRsc]] (for [[#HUDs|HUDs]] have all their own unique use cases. Here is an overview over what each command does or does not do:
{| class="wikitable"
|-
!
! createDialog
! createDisplay
! cutRsc
|-
| Interactable
| {{Checkbox|yes}}
| {{Checkbox|yes}}
| {{Checkbox|no}}
|-
| Player can move
| {{Checkbox|no}}
| Depends on the parent display.
| {{Checkbox|yes}}
|-
| Player can look around
| {{Checkbox|no}}
| {{Checkbox|no}}
| {{Checkbox|yes}}
|-
| Escape closes display
| {{Checkbox|yes}}
| {{Checkbox|yes}}
| {{Checkbox|no}}
|-
| Can be returned by [[findDisplay]]
| {{Checkbox|yes}}
| {{Checkbox|yes}}
| {{Checkbox|no}}
|-
| Returns created display
| {{Checkbox|no}}
| {{Checkbox|yes}}
| {{Checkbox|no}}
|-
| Can be created on top of another display
| {{Checkbox|yes}} (not recommended)
| {{Checkbox|yes}} (preferred method)
| {{Checkbox|yes}} (will coexist with other displays but is still not interactable with)
|}
 
== User Interface Event Handlers ==
User interface event handlers (UIEH) are a way to detect changes to the UI. A list of them can be found [[User_Interface_Event_Handlers|here]]. Once again, different control types have different UIEHs. For example onButtonClick will detect when a button is clicked. The arguments that are passed to the script also depend on the UIEH. The onButtonClick event will pass the button itself as the only argument in the _this variable. On the other hand onLBSelChanged will pass the control and the selected index as arguments into the script. Since the UIEH is a different script instance, all previously defined local variables will not be available in the code. There are two ways to add an UIEH to a control:
 
=== Adding UIEHs via config ===
The UIEH is given as an attribute of the control's class like this:
<syntaxhighlight lang=cpp>class ClickMe: RscButton
{
idc = -1;
text = "Click Me!";
onButtonClick = "hint 'You clicked the button!';"; // display a hint when clicked upon
x = GUI_GRID_CENTER_X + 10 * GUI_GRID_CENTER_W;
y = GUI_GRID_CENTER_Y + 12 * GUI_GRID_CENTER_H;
w = 20 * GUI_GRID_CENTER_W;
h = 1 * GUI_GRID_CENTER_H;
};</syntaxhighlight>
The UIEH's name always starts with "on". The code that should be executed is given as a string.
 
=== Adding UIEHs via script ===
To add UIEHs you can also use [[ctrlAddEventHandler]]. In this case the UIEH does NOT start with "on"!
<code>// This script does the same as the config example
_display = [[findDisplay]] 1234;
_ctrl = _display [[displayCtrl]] 1000;
_ctrl [[ctrlAddEventHandler]] ["ButtonClick", { {{cc|Notice the missiing "on"!}}
[[params]] ["_ctrl"];
[[hint]] "You clicked the button!";
}];</code>
 
= Final Result =
== description.ext or config.cpp ==
<syntaxhighlight lang=cpp>
#include "\a3\ui_f\hpp\defineCommonGrids.inc"
#include "UI\BaseControls.hpp"
#include "UI\RscDisplayMyDialog.hpp"
class RscTitles
{
#include "UI\RscMyHUD.hpp"
};</syntaxhighlight>
 
== BaseControls.hpp (from BIS_fnc_exportGUIBaseClasses) ==
{{Informative|Due to the lenght of this file it is not included here. It is exactly the output as described in [[#Export Classes Via BIS_fnc_exportGUIBaseClasses|this section]].}}
 
== RscDisplayMyDialog.hpp ==
<syntaxhighlight lang=cpp>class RscDisplayMyDialog
{
idd = 1234;
class ControlsBackground
{
class Background: RscText
{
idc = -1;
x = GUI_GRID_CENTER_X;
y = GUI_GRID_CENTER_Y;
w = 40 * GUI_GRID_CENTER_W;
h = 25 * GUI_GRID_CENTER_H;
colorBackground[] = {0,0,0,0.8};
};
};
class Controls
{
class ClickMe: RscButton
{
idc = -1;
text = "Click Me!";
onButtonClick = "hint 'You clicked the button!';";
x = GUI_GRID_CENTER_X + 10 * GUI_GRID_CENTER_W;
y = GUI_GRID_CENTER_Y + 12 * GUI_GRID_CENTER_H;
w = 20 * GUI_GRID_CENTER_W;
h = 1 * GUI_GRID_CENTER_H;
};
};
};</syntaxhighlight>
 
== RscMyHUD.hpp ==
<syntaxhighlight lang=cpp>class RscMyHUD
{
idd = -1;
onLoad = "uiNamespace setVariable ['RscMyHUD', _this select 0];";
duration = 10;
fadeIn = 1;
fadeOut = 1;
class Controls
{
class CenterText: RscStructuredText
{
text = "This text box will stay here for 10 seconds. You can still move and look around.";
x = GUI_GRID_CENTER_X;
y = GUI_GRID_CENTER_Y;
w = 40 * GUI_GRID_CENTER_W;
h = 25 * GUI_GRID_CENTER_H;
colorBackground[] = {0,0,0,0.8};
};
};
};</syntaxhighlight>
 
= Summary =
* A UI consists of the following parts:
** Base controls to inherit from
** The display
** UIEHs
* You can get the base controls in a few different ways
* The display contains a list of (non) interactable controls
* These controls can have different styles and functionalities
* You can use the GUI Editor or external tools to have a WYSIWYG approach
* UIEHs can detect interactions with the UI
 
= Afterword =
Now it is up to you to create some UIs. If you have questions feel free to ask them on the BI Forums for [https://forums.bohemia.net/forums/forum/154-arma-3-mission-editing-scripting/ mission makers] or [https://forums.bohemia.net/forums/forum/162-arma-3-addons-configs-scripting/ addon makers]. You can also find a discord channel dedicated to GUI editing on the [https://discord.com/invite/arma Arma 3 discord].
<!--If you have gained a little experience and have more questions you can take a look at [[Arma 3: GUI Framework]] to see how the displays in Arma 3 are handled.-->

Revision as of 14:24, 4 February 2021

                 _.                              _______
           __.--'  |             ____...,---'''''     .'''-.
       _,-'        \ ____...--'''                     | '   '-._
    ,-'             |                                 |  \      -.
 ,-'                '                                 |   '       `\
|                    \                               .'    '   _,._/
|                     \                              |      '  \
|                     \                              |       \  '
||                     \                             |        \<
|\                      \                           |          \|
|'.                     \                           /           |
| |                      \                         |            '
| '.                      |                  ____,..             \
|  |                       \__,...-----''''''       `.            |
|  '.                      \                          \           '
|   |                       \                          `           \
|   '                        \                          `           |
|    |                        \                          \          \
|    '.                       '                           \          \
|     \                        \                           \       _,|
|      |                        \                           \ _,.--  |
|      '.                        ,                       _,.-'       |
'       \                  _,.-''                 __.,-''            |
 |       |             _.-'                _,.,--'                   |
 \        \        _.-'           __,.,--''                          |
 '        `.    ,-'      __..---''                                   |
 '         \ ,-'___..,--'                ____                        '
  \         -'''                ____    / ___|                       .
   .        |             ___  / ___|  | |                          ,
    |       |    __  __  |_ _| \___ \  | |___                       |
    '       |   |  \/  |  | |   ___) |  \____|                      |
     \      |   | |\/| |  | |  |____/                               |
      \     |   | |  | | |___|                                      |
       \    |   |_|  |_|                                     __,.-''
        \   |                                        __,..-''
         \  |                              ___..--'''        [lf]
          \ |                     ___,.--''
           \|        ____...,--'''
            '_..,--''
Retrieved from "https://community.bistudio.com/wiki?title=User:7erra/Sandbox&oldid=238912"