Plug-in-Entwicklerhandbuch

• Einführung
• Entwicklungswerkzeuge installieren
• Ein Plug-in programmieren
• Weiterführendes

Einführung

Ab Version 1.5 ist es möglich, Sweet Home 3D neue Funktionen hinzuzufügen, mit Plug-in-Dateien, die in deinem Plug-in-Ordner abgelegt sind. Dies ermöglicht Java-Programmierern, neue Funktionen für Sweet Home 3D zu entwickeln und zu vertreiben, ohne die Quelldateien der aktuellen Version zu ändern (was gut für die Aufwärtskompatibilität ist), und ohne eine vollständige Version des Programms auszuliefern (was gut für die Liefergröße ist).
Dieses Dokument beschreibt die Werkzeuge, die zum Erstellen von Plug-ins erforderlich sind, zeigt dann, wie du ein Plug-in programmierst, das das maximale Volumen der beweglichen Möbel in einem Zuhause berechnet, und gibt schließlich einige zusätzliche Informationen, die dir helfen werden, weiterzukommen.

Entwicklungswerkzeuge installieren

Auch wenn Sweet Home 3D sich an ein breites Publikum richtet, erfordert die Entwicklung von Plug-ins spezielle Kenntnisse, und du solltest wissen, wie man in Java mit einer IDE programmiert, bevor du fortfährst. Dieses Handbuch zeigt, wie du ein Plug-in mit Eclipse erstellst, aber du kannst auch die IDE deiner Wahl oder gar keine IDE verwenden.

Eclipse herunterladen und installieren

Lade Eclipse zuerst von https://www.eclipse.org/ herunter. Die Version Eclipse IDE for Java Developers reicht aus, um ein Plug-in zu entwickeln, aber du kannst jede Version für die Java-Entwicklung herunterladen.
Nach dem Herunterladen ist die Installation von Eclipse sehr einfach: Entpacke einfach das Archiv, das du erhältst, öffne den Eclipse-Ordner und führe je nach System die Datei namens eclipse.exe (unter Windows), eclipse.app (unter Mac OS X) oder eclipse (unter Linux).
Beim ersten Start fordert Eclipse dich auf, einen Arbeitsbereichsordner auszuwählen, in dem Plug-in-Projekte gespeichert werden.
Wähle anschließend Datei > Neu > Projekt aus dem Menü, um ein neues Projekt zu erstellen, wähle Java > Java-Projekt im angezeigten Assistenten für neue Projekte, gib VolumePlugin als Projektnamen ein und klicke auf die Schaltfläche Fertig stellen. Schließe schließlich den Willkommen-Tab, um deinen Arbeitsbereich wie in Abbildung 1 gezeigt zu entdecken.

Sweet Home 3D Bibliothek herunterladen und installieren

Die Entwicklung eines Plug-ins basiert auf einigen Klassen von Sweet Home 3D, die Eclipse kennen muss, um dein Projekt erstellen zu können. Der einfachste Weg, Sweet Home 3D-Klassen zu Eclipse hinzuzufügen, ist das Herunterladen der ausführbaren JAR-Version von Sweet Home 3D, die unter https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download verfügbar ist. Nach dem Herunterladen ziehe die Datei SweetHome3D-7.5.jar auf das Projektsymbol VolumePlugin in der Package Explorer-Ansicht von Eclipse und wähle den Eintrag Build Path > Add to Build Path im Kontextmenü der Datei SweetHome3D-7.5.jar, wie in Abbildung 2 gezeigt.

Ein Plug-in programmieren

Nachdem du die erforderlichen Werkzeuge installiert hast, lass uns sehen, wie du dein erstes Plug-in für Sweet Home 3D programmieren kannst.

Die Plug-in-Klasse erstellen

Erstelle zuerst eine neue Unterklasse von com.eteks.sweethome3d.plugin.Plugin, indem du im Eclipse-Menü Datei > Neu > Klasse wählst.

