Lou Montana: Page creation

2025-01-23T16:54:11Z

Page creation

New page

{{TOC|side}}
The Configurable Dialog system allows to easily make a custom dialog given a config file.

== Dialog Creation ==

* Make a layout if needed.
* Inherit from {{Link/Enfusion|armaR|SCR_ConfigurableDialogUi}} for a custom dialog handler, if needed.
* Make a {{Link/Enfusion|armaR|SCR_ConfigurableDialogUiPresets}} config file or choose an existing one.
* Add entries of {{Link/Enfusion|armaR|SCR_ConfigurableDialogUiPreset}} in the config: these are your dialogs. Give them exclusive tags within the config file that holds them.
* In scripts, when you want to spawn a dialog, you need to:
** Instantiate the custom handler (if created)
** Call the static method <enforce inline>SCR_ConfigurableDialogUi.CreateFromPreset()</enforce>. The parameters you need to provide are:
*** '''presetsResourceName''': ResourceName (GUID) of the config file that holds the dialog preset.
*** '''tag''': unique identifier string to target the dialog to be spawned.
*** '''customDialogObj''': optional handler class inheriting from {{Link/Enfusion|armaR|SCR_ConfigurableDialogUi}} - if not provided the base SCR_ConfigurableDialogUi will be used instead.
The <enforce inline>CreateFromPreset()</enforce> method returns the instance of the dialog handler that has been made for the newly spawned dialog, so you can cast to your custom handler type to perform further operations.

=== Layouts ===

{{armaR}} generally uses three layouts: {{hl|ConfigurableDialog}}, {{hl|ConfigurableDialog_Medium}}, {{hl|ConfigurableDialog_Big}}.

<gallery>
</gallery>

The structure is:
* a Size widget that defines the dimensions of the whole dialog
* a Header with title and icon
* a Message text
* a Content area
* a Footer for the buttons.

The content of complex dialogs should be its own layout, which the system will dynamically add to the base.

Still, nothing stops anyone from creating their own "complete" layout by inheriting from one of the bases and filling the {{hl|ContentLayoutContainer}} widget manually with whatever needed content.

It is recommended to have the content be its own layout; however for ease of maintenance, future changes to the base hierarchy might cause the loss of content that is not protected in its own prefab layout.
Same goes with buttons: they either get added through the {{hl|.conf}} files or in the manually created layout.

=== SCR_ConfigurableDialogUi ===

The base dialog handler is a {{Link/Enfusion|armaR|ScriptedWidgetComponent}} that will be instantiated by the dialog creation process and attached to the dialog layout.

It provides handling of the Title, Message, Content and Footer as defined in the presets, and includes methods and invokers for confirming, canceling and closing.

The dialog itself is technically a menu,, since the Configurable layout is inserted into a proxy menu created with the enfusion Menu Manager, and thus has also access to menu events.

By inheriting from {{Link/Enfusion|armaR|SCR_ConfigurableDialogUi}} you can freely extend its functionality.

=== SCR_ConfigurableDialogUiPresets ===

These config files allow us to spread the large amount of dialogs needed by the game into multiple, smaller lists.

This avoids unnecessary clutter in chimeraMenus.conf, and allows to organize dialogs in their own .confs and scripts.

A dialog config file can contain multiple presets, identified by tag. The standard Configurable dialog preset should already have all the attributes necessary for your dialog, but you can always inherit from {{Link/Enfusion|armaR|SCR_ConfigurableDialogUiPreset}} and extend it.

'''The Tag is used to know which dialog to create'''. As such, you need unique tags in a single {{hl|.conf}} file.

The system will assemble the dialog, adding the content and buttons to the base.

