Skip to content

Notifications

One of the leading design principles is avoiding the use of modal message boxes for notifying the user about errors and other situations that may warrant the user's attention. As a replacement, the Consulo provides multiple non-modal notification UI options.

For an overview, refer to Notifications in Consulo UI Guidelines.

Dialogs

When working in dialog, instead of checking the validity of the input when the OK button is pressed and notifying the user about invalid data with a modal dialog, the recommended approach is to use DialogWrapper.doValidate(), which was described previously.

Editor Hints

For actions invoked from the editor (such as refactorings, navigation actions and different code insight features), the best way to notify the user about the inability to perform an action is to use the HintManager class. Its method showErrorHint() displays a floating popup above the editor which is automatically hidden when the user starts performing another action in the editor. Other HintManager methods can be used for displaying other kinds of non-modal notification hints over an editor.

Top-Level Notifications

The most general way to display non-modal notifications is to use the Notifications class.

It has two main advantages:

  • The user can control the way each notification type is displayed under Settings | Appearance & Behavior | Notifications
  • All displayed notifications are gathered in the Event Log tool window and can be reviewed later

For UI reference, see Balloon in Consulo UI Guidelines.

The specific method used to display a notification is Notifications.Bus.notify(). If the current Project is known, please use overload with Project parameter, so the notification is shown in its associated frame.

The text of the notification can include HTML tags.

Use Notification.addAction(AnAction) to add links below the content, use NotificationAction for convenience.

The groupId parameter of the Notification constructor specifies a notification type. The user can choose the display type corresponding to each notification type under Settings | Appearance and Behavior | Notifications.

To specify the preferred display type, you need to use NotificationGroup to create notifications.

Please see the following two paragraphs for setup, depending on the target platform version.

NotificationGroup (2020.3 and later)

NotificationGroup is registered in plugin.xml using com.intellij.notificationGroup extension point. Use key to provide a localized group display name.

<extensions defaultExtensionNs="com.intellij">
  <notificationGroup id="Custom Notification Group" displayType="BALLOON" key="notification.group.name"/>
</extensions>

Registered instances can then be obtained via their id.

TIP Code insight is available for parameters expecting notification group id.

public class MyNotifier {

  public static void notifyError(@Nullable Project project, String content) {
    NotificationGroupManager.getInstance().getNotificationGroup("Custom Notification Group")
            .createNotification(content, NotificationType.ERROR)
            .notify(project);
  }

}
NotificationGroup (Pre-2020.3)

NotificationGroup is registered in code.

public class MyNotifier {

  private static final NotificationGroup NOTIFICATION_GROUP =
          new NotificationGroup("Custom Notification Group", NotificationDisplayType.BALLOON, true);

  public static void notifyError(@Nullable Project project, String content) {
    NOTIFICATION_GROUP.createNotification(content, NotificationType.ERROR)
                      .notify(project);
  }

}