Gib im Dialogfeld Neue Java-Klasse VolumePlugin als Klassennamen ein, gib ein Paket ein (hier wurde das Paket com.eteks.test gewählt) und wähle com.eteks.sweethome3d.plugin.Plugin als Oberklasse von VolumePlugin. Klicke anschließend auf Fertig stellen. Eclipse erstellt die Datei der neuen Klasse mit folgendem Inhalt:

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 Automatisch generierter Methoden-Stub
 return null;
 }
}

Wie du dem TODO-Kommentar entnehmen kannst, musst du nun die Implementierung der getActions-Methode ändern, um eine Plug-in-Aktion zurückzugeben, die das Volumen der beweglichen Möbel berechnen kann. Ersetze return null; durch die folgende Anweisung:

  return new PluginAction [] {new VolumeAction()};  

und wähle Bearbeiten > Quick Fix aus dem Eclipse-Menü, um die fehlende Klasse VolumeAction zu erstellen, wie in Abbildung 4 gezeigt.

Wähle im angezeigten Dialogfeld Neue Java-Klasse das Kontrollkästchen Umschließender Typ, um eine innere Klasse von VolumePlugin zu erstellen, und klicke auf Fertig stellen. Dadurch wird die Klasse VolumeAction erstellt, die von der Klasse com.eteks.sweethome3d.plugin.PluginAction erbt und eine leere execute-Methode enthält:

  public class VolumeAction extends PluginAction {
 @Override
 public void execute() {
 // TODO Automatisch generierter Methoden-Stub
 }
 }

