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.
| Argument | Does |
|---|---|
title | The headline. Escaped for you, shown without added markup |
text | The body. Escaped for you |
subject | A model element, a collection of them, or any other value |
actions | Clickables rendered as links inside the balloon. Each label is escaped for you |
throwable | On 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.
Related
- Open API: show a notification — the raw Open API call this page wraps.
- Anvil: log from a resource — the logger a notifier writes through, and the category the two share.
- Anvil: render model values —
hString, which renders a notification'ssubject. - Anvil: write an auto-stereotype rule — a rule is the worked example of the throttling hazard above: notify once per batch, not once per candidate.