插件开发者指南
简介
从 1.5 版本开始，可以通过将插件文件放置在您的 Sweet Home 3D 插件文件夹中来添加新功能。这使 Java 程序员能够在不修改当前版本源文件的情况下开发和分发 Sweet Home 3D 的新功能（这有利于向上兼容），并且无需提供完整版本的程序（这有利于减小分发大小）。
本文档描述了创建插件所需的 工具，然后展示如何 编程一个插件 来计算添加到家居中的可移动家具的最大体积，最后提供一些帮助您更进一步的 附加信息。
安装开发工具
虽然 Sweet Home 3D 面向普通用户，但开发插件需要特殊技能，在继续之前您应该知道如何使用 Java 进行编程与 IDE。本指南展示如何使用 Eclipse 构建插件，但您可以使用您选择的 IDE，或者完全不使用 IDE。
下载并安装 Eclipse
首先从 https://www.eclipse.org/ 下载 Eclipse。名为 Eclipse IDE for Java Developers 的版本足以开发插件，但您也可以下载任何用于 Java 开发的版本。
下载完成后，安装 Eclipse 非常简单：只需解压获得的压缩包，打开 eclipse 文件夹，然后根据您的系统运行名为 eclipse.exe （在 Windows 下）的文件， eclipse.app （在 Mac OS X 下）的文件，或 eclipse （在 Linux 下）的文件。
首次运行时，Eclipse 将要求您选择一个 workspace 文件夹，用于存储插件项目。
完成后，从菜单中选择 File > New > Project 创建新项目，在显示的 New project 向导中选择 Java > Java project，输入 VolumePlugin 作为项目名称，然后点击 Finish 按钮。最后，关闭 Welcome 标签页以查看如图 1 所示的工作区。
下载并安装 Sweet Home 3D 库
插件的开发基于一些 Sweet Home 3D 的类，Eclipse 必须知道这些类才能构建您的项目。将 Sweet Home 3D 类添加到 Eclipse 的最简单方法是下载位于 https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download 的 Sweet Home 3D JAR 可执行版本。下载完成后，将 SweetHome3D-7.5.jar 文件拖放到 Eclipse 的 Package Explorer 视图中的 VolumePlugin 项目图标上，然后在 SweetHome3D-7.5.jar 文件的上下文菜单中选择 Build Path > Add to Build Path 项，如图 2 所示。
添加到构建路径
编程插件
现在您已经安装了所需的工具，让我们看看如何为 Sweet Home 3D 编程您的第一个插件。
创建插件类
首先，通过在 Eclipse 中选择 File > New > Class 菜单项来创建 com.eteks.sweethome3d.plugin.Plugin 的新子类。
在 New Java Class 对话框中，输入 VolumePlugin 作为类名，输入一个包名（这里选择的包名是 com.eteks.test），并选择 com.eteks.sweethome3d.plugin.Plugin 作为 VolumePlugin 的超类。完成后，点击 Finish。Eclipse 将创建新类文件，内容如下：
package com.eteks.test;
import com.eteks.sweethome3d.plugin.Plugin;
import com.eteks.sweethome3d.plugin.PluginAction;
public class VolumePlugin extends Plugin {
@Override
public PluginAction[] getActions() {
// TODO Auto-generated method stub
return null;
}
}
从 TODO 注释可以看出，您现在必须修改 getActions 方法的实现，以返回一个能够计算可移动家具体积的插件操作。将 return null; 替换为以下语句：
return new PluginAction [] {new VolumeAction()};
并从 Eclipse 菜单中选择 Edition > Quick Fix 来创建缺失的 VolumeAction 类，如图 4 所示。
在出现的 New Java Class 对话框中，选中 Enclosing type 复选框以创建 VolumePlugin 的内部类，然后点击 Finish。这将创建继承自 com.eteks.sweethome3d.plugin.PluginAction 类并包含一个空的 execute 方法的 VolumeAction 类：
public class VolumeAction extends PluginAction {
@Override
public void execute() {
// TODO Auto-generated method stub
}
}
当用户启动插件操作时，Sweet Home 3D 将调用这个方法；因此，这里是您必须实现如何计算家具体积并显示它的地方：
public class VolumeAction extends PluginAction {
@Override
public void execute() {
float volumeInCm3 = 0;
// 计算家居中每个可移动家具边界框体积的总和
for (PieceOfFurniture piece : getHome(). getFurniture()) {
if (piece. isMovable ()) {
volumeInCm3 += piece. getWidth()
* piece. getDepth()
* piece. getHeight();
}
}
// 在消息框中显示结果（³ 表示立方）
String message = String. format(
"家居中可移动家具的最大体积为 %.2f 立方米。",
volumeInCm3 / 1000000);
JOptionPane. showMessageDialog(null, message);
}
}
现在您已经指定了插件要做什么，您必须描述用户如何启动这个新操作。您可以选择在菜单中添加新的 菜单项，和/或在工具栏中添加新的 按钮。这个选择是通过在创建插件操作时设置适当的属性来完成的。例如，如果您希望用户通过 工具 菜单中的 计算体积 菜单项来启动体积操作，您将在 VolumeAction 类中添加以下构造函数：
public VolumeAction() {
putPropertyValue(Property.NAME, "计算体积");
putPropertyValue(Property.MENU, "工具");
// 默认启用该操作
setEnabled(true);
}
VolumePlugin 插件类现在已经编程完成，几乎可以在 Sweet Home 3D 中作为插件工作了。还需要做的两件事是：
- 创建 ApplicationPlugin.properties 描述文件，
- 将文件打包到 JAR 文件中。
创建插件描述文件
ApplicationPlugin.properties 文件 描述了插件名称、其类、支持的 Sweet Home 3D 和 Java 最低版本， 以及法律信息。从 Eclipse 菜单中选择 File > New > File，输入文件名 ApplicationPlugin.properties 并点击 Finish，如 图 5 所示。
然后在新文件中输入 以下描述 并保存：
name=可移动家具体积
class=com.eteks.test.VolumePlugin
description=计算家居中可移动家具的体积
version=1.0
license=GNU GPL
provider=(C) 版权所有 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5
创建插件 JAR
插件 JAR 包含从 VolumePlugin.java 文件编译生成的 类 文件， 和 ApplicationPlugin.properties 文件。由于 Eclipse 在保存 Java 文件时就会编译它，您 只需从菜单中选择 File > Export…，并在显示的 Export 对话框中选择 Java > JAR file。在如图 6 所示出现的 Jar Export 向导中，选中项目复选框 并输入放置在 Sweet Home 3D 插件文件夹中的 JAR 文件路径。适当的文件夹取决于 您的系统，如下所示：
- 在 Windows Vista / 7 / 8 / 10 / 11 下，此文件夹是 C:\Users\user\AppData\Roaming\eTeks\Sweet Home 3D\plugins，
- 在 Windows XP 和更早版本的 Windows 下，此文件夹是 C:\Documents and Settings\user\Application Data\eTeks\Sweet Home 3D\plugins，
- 在 macOS 下，是您用户文件夹中的 Library/Application Support/eTeks/Sweet Home 3D/plugins 子文件夹 ，
- 在 Linux 和其他 Unix 下，是您用户文件夹中的 .eteks/sweethome3d/plugins 子文件夹。
测试插件
您开发的 插件 将在 Sweet Home 3D 中运行，无论是 Java Web Start 版本、安装程序 版本，还是您之前下载的 SweetHome3D-7.5.jar。由于后者是一个可执行的 JAR，您可以通过双击它或使用以下命令来运行它：
您开发的 插件 将在 Sweet Home 3D 中运行，无论是 Java Web Start 版本、安装程序 版本，还是您之前下载的 SweetHome3D-7.5.jar。由于后者是一个可执行的 JAR，您可以通过双击它或使用以下命令来运行它：
java -jar /path/to/SweetHome3D-7.5.jar
在测试期间，您可能更喜欢使用此命令运行 Sweet Home 3D，以便能够在控制台中读取插件执行期间抛出的异常的堆栈跟踪。
一旦 Sweet Home 3D 启动，您将看到如图 7 所示的新菜单及其项目：
如果您为 用户指南 中创建的 家居示例 选择新菜单项，您将得到以下结果：
调试插件
如果您需要从 Eclipse 调试您的插件，请按照以下步骤创建调试配置：
- 从菜单中选择 Run > Debug Configurations…，在 Debug configurations 对话框的可用配置列表中选择 Java Application 项 ，点击左上角的 New 按钮，并为配置输入一个名称。
- 点击 Main class 文本字段右侧的 Search… 按钮，并在建议的类中双击 SweetHome3DBootstrap 类。
- 点击 Classpath 标签，在 Classpath 列表中选择 User Entries 项下的 VolumePlugin (default classpath) 子项，然后点击 Remove 按钮。
- 点击 Classpath 列表中的 User Entries 项，点击 Add JARs… 按钮，选择 SweetHome3D-7.5.jar 项并确认您的选择。
- 选择 Source 标签，点击 Add… 按钮，在 Add Source 对话框中双击 Java Project 项，在 Project Selection 弹出窗口中选择 VolumePlugin 项并确认您的选择。
- 最后，点击 Debug 按钮以调试模式启动 Sweet Home 3D。程序运行后，打开 VolumePlugin.java 文件， 在 execute 方法中设置断点，并从 Sweet Home 3D 菜单中选择 工具 > 计算体积。Eclipse 将在选定的 断点处停止，让您逐步执行程序并检查变量值。
每次修改插件的源代码时，不要忘记在启动您创建的调试配置之前 生成插件 JAR。要加快 Eclipse 中的 JAR 导出过程，请转到 JAR 导出向导的第二步，选择 Save the description of this JAR in the workspace 选项。这将在项目中添加一个带有上下文 Create JAR 菜单项的新项。
部署插件
准备就绪后，您的插件可以通过简单地将其复制到其他 Sweet Home 3D 用户的 SweetHome3D 是 Sweet Home 3D 安装程序提供的可执行文件的名称）：
/path/to/SweetHome3D /path/to/plugin.sh3p
要停止使用插件，请从插件文件夹中删除其文件并重新启动 Sweet Home 3D。
如果您希望您的插件能够与本网站上提供的所有 Sweet Home 3D 安装程序 一起运行，请通过在 Eclipse 的 Project > Properties 菜单项显示的对话框的 Java Compiler 部分中可用的 Compiler compliance level 字段中选择 1.5 来保持其与 Java 5 兼容。
如果您使用的 Java 编译器版本不再提供 Java 1.5 兼容性，请尝试至少针对 Sweet Home 3D 最新版本中仍在使用的 Java 1.8，并在插件的 ApplicationPlugin.properties 文件中相应地设置 javaMinimumVersion。
更进一步
第一个插件的编程向您展示了大致情况。这里有一些将帮助您更进一步的附加信息。
Sweet Home 3D API – javadoc
开发新插件最有用的文档是用 javadoc 工具生成的 Sweet Home 3D API（应用程序编程接口）。
如果您希望插件与未来版本的 Sweet Home 3D 向上兼容，请在插件中仅使用 com.eteks.sweethome3d.plugin、com.eteks.sweethome3d.model、com.eteks.sweethome3d.tools 和 com.eteks.sweethome3d.viewcontroller 包中的类。这对于编程任何在 Sweet Home 3D 中处理可用家居数据的插件来说已经足够了。
程序其他层的包包含在 Javadoc 中仅供参考。不要依赖它们的 API，因为它在未来可能会改变，且不保证向上兼容（无论如何，您在上述包中不会看到对 com.eteks.sweethome3d.swing、com.eteks.sweethome3d.j3d、com.eteks.sweethome3d.io 或 com.eteks.sweethome3d 包中类的引用）。
模型类架构
Sweet Home 3D 基于 MVC（模型-视图-控制器）架构，因此理解其模型层的组织方式至关重要。图 13（也可在 PDF 格式 中获取）展示了 com.eteks.sweethome3d.model 包 1.5 版本中几乎所有可用的类和接口。
(click on a class to view its javadoc)
模型层中的核心类是 HomeApplication 类（10），它是 SweetHome3D 应用程序主类的抽象超类。此类的实例提供对当前正在编辑的 Home 实例（7）的访问，以及存储正在使用的 长度单位（12）、家具目录（14）和 纹理目录（15）的 UserPreferences 对象（11），用户从中选择 家具（17）和 纹理（18）。
一个 Home 实例（7）存储用户在家居平面图中创建的所有对象：
- 实现 PieceOfFurniture 接口（16）的 HomePieceOfFurniture 对象（13）列表，
- Wall 对象（9）的集合，
- Room 对象（5）的列表，
- DimensionLine 对象（2）的集合，
- Label 对象（3）的集合。
这些对象实现 Selectable 接口（1），以及存储 虚拟访客 模式下摄像机位置的 ObserverCamera 对象（4）。模型对象管理的所有外部信息，如 家具（16）的图标和 3D 模型，或 纹理（20）的图像，都通过 Content 接口（19）访问，该接口由 URLContent 类和 com.eteks.sweethome3d.tools 包中的其他类实现。
这个 UML 图应该帮助您理解 Sweet Home 3D 模型中有哪些类可用以及如何访问它们，但您可能会注意到其中没有引用任何构造函数和修改器（或者如果您愿意，称之为设置器）。这只是因为空间不足，但您可以在插件类中毫无问题地使用它们。还要注意，对模型中现有对象的任何修改都将通过 PropertyChangeEvent、CollectionEvent（8）或 SelectionEvent（6）通知给显示的组件，从而使所有更改立即反映在屏幕上。
Sweet Home 3D 模型出于性能原因不是线程安全的。对属于模型的对象的任何 修改 都应在事件调度线程中完成。
插件类架构
插件类的架构比模型层的架构更容易理解。com.eteks.sweethome3d.plugin 包仅包含三个类，其中您应该只使用 Plugin 和 PluginAction 类，如图 14 所示（也可通过 PDF 格式 获取）。
(click on a class to view its javadoc)
一个 PluginManager 实例 (1) 在应用程序启动时创建，并搜索用户 插件文件夹 中安装的插件。每次编辑新家时，此管理器都会为启动时找到的每个插件实例化并配置一个 Plugin 对象 (3)。然后，它调用 getActions 方法以检索所有 操作 (4)，这些操作将作为菜单项和/或工具栏按钮添加到主窗口中。每个操作都是 PluginAction 的一个实例，它类似于 Action 类，具有其 execute 方法和可修改的 属性 (2)。
请注意，Plugin 类通过其 getUndoableEditSupport 方法为您提供对 UndoableEditSupport 实例的访问权限。一旦您在 PluginAction 实例的 execute 方法中修改了家或其对象（家具、墙壁等），您还应该将一个 UndoableEdit 对象发布到 getUndoableEditSupport 方法返回的可撤销编辑支持中，否则用户将无法正确撤消/重做您所做的更改。
本地化
如果您计划为 Sweet Home 3D 用户社区开发插件，请尝试本地化它在操作名称和菜单中或在您将创建的对话框中显示的字符串（或至少准备其本地化）。PluginAction 类的两个构造函数将帮助您使用 .properties 文件组织操作属性的翻译，如果您需要在插件中翻译其他字符串（例如 测试插件 所示对话框中的字符串），请使用 ResourceBundle Java 类重用这些 .properties 文件。
如果您希望限制属性文件的数量，您甚至可以将操作属性和其他字符串的值写入插件的 ApplicationPlugin.properties 描述文件 中。
如果您想要一个使用此架构的示例，请下载可在 https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p 获取的 导出到 SH3F 插件，并解压缩它（此插件文件也包含插件的源代码）。
如 帮助论坛 中所述，此插件会创建一个 SH3F 文件，其中包含您导入到 Sweet Home 3D 家具目录中的所有家具。
贡献插件
您可以将您编写的插件发布到 插件贡献 跟踪系统，以便与 Sweet Home 3D 用户社区共享。
通过插件，可以为 Sweet Home 3D 添加许多功能，从导入器到导出器，以及能够修改家数据（例如 Michel Mbem 开发的 Home Rotator 插件）的插件，以及 Hans Dirkse 编写的 插件和扩展教程 (PDF) 和 插件和工具 页面中列出的其他插件。