Diese Methode wird von Sweet Home 3D aufgerufen, wenn der Benutzer die Plug-in-Aktion startet; daher ist dies der Ort, an dem du implementieren musst, wie das Volumen der Möbel berechnet und angezeigt wird:

  public class VolumeAction extends PluginAction {  
  @Override
  public void execute() { 
  float volumeInCm3 = 0;
 // Berechne die Summe des Volumens der Bounding Box von 
 // jedem beweglichen Möbelstück im Zuhause
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Zeige das Ergebnis in einem Meldungsfeld an (³ steht für hochgestellte 3)
 String message = String. format(
 „Das maximale Volumen der beweglichen Möbel im Zuhause beträgt %.2f m³.“, 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

Nachdem du festgelegt hast, was das Plug-in tun soll, musst du beschreiben, wie der Benutzer diese neue Aktion starten wird. Du hast die Wahl, ob du einen neuen Menüpunkt zu einem Menü und/oder einen neuen Button zur Werkzeugleiste hinzufügen möchtest. Diese Wahl triffst du, indem du die entsprechenden Eigenschaften der Plug-in-Aktion bei ihrer Erstellung festlegst. Wenn du beispielsweise möchtest, dass Benutzer die Volumenaktion mit dem Menüpunkt Volumen berechnen im Menü Werkzeuge starten, fügst du den folgenden Konstruktor zur Klasse VolumeAction hinzu:

  public VolumeAction() {
           putPropertyValue(Property.NAME, „Volumen berechnen“);
           putPropertyValue(Property.MENU, „Werkzeuge“);
 // Aktiviert die Aktion standardmäßig
           setEnabled(true);
 }

Die Plug-in-Klasse VolumePlugin ist nun programmiert und fast bereit, als Plug-in in Sweet Home 3D zu funktionieren. Die letzten beiden Dinge, die zu tun sind, sind:

• eine ApplicationPlugin.properties-Beschreibungsdatei erstellen,
• die Dateien in einer JAR-Datei zusammenfassen.
  

Die Plug-in-Beschreibungsdatei erstellen

Eine ApplicationPlugin.properties-Datei beschreibt den Plug-in-Namen, seine Klasse, die Sweet Home 3D- und Java-Mindestversionen, unter denen es unterstützt wird, und rechtliche Hinweise. Wähle Datei > Neu > Datei aus dem Eclipse-Menü, gib den Dateinamen ApplicationPlugin.properties ein und klicke auf Fertig stellen, wie in Abbildung 5 gezeigt.

Dann gib die folgende Beschreibung in die neue Datei ein und speichere sie:

name=Volumen der beweglichen Möbel
class=com.eteks.test.VolumePlugin
description=Berechnet das Volumen der beweglichen Möbel im Zuhause
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Die Plug-in-JAR erstellen

Die Plug-in-JAR enthält die Class-Dateien, die aus der Kompilierung der Datei VolumePlugin.java und der Datei ApplicationPlugin.properties erstellt wurden. Da Eclipse eine Java-Datei kompiliert, sobald du sie speicherst, musst du lediglich Datei > Exportieren… aus dem Menü wählen und Java > JAR-Datei im angezeigten Export-Dialogfeld auswählen. Wähle im JAR-Export-Assistenten, der wie in Abbildung 6 gezeigt erscheint, das Projekt-Kontrollkästchen aus und gib den Pfad einer JAR-Datei ein, die im Plug-in-Ordner von Sweet Home 3D abgelegt wird. Dieser entsprechende Ordner hängt von deinem System ab, wie folgt:

• unter Windows Vista / 7 / 8 / 10 / 11 ist dieser Ordner C:\Users\Benutzer\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• unter Windows XP und früheren Windows-Versionen ist dieser Ordner C:\Dokumente und Einstellungen\Benutzer\Anwendungsdaten\eTeks\Sweet Home 3D\plugins,
• unter macOS ist es der Unterordner Library/Application Support/eTeks/Sweet Home 3D/plugins deines Benutzerordners,
• unter Linux und anderen Unix-Systemen ist es der Unterordner .eteks/sweethome3d/plugins deines Benutzerordners.

Das Plug-in testen

Das von dir entwickelte Plug-in wird in Sweet Home 3D ausgeführt, entweder mit der Java Web Start-Version, der Installer-Version oder der SweetHome3D-7.5.jar, die du zuvor heruntergeladen hast. Da letztere eine ausführbare JAR ist, kannst du sie durch Doppelklicken oder mit dem folgenden Befehl ausführen:

Das von dir entwickelte Plug-in wird in Sweet Home 3D ausgeführt, entweder mit der Java Web Start-Version, der Installer-Version oder der SweetHome3D-7.5.jar, die du zuvor heruntergeladen hast. Da letztere eine ausführbare JAR ist, kannst du sie durch Doppelklicken oder mit dem folgenden Befehl ausführen:

java -jar /path/to/SweetHome3D-7.5.jar

Solange du testest, wirst du Sweet Home 3D wahrscheinlich lieber mit diesem Befehl ausführen, um in der Konsole den Stack-Trace der Ausnahmen lesen zu können, die während der Ausführung deines Plug-ins ausgelöst werden.

Sobald Sweet Home 3D gestartet ist, siehst du das neue Menü und seinen Eintrag, wie in Abbildung 7 gezeigt:

Wenn du den neuen Menüpunkt für das Heimbeispiel in der Benutzeranleitung erstellte wählst, erhältst du folgendes Ergebnis:

Das Plug-in debuggen

Wenn du dein Plug-in von Eclipse aus debuggen musst, erstelle eine Debug-Konfiguration, indem du diese Schritte befolgst:

• Wähle Ausführen > Debug-Konfigurationen… aus dem Menü, wähle den Eintrag Java-Anwendung in der Liste der verfügbaren Konfigurationen des Dialogfelds Debug-Konfigurationen, klicke oben links auf die Schaltfläche Neu und gib einen Namen für die Konfiguration ein.
• Klicke auf die Schaltfläche Suchen… rechts neben dem Textfeld Hauptklasse und doppelklicke auf die Klasse SweetHome3DBootstrap
  unter den vorgeschlagenen Klassen.

• Klicke auf den Tab Classpath, wähle den Unterpunkt VolumePlugin (Standard-Classpath) des Eintrags Benutzereinträge in der Liste Classpath und klicke auf die Schaltfläche Entfernen.
• Klicke auf den Eintrag Benutzereinträge in der Liste Classpath, klicke auf die Schaltfläche JARs hinzufügen…, wähle den Eintrag SweetHome3D-7.5.jar aus und bestätige deine Wahl.

• Wähle den Tab Quelle, klicke auf die Schaltfläche Hinzufügen…, doppelklicke auf den Eintrag Java-Projekt im Dialogfeld Quelle hinzufügen, wähle den Eintrag VolumePlugin im Popup-Fenster Projektauswahl aus und bestätige deine Wahl.

• Klicke schließlich auf die Schaltfläche Debuggen, um Sweet Home 3D im Debug-Modus zu starten. Sobald das Programm läuft, öffne die Datei VolumePlugin.java, setze einen Haltepunkt in der Methode execute und wähle Werkzeuge > Volumen berechnen aus dem Sweet Home 3D-Menü. Eclipse hält am ausgewählten Haltepunkt an, damit du das Programm Schritt für Schritt ausführen und Variablenwerte überprüfen kannst.

Jedes Mal, wenn du den Quellcode deines Plug-ins änderst, vergiss nicht, die Plug-in-JAR zu generieren, bevor du die von dir erstellte Debug-Konfiguration startest. Um den JAR-Exportprozess in Eclipse zu beschleunigen, gehe zum zweiten Schritt des JAR-Export-Assistenten und wähle die Option Beschreibung dieser JAR im Arbeitsbereich speichern. Dies fügt dem Projekt einen neuen Eintrag mit einem kontextuellen Menüpunkt JAR erstellen hinzu.

Das Plug-in bereitstellen

Sobald es fertig ist, kann dein Plug-in auf den Computern anderer Sweet Home 3D-Benutzer bereitgestellt werden, indem du es einfach in ihren Plug-in-Ordner kopierst. Ab Version 1.6 kann eine Plug-in-Datei auch im Plug-in-Ordner von Sweet Home 3D installiert werden, indem man darauf doppelklickt, wenn ihre Erweiterung SH3P ist (ändere einfach die Dateierweiterung von .zip zu .sh3p). Wenn ein Doppelklick auf eine .sh3p-Datei Sweet Home 3D nicht startet (meistens unter Linux), kannst du ein Plug-in auch mit dem folgenden Befehl in einem Terminal-Fenster installieren (wobei SweetHome3D der Name der ausführbaren Datei ist, die mit den Sweet Home 3D-Installern geliefert wird):

/path/to/SweetHome3D /path/to/plugin.sh3p

Um ein Plug-in nicht mehr zu verwenden, entferne seine Datei aus dem Plug-in-Ordner und starte Sweet Home 3D neu.

Wenn du möchtest, dass dein Plug-in mit allen auf dieser Website verfügbaren Sweet Home 3D-Installern läuft, achte darauf, es Java 5-kompatibel zu halten, indem du 1.5 im Feld Compiler-Kompatibilitätsstufe auswählst, das im Abschnitt Java-Compiler des Dialogfelds verfügbar ist, das über den Menüpunkt Projekt > Eigenschaften von Eclipse angezeigt wird.
Wenn du eine Java-Compiler-Version verwendest, in der Java 1.5-Kompatibilität nicht mehr verfügbar ist, versuche, mindestens Java 1.8 anzustreben, das immer noch in neueren Versionen von Sweet Home 3D verwendet wird, und setze javaMinimumVersion in der ApplicationPlugin.properties Datei deines Plug-ins entsprechend.

Weiterführendes

Die Programmierung des ersten Plug-ins hat Ihnen das Gesamtbild gezeigt. Hier sind einige zusätzliche Informationen, die Ihnen helfen werden, noch weiter zu gehen.

Sweet Home 3D API – javadoc

Die nützlichste Dokumentation zur Entwicklung eines neuen Plug-ins ist die Sweet Home 3D API (Application Programming Interface), die mit dem Javadoc-Tool generiert wurde.
Verwenden Sie nur die Klassen der Pakete com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools und com.eteks.sweethome3d.viewcontroller in Ihrem Plug-in, wenn Sie möchten, dass es mit zukünftigen Versionen von Sweet Home 3D aufwärtskompatibel ist. Dies wird weitgehend ausreichen, um jedes Plug-in zu programmieren, das mit den in Sweet Home 3D verfügbaren Hausdaten arbeitet.
Die Pakete, die den anderen Ebenen des Programms entsprechen, sind nur zu Informationszwecken in der Javadoc enthalten. Verlassen Sie sich nicht auf deren API, da sie sich in Zukunft ohne Garantie aufwärtskompatibel ändern kann (Sie werden ohnehin keinen Verweis auf eine Klasse der Pakete com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io oder com.eteks.sweethome3d in den oben genannten Paketen sehen).

Architektur der Modellklassen

Sweet Home 3D basiert auf einer MVC-Architektur (Model View Controller), daher ist es wichtig zu verstehen, wie die Modellebene organisiert ist. Abbildung 13 (auch im PDF-Format verfügbar) zeigt fast alle Klassen und Schnittstellen, die in Version 1.5 des Pakets com.eteks.sweethome3d.model verfügbar sind, das dieser Modellebene entspricht.

Die zentrale Klasse in der Modellebene ist die Klasse HomeApplication (10), die abstrakte Superklasse der Hauptklasse der Anwendung SweetHome3D. Die Instanz dieser Klasse ermöglicht den Zugriff auf die aktuell bearbeiteten Home-Instanzen (7) und auf das Objekt UserPreferences (11), das die verwendete Längeneinheit (12), den Möbelkatalog (14) und den Texturenkatalog (15) speichert, aus denen der Benutzer Möbelstücke (17) und Texturen (18) auswählt.
Eine Home-Instanz (7) speichert alle Objekte, die der Benutzer im Hausplan erstellt hat:

• die Liste der HomePieceOfFurniture-Objekte (13), die die Schnittstelle PieceOfFurniture (16) implementieren,
• die Sammlung von Wall-Objekten (9),
• die Liste der Room-Objekte (5),
• die Sammlung von DimensionLine-Objekten (2),
• die Sammlung von Label-Objekten (3).

Diese Objekte implementieren die Schnittstelle Selectable (1) sowie das Objekt ObserverCamera (4), das die Position der Kamera im Modus Virtueller Besucher speichert. Alle externen Informationen, die von Modellobjekten verwaltet werden, wie das Symbol und das 3D-Modell eines Möbelstücks (16) oder das Bild einer Textur (20), werden über die Schnittstelle Content (19) abgerufen, die von der Klasse URLContent und anderen Klassen des Pakets com.eteks.sweethome3d.tools implementiert wird.

Dieses UML-Diagramm soll Ihnen helfen zu verstehen, welche Klassen im Sweet Home 3D-Modell verfügbar sind und wie Sie auf diese zugreifen können. Sie werden jedoch wahrscheinlich feststellen, dass darin keine Konstruktoren und keine Mutatoren (oder Setter, wenn Sie es vorziehen) genannt werden. Dies liegt nur am Platzmangel, aber Sie können diese problemlos in einer Plug-in-Klasse verwenden. Beachten Sie auch, dass jede Änderung eines vorhandenen Objekts des Modells an die angezeigten Komponenten entweder mit PropertyChangeEvents, mit CollectionEvents (8) oder mit SelectionEvents (6) gemeldet wird, wodurch alle Änderungen sofort auf dem Bildschirm widergespiegelt werden.

Das Sweet Home 3D-Modell ist aus Performancegründen nicht threadsicher. Alle Änderungen an einem Objekt, das zum Modell gehört, sollten im Event Dispatch Thread erfolgen.

Architektur der Plug-in-Klassen

Die Architektur der Plug-in-Klassen ist viel einfacher zu verstehen als die der Modellebene. Das Paket com.eteks.sweethome3d.plugin enthält nur drei Klassen, von denen Sie vermutlich nur die Klassen Plugin und PluginAction verwenden werden, wie in Abbildung 14 (auch im PDF-Format verfügbar) dargestellt.

Eine PluginManager-Instanz (1) wird beim Start der Anwendung erstellt und sucht nach den Plug-ins, die im Plug-in-Ordner des Benutzers installiert sind. Jedes Mal, wenn ein neues Haus bearbeitet wird, instanziiert und konfiguriert dieser Manager ein Plugin-Objekt (3) für jedes Plug-in, das beim Start gefunden wurde. Anschließend ruft er die Methode getActions auf, um alle Aktionen (4) abzurufen, die als Menüpunkte und/oder Symbolleistenschaltflächen im Hausfenster hinzugefügt werden. Jede Aktion ist eine Instanz von PluginAction, die wie die Klasse Action aussieht, mit ihrer Methode execute und ihren modifizierbaren Eigenschaften (2).

Beachten Sie, dass die Klasse Plugin Ihnen über ihre Methode getUndoableEditSupport Zugriff auf eine UndoableEditSupport-Instanz gewährt. Sobald Sie ein Haus oder seine Objekte (Möbel, Wände…) in der Execute-Methode einer PluginAction-Instanz ändern, sollten Sie auch ein UndoableEdit-Objekt an die Undoable-Edit-Unterstützung senden, die von der GetUndoableEditSupport-Methode zurückgegeben wird, da die Benutzer sonst die von Ihnen vorgenommenen Änderungen nicht korrekt rückgängig machen/wiederherstellen können.

Lokalisierung

Wenn Sie planen, ein Plug-in für die Sweet Home 3D-Benutzergemeinschaft zu entwickeln, versuchen Sie, die darin angezeigten Zeichenketten entweder in Aktionsnamen und Menüs oder in von Ihnen erstellten Dialogen zu lokalisieren (oder zumindest deren Lokalisierung vorzubereiten). Zwei Konstruktoren der PluginAction-Klasse helfen Ihnen, die Übersetzung von Aktionseigenschaften mit .properties-Dateien zu organisieren, und wenn Sie andere Zeichenketten in Ihrem Plug-in übersetzen müssen (wie die im Dialog des getesteten Plug-ins angezeigten), verwenden Sie diese .properties-Dateien mit der Java-Klasse ResourceBundle wieder.
Wenn Sie die Anzahl der Properties-Dateien begrenzen möchten, können Sie die Werte der Aktionseigenschaften und anderer Zeichenketten auch in die Beschreibungsdatei ApplicationPlugin.properties Ihres Plug-ins schreiben.

Wenn Sie ein Beispiel für die Verwendung dieser Architektur wünschen, laden Sie das Plug-in Export to SH3F herunter, das unter https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p verfügbar ist, und entpacken Sie es (diese Plug-in-Datei enthält auch den Quellcode des Plug-ins).
Wie im Hilfeforum beschrieben, erstellt dieses Plug-in eine SH3F-Datei, die alle Möbel enthält, die Sie in den Möbelkatalog von Sweet Home 3D importiert haben.

Beitragen von Plug-ins

Sie können die von Ihnen programmierten Plug-ins im Plug-ins Contributions Tracking System veröffentlichen, um sie mit der Sweet Home 3D-Benutzergemeinschaft zu teilen.
Dank Plug-ins können Sweet Home 3D viele Funktionen hinzugefügt werden, von Importeuren bis hin zu Exporteuren, aber auch Plug-ins, die in der Lage sind, die Daten eines Hauses zu verändern, wie das von Michel Mbem entwickelte Home Rotator Plug-in und andere, die im Tutorial for Plug-ins and Extensions (PDF) von Hans Dirkse und auf der Seite Plug-ins and tools aufgeführt sind.