Anvil
How-to guides

Anvil: notify a modeller

The raw Open API version of this page is Open API: show a notification.

A resource occasionally needs to tell a modeller that something happened, at the moment it happens. An export finished. A rule applied a stereotype. An import rejected a row. The resource log records all of it and shows the modeller none of it, because a modeller does not watch a log file while modelling.

The notification package answers this with a balloon in the lower-right corner. It escapes the text, builds an anchor for any element worth clicking, records the same message in the log, and marshals the display onto the event dispatch thread.

Hold a notifier

import com.mbseconsulting.anvil.notification.Notify

private val notes = Notify.of("ACME")

Notify.of(category) caches one notifier per category, in the shape ResourceLog.of(category) already uses. Use the same short symbolic name for both, so a resource's balloons and its log lines narrate under one category.

Show a balloon

notes.info("Export finished", text = "12 diagrams", subject = diagram)

Three methods carry the severity — info, warn and error — and the tool's presentation follows from it. Apply no colour of your own: a hardcoded colour loses against a dark theme.

ArgumentDoes
titleThe headline. Escaped for you, shown without added markup
textThe body. Escaped for you
subjectA model element, a collection of them, or any other value
actionsClickables rendered as links inside the balloon. Each label is escaped for you
throwableOn warn and error: goes on the log line, its message onto the balloon's expandable detail

subject renders through hString, so a model element becomes a clickable anchor that selects it in the containment tree, a collection becomes one anchor per element, and anything else becomes escaped text. A null subject and an empty collection contribute nothing.

Two calls sharing a category and a title share the same notification id, which is what the tool's own "do not show me this message again" suppression keys on: suppressing one such balloon suppresses every balloon with that title from that category.

Offer an action

import com.mbseconsulting.anvil.notification.NotifyAction

notes.info(
    "12 diagrams saved",
    actions = listOf(NotifyAction("Open folder") { Desktop.getDesktop().open(folder) }),
)

The tool runs the lambda on the event dispatch thread when the modeller selects the link, and closes the balloon afterwards unless you pass closeOnRun = false. A failure inside the lambda is caught and logged under your category.

Report a failure

notes.error("Export failed", subject = diagram, throwable = cause)

The balloon stays short and the detail stays reachable: the throwable's message becomes the long text the balloon reveals on expand, and the throwable itself goes on the log line with its stack.

Throttle at your call site

The facility does not throttle. A resource notifying once per model change produces one balloon per model change, which puts a balloon in front of the modeller on every edit.

A resource notifying from a commit listener or an auto-stereotype rule must therefore decide its own throttling, and the natural shape is one notification summarising a completed batch:

// Not this — one balloon per element.
candidates.forEach { notes.info("Stereotype applied", subject = it) }

// This — one balloon per batch.
notes.info("Stereotype applied", text = "${candidates.size} elements", subject = candidates)

What this is not

A balloon opens no window and takes no focus. That is what separates NotificationManager.showNotification, which this package calls, from GUILog.log(String), whose one-argument form opens the notification window on every call. Nothing in Anvil reaches the Message Window, and this facility does not change that — see Anvil: log from a resource. showNotification does chain into NotificationWindowManager.log, which records a history entry and sets the status-bar severity indicator, but it never calls setVisible or show, so no window reaches the modeller.

The relationship between the two facilities runs one way. The logger never notifies. The notifier always logs, and it logs first, on the calling thread, so a balloon that never renders is still recoverable from the log.

On this page