Anleitung für Plug-in-Entwickler

Einführung

Ab Version 1.5 ist es möglich, Sweet Home 3D mit Plug-in-Dateien, die sich in Ihrem Plug-in-Ordner befinden, neue Funktionen hinzuzufügen. Dies ermöglicht es Java-Programmierern, neue Funktionen für Sweet Home 3D zu entwickeln und zu verteilen, ohne die Quelldateien der aktuellen Version zu verändern (was gut für die Aufwärtskompatibilität ist) und ohne eine Vollversion des Programms auszuliefern (was gut für die Liefergröße ist).
Dieses Dokument beschreibt die Werkzeuge, die zur Erstellung von Plug-ins benötigt werden, und zeigt dann, wie man ein Plug-in programmiert, das das maximale Volumen der beweglichen Möbel berechnet, die einem Haus hinzugefügt wurden, und gibt schließlich einige zusätzliche Informationen, die Ihnen helfen werden, weiterzukommen.

Installation von Entwicklungswerkzeugen

Wenn Sweet Home 3D ein allgemeines Publikum anspricht, erfordert die Entwicklung von Plug-ins spezielle Kenntnisse, und Sie sollten wissen, wie man in Java mit einer IDE programmiert, bevor Sie fortfahren. Diese Anleitung zeigt, wie man ein Plug-in mit Eclipse erstellt, aber Sie können die IDE Ihrer Wahl oder gar keine IDE verwenden.

Eclipse herunterladen und installieren

Laden Sie zuerst Eclipse von https://www.eclipse.org/ herunter. Die Version mit dem Namen Eclipse IDE for Java Developers reicht aus, um ein Plug-in zu entwickeln, aber Sie können jede Version für die Java-Entwicklung herunterladen.
Nach dem Herunterladen ist die Installation von Eclipse sehr einfach: Entpacken Sie einfach das Archiv, das Sie erhalten, öffnen Sie den Eclipse-Ordner und führen Sie je nach System die Datei mit dem Namen aus eclipse.exe (unter Windows), eclipse.app (unter Mac OS X) oder eclipse (unter Linux).
Beim ersten Start fordert Eclipse Sie auf, einen Arbeitsbereichsordner auszuwählen, in dem Plug-in-Projekte gespeichert werden.
Wählen Sie anschließend Datei > Neu > Projekt aus dem Menü, um ein neues Projekt zu erstellen, wählen Sie Java > Java-Projekt im Assistent für neue Projekte, der angezeigt wird, geben Sie VolumePlugin als Projektnamen ein und klicken Sie auf die Schaltfläche Fertigstellen. Schließen Sie abschließend die Registerkarte Willkommen, um Ihren Arbeitsbereich wie in Abbildung 1 dargestellt 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 Ihr 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. Ziehen Sie nach dem Herunterladen die Datei SweetHome3D-7.5.jar auf das VolumePlugin-Projektsymbol in der Ansicht Package Explorer von Eclipse und wählen Sie den Eintrag Build Path > Zum Build-Pfad hinzufügen im Kontextmenü der Datei SweetHome3D-7.5.jar, wie in Abbildung 2 dargestellt.

Programmierung eines Plug-ins

Nachdem Sie die erforderlichen Werkzeuge installiert haben, wollen wir sehen, wie Sie Ihr erstes Plug-in für Sweet Home 3D programmieren können.

Erstellung der Plug-in-Klasse

Erstellen Sie zunächst eine neue Unterklasse von com.eteks.sweethome3d.plugin.Plugin, indem Sie den Menüpunkt Datei > Neu > Klasse in Eclipse auswählen.

Geben Sie im Dialogfeld Neue Java-Klasse VolumePlugin als Klassennamen ein, geben Sie ein Paket ein (hier wurde das Paket com.eteks.test gewählt) und wählen Sie com.eteks.sweethome3d.plugin.Plugin als Superklasse von VolumePlugin. Klicken Sie anschließend auf Fertigstellen. 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 Auto-generated method stub
 return null;
 }
}

Wie Sie aus dem TODO-Kommentar erraten können, müssen Sie nun die Implementierung der Methode getActions ändern, um eine Plug-in-Aktion zurückzugeben, die in der Lage ist, das Volumen der beweglichen Möbel zu berechnen. Ersetzen Sie return null; durch die folgende Anweisung:

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

