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.
| Tag | Takes | Decides |
|---|---|---|
runsOn | one or more metaclasses, stereotypes, or both | Which elements the item is offered on |
includeSubtypes | a Boolean, true by default | Whether a subclass or a specialization also matches |
iconSource | one element | Whose 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 by | The 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.
Related pages
- Anvil: write a macro — the drawn half of the same menu
- The macro steps — what a macro calls, for a reader deciding between drawing one and coding an automation
- Anvil: write an auto-stereotype rule — the engine that applies «MenuPart» and «MenuItem», and how to suspend it around an automation
- How macros run — what one run commits, and why enablement and the launch read the same compilation