Anvil
How-to guides

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:

RowSetsDefault
Enable diagram image exportWhether the three shortcut menus offer the export at allOn
DestinationClipboard, Ask, or FolderClipboard
FolderWhere Folder mode writes; left empty, Folder mode prompts instead of guessingEmpty
File formatPNG, JPEG, TIFF, SVG, EMF, WMF, or EPSPNG
Show diagram toolbar buttonWhether the command bar above a diagram carries the buttonOn

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.

On this page