IDEA 用户界面组件(一)

IntelliJ Platform 中提供了大量的自定义 Swing 组件，使用这些组件能让你的 Plugin 保持跟 IDE 其他部分一致的展示效果及运行状态。同时使用这些组件相比使用默认的 Swing 组件可以减少大量的代码编写工作。

Tool Windows

ToolWindow 是 IDE 的子窗口（面板），用于显示信息及其他交互操作。这些窗口通常在主窗口的外边缘有自己的工具栏（如 Project 窗口），其中包含一个或多个工具窗口按钮，这些按钮显示在主 IDE 窗口左侧、底部和右侧的面板。

ToolWindow 使用 com.intellij.toolWindow 扩展点在 plugin.xml 中注册。下面是 com.intellij.toolWindow 扩展点所支持的属性：

• id : 对应于工具窗口按钮上显示的文本
• icon : 在工具窗口按钮上显示的图标（13x13 像素，灰色且单色；请参阅 IntelliJ Plateform UI 指南中的说明）
• anchor : 表示 ToolWindow 显示在的屏幕哪一侧（支持 left（默认）、right、bottom）
• secondary : 指定 ToolWindow 是显示在主要组还是次要组
• factoryClass : 需要实现 ToolWindowFactory 接口的类名称。只有当用户点击 ToolWindow 按钮时，工厂类的 createToolWindowContent() 方法才会调用并初始化 ToolWindow 的 UI。如果用户不与 ToolWindow 交互，则不会加载或执行任何插件代码。

示例

下面我们编写一个最简单的 ToolWindow 示例，用来实时显示系统时间，虽然这个功能貌似没有任何用o(╯□╰)o。

首先我们定义 ToolWindow 的显示布局，及操作行为。

/**
* 时间展示窗口
*
* @author 鱼蛮 Date 2022/6/18
*/
public class TimeDisplayWindow {
    
    /** 容器 */
    private JPanel content;
    
    /** 时间显示 label */
    private JLabel timeLabel;
    
    public TimeDisplayWindow(ToolWindow toolWindow) {
        new Thread(() -> {
            while (true) {
                timeLabel.setText(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss").format(LocalDateTime.now()));
                try {
                    TimeUnit.SECONDS.sleep(1L);
                } catch (InterruptedException e) {
                    // do nothing
                }
            }
        }).start();
    }
    
    public JPanel getContent() {
        return content;
    }
}

代码很简单，只是启动了一个线程，每隔 1 秒钟修改 timeLabel 字段的 text 属性为当前时间。

这里 ToolWindow 的显示布局我使用的是 IDEA 提供的 GUI Designer form，虽然不那么好用，但是总比在代码中手动去布局要好点，逻辑代码跟 Swing 布局代码也可以做到分离，有点 MVC 的意思。

所以这里需要定义一个 GUI Designer form 文件并与 TimeDisplayWindow 进行绑定。

<?xml version="1.0" encoding="UTF-8"?>
<form xmlns="http://www.intellij.com/uidesigner/form/" version="1" bind-to-class="com.roc.toolwindws.TimeDisplayWindow">
  <grid id="27dc6" binding="content" layout-manager="GridLayoutManager" row-count="3" column-count="3" same-size-horizontally="false" same-size-vertically="false" hgap="-1" vgap="-1">
    <margin top="0" left="0" bottom="0" right="0"/>
    <constraints>
      <xy x="20" y="20" width="500" height="400"/>
    </constraints>
    <properties/>
    <border type="none"/>
    <children>
      <component id="e0311" class="javax.swing.JLabel">
        <constraints>
          <grid row="0" column="0" row-span="1" col-span="1" vsize-policy="0" hsize-policy="0" anchor="8" fill="0" indent="0" use-parent-layout="false"/>
        </constraints>
        <properties>
          <text value="当前时间 : "/>
        </properties>
      </component>
      <component id="c6bed" class="javax.swing.JLabel" binding="timeLabel">
        <constraints>
          <grid row="0" column="1" row-span="1" col-span="1" vsize-policy="0" hsize-policy="0" anchor="8" fill="0" indent="0" use-parent-layout="false"/>
        </constraints>
        <properties>
          <text value="Label"/>
        </properties>
      </component>
      <hspacer id="b81a1">
        <constraints>
          <grid row="0" column="2" row-span="3" col-span="1" vsize-policy="1" hsize-policy="6" anchor="0" fill="1" indent="0" use-parent-layout="false"/>
        </constraints>
      </hspacer>
      <vspacer id="b08fe">
        <constraints>
          <grid row="1" column="0" row-span="2" col-span="1" vsize-policy="6" hsize-policy="1" anchor="0" fill="2" indent="0" use-parent-layout="false"/>
        </constraints>
      </vspacer>
      <vspacer id="ab7b8">
        <constraints>
          <grid row="1" column="1" row-span="2" col-span="1" vsize-policy="6" hsize-policy="1" anchor="0" fill="2" indent="0" use-parent-layout="false"/>
        </constraints>
      </vspacer>
    </children>
  </grid>
</form>

在 IDEA 的 GUI Designer 面板中可以新增、删除、拖动组件来调整布局，不是那么好用，需要习惯。调整完的布局也很简单，只是定义了一个 JPanel 当容器，定义了两个 JLabel 一个固定展示“当前时间 : ”，一个动态展示“当前时间”。GUI Designer 面板效果如下所示。

GUI Designer 面板

接着我们需要定义一个 ToolWindowFactory 对象，来实现 ToolWindow 的创建。

/**
* 日期显示窗口工厂
*
* @author 鱼蛮 Date 2022/6/18
*/
public class TimeDisplayWindowFactory implements ToolWindowFactory {
    