und wählen Sie Edition > Schnellkorrektur aus dem Eclipse-Menü, um die fehlende Klasse VolumeAction zu erstellen, wie in Abbildung 4 dargestellt.

Aktivieren Sie im Dialogfeld Neue Java-Klasse, das angezeigt wird, das Kontrollkästchen Umschließender Typ, um eine innere Klasse von VolumePlugin zu erstellen, und klicken Sie auf Fertigstellen. 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 Auto-generated method stub
 }
 }

Diese Methode ist diejenige, die Sweet Home 3D aufruft, wenn der Benutzer die Plug-in-Aktion startet; dies ist also der Ort, an dem Sie implementieren müssen, wie das Volumen der Möbel berechnet und angezeigt wird:

  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);
  }
  }

Nachdem Sie nun festgelegt haben, was das Plug-in tun soll, müssen Sie beschreiben, wie der Benutzer diese neue Aktion starten wird. Sie haben die Wahl zwischen dem Hinzufügen eines neuen Menüpunkts zu einem Menü und/oder einer neuen Schaltfläche zur Werkzeugleiste. Diese Wahl wird durch das Setzen der entsprechenden Eigenschaften der Plug-in-Aktion bei ihrer Erstellung getroffen. Wenn Sie beispielsweise möchten, dass die Benutzer die Volumenaktion mit dem Menüpunkt Volumen berechnen im Menü Werkzeuge starten, fügen Sie der VolumnAction-Klasse den folgenden Konstruktor hinzu:

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

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

• Erstellung einer ApplicationPlugin.properties-Beschreibungsdatei,
• Zusammenfügen der Dateien in einer JAR-Datei.
  

Erstellung der Plug-in-Beschreibungsdatei

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 Dinge. Wählen Sie Datei > Neu > Datei aus dem Eclipse-Menü, geben Sie den Dateinamen ApplicationPlugin.properties ein und klicken Sie auf Fertigstellen, wie in Abbildung 5 dargestellt.

Geben Sie dann die folgende Beschreibung in die neue Datei ein und speichern Sie sie:

name=Movable furniture volume
class=com.eteks.test.VolumePlugin
description=Computes the volume of the movable furniture in home
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Erstellung der Plug-in-JAR

Die Plug-in-JAR enthält die Klassendateien, die aus der Kompilierung der Datei VolumePlugin.java erstellt wurden, und die Datei ApplicationPlugin.properties. Da Eclipse eine Java-Datei kompiliert, sobald Sie sie speichern, müssen Sie nur Datei > Exportieren… aus dem Menü wählen und Java > JAR-Datei im Dialogfeld Exportieren auswählen , das angezeigt wird. Wählen Sie im Jar-Export-Assistenten, der wie in Abbildung 6 dargestellt erscheint, das Kontrollkästchen des Projekts aus und geben Sie den Pfad einer JAR-Datei ein, die sich im Sweet Home 3D-Plug-in-Ordner befindet. Dieser entsprechende Ordner hängt von Ihrem System wie folgt ab:

• 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 Versionen von Windows 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 Ihres Benutzerordners,
• unter Linux und anderen Unix-Systemen ist es der Unterordner .eteks/sweethome3d/plugins Ihres Benutzerordners.

Testen des Plug-ins

Das von Ihnen entwickelte Plug-in wird in Sweet Home 3D ausgeführt, entweder mit der Java Web Start-Version, der Installationsprogramm-Version oder der SweetHome3D-7.5.jar, die Sie zuvor heruntergeladen haben. Da die letzte eine ausführbare JAR-Datei ist, können Sie sie durch Doppelklicken darauf oder mit dem folgenden Befehl ausführen:

Das von Ihnen entwickelte Plug-in wird in Sweet Home 3D ausgeführt, entweder mit der Java Web Start-Version, der Installationsprogramm-Version oder der SweetHome3D-7.5.jar, die Sie zuvor heruntergeladen haben. Da die letzte eine ausführbare JAR-Datei ist, können Sie sie durch Doppelklicken darauf oder mit dem folgenden Befehl ausführen:

java -jar /Pfad/zu/SweetHome3D-7.5.jar

