The macro steps
Anvil ships 17 steps in Anvil_Macros_Steps.mdzip, and a macro calls one through a step action.
This page states what each step does, what each parameter means, and whether a macro feeds that
parameter a constant on a value pin or a value on a flow.
This page is generated from the shipped archive by
tools/model-library/generate_step_catalogue.py. Change the model rather than the page:
tools/model-library/steps-documentation.json carries the text,
tools/model-library/document_behaviors.py writes it into the archive, and StepCatalogueTest
fails the build when the two disagree.
| Category | Steps |
|---|---|
| Copying | Acceptable owner, Counterpart, Copy |
| Model | Has stereotype, Set owner, Set tag, Apply stereotype, Replace in names |
| Diagrams | Open diagrams, Diagrams of |
| Dialogs | Confirm, Ask elements, Ask choice, Ask text |
| Feedback | Fail, Notify, Select in browser |
Acceptable owner
Answers the near element when it may own the given element, and otherwise the nearest owner of the near element that may. Fails when no owner up the chain accepts it.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
element | Element | 1..1 | a flow | The element that needs an owner. |
near | Element | 1..1 | a flow | Where the search starts. The step walks up this element's owners. |
Returns Element [1..1].
Counterpart
Answers the copy of an element that an earlier Copy step in this run produced, looking inside the given copy. Answers nothing when the element was not part of what that Copy copied. Runs only inside a macro, where the pairs were recorded.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
original | Element | 1..1 | a value pin | An element the template owns, whose copy is wanted. Pick the element inside the template, not the copy. |
copy | Element | 1..1 | a flow | The copy to look inside, as an earlier Copy step answered it. |
Returns Element [0..1].
Copy
Copies the source element and everything it owns under the owner, and answers the copy. Records every original-to-copy pair for the rest of the run, so a Counterpart step finds the copy of any element the source owned. Fails when the owner is read-only or the tool refuses the paste.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
source | Element | 1..1 | a value pin | The element to copy, with everything under it. Pick the template. |
owner | Element | 1..1 | a flow | The element the copy is placed under. An Acceptable owner step answers one that accepts it. |
Returns Element [1..1].
Has stereotype
Answers whether the element carries the stereotype. Reads as a decision's input, so a macro branches on it.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
element | Element | 1..1 | a flow | The element to test. |
stereotype | Stereotype | 1..1 | a value pin | The stereotype to look for. Pick a Stereotype element from a profile. |
includeSubtypes | Boolean | 1..1 | a value pin | True also matches an element carrying a specialization of the stereotype; false matches the stereotype alone. |
Returns Boolean [1..1].
Set owner
Moves each given element under the owner. Fails when the owner may not own one of them, or when one is read-only.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
elements | Element | 0..* | a flow | The elements to move. |
owner | Element | 1..1 | a flow | The element they are moved under. |
Returns nothing.
Set tag
Sets one tag of a stereotype on the element, applying the stereotype first when the element does not carry it. Fails when the tag belongs to no stereotype, or when the element is read-only.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
element | Element | 1..1 | a flow | The element to tag. |
tag | Property | 1..1 | a value pin | The tag to set. Pick the property of the stereotype that defines it, not the stereotype. |
value | any | 0..* | a flow | The values to write. One value for a tag that holds one. |
Returns nothing.
Apply stereotype
Applies the stereotype to each given element. Fails on a read-only element.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
elements | Element | 0..* | a flow | The elements to stereotype. |
stereotype | Stereotype | 1..1 | a value pin | The stereotype to apply. Pick a Stereotype element from a profile. |
Returns nothing.
Replace in names
Replaces every occurrence of the placeholder with the replacement, in the name of each given element and of every named element under it. Fails on an empty placeholder or a read-only element.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
elements | Element | 0..* | a flow | The elements to rename under, each renamed as well. |
placeholder | String | 1..1 | a value pin | The text to replace, spelled as the template's names spell it. |
replacement | String | 1..1 | a flow | The text that takes its place. An Ask text step answers what the modeller typed. |
Returns nothing.
Open diagrams
Opens each diagram in the tool. A diagram the tool holds no presentation for is skipped.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
diagrams | Diagram | 0..* | a flow | The diagrams to open. A Diagrams of step, or a Counterpart step, answers them. |
Returns nothing.
Diagrams of
Answers the diagrams the given elements own, and every diagram under them when recursive.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
elements | Element | 0..* | a flow | The elements to read diagrams from. |
recursive | Boolean | 1..1 | a value pin | True reads every diagram under the elements; false reads only the diagrams they own directly. |
Returns Diagram [0..*].
Confirm
Asks the modeller a yes-or-no question and answers true for yes. Cancelling the dialog cancels the run, which rolls the model back and reports nothing. Reads as a decision's input, so a macro branches on the answer.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
title | String | 1..1 | a value pin | The dialog's title. |
question | String | 1..1 | a value pin | The question the modeller answers yes or no to. |
Returns Boolean [1..1].
Ask elements
Opens the tool's element selection dialog, restricted to the given types, and answers what the modeller picked. Cancelling the dialog cancels the run, which rolls the model back and reports nothing.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
title | String | 1..1 | a value pin | The dialog's title. |
types | Class | 0..* | a value pin | What the dialog offers. Pick a metaclass or a Stereotype element, or leave the pin empty to offer every element. |
multiple | Boolean | 1..1 | a value pin | True lets the modeller pick several elements; false one. |
Returns Element [0..*].
Ask choice
Asks the modeller to pick one of the offered options and answers it. Cancelling the dialog cancels the run, which rolls the model back and reports nothing.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
title | String | 1..1 | a value pin | The dialog's title. |
question | String | 1..1 | a value pin | The question shown above the options. |
options | String | 1..* | a flow | The options to offer. An upstream step answers them; one value pin would offer one option, so a flow feeds this pin. |
Returns String [1..1].
Ask text
Asks the modeller for one line of text and answers it. Cancelling the dialog cancels the run, which rolls the model back and reports nothing.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
title | String | 1..1 | a value pin | The dialog's title. |
question | String | 1..1 | a value pin | The question shown above the field. |
initial | String | 0..1 | a value pin | The text the field starts with. Leave the pin empty for an empty field. |
Returns String [1..1].
Fail
Ends the run as a failure carrying the message. Nothing after it runs, and the model rolls back to where the run started. This is how a macro stops deliberately after a decision.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
message | String | 1..1 | a value pin | The text shown to the modeller. A blank message is replaced by a generic one. |
Returns nothing.
Notify
Shows the message as an information balloon once the run has committed. A macro may notify more than once; the balloons appear together at the end.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
message | String | 1..1 | a value pin | The text the balloon carries. |
Returns nothing.
Select in browser
Selects the element in the containment tree, so the modeller sees what the macro produced.
| Parameter | Type | Multiplicity | Fed by | Means |
|---|---|---|---|---|
element | Element | 1..1 | a flow | The element to select. |
Returns nothing.
Related pages
- Anvil: write a macro — drawing an Activity that calls these steps, and reaching it from the shortcut menu
contributing/add-a-step.mdin the repository — writing a step of your own, binding it from a model library, and documenting it- How macros run — what one run commits, and how a value reaches a pin