外掛程式開發人員指南 Sweet Home 3D

簡介

從 1.5 版本開始，您可以將外掛程式檔案放置在您的外掛程式資料夾中，以新增功能到 Sweet Home 3D。這讓 Java 程式設計師能夠開發和發布 Sweet Home 3D 的新功能，而無需修改目前版本的原始檔（這有利於向上相容性），也無需交付完整版本的程式（這有利於縮減交付大小）。
本文檔說明了建立外掛程式所需的工具，然後展示如何編寫外掛程式來計算新增到房屋中的可移動家具的最大體積，最後提供一些額外資訊，以幫助您更進一步。

安裝開發工具

如果 Sweet Home 3D 的目標受眾是一般使用者，那麼開發外掛程式需要特殊的技能，並且在繼續之前，您應該知道如何使用 IDE 以 Java 進行程式設計。本指南展示了如何使用 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 會要求您選擇一個工作區資料夾，外掛程式專案將儲存在該資料夾中。
完成後，從選單中選擇 檔案 > 新增 > 專案以建立新專案，在將顯示的新增專案精靈中選擇 Java > Java 專案，輸入 VolumePlugin 作為專案名稱，然後按一下完成按鈕。最後，關閉 歡迎使用 標籤，以探索您的工作區，如圖 1 所示。

下載並安裝 Sweet Home 3D 程式庫

外掛程式的開發基於 Sweet Home 3D 的一些類別，Eclipse 必須知道這些類別才能夠建立您的專案。將 Sweet Home 3D 類別新增到 Eclipse 的最簡單方法是下載 Sweet Home 3D 的 JAR 可執行版本，該版本可在 https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download 取得。下載完成後，將檔案 SweetHome3D-7.5.jar 拖放到 Eclipse 的 Package Explorer 檢視中的 VolumePlugin 專案圖示上，然後在 SweetHome3D-7.5.jar 檔案的上下文選單中選擇項目 Build Path > Add to Build Path，如圖 2 所示。

圖 2. 將 SweetHome3D-7.5.jar
新增到 Build Path

程式設計外掛程式

現在您已經安裝了所需的工具，讓我們看看如何為 Sweet Home 3D 程式設計您的第一個外掛程式。

建立外掛程式類別

首先，透過在 Eclipse 中選擇 檔案 > 新增 > 類別 選單項目，來建立 com.eteks.sweethome3d.plugin.Plugin 的新子類別。

在 新增 Java 類別 對話方塊中，輸入 VolumePlugin 作為類別名稱，輸入一個套件（此處選擇的套件是 com.eteks.test），然後選擇 com.eteks.sweethome3d.plugin.Plugin 作為 VolumePlugin 的超類別。完成後，按一下完成。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 所示。