It is possible to create prefab {{hl|.conf}} files for single dialogs and buttons, and then use those in the general dialog {{hl|.conf}} files.
An example is {{Link|enfusion://ResourceManager/~ArmaReforger:Configs/ConfigurableDialogs/DialogPrefabs/MessageOkCancel.conf}}.

=== Related Classes ===

==== Configuration Classes ====
* {{Link/Enfusion|armaR|SCR_ConfigurableDialogUiPresets}} - collection of dialog presets. This is a config root.
* {{Link/Enfusion|armaR|SCR_ConfigurableDialogUiPreset}} - class of one preset configuration. A preset contains some properties of a dialog (dialog tag, style, message, title, buttons configuration)
* {{Link/Enfusion|armaR|SCR_ConfigurableDialogUiButtonPreset}} - class of one button configuration (button tag, name, label, alignment).

==== Main Classes ====
* {{Link/Enfusion|armaR|SCR_ConfigurableDialogUi}} - the main class which represents a configurable dialog. You can override some methods in inherited classes for custom functionality. This class inherits from {{Link/Enfusion|armaR|ScriptedWidgetComponent}}, and in the end gets attached to the dialog's root widget as a component. There are several ways to attach it to the widget:
*# call <enforce inline>CreateByPreset()</enforce> with customDialogObj left null. In this case the system creates a new <enforce inline>SCR_ConfigurableDialogUi</enforce> object and attaches it to the widget.
*# call <enforce inline>CreateByPreset()</enforce> and provide it with a customDialogObj, in this case the provided object will be attached to the widget.
*# attach a {{Link/Enfusion|armaR|SCR_ConfigurableDialogUi}}-inherited object directly to the layout's root widget, in the layout file.
* {{Link/Enfusion|armaR|SCR_ConfigurableDialogUiProxy}} - this is the parent menu which holds the actual dialog widgets.

== Initialisation Sequence ==

The whole dialog creation and initialisation sequence is done in <enforce inline>SCR_ConfigurableDialogUi.CreateFromPreset()</enforce> and <enforce inline>CreateByPreset</enforce> methods.

* <enforce inline>CreateFromPreset(ResourceName presetsResourceName, string tag, SCR_ConfigurableDialogUi customDialogObj = null)</enforce> is called.
* the config file provided in presetsResourceName is loaded, the preset object is found by tag.
* the proxy dialog in game's MenuManager is created.
* the actual dialog widgets are created inside proxy dialog's root widget. The actual dialog layout is taken from preset's {{hl|m_sLayout}} property.
* a new {{hl|customDialogObj}} is created and attached to the dialog's root, or the provided {{hl|customDialogObj}} is used, or the one which is already attached to the layout.
* <enforce inline>Dialog.Init</enforce> is called - here we apply title, message, add buttons.
* <enforce inline>Dialog.OnMenuOpen</enforce> is called - here we expect derived class to perform the custom initialisation, if needed.

== Examples ==

=== Basic Usage ===

We create a simple dialog with message. If we want to do something when a button is pressed, we can subscribe to one of the available events.

<enforce>
const ResourceName DIALOGS_CONFIG = "{814FCA3CB7851F6B}Configs/Dialogs/CommonDialogs.conf";

SCR_ConfigurableDialogUi dialog = SCR_ConfigurableDialogUi.CreateFromPreset(DIALOGS_CONFIG, "timeout_ok"); // "timeout_ok" is the Tag property

// we can execute our code when dialog is closed
// useful for a common dialog which is called from many places,
// but in each place we want to run different code on dialog closure
dialog.m_OnClose.Insert(OnDialogClose);

// we can also use m_OnConfirm or m_OnCancel events
</enforce>

=== Standard Usage ===

The dialog has some code associated only with itself, and we want that code to run regardless from where the dialog was invoked.

The takeaway here is the call signature of <enforce inline>CreateFromPreset</enforce>:
<enforce>
static SCR_ConfigurableDialogUi CreateFromPreset(ResourceName presetsResourceName, string tag, SCR_ConfigurableDialogUi customDialogObj = null)
</enforce>

the last argument is {{hl|customDialogObj}}, which lets us tie an object to a dialog if needed.

<enforce>
class SCR_ExitGameWhileDownloadingDialog : SCR_ConfigurableDialogUi
{
//---------------------------------------------------------------------------------------------
void SCR_ExitGameWhileDownloadingDialog()
{
// note that we pass 'this' into CreateFromPreset call!
SCR_ConfigurableDialogUi.CreateFromPreset(SCR_CommonDialogs.DIALOGS_CONFIG, "exit_game_while_downloading", this);
}

//---------------------------------------------------------------------------------------------
override void OnConfirm()
{
// try to terminate all current downloads
SCR_DownloadManager dlManager = SCR_DownloadManager.GetInstance();
if (dlManager)
dlManager.EndAllDownloads();

// exit the game
GetGame().RequestClose();
SCR_AllFilterSetsStorage.ResetAllToDefault();
}
}

void SomeOtherMethod()
{
new SCR_ExitGameWhileDownloadingDialog();
}
</enforce>



=== Advanced Usage ===

We can create a dialog's more advanced content
<enforce>
class SCR_AddonListDialog : SCR_ConfigurableDialogUi
{
array<ref SCR_WorkshopItem> m_aItems = {};
protected ref array<SCR_DownloadManager_AddonDownloadLine> m_aDownloadLines = {};

protected ResourceName ADDON_LINE_LAYOUT = "{BB5AEDDA3C4134FD}UI/layouts/Menus/ContentBrowser/DownloadManager/DownloadManager_AddonDownloadLineConfirmation.layout";

//------------------------------------------------------------------------------------------------
void SCR_AddonListDialog(array<ref SCR_WorkshopItem> items, string preset)
{
foreach (SCR_WorkshopItem i : items)
{
m_aItems.Insert(i);
}

if (!preset.IsEmpty())
SCR_ConfigurableDialogUi.CreateFromPreset(SCR_WorkshopUiCommon.DIALOGS_CONFIG, preset, this);
}

//------------------------------------------------------------------------------------------------
override void OnMenuOpen(SCR_ConfigurableDialogUiPreset preset)
{
VerticalLayoutWidget layout = VerticalLayoutWidget.Cast(GetRootWidget().FindAnyWidget("AddonList")); // the widget we have added
WorkspaceWidget workspace = getGame().GetWorkspace();

// Create a line for each entry in m_aItems
Widget w;
SCR_DownloadManager_AddonDownloadLine comp;
foreach (SCR_WorkshopItem item : m_aItems)
{
w = workspace.CreateWidgets(ADDON_LINE_LAYOUT, layout);

component = SCR_DownloadManager_AddonDownloadLine.Cast(w.FindHandler(SCR_DownloadManager_AddonDownloadLine));
component.InitForWorkshopItem(item, string.Empty, false);

m_aDownloadLines.Insert(component);
}
}
}
</enforce>

=== Common ConfigurableDialog ===

# Game exit popup - MainMenuUI:<br>Binds the OnBack function to the "Back" button click<enforce>
// subscribe to buttons
SCR_InputButtonComponent back = SCR_InputButtonComponent.GetInputButtonComponent("Back", footer);
if (back)
back.m_OnActivated.Insert(OnBack);
</enforce>
# <enforce inline>OnBack()</enforce> calls <enforce inline>TryExitGame()</enforce>:<enforce>
protected static void TryExitGame()
{
int numCompleted, numTotal;
SCR_DownloadManager dlManager = SCR_DownloadManager.GetInstance();
if (dlManager)
dlManager.GetDownloadQueueState(numCompleted, numTotal);

if (numTotal > 0)
new SCR_ExitGameWhileDownloadingDialog();
else
new SCR_ExitGameDialog();
}
</enforce>
# {{Link/Enfusion|armaR|SCR_ExitGameWhileDownloadingDialog}} and {{Link/Enfusion|armaR|SCR_ExitGameDialog}} are defined in {{hl|CommonDialogs.c}}, they inherit from {{Link/Enfusion|armaR|SCR_ConfigurableDialogUi}}.<enforce>
class SCR_ExitGameDialog : SCR_ConfigurableDialogUi
{
//---------------------------------------------------------------------------------------------
void SCR_ExitGameDialog()
{
SCR_ConfigurableDialogUi.CreateFromPreset(SCR_CommonDialogs.DIALOGS_CONFIG, "exit_game", this);
}

//---------------------------------------------------------------------------------------------
override void OnConfirm()
{
GetGame().RequestClose();
SCR_AllFilterSetsStorage.ResetAllToDefault();
}
}
</enforce>
# DIALOGS_CONFIG is the config file CommonDialogs.conf.<br>"exit_game" is a tag in CommonDialogs that <enforce inline>CreateFromPreset()</enforce> uses to find the right preset. <enforce inline>CreateFromPreset()</enforce> then calls <enforce inline>CreateByPreset()</enforce> to initialise the dialog and bind events to the buttons. {{Feature|informative|
The actual widget created is ConfigurableDialogProxy, an empty overlay widget which is referenced in {{hl|chimeraMenus.conf}}, and the new {{hl|ConfigurableDialog}} preset is then created inside it.}}<enforce>
static SCR_ConfigurableDialogUi CreateByPreset(SCR_ConfigurableDialogUiPreset preset, SCR_ConfigurableDialogUi customDialogObj = null)
{
// Open the proxy dialog
SCR_ConfigurableDialogUiProxy proxyComp = SCR_ConfigurableDialogUiProxy.Cast(GetGame().GetMenuManager().OpenDialog(ChimeraMenuPreset.ConfigurableDialog));

// Create the actual layout inside proxy
Widget internalWidget = GetGame().GetWorkspace().CreateWidgets(preset.m_sLayout, proxyComp.GetRootWidget());
if (!internalWidget)
{
Print(string.Format("[SCR_ConfigurableDialogUi] internalWidget wans't created"), LogLevel.ERROR);
return null;
}

SCR_ConfigurableDialogUi dialog = SCR_ConfigurableDialogUi.Cast(internalWidget.FindHandler(SCR_ConfigurableDialogUi));

// Create a new dialog object, or apply the provided one, if the dialog obj was not found in the layout.
if (!dialog)
{
if (customDialogObj)
dialog = customDialogObj;
else
dialog = new SCR_ConfigurableDialogUi();

dialog.InitAttributedVariables();
internalWidget.AddHandler(dialog);
}

dialog.Init(internalWidget, preset, proxyComp);
proxyComp.Init(dialog);

// Set action context
if (!preset.m_sActionContext.IsEmpty())
proxyComp.SetActionContext(preset.m_sActionContext);

// Call dialog's events manually
dialog.OnMenuOpen(preset);

return dialog;
}
</enforce>

=== Accessing the content layout ===

<enforce>
VerticalLayoutWidget layout = VerticalLayoutWidget.Cast(GetContentLayoutRoot(GetRootWidget()).FindAnyWidget("AddonList"));
</enforce>

<enforce inline>SCR_ConfigurableDialogUi.GetContentLayoutRoot()</enforce> will return the first widget of the content layout. Useful for those dynamically generated dialogs.

{{GameCategory|armaR|Modding|Tutorials}}

Arma Reforger:Dialog Configuration Tutorial - Revision history

Lou Montana: Page creation