Solange Sie testen, werden Sie es wahrscheinlich vorziehen, Sweet Home 3D mit diesem Befehl auszuführen, um in der Konsole den Stack-Trace der Ausnahmen lesen zu können, die während der Ausführung Ihres Plug-ins ausgelöst werden.

Sobald Sweet Home 3D gestartet ist, sehen Sie das neue Menü und seinen Eintrag, wie in Abbildung 7 dargestellt:

Wenn Sie den neuen Menüpunkt für das Beispielhaus wählen, das in der Bedienungsanleitung erstellt wurde, erhalten Sie folgendes Ergebnis:

Debuggen des Plug-ins

Wenn Sie Ihr Plug-in von Eclipse aus debuggen müssen, erstellen Sie eine Debug-Konfiguration, indem Sie die folgenden Schritte ausführen:

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

• Klicken Sie auf die Registerkarte Classpath, wählen Sie den Untereintrag VolumePlugin (Standard-Classpath) des Eintrags Benutzereinträge in der Liste Classpath und klicken Sie auf die Schaltfläche Entfernen.
• Klicken Sie auf den Eintrag Benutzereinträge in der Liste Classpath, klicken Sie auf die Schaltfläche JARs hinzufügen…, wählen Sie den Eintrag SweetHome3D-7.5.jar aus und bestätigen Sie Ihre Auswahl.

• Wählen Sie die Registerkarte Quelle, klicken Sie auf die Schaltfläche Hinzufügen…, doppelklicken Sie auf den Eintrag Java-Projekt im Dialogfeld Quelle hinzufügen, wählen Sie den Eintrag VolumePlugin im Popup Projektauswahl und bestätigen Sie Ihre Auswahl.

• Klicken Sie abschließend auf die Schaltfläche Debuggen, um Sweet Home 3D im Debug-Modus zu starten. Sobald das Programm läuft, öffnen Sie die Datei VolumePlugin.java, setzen Sie einen Haltepunkt in der Methode execute und wählen Sie Werkzeuge > Volumen berechnen aus dem Sweet Home 3D-Menü. Eclipse stoppt am ausgewählten Haltepunkt, damit Sie das Programm Schritt für Schritt ausführen und Variablenwerte überprüfen können.

Bereitstellung des Plug-ins

Sobald Ihr Plug-in fertig ist, kann es auf dem Computer anderer Sweet Home 3D-Benutzer bereitgestellt werden, indem Sie es einfach in ihren Plug-in-Ordner kopieren. Ab Version 1.6 kann eine Plug-in-Datei auch im Plug-in-Ordner von Sweet Home 3D installiert werden, indem Sie darauf doppelklicken, wenn ihre Erweiterung SH3P ist (ändern Sie einfach die Dateierweiterung von .zip in .sh3p). Wenn ein Doppelklick auf eine .sh3p-Datei Sweet Home 3D nicht startet (höchstwahrscheinlich unter Linux), können Sie 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-Installationsprogrammen bereitgestellt wird):

/Pfad/zu/SweetHome3D /Pfad/zu/plugin.sh3p

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

Weiterführende Informationen

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

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 Schichten 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 Modellschicht aufgebaut 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 Modellschicht entspricht.

[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)“]

Die zentrale Klasse in der Modellschicht 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 Grundriss 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 sie zugreifen können. Sie werden jedoch wahrscheinlich feststellen, dass keine Konstruktoren und keine Mutatoren (oder Setter, wenn Sie es vorziehen) darin zitiert werden. Das liegt nur am Platzmangel, aber Sie können sie 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 angezeigt werden können.

Architektur der Plug-in-Klassen

Die Architektur der Plug-in-Klassen ist viel einfacher zu verstehen als die der Modellschicht. 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.

[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)“]

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üelemente 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 usw.) 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 von ihm angezeigten Zeichenketten entweder im Aktionsnamen und im Menü oder in den von Ihnen erstellten Dialogen zu lokalisieren (oder bereiten Sie zumindest seine Lokalisierung vor). 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, der vom getesteten Plug-in angezeigt wird), verwenden Sie diese .properties-Dateien mit der Java-Klasse ResourceBundle wieder.
Wenn Sie die Anzahl der Eigenschaftsdateien begrenzen möchten, können Sie die Werte der Aktionseigenschaften und anderer Zeichenketten sogar 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://test.sweethome3d.eu/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 ä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.