Anvil
How-to guides

Open API: show a notification

A plugin tells a modeller something happened through a balloon in the lower-right corner. NotificationManager shows it, and nothing about the call opens a window or takes focus.

Show a balloon

import com.nomagic.magicdraw.ui.notification.Notification
import com.nomagic.magicdraw.ui.notification.NotificationManager

NotificationManager.getInstance().showNotification(
    Notification("myPlugin.export", "Export finished", "12 diagrams"),
)

The three arguments are an id, a title and a body. The id groups notifications the tool may collapse, so give it a stable value per kind of message rather than per message.

Carry a severity

import com.nomagic.magicdraw.ui.notification.NotificationSeverity

NotificationManager.getInstance().showNotification(
    Notification("myPlugin.export", "Export failed", "no diagram selected", NotificationSeverity.ERROR),
)

The tool's presentation follows from the severity. Apply no colour of your own — a hardcoded colour loses against a dark theme.

Offer an action

import com.nomagic.magicdraw.ui.notification.HRefRunnable
import java.awt.Desktop

val open = HRefRunnable.create("Open folder", true) { Desktop.getDesktop().open(folder) }

NotificationManager.getInstance().showNotification(
    Notification("myPlugin.export", "12 diagrams saved", null, arrayOf(open)),
)

HRefRunnable.create(label, closeOnRun) { } builds a link the tool renders inside the balloon. The tool runs the lambda on the event dispatch thread, and closes the balloon afterwards when closeOnRun is true. There are two forms: the static create used here, and subclassing HRefRunnable directly, which is what the sample plugin does.

Escape your own text

The tool renders a title, a body and a link label as HTML. An element named A<B reaches the balloon as a broken tag, and a name carrying & swallows what follows it. Escape every value you interpolate before it reaches the constructor. A link label lands inside <a href="…">{text}</a>, so it needs escaping too.

Show it from the right thread

showNotification ends in the tool's own dispatcher marshalling, but it reads MainFrame state and takes a lock on the calling thread first. A commit listener runs on the thread that closes the session, so a call from there touches Swing off-thread:

import javax.swing.SwingUtilities

val notification = Notification("myPlugin.rule", "Stereotype applied", "3 elements")
SwingUtilities.invokeLater { NotificationManager.getInstance().showNotification(notification) }

Build the Notification on the calling thread and dispatch only the display, so a failure in its construction stays yours to catch. Dispatch unconditionally rather than behind an isEventDispatchThread check, so the order a caller raised its balloons in survives.

What not to reach for

GUILog.log(String) opens the notification window on every call. A resource logging once per model change puts that window in front of the modeller once per edit. It is a different facility from a balloon.

Reference

  • Developer Guide — General › Using and extending UI components, "Showing notifications, adding text into Message Window"
  • Sample plugin — <install>/openapi/examples/notifications/
  • API — com.nomagic.magicdraw.ui.notification, com.nomagic.magicdraw.core
  • Local digest — dev-env/ai-docs/reference/guide/showing-notifications-adding-text-into-message-window.md

On this page