Workbench Plugin – Arma Reforger
Lou Montana (talk | contribs) (Add OnResourceContextMenu) |
Lou Montana (talk | contribs) (Add modal information) |
||
Line 123: | Line 123: | ||
The {{hl|OnResourceContextMenu}} method is called when clicking {{Link|Arma Reforger:Resource Manager}} Resource Browser Context Menu's Plugins > ''Plugin Name''. | The {{hl|OnResourceContextMenu}} method is called when clicking {{Link|Arma Reforger:Resource Manager}} Resource Browser Context Menu's Plugins > ''Plugin Name''. | ||
{{Feature|important|For the plugin to appear, {{hl|WorkbenchPluginAttribute}}'s {{hl|resourceTypes}} parameter must be defined (e.g <enforce inline>resourceTypes: { "fbx", "xob", "et" }</enforce>) | {{Feature|important|For the plugin to appear, {{hl|WorkbenchPluginAttribute}}'s {{hl|resourceTypes}} parameter must be defined (e.g <enforce inline>resourceTypes: { "fbx", "xob", "et" }</enforce>) | ||
=== Modal === | |||
The <enforce inline>Workbench.ScriptDialog()</enforce> method can be used to create a modal addressed to the user. It takes a caption (modal title) a text (in-modal description text), and a class instance - usually <enforce inline>this</enforce>. | |||
The class instance can be anything but {{hl|null}}, but it is much more interesting to offer options to the user, at least an OK/Cancel button choice. | |||
{{Feature|informative|If no buttons are defined, the modal can still be closed through the close button (« × ») or using {{Controls|Alt|F4}}.}} | |||
==== Attributes ==== | |||
Same as a {{Link|Arma Reforger:Scripting: Config Object|Config Object}} declaration, the <enforce inline>[Attribute()]</enforce> decorator is required. | |||
<enforce> | |||
[Attribute(defvalue: "1", desc: "Does something, otherwise does nothing")] | |||
protected m_bDoSomething; | |||
</enforce> | |||
==== Buttons ==== | |||
A button method is decorated with a <enforce inline>[Button()]</enforce> decorator which signature is as follow: | |||
<enforce> | |||
ButtonAttribute(string label = "ScriptButton", bool focused = false) | |||
</enforce> | |||
A button method's return type can be anything, but the value will be treated as a boolean int (1 = true, 0 = false). A {{hl|void}} method will return 0. | |||
{{Feature|important|Beware, as an empty string result will convert as a 1.}} | |||
<enforce> | |||
[ButtonAttribute("OK", true)] // focused by default | |||
int ButtonOK() | |||
{ | |||
return 42; // Workbench.ScriptDialog will return 1/true | |||
} | |||
[ButtonAttribute("Cancel")] | |||
int ButtonCancel() | |||
{ | |||
return 0; // Workbench.ScriptDialog will return 0/false | |||
} | |||
</enforce> | |||
The {{hl|Workbench.ScriptDialog}}'s return value can then be used to know if the user confirmed or cancelled an interface. | |||
{{Feature|informative|By default, a scripted dialog does not have any buttons and clicking on the close button (« × ») or using {{Controls|Alt|F4}} will make the {{hl|Workbench.ScriptDialog}} method return 0.}} | |||
Revision as of 16:46, 26 April 2024
Workbench Plugins are script files that can be triggered from within any editor (Resource Browser, World Editor, Script Editor, etc).
Existing plugins are listed in Data
Editor | Directory | API Class (Module Type) |
---|---|---|
Common Plugins | Data |
N/A |
Resource Manager | Data |
ResourceManager |
World Editor (Tools and Plugins) | Data |
WorldEditor |
Particle Editor | N/A | N/A |
Animation Editor | N/A | N/A |
Script Editor | Data |
ScriptEditor |
Audio Editor | N/A | N/A |
Behavior Editor | N/A | N/A |
String Editor | Data |
LocalizationEditor |
Procedural Animation Editor | N/A | N/A |
A Plugin must be named ClassnamePlugin, and its file too.
A Tool must be named ClassnameTool, and its file too.
Plugin
A plugin inherits from WorkbenchPlugin and is decorated with a WorkbenchPluginAttribute attribute which signature is as follow:
- name is mandatory: it is the plugin's display name
- description
- shortcut: none (empty string) can be defined, the plugin will then need to be triggered from the Plugin top menu
- icon
- wbModules: to which editors does this plugin apply (e.g wbModules = { "ScriptEditor" })
- category: the plugins menu entry in which this plugin will find itself (e.g Plugins > Text > TutorialPlugin)
- awesomeFontCode: the FontAwesome icon associated with the plugin (see FontAwesome's Cheatsheet)
A plugin must also override either or both Run or RunCommandLine methods in order to have an impact. It can also, but is not mandatory, override the Configure method to display a settings entry.
Tool
A tool is a system that allows for direct manipulation with a config panel available on the side.
A tool inherits from the editor-related class (e.g World Editor: WorldEditorTool) in order to be found in said editor's Tools menu.
It is decorated with a WorkbenchToolAttribute attribute which signature is identical to WorkbenchPluginAttribute (see above).
Scripting
Modules
A plugin has access to the currently loaded game/project resources, but in order to be as adaptable as possible it should also be generic.
Each Workbench module (editor) API can be accessed through the following script:
Where ModuleType can be one of the classes listed at the beginning of this document, all children of the WBModuleDef class).
Each module has obviously a different API - see their classes for more information.
Plugins
Other plugins can be accessed through aWorkbenchModule.GetPlugin(TAG_ClassNamePlugin);.
Common Methods
See WorkbenchPlugin.
Run
The Run method is called when clicking Plugins > Plugin Name or using its shortcut if any. If this method is not overridden with a non-empty code, the plugin does not appear in this menu.
RunCommandline
The RunCommandline method is called when calling the script from Startup Parameters's plugin option, e.g:
ArmaReforgerWorkbenchSteam.exe -wbModule=ScriptEditor -plugin=TAG_MyPlugin pluginArguments
Configure
The Configure method is called when clicking Plugins > Settings > Plugin Name. If this method is not overridden with a non-empty code, the entry does not appear in this menu.
OnResourceContextMenu
The OnResourceContextMenu method is called when clicking Resource Manager Resource Browser Context Menu's Plugins > Plugin Name. {{Feature|important|For the plugin to appear, WorkbenchPluginAttribute's resourceTypes parameter must be defined (e.g resourceTypes: { "fbx", "xob", "et" })
Modal
The Workbench.ScriptDialog() method can be used to create a modal addressed to the user. It takes a caption (modal title) a text (in-modal description text), and a class instance - usually this.
The class instance can be anything but null, but it is much more interesting to offer options to the user, at least an OK/Cancel button choice.
Attributes
Same as a Config Object declaration, the [Attribute()] decorator is required.
Buttons
A button method is decorated with a [Button()] decorator which signature is as follow:
A button method's return type can be anything, but the value will be treated as a boolean int (1 = true, 0 = false). A void method will return 0.
The Workbench.ScriptDialog's return value can then be used to know if the user confirmed or cancelled an interface.