Workbench Plugin – Arma Reforger
Lou Montana (talk | contribs) (Add OnResourceContextMenu) |
Lou Montana (talk | contribs) m (Some wiki formatting) |
||
(4 intermediate revisions by the same user not shown) | |||
Line 64: | Line 64: | ||
* name is mandatory: it is the plugin's display name | * name is mandatory: it is the plugin's display name | ||
* description | * description: optional, it is the on hover description text | ||
* shortcut: none (empty string) can be defined, the plugin will then need to be triggered from the Plugin top menu | * shortcut: in format e.g {{hl|"Ctrl+Shift+I"}} for {{Controls|Ctrl|shift|I}} - none (empty string) can be defined, the plugin will then need to be triggered from the Plugin top menu | ||
* icon | * icon | ||
* wbModules: to which editors does this plugin apply (e.g {{hl|wbModules {{=}} { "ScriptEditor" }<nowiki/>}}) | * wbModules: to which editors does this plugin apply (e.g {{hl|wbModules {{=}} { "ScriptEditor" }<nowiki/>}}) | ||
* category: the plugins menu entry in which this plugin will find itself (e.g Plugins > Text > | * category: the plugins menu entry in which this plugin will find itself (e.g Plugins > Text > ''Plugin Name''){{Feature|informative|{{hl|category}} accepts forward slash {{hl|/}} to create sub-categories.}} | ||
* awesomeFontCode: the FontAwesome icon associated with the plugin (see | * awesomeFontCode: the FontAwesome icon associated with the plugin (see {{Link|https://fontawesome.com/FontAwesome}}'s {{Link|https://fontawesome.com/v5/search?o{{=}}r&m{{=}}free|Free Icons Cheatsheet}}) | ||
A plugin must also override either or both {{hl|Run}} or {{hl|RunCommandLine}} methods in order to have an impact. | A plugin must also override either or both {{hl|Run}} or {{hl|RunCommandLine}} methods in order to have an impact. | ||
Line 119: | Line 119: | ||
==== Configure ==== | ==== Configure ==== | ||
The {{hl|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. | The {{hl|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. | ||
{{Feature|informative| | |||
Think of the plugin's behaviour: should the end user encounter a configuration popup: | |||
* on each plugin usage (e.g from the <enforce inline>Run</enforce> method) | |||
* only when reaching for the plugin settings | |||
* and/or should only ''some'' settings be offered on every usage? | |||
}} | |||
==== OnResourceContextMenu ==== | ==== OnResourceContextMenu ==== | ||
Line 124: | Line 131: | ||
{{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>) | ||
=== Generic Modal === | |||
The <enforce inline>Workbench.Dialog()</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 detailed text if needed. | |||
The end result is a modal with an OK button and a "Show Details" button if a detailed text has been provided. | |||
=== Scripted Modal === | |||
The <enforce inline>Workbench.ScriptDialog()</enforce> method can be used to create a modal addressed to the user to confirm an action or set values. It can be used in any method (e.g not only {{hl|Configure}}). | |||
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.}} | |||
== Tutorials == | == Tutorials == |
Latest revision as of 23:46, 29 September 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: optional, it is the on hover description text
- shortcut: in format e.g "Ctrl+Shift+I" for Ctrl + ⇧ Shift + I - 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 > Plugin Name)
- awesomeFontCode: the FontAwesome icon associated with the plugin (see https://fontawesome.com/FontAwesome's Free Icons 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" })
Generic Modal
The Workbench.Dialog() 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 detailed text if needed.
The end result is a modal with an OK button and a "Show Details" button if a detailed text has been provided.
Scripted Modal
The Workbench.ScriptDialog() method can be used to create a modal addressed to the user to confirm an action or set values. It can be used in any method (e.g not only Configure). 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.