Open API: add a project option
A project option is a setting stored with the model. It travels inside the .mdzip, so every
modeller who opens the project sees it, and a change to it is a change to the project. A setting
belonging to the workstation rather than to the model is an environment option instead — see
Open API: add an environment options group.
Choose a category
| Category | Holds |
|---|---|
ProjectOptions.PROJECT_GENERAL_PROPERTIES | Visible in the Project Options window |
ProjectOptions.PROJECT_INVISIBLE_PROPERTIES | Stored with the project, hidden from that window |
ProjectOptions.PERSONAL_INVISIBLE_PROPERTIES | Hidden, and held per user on a server project |
A personal option is one value per user on a Teamwork Cloud project and an ordinary option on a local one. Reach for it when two modellers on the same project need different answers.
Add a property from a configurator
import com.nomagic.magicdraw.core.options.ProjectOptions
import com.nomagic.magicdraw.properties.StringProperty
ProjectOptions.addConfigurator { options ->
if (options.getProperty(ProjectOptions.PROJECT_GENERAL_PROPERTIES, PROPERTY_ID) == null) {
val property = StringProperty(PROPERTY_ID, "")
property.group = GROUP_ID
property.resourceProvider = MyLabels
options.addProperty(ProjectOptions.PROJECT_GENERAL_PROPERTIES, property)
}
}Register the configurator in the plugin's init(). The tool calls it for every project, including
projects created afterwards.
Create a property only when getProperty answers null. The configurator runs against every
project, and one that overwrites unconditionally replaces whatever the modeller chose the last time
they opened it.
Do the work in configure, not configureLoadedOptions. The contract gives configure the
default values and configureLoadedOptions the real ones. Declaring a default must not mark the
project modified — a resource that dirties every project it opens is unusable.
addProperty also takes a predicate, which decides per project whether the property applies:
options.addProperty(property, ::appliesToThisProject)Use it to keep a group out of projects that carry none of your profile, where the setting could not mean anything.
Register once, and remove what you registered
ProjectOptions.addConfigurator appends to a static list, and removeConfigurator takes one
occurrence off it. A plugin that registers twice therefore leaves one configurator behind that a
single removal cannot take back — and that one survives Plugin.close(), configuring every project
the installation opens afterwards against classes that are no longer loaded.
Guard the registration so a second call does nothing, and pair it in close():
if (installed) return
installed = true
ProjectOptions.addConfigurator(configurator)Translate the identifiers
The property id, its description and its group all reach the UI as raw identifiers unless a
PropertyResourceProvider translates them. The provider is asked for each in turn and returns the
string unchanged when it does not recognise it. Both of getString's parameters carry
@CheckForNull, so Kotlin requires the nullable types, and the fallback needs orEmpty():
import com.nomagic.magicdraw.properties.Property
import com.nomagic.magicdraw.properties.PropertyResourceProvider
object MyLabels : PropertyResourceProvider {
override fun getString(id: String?, property: Property?): String =
when (id) {
PROPERTY_ID -> "Report folder"
"${PROPERTY_ID}_DESCRIPTION" -> "Where generated reports are written"
GROUP_ID -> "My Resource"
else -> id.orEmpty()
}
}A configurator runs no super-constructor callback, so either an object or a private val works
here. Reach for a private val when the labels depend on something the configurator is constructed
with.
Read a value back
val property = project.options.getProperty(ProjectOptions.PROJECT_GENERAL_PROPERTIES, PROPERTY_ID)
val folder = property?.value as? StringgetProperty answers null for an option no configurator has added yet, so read defensively.
Reference
- Developer Guide — General › Working with project, "Project options"
- API —
com.nomagic.magicdraw.core.options,com.nomagic.magicdraw.properties - Local digest —
dev-env/ai-docs/reference/guide/project-options.md
Related
- Open API: add an environment options group — the other kind of setting, and the initialisation trap it shares with this one.
- Anvil: write an auto-stereotype rule — the rules whose per-rule switches are this page's worked example.