在出現的 新增 Java 類別 對話方塊中，選取 封閉類型 核取方塊以建立 VolumePlugin 的內部類別，然後按一下完成。這將建立從 com.eteks.sweethome3d.plugin.PluginAction 類別繼承的 VolumeAction 類別，並包含一個空的 execute 方法：

  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;
 // Compute the sum of the volume of the bounding box of 
 // each movable piece of furniture in home
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Display the result in a message box (³ is for 3 in supercript)
 String message = String. format(
 "The maximum volume of the movable furniture in home is %.2f m³.", 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

現在您已經指定了您希望外掛程式執行的操作，您必須描述使用者將如何啟動此新動作。您可以選擇將新的 選單項目 新增到選單，和/或將新的按鈕新增到工具列。此選擇是透過在其建立時設定外掛程式動作的適當屬性來完成的。例如，如果您希望使用者使用工具選單中找到的選單項目 計算體積 來啟動體積動作，您將將以下建構函式新增到 VolumnAction 類別：

  public VolumeAction() {
           putPropertyValue(Property.NAME, "Compute volume");
           putPropertyValue(Property.MENU, "Tools");
 // Enables the action by default
           setEnabled(true);
 }

VolumePlugin 外掛程式類別現在已程式設計完成，並且幾乎可以作為 Sweet Home 3D 中的外掛程式運作。最後要做的兩件事是：

建立 ApplicationPlugin.properties 描述檔案，
將檔案放在一起到 JAR 檔案中。

建立外掛程式描述檔案

ApplicationPlugin.properties 檔案描述了外掛程式名稱、其類別、支援它的 Sweet Home 3D 和 Java 最低版本，以及法律內容。從 Eclipse 選單中選擇 檔案 > 新增 > 檔案，輸入檔案名稱 ApplicationPlugin.properties，然後按一下完成，如圖 5 所示。

然後在新檔案中輸入以下描述並儲存它：

name=可移動家具體積
class=com.eteks.test.VolumePlugin
description=計算房屋中可移動家具的體積
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

建立外掛程式 JAR

外掛程式 JAR 包含從 VolumePlugin.java 檔案的編譯建立的 類別 檔案，以及 ApplicationPlugin.properties 檔案。由於 Eclipse 會在您儲存 Java 檔案時立即編譯它，因此您只需從選單中選擇檔案匯出…，然後在將顯示的匯出對話方塊中選取 Java JAR 檔案。在出現的 Jar 匯出 精靈中，如圖 6 所示，選取專案核取方塊，然後輸入放置在 Sweet Home 3D 外掛程式資料夾中的 JAR 檔案的路徑。此適當的資料夾取決於您的系統，如下所示：

在 Windows Vista / 7 / 8 / 10 / 11 下，此資料夾是 C:\Users\使用者\AppData\Roaming\eTeks\Sweet Home 3D\plugins，
在 Windows XP 和舊版 Windows 下，此資料夾是 C:\Documents and Settings\使用者\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，您可以透過雙擊它或使用以下命令來執行它：

java -jar /路徑/到/SweetHome3D-7.5.jar

只要您正在測試，您可能更喜歡使用此命令執行 Sweet Home 3D，以便能夠在主控台中讀取外掛程式執行期間擲回的例外狀況的堆疊追蹤。

啟動 Sweet Home 3D 後，您將看到新的選單及其項目出現，如圖 7 所示：

圖 7. 外掛程式選單

如果您為在使用者指南中建立的房屋範例選擇新的選單項目，您將獲得以下結果：

偵錯外掛程式

如果您需要從 Eclipse 偵錯您的外掛程式，請按照以下步驟建立偵錯組態：

從選單中選擇 執行 > 偵錯組態…，在 偵錯組態 對話方塊的可用組態清單中選取 Java 應用程式 項目，按一下左上角的新增按鈕，然後輸入組態的名稱。
按一下 主要類別 文字欄位右側的 搜尋… 按鈕，然後在建議的類別中雙擊 SweetHome3DBootstrap 類別
。

按一下 類別路徑 標籤，在 類別路徑 清單中選取 使用者項目 項目下的 VolumePlugin (預設類別路徑) 子項目，然後按一下移除按鈕。
按一下 類別路徑 清單中的使用者項目 項目，按一下 新增 JAR… 按鈕，選取 SweetHome3D-7.5.jar 項目，然後確認您的選擇。

選取來源標籤，按一下 新增… 按鈕，在 新增來源 對話方塊中雙擊 Java 專案 項目，在 專案選取 快顯視窗中選取 VolumePlugin 項目，然後確認您的選擇。

最後，按一下偵錯按鈕以在偵錯模式下啟動 Sweet Home 3D。程式執行後，開啟 VolumePlugin.java 檔案，在 execute 方法中設定一個中斷點，然後從 Sweet Home 3D 選單中選擇 工具 > 計算體積。Eclipse 將在選定的中斷點停止，讓您逐步執行程式並檢查變數值。

每次您修改外掛程式的原始碼時，請不要忘記在啟動您建立的偵錯組態之前產生外掛程式 JAR。為了加快 eclipse 中的 JAR 匯出過程，請前往 JAR 匯出精靈的第二個步驟，然後選取選項 將此 JAR 的描述儲存在工作區中。這將在專案中新增一個具有上下文 建立 JAR 選單項目的新項目。

部署外掛程式

準備就緒後，只需將您的外掛程式複製到其他 Sweet Home 3D 使用者的電腦上的外掛程式資料夾中，即可將其部署在這些電腦上。從 1.6 版本開始，如果外掛程式檔案的副檔名為 SH3P（只需將檔案副檔名從 .zip 變更為 .sh3p），也可以透過雙擊它將其安裝到 Sweet Home 3D 的外掛程式資料夾中。如果雙擊 .sh3p 檔案沒有啟動 Sweet Home 3D（在 Linux 下最有可能），您也可以在 終端機 視窗中使用以下命令安裝外掛程式（其中 SweetHome3D 是 Sweet Home 3D 安裝程式提供的可執行檔案的名稱）：

/路徑/到/SweetHome3D /路徑/到/plugin.sh3p

若要停止使用外掛程式，請從外掛程式資料夾中移除其檔案，然後重新啟動 Sweet Home 3D。

如果您希望您的外掛程式能夠與此網站上提供的所有 Sweet Home 3D 安裝程式一起執行，請注意使其與 Java 5 相容，方法是在 Eclipse 的 專案 > 屬性 選單項目顯示的對話方塊的 Java 編譯器 區段中提供的欄位 編譯器相容性層級 中選取 1.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 版本中幾乎所有可用的類別和介面。

[uml_diagram slug=”model-classes-diagram” map_name=”model-classes-diagram” caption=”Figure 13. UML diagram of com.eteks.sweethome3d.model package” caption_small=”(click on a class to view its javadoc)”]

模型層中的中心類別是 HomeApplication 類別 (10)，它是 SweetHome3D 應用程式主類別的抽象超類別。此類別的實例提供對目前編輯的 Home 實例 (7) 的存取，以及對儲存使用中的長度單位 (12)、家具目錄 (14) 和使用者從中選擇家具 (17) 和紋理 (18) 的紋理目錄 (15) 的 UserPreferences 物件 (11) 的存取。
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) 通知到顯示的元件，從而允許所有變更立即反映在螢幕上。