    @Override
    public void createToolWindowContent(@NotNull Project project, @NotNull ToolWindow toolWindow) {
        TimeDisplayWindow timeDisplayWindow = new TimeDisplayWindow(toolWindow);
        ContentFactory contentFactory = ContentFactory.SERVICE.getInstance();
        Content content = contentFactory.createContent(timeDisplayWindow.getContent(), "", false);
        toolWindow.getContentManager().addContent(content);
    }
}

最后我们还需要在 plugin.xml 中声明这个扩展点。

<extensions defaultExtensionNs="com.intellij">
  <toolWindow id="时间显示窗口" anchor="right" factoryClass="com.roc.toolwindws.TimeDisplayWindowFactory"  />
</extensions> 

至此我们新增一个 ToolWindow 的工作就全部完成了，运行这个插件，发现在 IDEA 右侧的边栏多出了“时间显示窗口”这个按钮，点击后将展示我们定义的 ToolWindow ，时间也可以做到不停更新。

Dialogs

DialogWrapper

DialogWrapper 是应用于 IntelliJ Plateform 中显示的所有模态对话框（和一些非模态对话框）的基类。
它提供以下功能：

• 按钮布局（特定于平台的确定/取消按钮顺序，及 macOS 中特定的帮助按钮）
• 上下文帮助
• 记住对话框的大小
• 非模态验证（当对话框中输入的数据无效时显示错误消息文本）
• 键盘快捷键：
  • Esc 关闭对话框
  • 左/右按键用于在按钮之间切换
  • Y/N 表示是/否操作（如果它们存在于对话框中）
• 可选的不再询问复选框

使用步骤

1. 调用基类构造函数并传入需要显示 Dialog 的 Project 对象，或提供 Dialog 的父组件
2. 调用 setTitle() 方法来设置 Dialog 的标题
3. 在构造函数中调用 init() 方法
4. 实现 createCenterPanel() 方法，返回这个 Dialog 中的组件（包含要展示的内容）

其他说明

• 可以重写 getPreferredFocusedComponent() 方法来返回一个组件，用与在 Dialog 首次展示时获取焦点
• 可以重写 getDimensionServiceKey() 方法来返回一个用于持久化 Dialog 尺寸的标识
• 可以重写 getHelpId() 方法来返回一个与 Dialog 相关的的上下文帮助主题
• 使用 show() 方法来展示 Dialog，并且使用 getExitCode() 方法来检查 Dialog 是如何关闭的（ DialogWrapper#OK_EXIT_CODE|CANCEL_EXIT_CODE|CLOSE_EXIT_CODE），showAndGet() 方法可以看成是上面两种方法的组合。
• 如果想自定义 Dialog 的展示按钮（代替标准的 OK/Cancel/Help），可以重写 createActions() 或者 createLeftActions() 方法。如果是关闭按钮，需要使用 DialogWrapperExitAction 作为这个类的基类。
• 使用 action.putValue(DialogWrapper.DEFAULT_ACTION, true) 方法来设置默认的按钮。

示例

跟 ToolWindow 类似 DialogWrapper 类也经常与 GUI Designer form 一起使用，绑定一个GUI Designer form 到一个继承自 DialogWrapper 的类，并且绑定这个 form 的顶级 panel 到一个字段，在 createCenterPanel() 方法中返回这个字段。

/**
* 提醒休息的 Dialog
*
* @author 鱼蛮 Date 2022/6/18
*/
public class RestRemindDialogWrapper extends DialogWrapper {
    
