IDEA 用户界面组件(一)

2022-06-18 本文已影响0人鱼蛮子9527

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 表示是/否操作（如果它们存在于对话框中）
可选的不再询问复选框

使用步骤

调用基类构造函数并传入需要显示 Dialog 的 Project 对象，或提供 Dialog 的父组件
调用 setTitle() 方法来设置 Dialog 的标题
在构造函数中调用 init() 方法
实现 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