外掛程式類別架構

外掛程式類別的架構比模型層的架構更容易理解。com.eteks.sweethome3d.plugin 套件僅包含三個類別，其中您應該僅使用 Plugin 和 PluginAction 類別，如圖 14 所示（也可在 PDF 格式中取得）。

[uml_diagram slug=”plugin-classes-diagram” map_name=”plugin-classes-diagram” caption=”Figure 14. UML diagram of com.eteks.sweethome3d.plugin package” caption_small=”(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 描述檔案中寫入動作屬性和其他字串的值。

如果您想要使用此架構的範例，請下載 匯出到 SH3F 外掛程式，該外掛程式可在 https://test.sweethome3d.eu/plugins/ExportToSH3F-1.0.sh3p 取得，並解壓縮它（此外掛程式檔案也包含外掛程式的原始碼）。
如說明論壇中所述，此外掛程式會建立一個 SH3F 檔案，其中包含您匯入到 Sweet Home 3D 家具目錄中的所有家具。

貢獻外掛程式

您可以將您程式設計的外掛程式發布到外掛程式貢獻追蹤系統，以與 Sweet Home 3D 使用者社群分享它們。
借助外掛程式，可以將許多功能新增到 Sweet Home 3D，從匯入程式到匯出程式，還可以新增能夠修改房屋資料的外掛程式，例如 Michel Mbem 開發的房屋旋轉器外掛程式，以及 Hans Dirkse 編寫的外掛程式和擴充功能教學課程 (PDF) 和外掛程式和工具頁面中列出的其他外掛程式。