hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-30 02:07:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

notifications.md: notificationGroup EP 2020.3 (IJSDK-925)

Browse Source
This commit is contained in:
Yann Cébron 2020-10-29 16:41:01 +01:00
parent 449c1d967e
commit 31fba205d5
1 changed files with 37 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
user_interface_components/notifications.md
View File

@ -3,8 +3,7 @@ title: Notifications
---
<!-- Copyright 2000-2020 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
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 *IntelliJ Platform* provides multiple non-modal notification UI options.
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 *IntelliJ Platform* provides multiple non-modal notification UI options.
### Dialogs
@ -12,8 +11,7 @@ When working in dialog, instead of checking the validity of the input when the _
### 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`](upsource:///platform/platform-api/src/com/intellij/codeInsight/hint/HintManager.java) 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.
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`](upsource:///platform/platform-api/src/com/intellij/codeInsight/hint/HintManager.java) 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`](upsource:///platform/platform-api/src/com/intellij/codeInsight/hint/HintManager.java) methods can be used for displaying other kinds of non-modal notification hints over an editor.
### Top-Level Notifications
@ -21,44 +19,60 @@ Other [`HintManager`](upsource:///platform/platform-api/src/com/intellij/codeIns
The most general way to display non-modal notifications is to use the [`Notifications`](upsource:///platform/platform-api/src/com/intellij/notification/Notifications.java) 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
The specific method used to display a notification is [`Notifications.Bus.notify()`](upsource:///platform/platform-api/src/com/intellij/notification/Notifications.java).
If the current Project is known, please use overload with `Project` parameter, so the notification is shown in its associated frame.
The specific method used to display a notification is [`Notifications.Bus.notify()`](upsource:///platform/platform-api/src/com/intellij/notification/Notifications.java). 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`](upsource:///platform/platform-api/src/com/intellij/notification/NotificationAction.java) for convenience.
The `groupId` parameter of the [`Notification`](upsource:///platform/platform-api/src/com/intellij/notification/Notification.java) constructor specifies a notification type.
The user can choose the display type corresponding to each notification type under `Settings | Appearance and Behavior | Notifications`.
The `groupId` parameter of the [`Notification`](upsource:///platform/platform-api/src/com/intellij/notification/Notification.java) 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`](upsource:///platform/platform-api/src/com/intellij/notification/NotificationGroup.kt) to create notifications.
#### Example
Please see the following two paragraphs for setup, depending on the target platform version.
Simple use of notifications using [`NotificationGroup`](upsource:///platform/platform-api/src/com/intellij/notification/NotificationGroup.kt).
##### 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.
```xml
<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`.
```java
public class MyGroovyDSLErrorsNotifier {
private final NotificationGroup NOTIFICATION_GROUP =
new NotificationGroup("Groovy DSL errors", NotificationDisplayType.BALLOON, true);
public class MyNotifier {
public Notification notify(String content) {
return notify(null, content);
public static void notifyError(@Nullable Project project, String content) {
NotificationGroupManager.getInstance().getNotificationGroup("Custom Notification Group")
.createNotification(content, NotificationType.ERROR)
.notify(project);
}
public Notification notify(Project project, String content) {
final Notification notification = NOTIFICATION_GROUP.createNotification(content, NotificationType.ERROR);
notification.notify(project);
return notification;
}
}
```
Usage of the class with [`NotificationGroup`](upsource:///platform/platform-api/src/com/intellij/notification/NotificationGroup.kt) above.
##### NotificationGroup (Pre-2020.3)
`NotificationGroup` is registered in code.
```java
MyGroovyDSLErrorsNotifier myGroovyDSLErrorsNotifier = new MyGroovyDSLErrorsNotifier();
myGroovyDSLErrorsNotifier.notify("Some Groovy DSL error text");
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);
}
}
```