    /** 容器 */
    private JPanel content;
    
    /** 显示内容 */
    private JLabel textLabel;
    
    /** 图片内容 */
    private JLabel imageLabel;
    
    public RestRemindDialogWrapper() {
        // 使用当前窗口作为父窗口
        super(true);
        setTitle("休息一下");
        init();
    }
    
    @Nullable
    @Override
    protected JComponent createCenterPanel() {
        imageLabel.setIcon(new ImageIcon(getClass().getResource("/dialog/relax.png")));
        textLabel.setText("工作再忙，也要记得休息一下。");
        return content;
    }
}

首先定义一个 RestRemindDialogWrapper 类继承自 DialogWrapper，这里也不做其他操作，只是设置了两个 JLabel 的属性，一个加载一张图片，一个设置固定的文本内容。

下面是新建一个 GUI Designer form ，来控制容器的布局。

<?xml version="1.0" encoding="UTF-8"?>
<form xmlns="http://www.intellij.com/uidesigner/form/" version="1" bind-to-class="com.roc.dialog.RestRemindDialogWrapper">
  <grid id="1ec18" binding="content" layout-manager="GridLayoutManager" row-count="4" column-count="5" same-size-horizontally="false" same-size-vertically="false" hgap="-1" vgap="-1">
    <margin top="0" left="0" bottom="0" right="0"/>
    <constraints>
      <xy x="5" y="5" width="650" height="373"/>
    </constraints>
    <properties/>
    <border type="none"/>
    <children>
      <component id="aa8ee" class="javax.swing.JLabel" binding="textLabel">
        <constraints>
          <grid row="2" column="2" row-span="1" col-span="1" vsize-policy="0" hsize-policy="0" anchor="0" fill="0" indent="0" use-parent-layout="false"/>
        </constraints>
        <properties>
          <text value="Label"/>
        </properties>
      </component>
      <vspacer id="991cc">
        <constraints>
          <grid row="0" column="2" row-span="1" col-span="1" vsize-policy="6" hsize-policy="1" anchor="0" fill="2" indent="0" use-parent-layout="false"/>
        </constraints>
      </vspacer>
      <vspacer id="b381e">
        <constraints>
          <grid row="3" column="2" row-span="1" col-span="1" vsize-policy="6" hsize-policy="1" anchor="0" fill="2" indent="0" use-parent-layout="false"/>
        </constraints>
      </vspacer>
      <component id="69863" class="javax.swing.JLabel" binding="imageLabel">
        <constraints>
          <grid row="1" column="2" row-span="1" col-span="1" vsize-policy="0" hsize-policy="0" anchor="8" fill="0" indent="0" use-parent-layout="false"/>
        </constraints>
        <properties>
          <text value=""/>
        </properties>
      </component>
      <hspacer id="a49e4">
        <constraints>
          <grid row="1" column="0" row-span="1" col-span="1" vsize-policy="1" hsize-policy="6" anchor="0" fill="1" indent="0" use-parent-layout="false"/>
        </constraints>
      </hspacer>
      <hspacer id="7a146">
        <constraints>
          <grid row="1" column="4" row-span="1" col-span="1" vsize-policy="1" hsize-policy="6" anchor="0" fill="1" indent="0" use-parent-layout="false"/>
        </constraints>
      </hspacer>
    </children>
  </grid>
</form>

Dialog 本身是不需要在 plugin.xml 中声明的，可以在任意地方新建展示，比如对一个休息提醒的插件来说，应该是在后台计算运行时间，到点自动提醒。这里我们为了简单，定义了一个 Action 作为插件的唤起入口，并在 plugin.xml 中进行声明。

/**
 * 休息提醒 Action
 * @author 鱼蛮 on 2022/2/18
 **/
public class ResetRemindAction extends AnAction {
    @Override
    public void actionPerformed(@NotNull AnActionEvent e) {
        if (new RestRemindDialogWrapper().showAndGet()) {
            // 按下了 OK 键
            System.out.println("休息结束");
        }
    }
}

<action id="dialog_show" class="com.roc.dialog.ResetRemindAction" text="休息一下" >
  <add-to-group group-id="ShowIntentionsGroup" anchor="first" />
</action>

做完这些之后，运行一下插件。在编辑面板中右键，选择“休息一下”，就可以看到我们要展示的 Dialog 了，与预期完全一致。

工作再忙也要休息一下

User Interface Components