Anvil
How-to guides

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

CategoryHolds
ProjectOptions.PROJECT_GENERAL_PROPERTIESVisible in the Project Options window
ProjectOptions.PROJECT_INVISIBLE_PROPERTIESStored with the project, hidden from that window
ProjectOptions.PERSONAL_INVISIBLE_PROPERTIESHidden, 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? String

getProperty 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

On this page