Anvil
How-to guides

Anvil: put an automation in a menu

A menu item is a macro a modeller drew or an automation a developer coded, and both reach the modeller through the same shortcut menu. This page ships an automation: one Kotlin function, one behavior in a model library, one runsOn tag, and one property on a menu Class. No action class and no configurator.

Write the automation

An automation is an OpaqueBehavior whose body binds to Kotlin, the way a step or a query operation binds. It takes the selection and nothing else.

/**
 * Renames every port under [selection] after the interface that types it, and reports what it
 * renamed.
 *
 * Bound in the model library as the OpaqueBehavior `Align port names`, whose Groovy body reads
 * `com.example.resource.automations.Automations.alignPortNames(selection)`.
 */
fun alignPortNames(selection: Collection<Element>) { … }

Append the behavior with tools/model-library/add_behavior.py, apply «Automation» to it, and give it one in parameter typed by the Element metaclass at 1..1 or 1..*. That parameter is the launch contract, exactly as it is for a macro: Anvil binds the selection to it and offers the item only when the selection size fits.

An automation runs inside the session Anvil opened, so it asserts that session rather than opening one, and it throws StepFailure to fail the run. An exception it lets escape is swallowed by the expression engine, which is the same trap a step carries.

Say what it runs on

Three tags on «Automation» decide when the item is offered and how it looks. «Macro» carries the same three.

TagTakesDecides
runsOnone or more metaclasses, stereotypes, or bothWhich elements the item is offered on
includeSubtypesa Boolean, true by defaultWhether a subclass or a specialization also matches
iconSourceone elementWhose icon the entry borrows

An item is enabled when the selection is not empty, its size fits the in parameter's bounds, and every selected element matches one runsOn entry — an instance of the metaclass, or an element carrying the stereotype. With includeSubtypes, an instance of a subclass matches the metaclass and an element carrying a specialization matches the stereotype.

iconSource names an element rather than an image, so an automation creating «LogicalComponent» elements shows that stereotype's icon by pointing at it. «Menu» carries the tag too, so a sub-menu borrows an icon the same way.

Never name a tag icon. The Specification window binds a cell editor by property name, and icon is bound to an image editor that casts the value to an Image — so a tag named icon and typed Element throws a ClassCastException when the modeller browses it. The reserved names are icon, appliedStereotype, generalization, metaclass, signature, operation, messageSort, APPLIED_PROFILES, STATE_INVARIANT_STATE and TRANSITION_OPERATION.

Draw the menu

A menu is a Class carrying «Menu», and its owned properties, in declaration order, are its entries. The property's type decides what the entry is:

The property is typed byThe entry is
a Class carrying «Menu»a sub-menu, holding that menu's own entries
an Activity carrying «Macro»a runnable item
an OpaqueBehavior carrying «Automation»a runnable item

An entry's label is the property's name when it has one, and the type's name otherwise, so a project reusing a library macro under a name of its own renames the property. Reorder the entries in the Class's specification window, the same gesture as reordering parts, and draw the whole thing as a composition tree on a block definition diagram if you want to see it.

Set iconSource on the «Menu» Class to give the sub-menu an icon of its own. A Class leaving the tag unset shows the «Menu» stereotype's icon, so every untagged menu in a project looks alike. The tag sits on the Class rather than on the property, so two properties typed by one «Menu» share its icon, the way two properties typed by one macro do.

Anvil applies «MenuPart» and «MenuItem» as you draw: a property owned by a «Menu» earns one of them from what types it. A property you forgot to stereotype still builds the menu.

A sub-menu is offered greyed when nothing under it can run on the selection, and the verdict climbs: a menu whose every branch is dead greys out with them, the root included. An item counts as dead when the selection misses its runsOn and when its macro does not compile, so a branch holding one broken macro alone greys out on every selection. A «Menu» Class owning no entry Anvil recognises greys out too, because it offers nothing to run.

Name the root, and refresh

One project option decides which menu the modeller sees. Open Options > Project > General > Anvil and set Macro menu root to the «Menu» Class that owns everything else.

The root is the entry. A root A owning B and C puts one entry A in the shortcut menu, with B and C nested inside it — never B and C at the top level, which would fill a modeller's right-click with a project's whole menu. The entry joins the group that holds Create Element and Create Diagram, in the containment tree and on every diagram, and it reads the root's own iconSource for its icon.

The tree is built when a project opens and when it is activated. After editing the menu, press F7, or use Refresh macro menu, which sits beside the tool's own Refresh in the View menu. Anvil does not rebuild the menu on every model change: the cost of tracing every commit buys less than one keystroke.

A project that uses the profile but names no root logs a warning once and offers nothing. A root carrying no «Menu» is reported the same way.

On this page