Anvil: export a diagram image
A modeller often needs a diagram as an image — for a slide, a report, or a review comment — without
leaving the tool to hunt through File → Save As Image. The diagramimage package puts the same
export one gesture away, from the shortcut menus a modeller already uses, and offers the identical
call to a plugin author who
needs it from Kotlin.
Where it appears
Export Diagram Image appears under Tools in three shortcut menus: the containment tree's, the
Diagrams tree's, and a diagram's own. The entry sits in the tool's existing Tools group rather than
at the top level, because a shortcut menu is long before a resource adds anything to it. A menu the
tool builds without that group receives no entry, and the omission is reported once per run under
ANVIL.IMAGE; the export stays reachable from whichever menus do carry the group.
A button also sits on the command bar above an open diagram — the strip the tool draws across the top of the diagram pane — carrying the same export and the same icon. It draws the icon alone, above a table and a matrix as well as above a diagram, and names the export in its tooltip. The button sits beside the tool's own Options gear on that bar rather than arriving in a group of its own, which is what keeps the bar to one row; a command bar built without that group carries no button, and the three shortcut menus still reach the export. The command bar is built when the diagram window opens, so a modeller switching the button off keeps it, greyed, on the diagrams already open, and the diagrams opened afterwards carry none. The export carries no keyboard shortcut.
Every surface exports the whole diagram, never a selection of symbols within it — justSelected is
false at every call site, so a modeller's current symbol selection never changes what the export
yields. Cropping to a selection stays with the tool's own File → Save As Image, which this gesture
does not replace.
A tree selection can hold several diagrams at once. The containment tree and the Diagrams tree both export every diagram the selection carries, in one gesture, under the batch behaviour described below.
Setting the destination
Five rows under Environment Options → Anvil, in a Diagram Image section, decide what the gesture does and where it writes:
| Row | Sets | Default |
|---|---|---|
| Enable diagram image export | Whether the three shortcut menus offer the export at all | On |
| Destination | Clipboard, Ask, or Folder | Clipboard |
| Folder | Where Folder mode writes; left empty, Folder mode prompts instead of guessing | Empty |
| File format | PNG, JPEG, TIFF, SVG, EMF, WMF, or EPS | PNG |
| Show diagram toolbar button | Whether the command bar above a diagram carries the button | On |
Clipboard copies one diagram with no file and no dialog, always as a PNG: no clipboard carries a
vector flavour, so the File format row governs the two file destinations alone. The clipboard's native
PNG type is registered on macOS only; Windows already converts DataFlavor.imageFlavor into a
CF_DIB its own applications read, so nothing needs registering there. Ask opens a file chooser.
Folder writes into the configured folder, silently. Resolution and scale stay off this page
entirely: the export reads
them from the tool's own Environment Options → General → Image Export rows at the moment it runs.
Changing them there changes every export, with no second copy to keep in step.
The tool's exporter scales a render by scalePercentage / 100 and again by dpi / 72f, so 72 is the
resolution at which that second factor is 1 — the base every DPI setting is measured against.
What a batch does
A batch exports every diagram in the selection, under a cancellable progress dialog. It prompts once for a folder in Ask mode and in Clipboard mode. A clipboard holds one image and has no destination of its own for a batch, which is why it borrows the same folder prompt. Folder mode behaves differently. A folder already configured receives every diagram directly, with no prompt, whatever the selection size. An unconfigured folder prompts once, the same as it does for a single diagram. Cancelling the dialog stops the batch after the diagram in progress, and every diagram already written keeps its file.
Why the folder prompt is an Open dialog
The folder prompt opens as an Open dialog, and the dialog type decides which answer the chooser
returns. macOS puts one of two panels behind a JFileChooser asking for a folder. A Save dialog gets
the panel that reads the name field beside the folder list; an Open dialog gets the panel that reads
the list. The Save panel resolves that name against the folder on screen, so a modeller who names
shots in Downloads and then opens shots receives Downloads/shots/shots. No directory matches
that path, and every diagram in the batch fails to write. The Open panel shows no name field, so the
folder the modeller highlighted is the folder the batch writes into. Windows and Linux fill the same
field with a full path, which resolves correctly under either type and hides the defect. The prompt
therefore pins OPEN_DIALOG in code, and PromptsTest holds it there. A chooser that approves with
no selection names the folder it is looking at.
What the files are called
A saved file is named <diagram name>_<element ID>.<extension>. The element ID is what keeps two
diagrams sharing a name in different packages from overwriting one another, and it is also why
re-exporting the same diagram overwrites its own earlier file rather than accumulating copies.
The background
The diagram background follows Environment Options → General → Image Export → Save Diagram Background in Image, which the tool applies to every export it performs. Leave it ticked, as it arrives, and an exported PNG carries an opaque background. Untick it and the same export carries a transparent one. Anvil passes nothing here: the tool reads its own option while it builds the export, exactly as it does for resolution and scale.
The clipboard
Resolution and scale reach a saved file the same way the background does, through the tool's own
Image Export options. The clipboard is the exception: exportContainerToIcon pins DPI to 72, so
a clipboard render folds the resolution into its scale instead. clipboardScalePercent in
diagramimage/ExportSettings.kt is what carries the result.
The order a Transferable answers its flavours in also matters, because macOS acts on it.
CDataTransferer derives public.png, public.jpeg and public.tiff from one raster conversion of
DataFlavor.imageFlavor and writes TIFF bytes under all three. An application reading
public.png — Slack, Notion, any Electron paste — then finds 4d 4d 00 2a where 89 50 4e 47
belongs, and drops the paste.
Each flavour overwrites the last, so DiagramImageTransferable answers the raster first and the
encoded PNG last. Reverse the two and the raster conversion overwrites the PNG. The PNG also needs
SystemFlavorMap.addUnencodedNativeForFlavor(…, "public.png"), or it lands under a generated dyn.…
type that nothing reads.
Calling it from Kotlin
DiagramImage exposes the same export with no UI involved:
import com.mbseconsulting.anvil.diagramimage.DiagramImage
import com.mbseconsulting.anvil.diagramimage.ImageFormat
val diagram = project.getDiagram(someDiagramElement)
val file = File(folder, DiagramImage.fileNameFor(diagram, ImageFormat.PNG))
DiagramImage.save(diagram, file, ImageFormat.PNG)
DiagramImage.copyToClipboard(diagram)Neither call throws. A failure — a read-only folder, a diagram the tool cannot render — is logged
under ANVIL.IMAGE with its cause and answered with false, so a resource exporting many diagrams in
a loop does not lose the ones that worked because one of them failed.
Switching it off
Turning off Enable diagram image export drops the entry from all three shortcut menus at once, because a shortcut menu is rebuilt on every invocation and a switched-off feature adds nothing to it. The command bar button behaves differently: the tool builds a diagram's command bar when its window opens and, in its own words, "the actions can be only disabled but not removed later", so the button greys out on a diagram already open rather than disappearing. Show diagram toolbar button is the switch that is rid of it, and it takes effect on the next diagram window opened, in either direction.
Related
- Anvil: notify a modeller — the balloon this gesture reports through.
- Anvil: log from a resource — the
ANVIL.IMAGEcategory a failure is logged under. - Open API: add an environment options group — the
tool's own API for
DiagramImageOptions, the switch this page cites as its worked example.