Dynamic Dialog

A good module needs a GUI. For this purpose we provide a simple to use, but powerful dynamic dialog system.

1. Creating the dialog

All dynamic dialogs are created using the achilles_dialog_fnc_create function.

Here’s an example dialog:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
[
    "My awesome dialog",
    [
        ["CHECKBOX", "My Checkbox", true],
        ["COLOR", "Red Color", [1, 0, 0]],
        ["COLOR", "Faded Green", [0, 1, 0, 0.5]],
        ["SELECT", ["My Select", "With tooltip!"], [
            ["this", "my", true, "values"],
            [
                ["My basic thing"],
                ["This", "fancy tooltip", "\A3\Data_F\Flags\Flag_AAF_CO.paa", [0, 1, 0, 1]],
                ["Something else"],
                ["Other values"]
            ],
            1
        ]],
        ["TEXT", "Text Input", ["Default string", {params ["_notSanitized"]; _notSanitized}]],
        ["SIDES", "Your allegiance", east],
        ["SLIDER", "Awesomeness", [0, 10, 5, 2]],
        ["BLOCK:YESNO", "Is Demo?", true],
        ["BLOCK:ENABLED", "Internet status"],
        ["BLOCK", "Fine", [1, ["Dining", "Wine", "Arma"]]],
        ["VECTOR", "What's your", [5, 25]],
        ["VECTOR", "Vector, Victor?", [15, 30, -5]]
    ],
    {
        // On success
        systemChat str _this;
        diag_log _this;
    },
    {
        // On cancel
        systemChat str _this;
        diag_log _this;
    }
] call achilles_dialog_fnc_create;

Produces the following dialog:

Example dialog

2. Function Arguments

The arguments for the actual dialog function is pretty simple, however, it can scale up to suit most of your needs.

Name Type Default
Dialog title STRING Required
Controls ARRAY Required
On Confirm CODE Required
On Cancel CODE {}
Arguments ANY []

3. Control Arguments

Currently, there are 8 different controls for the dynamic dialog.

Name Control Type Alternative Control Types
Checkbox CHECKBOX N/A
Color (RGB or RGBA) COLOR N/A
Select dropdown SELECT N/A
Text TEXT N/A
Side selection SIDES SIDES:ALL
Slider SLIDER N/A
Block selection BLOCK BLOCK:YESNO, BLOCK:ENABLED
Vector (2 or 3 axis) VECTOR N/A
Description DESCRIPTION N/A

3.1. Checkbox control

The checkbox control is simple to use and doesn’t have a lot of options.

Arguments:

Name Type Allowed Values Description Default
Control STRING "CHECKBOX" Display a checkbox type control. Required
Display Name STRING or ARRAY STRING or ["Display Name", "Tooltip"] What does the control represent? Required
Is checked? BOOL BOOL Should the checkbox be checked? false
Force default value? BOOL BOOL Should the given default value be forced? Should we ignore the last saved value? false
Resource function CODE CODE Arguments are [Control Group, Row Index, Default Value, Row Settings]. {}

Example:

1
2
3
4
5
6
7
["My Dialog", [
    [
        "CHECKBOX",
        "Is Achilles?",
        true
    ]
], {}] call achilles_dialog_fnc_create;

Result:

Checkbox dialog

3.2. Color control

The color control supports two different types. RGB (red-green-blue) or RGBA (red-green-blue-alpha)

There is no specific flag to set. The dynamic dialog system will automatically set the type depending on the value data array length.

Arguments:

Name Type Allowed Values Description Default
Control STRING "COLOR" Display a color type control. Required
Display Name STRING or ARRAY STRING or ["Display Name", "Tooltip"] What does the control represent? Required
Default color data ARRAY [1, 1, 1] or [1, 1, 1, 1] What should the default color data be? If 4 arguments provided in the array, then it displays an RGBA control. [1, 1, 1]
Force default value? BOOL BOOL Should the given default value be forced? Should we ignore the last saved value? false
Resource function CODE CODE Arguments are [Control Group, Row Index, Default Value, Row Settings]. {}

3.2.1. Color RGB

Example:

1
2
3
4
5
6
7
["My Dialog", [
    [
        "COLOR",
        "Blue color",
        [0, 0, 1]
    ]
], {}] call achilles_dialog_fnc_create;

Result:

RGB control dialog

3.2.2. Color RGBA

Example:

1
2
3
4
5
6
7
["My Dialog", [
    [
        "COLOR",
        "Faded Dark Purple",
        [0.5, 0, 0.8, 0.25]
    ]
], {}] call achilles_dialog_fnc_create;

Result:

RGBA control dialog

