NetBeans Options Window Extension 模块教程

安装软件

开始之前，需要在您的计算机上安装以下软件：

• NetBeans IDE 5.0（下载）
• Java Standard Development Kit (JDK!") version 1.4.2（下载）或 5.0（下载）

安装并介绍示例

采用以下步骤来安装示例：

1. 解压缩附加的文件。
2. 在 IDE 中，选择 File > Open Project，然后浏览到包含已解压缩文件的文件夹。打开模块项目。其形式如下：

   

3. 右键单击项目节点并在 Target Platform 中选择 Install/Reload。将打开目标平台并安装该模块。
4. 选择 Tools > Options，单击 Miscellaneous 并注意到称为“My First Option Category”的新类别。两个选项“Option 1”和“Option 2”不执行任何操作。它们是用于您自己的选项的占位符。此处，新的选项类别被嵌入到 Miscellaneous 面板中。在本教程中，您将学习如何执行该操作，以及如何将该类别嵌入到新的面板中而使它自己的图标位于 Options 窗口的左边栏中。

现在您了解了 NetBeans Options Window Extension Module 的用户界面，让我们从头开始创建该模块。

访问 NetBeans IDE 源

当您使 IDE 的源可用于 NetBeans Platform Manager 时，您可以从 Source Editor 中访问 IDE 的源文件和 Javadoc。这样便简化了插件模块的开发，原因是它使您能够非常快速地查找有关执行的类和方法的信息。整个教程中都提到源和 Javadoc，因此应该在进行下一步前先获得它们。

1. 如果您尚未这样做，请从此处下载源。
2. 选择 Tools > NetBeans Platform Manager。
3. 在 Sources 选项卡中，单击 Add ZIP/Folder，并浏览到包含 NetBeans IDE 源的 ZIP 文件，如下所示：

   

4. 单击 Close。

创建模块项目

1. 选择 File > New Project。在 Categories 下，选择 NetBeans Plug-in Modules。在 Projects 下，选择 Module Project 并单击 Next。
2. 在 Name and Location 面板中，在 Project Name 中键入 MyFirstOption。将 Project Location 更改为您计算机上的任何目录，如 c:\mymodules。选择 Standalone Module 单选按钮和 Set as Main Project 复选框。单击 Next。
3. 在 Basic Module Configuration 面板中，用 myorg 替换 Code Name Base 中的 yourorghere，从而整个 Code Name Base 为 org.myorg.myfirstoptioncategory。在 Module Display Name 中填入 MyFirstOption。留出本地化包和 XML 层的位置，以便它们存储在名为 org.myorg.myfirstoptioncategory 的包中。单击 Finish。

IDE 创建 MyFirstOption 项目。该项目包含所有资源和项目元数据，如该项目的 Ant 构建脚本。该项目在 IDE 中打开。您可以在 Projects 窗口 (Ctrl-1) 中查看其逻辑结构，在 Files 窗口 (Ctrl-2) 中查看其文件结构。

指定模块的依存关系

您需要子类化三个属于 NetBeans API 的类。每个类都将被声明为 Module 依存关系。使用 Project Properties 对话框来执行此操作。

1. 在 Projects 窗口中，右键单击 MyFirstOptionCategory 项目节点并选择 Properties。在 Project Properties 对话框中单击 Libraries。
2. 对于以下每个 API，单击“Add...”，从 Module 列表中选择名称，然后单击 OK 确认：

   

3. 单击 OK，退出 Project Properties 对话框。
4. 在 Projects 窗口中，展开 Important Files 节点，双击 Project Metadata 节点，并注意查看您选择的 API 是否按模块依存关系进行了声明：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://www.netbeans.org/ns/project/1">
    <type>org.netbeans.modules.apisupport.project</type>
    <configuration>
        <data xmlns="http://www.netbeans.org/ns/nb-module-project/2">
            <code-name-base>org.myorg.myfirstoption</code-name-base>
            <standalone/>
            <module-dependencies>
                <dependency>
                    <code-name-base>org.jdesktop.layout</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <release-version>1</release-version>
                        <specification-version>1.2</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.netbeans.modules.options.api</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <release-version>0</release-version>
                        <specification-version>1.1</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.openide.util</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <specification-version>6.5</specification-version>
                    </run-dependency>
                </dependency>
            </module-dependencies>
            <public-packages/>
        </data>
    </configuration>
</project>

设计 Options 面板

执行以下操作：

1. 创建文件。 右键单击 MyFirstOptionCategory 项目节点，选择 New > File/Folder，然后从 Java GUI Forms 类别中选择 JPanel Form。单击 Next。在 Class Name 中，键入 MyFirstOptionPanel，然后从 Package 下拉列表中选择 org.myorg.myfirstoptioncategory。单击 Finish。新 JPanel Forms 将在 Source Editor 中打开。
2. 设计面板。 在本教程中创建的面板将不执行任何有用的操作。本教程的目的是演示如何将类别添加到 Options 窗口中，而不是如何创建选项。因此，您可以向 JPanel Form 中添加您想要的任何组件。例如，下图将两个 JLabel 和两个 JTextArea 添加到 JPanel Form 中：

   

您已拥有用户界面，现在让我们在 Options 窗口中创建一个类别。

放置 Options 类别

在 Options 窗口中，类别由 PanelController 组成，它提供 JPanel 和有关 JPanel 如何与 Options 窗口交互的信息以及以下组合之一（取决于放置类别的位置）：

• 图标、类别名称和标题（如果类别扩展 OptionsCategory）。图标显示在 Basic Options 视图的左边栏中，类别名称也显示在左边栏中，而标题则显示在面板自身中。
• 显示名称和工具提示（如果类别扩展 AdvancedOption）。显示名称显示在 Miscellaneous 面板中，而当鼠标停留在标题上时显示工具提示。

下面演示两个方案。

执行以下操作：

1. 创建文件。 右键单击 MyFirstOptionCategory 项目节点，选择 New > Java Class，在 Class Name 中键入 MyFirstOptionCategory，然后从 Package 下拉列表中选择 org.myorg.myfirstoptioncategory。单击 Finish。新 Java 类将在 Source Editor 中打开。用以下内容替换默认代码：

   package org.myorg.myfirstoptioncategory;
   
   import org.netbeans.spi.options.AdvancedOption;
   import org.netbeans.spi.options.OptionsCategory;
   import org.netbeans.spi.options.OptionsCategory.PanelController;
   import org.openide.util.NbBundle;
   
   public final class MyFirstOptionCategory extends OptionsCategory  {
   
       public String getIconBase () {
           return "org/netbeans/modules/options/resources/generalOptions";
       }
      
       public String getCategoryName () {
           return loc ("CTL_Example_Category_Name");
       }
   
       public String getTitle () {
           return loc ("CTL_Example_Title");
       }
      
       public PanelController create () {
           return new MyFirstOptionPanelController ();
       }   
   
       private static String loc (String key) {
           return NbBundle.getMessage (MyFirstOptionCategory.class, key);
       }
   
   }

2. 读取源。 按下 Ctrl 键，将鼠标移动到 OptionsCategory 标识符上，并注意到出现一个超链接：

   

   单击该链接。OptionsCategory 类在 Source Editor 中打开。熟悉一下源文件并理解它如何与 MyFirstOptionCategory 实现相关。

3. 重新放置类别。 如果您想让类别出现在 Miscellaneous 面板中，而不是它自己单独的面板中，请确保 MyFirstOptionCategory.java 扩展AdvancedOption 而不是 OptionsCategory。但是，AdvancedOption 实现两个附加的方法：getDisplayName() 和 getTooltip()。因此，如果您想扩展 AdvancedOption，则向以上类中添加以下内容：

       public String getDisplayName() {
            return loc ("CTL_Example_Title");
       }
   
       public String getTooltip() {
            return loc ("CTL_Example_Title");
       }

   注意，AdvancedOption 并不使用方法 getIconBase()、getCategoryName() 和 getTitle()。因此，您可以从 MyFirstOptionCategory.java 将它们删除。

   接下来，按下 Ctrl 键，将鼠标移动到 AdvancedOption 标识符上，并注意到出现一个超链接：

   

   单击该链接。AdvancedOption 类在 Source Editor 中打开。熟悉一下源文件并理解它如何与 MyFirstOptionCategory 实现相关。

与 Options 窗口交互

现在您已拥有面板和类别，您需要提供有关如何让它们与 Options 窗口交互的信息。在扩展 PanelController 的类中定义类别和 Options 窗口之间的交互。例如，当用户单击 Options 窗口中的 OK 按钮时，则调用 applyChanges() 方法。当单击 Cancel 按钮时，则调用 cancel() 方法。由于您没有在 MyFirstOptionPanel 中定义任何有意义的选项，因此，以下 PanelControler 实现非常简单。

执行以下操作：

1. 创建文件。 右键单击 MyFirstOptionCategory 项目节点，选择 New > Java Class，在 Class Name 中键入 MyFirstOptionPanelController ，然后从 Package 下拉列表中选择 org.myorg.myfirstoptioncategory。单击 Finish。新 Java 类将在 Source Editor 中打开。用以下内容替换默认代码：

   package org.myorg.myfirstoptioncategory;
   
   import java.beans.PropertyChangeListener;
   import java.beans.PropertyChangeSupport;
   import javax.swing.JComponent;
   import org.netbeans.spi.options.OptionsCategory.PanelController;
   import org.openide.util.HelpCtx;
   import org.openide.util.Lookup;
   
   public final class MyFirstOptionPanelController extends PanelController {
   
       private MyFirstOptionPanel examplePanel;
       private boolean changed = false;   
      
       public MyFirstOptionPanelController () {
           examplePanel = new MyFirstOptionPanel (); 
       }
      
       public void update () {
           // init values in your panel here
       }
      
       public void applyChanges () {
           // this method is called when OK button has been pressed
           // save values here
       }
      
       public void cancel () {
           // this method is called when Cancel button has been pressed
           // revert any possible changes here
       }
      
       public boolean isValid () {
           return true;
       }
      
       public boolean isChanged () {
           return changed;
       }
      
       public HelpCtx getHelpCtx () {
           return new HelpCtx ("netbeans.optionsDialog.editor.example");
       }
      
       public JComponent getComponent (Lookup masterLookup) {
           return examplePanel;
       }
   
       public void addPropertyChangeListener(PropertyChangeListener l) {
       }
   
       public void removePropertyChangeListener(PropertyChangeListener l) {
       }
    
   }

2. 读取源。 按下 Ctrl 键，将鼠标移动到 PanelController 标识符上，并注意到出现一个超链接：

   

   单击该链接。OptionsCategory.PanelController 类在 Source Editor 中打开。熟悉一下源文件并理解它如何与其 PluginsFactory 实现相关。

此时，Projects 窗口应该如下所示：

要在 Options 窗口中注册模块，您必须在 layer.xml 文件中执行以下操作：

1. 更新 layer.xml 文件。要在 Miscellaneous 面板中注册该类别，请向 layer.xml 文件中添加以下条目：

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
   <filesystem>
       <folder name="OptionsDialog">
         <folder name="Advanced">
           <file name="Example.instance">
               <attr name="instanceClass" stringvalue="org.myorg.myfirstoptioncategory.MyFirstOptionCategory"/>
           </file>
         </folder>
       </folder>
   </filesystem>

注意： 在上面的方案中，MyFirstOptionCategory 必须扩展 AdvancedOption。

要将类别注册为新面板，请向 layer.xml 文件中添加以下条目，而不是以上条目：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
<filesystem>
    <folder name="OptionsDialog">
        <attr name="Keymaps.instance/Example.instance" boolvalue="true" />
        <file name="Example.instance">
            <attr name="instanceClass" stringvalue="org.myorg.myfirstoptioncategory.MyFirstOptionCategory"/>
        </file>
        <attr name="Example.instance/Advanced.instance" boolvalue="true" />
    </folder>
</filesystem>

注意： 在上面的方案中，MyFirstOptionCategory 必须扩展 OptionsCategory。

2. 本地化标签。 在 layer.xml 文件所在的包中，向 Bundle.properties 文件中添加以下条目：

   OpenIDE-Module-Name=MyFirstOptionCategory
   OpenIDE-Module-Display-Category=Tools
   CTL_Example_Category_Name=M&y First Option Category
   CTL_Example_Title=My First Option Category

安装和测试 NetBeans 模块

1. 在 Projects 窗口，右键单击 MyFirstOptionCategory 项目并在 Target Platform 中选择 Install/Reload。

   模块即在目标平台中构建和安装。目标平台打开，您可以试用新的模块。默认目标平台是由开发 IDE 的当前实例使用的安装。

2. 在主菜单栏中，选择 Tools > Options 并在 Options 窗口中检查新的选项类别。

创建可共享的模块二进制文件（NBM 文件）

NBM 文件是一个 NetBeans 模块，该模块已被打包以便通过 Web 发送。NBM 文件和模块 JAR 文件之间的主要差别为：

• NBM 文件是压缩的文件。
• NBM 文件可以包含多个 JAR 文件，即模块可以将它们使用的任何库打包到它们的 NBM 文件中。
• NBM 文件包含 NetBeans 将用来在 Update Center 显示有关它信息的元数据，如 manifest 内容、许可等。
• 出于安全考虑，NBM 文件通常都有签名。

NBM 文件只是具有特殊扩展名的 ZIP 文件。它们使用 JDK 机理给 JAR 文件签名。除非您正在执行一些不同寻常的操作，否则不需要担心 NBM 文件的内容，只需让 NBM 创建的标准 Ant 构建脚本为您完成所有工作。IDE 根据在 Project Properties 对话框的项目中输入的选项生成构建脚本。您可以在 Project Properties 对话框中设置模块的依存关系、版本控制和打包信息。通过为项目编辑 Ant 脚本和 Ant 属性，您可以进一步自定义程序执行。

1. 在 Projects 窗口中，右键单击 MyFirstOptionCategory 项目节点，并选择 Create NBM。

   将创建 NBM 文件并且可以在 Files 窗口中查看它 (Ctrl-2)：

   

2. 通过电子邮件使其他人也可以使用。
3. 使用 Update Center 来安装 NBM 文件。

有关创建和开发 NetBeans 模块的更多信息，请参见以下资源：

• 模块开发者资源
• NetBeans API 列表（当前开发版本）
• NetBeans Options API

版本	日期	更改
1	2005 年 10 月 29 日	初稿。 待办事项： 向该模块的源添加链接。 在任何位置添加 Javadoc 链接。 解释文件的目的（介绍性段落）。 添加更多有意义的选项，以便它们实际上执行有用的操作。 检查复制/粘贴错误（文件和包的命名等） 为 AdvancedOption 和 OptionsCategory 添加代码（差别也位于 layer.xml 中） 在结尾添加摘要，以便获得在实现这两个方案时的差别。 包含一些小示例（或到 NetBeans 源的链接）以显示如何设置一些选项，如 Ant 主页、显示 Mnemonics Dialog。 本教程之后可能制作更高级的教程，以显示一些实际运行的选项（然后使用当前不支持的选项，并且这将向 IDE 中添加一些有用的内容）。
2	2005 年 10 月 30 日	添加了很多细节。 待办事项： 工具提示似乎并不起作用。 提供有关 Bundle.properties 的“M&y First Option Category”中的“与”符号 (&) 所代表含义的信息。 添加更多有意义的选项，以便它们实际上执行有用的操作。 检查复制/粘贴错误（文件和包的命名等） 包含一些小示例（或到 NetBeans 源的链接）以显示如何设置一些选项，如 Ant 主页、显示 Mnemonics Dialog。 本教程之后可能制作更高级的教程，以显示一些实际运行的选项（然后使用当前不支持的选项，并且这将向 IDE 中添加一些有用的内容）。 如何使用 Options 窗口的左边栏中的其他图标（或您自己的图标）？ 如何隐藏现有的类别？例如，如果我不想使用 Miscellaneous 类别，应该怎么做？