Open API: add an environment options group
An environment option is a per-workstation setting. It lives on the Options > Environment page,
it is stored in global.opt under the user's home directory, and it survives whichever project is
open. A setting belonging to the model rather than to the machine is a project option instead — see
Open API: add a project option.
Extend AbstractPropertyOptionsGroup
import com.nomagic.magicdraw.core.options.AbstractPropertyOptionsGroup
class MyOptions : AbstractPropertyOptionsGroup(ID) {
override fun setDefaultValues() {
// addProperty(...) for each row
}
override fun getName(): String = "My Resource"
companion object {
const val ID = "MY_RESOURCE_OPTIONS"
}
}One shared page, many sections
OptionsGroup supports nesting a page's children into sub-pages, but EnvironmentOptions.addGroup
does not walk that nesting — it renders exactly the property groups you assign rows to as titled
sections on one page. A resource with more than one feature that wants a settings row registers one
group and gives each feature its own section on it, rather than a page each. Anvil's own
DiagramImageOptions is that shared Anvil page: a second Anvil feature adds a section beside
Diagram Image, not a page of its own.
Register it once, in init()
import com.nomagic.magicdraw.core.Application
Application.getInstance().environmentOptions.addGroup(MyOptions())Never remove the group in close()
close() runs before the tool calls saveEnvironmentOptions, and save() writes only the groups
still registered. Pairing addGroup with removeGroup therefore discards every setting the modeller
changed, silently, on every shutdown.
This is the one exception to a plugin's mirror rule. Register the group once, reuse one already
registered, and leave it. Every other registration a plugin makes still gets undone in close().
setDefaultValues() runs inside the super constructor
AbstractPropertyOptionsGroup(String) calls createDefault(), which calls setDefaultValues() —
before Kotlin initialises any field the subclass declares. A resource provider held in a
private val is still null there, so every row and section header renders as its raw identifier:
import com.nomagic.magicdraw.properties.PropertyResourceProvider
class MyLabels : PropertyResourceProvider { /* … */ }
// Broken: labels is null when setDefaultValues() runs.
private val labels = MyLabels()import com.nomagic.magicdraw.properties.PropertyResourceProvider
// Works: the object is initialised before the constructor needs it.
private object MyLabels : PropertyResourceProvider { /* … */ }A test calling setDefaultValues() a second time hides this, because the field is initialised by
then. The tool never makes that second call.
Reference
- Developer Guide — General, "Environment Options"
- Sample plugin —
<install>/openapi/examples/environmentoptions/ - API —
com.nomagic.magicdraw.core.options,com.nomagic.magicdraw.properties - Local digest —
dev-env/ai-docs/reference/guide/environment-options.md
Related
- Open API: add a project option — the other kind of setting, and when to choose it.
- Anvil: export a diagram image — the feature whose options group this page cites.