3.3. Select dropdown control

Select dropdown is a dropdown list control that is very powerful. It allows for you to set tooltips, images, text colors, etc.

Arguments:

Name Type Allowed Values Description Default
Control STRING "SELECT" Display a select type control. Required
Display Name STRING or ARRAY STRING or ["Display Name", "Tooltip"] What does the control represent? Required
Array of selectable items ARRAY See “3.3.1. Allowed values” Array of selectable elements that will be displayed to the user. Required
Force default value? BOOL BOOL Should the given default value be forced? Should we ignore the last saved value? false
Resource function CODE CODE Arguments are [Control Group, Row Index, Default Value, Row Settings]. {}

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
["My Dialog", [
    [
        "SELECT",
        [
            "What should we eat tonight?",
            "Pick something delicious!"
        ],
        [
            [
                ["Flour", "Cheese", "Magic"], "Find it!", false
            ],
            [
                ["Pizza", "Delicious?"],
                ["An apple", "Easy!", "\A3\Data_F\Flags\Flag_green_CO.paa", [0, 1, 0, 1]],
                ["Steak"]
            ],
            1
        ]
    ]
], {}] call achilles_dialog_fnc_create;

Result:

Select dropdown control dialog

3.3.1. Allowed values

Name Type Default Description
Value array of anything ARRAY Required Once the user selects an item from the dialog and closes it (OK or Cancel) the selected value will be returned from this array.
Array of display values ARRAY (See display arguments) Required An array of values that will be displayed to the user.
Default selected value SCALAR 0 Allows to select which element will be the default selected one.

Display text arguments:

Below is a table with arguments for the display content of one element.

Name Type Default Description
Display Name STRING Required Dropdown item name to be displayed to the user.
Tooltip Name STRING "" Tooltip to display when the user moves his mouse over the dropdown item.
Picture Path STRING "" Path to the image to be displayed to the left of the display name.
Text Color ARRAY [1, 1, 1, 1] The text color for that one dropdown item. Requires color RGBA.

3.4. Text control

The text control is a simple text box that allows users to input data into the box.

Arguments:

Name Type Allowed Values Description Default
Control STRING "TEXT" Display a text type control. Required
Display Name STRING or ARRAY STRING or ["Display Name", "Tooltip"] What does the control represent? Required
Default string to display STRING or ARRAY STRING or ["Default Text", {_this}] The default text what should be displayed when the control is first displayed. Required
Force default value? BOOL BOOL Should the given default value be forced? Should we ignore the last saved value? false
Resource function CODE CODE Arguments are [Control Group, Row Index, Default Value, Row Settings]. {}

Default text has two options:

  • Any string.
  • Array of default text to display and the sanitize function or code to call.

This sanitize function receives the text the user is currently entering in _this variable. This function is called on each key press in the unscheduled enviornment.

Warning

As this function is called on each key press, it has to be very quick.

Example:

1
2
3
4
5
6
7
["My Dialog", [
    [
        "TEXT",
        "What's the year?",
        "20"
    ]
], {}] call achilles_dialog_fnc_create;

Result:

Text control dialog

3.5. Side select control

A simple side selector control which allows the user to select between the 4 main sides.

  • BLUFOR
  • OPFOR
  • Independent
  • Civilian

An optional 5th side can be added: Logic side (sideLogic). This is achieved using the secondary control SIDES:ALL.

Warning

It’s highly recommended to provide a default value for the side. If not done so, then if the user doesn’t select anything when prompted to, will result in a nil value in the dialog result.

Arguments:

Name Type Allowed Values Description Default
Control STRING "SIDES" or "SIDES:ALL" Display a side type control. Required
Display Name STRING or ARRAY STRING or ["Display Name", "Tooltip"] What does the control represent? Required
Default side to show as selected SIDE SIDE The default side that should be selected. nil
Force default value? BOOL BOOL Should the given default value be forced? Should we ignore the last saved value? false
Resource function CODE CODE Arguments are [Control Group, Row Index, Default Value, Row Settings]. {}

Example:

1
2
3
4
5
6
7
["My Dialog", [
    [
        "SIDES",
        "You like the",
        west
    ]
], {}] call achilles_dialog_fnc_create;

Result:

Side control dialog

3.6. Slider control

The slider control is a simple slider that allows you to select a value in the defined range.

Arguments:

Name Type Allowed Values Description Default
Control STRING "SLIDER" Display a slider type control. Required
Display Name STRING or ARRAY STRING or ["Display Name", "Tooltip"] What does the control represent? Required
Array of slider settings ARRAY [min, max, default, decimals] Array of the minimum and maximum allowed values of the slider, the default value to set the slider at and the decimal point. [0, 1, 0, 2]
Force default value? BOOL BOOL Should the given default value be forced? Should we ignore the last saved value? false
Resource function CODE CODE Arguments are [Control Group, Row Index, Default Value, Row Settings]. {}

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
["My Dialog", [
    [
        "SLIDER",
        "Distance to Altis",
        [
            0,
            100,
            25,
            1
        ]
    ]
], {}] call achilles_dialog_fnc_create;

Result:

Slider control dialog

3.7. Block selection control

The block selection is a way to select something without having to go into a select dropdown or something that the simple checkbox can’t handle.

Arguments:

Name Type Allowed Values Description Default
Control STRING "BLOCK", BLOCK:YESNO, BLOCK:ENABLED Display a block select type control. Allows to quickly use Yes/No or Enabled/Disabled type questions. Required
Display Name STRING or ARRAY STRING or ["Display Name", "Tooltip"] What does the control represent? Required
Array of block questions ARRAY See “3.7.1. Allowed values” An array of data to be displayed to the user (not required if using the :YESNO or :ENABLED secondary controls.) [0, 1, 0, 2]
Force default value? BOOL BOOL Should the given default value be forced? Should we ignore the last saved value? false
Resource function CODE CODE Arguments are [Control Group, Row Index, Default Value, Row Settings]. {}

3.7.1. Allowed values

Note

If using any of the secondary control types, then you do not have to add the questions.

Note

The maximum amount of items to select in the block control that can be added is 5.

To select the default value you can use the indexes of the question (0, 1, etc.) but if you only have 2 questions, then you can use a boolean.

If you are using the secondary control then you can also specify which control should be the default selected one. You can use a boolean to select the default question. false would be on the left and true would be on the right.

Examples:

1
2
3
4
5
6
7
["My Dialog", [
    [
        "BLOCK:YESNO",
        "Taras Kul",
        [true]
    ]
], {}] call achilles_dialog_fnc_create;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
["My Dialog", [
    [
        "BLOCK",
        "She's",
        [
            2,
            [
                "Old",
                "Cool",
                "On Fire",
                "Boring",
                "Other"
            ]
        ]
    ]
], {}] call achilles_dialog_fnc_create;

Results:

Block select control with YESNO dialog Block select with multiple choices control dialog

3.8. Vector control

The vector control works very similarly to the color control. As in it’s dependent on the number of elements provided to display the number of axes you want.

If you provide 2 elements then you will only see the option to enter the X and Y axes, but if you provide 3 then the Z axis is added too.

Arguments:

Name Type Allowed Values Description Default
Control STRING "VECTOR" Display a vector type control. Required
Display Name STRING or ARRAY STRING or ["Display Name", "Tooltip"] What does the control represent? Required
Array of vector axes ARRAY [0, 0] or [0, 0, 0] The number of elements dictates if the Z axis should also be displayed. [0, 0]
Force default value? BOOL BOOL Should the given default value be forced? Should we ignore the last saved value? false
Resource function CODE CODE Arguments are [Control Group, Row Index, Default Value, Row Settings]. {}

Example:

1
2
3
4
5
6
7
["My Dialog", [
    [
        "VECTOR",
        "Universe Length",
        [-5034, 1000, 3]
    ]
], {}] call achilles_dialog_fnc_create;

Result:

Vector control dialog

3.9. Description control

The description control is designed to display a multi-line text message to the user to describe anything you like.

If you want to display a multi-line message then you have to append the new line character (\n) to your string of text.

Note

This control does not return it’s value when cancelling or confirming the dialog.

Arguments:

Name Type Allowed Values Description Default
Control STRING "DESCRIPTION" Display a description type control. Required
Display Name STRING or ARRAY STRING or ["Display Name", "Tooltip"] What does the control represent? Required
Text to display STRING STRING This text will be displayed to the user. To add a new line use the \n character. Required
Resource function CODE CODE Arguments are [Control Group, Row Index, Default Value, Row Settings]. {}

Example:

1
2
3
4
5
6
7
["My Dialog", [
    [
        "DESCRIPTION",
        "Description",
        "This is a very long description of my dialog/module.\nThis is now on a new line."
    ]
], {}] call achilles_dialog_fnc_create;

Result:

Description control dialog

4. On Confirm and On Cancel

On confirm and on cancel are two different scripts that will be executed depending on the following conditions:

  • If the user presses the OK or Cancel buttons.
  • If the user presses the Escape key.

When these scripts are called, data is passed in the _this variable.

Name Type Default
Array of selected values ARRAY N/A
Array of arguments (provided when calling the function) ARRAY []