Plug-in utvecklarguide

Introduktion

Från och med version 1.5 är det möjligt att lägga till nya funktioner i Sweet Home 3D med plug-in-filer som placeras i din plug-in-mapp. Detta tillåter Java-programmerare att utveckla och distribuera nya funktioner för Sweet Home 3D utan att modifiera källfilerna i den aktuella versionen (vilket är bra för uppåtriktad kompatibilitet) och utan att leverera en fullständig version av programmet (vilket är bra för leveransstorleken).
Det här dokumentet beskriver de verktyg som krävs för att skapa plug-ins, och visar sedan hur man programmerar en plug-in som beräknar den maximala volymen av de flyttbara möblerna som lagts till i ett hem, och ger slutligen lite ytterligare information som hjälper dig att gå vidare.

Installera utvecklingsverktyg

Om Sweet Home 3D riktar sig till en allmän publik kräver utveckling av plug-ins speciella färdigheter, och du bör veta hur man programmerar i Java med en IDE innan du går vidare. Den här guiden visar hur du bygger en plug-in med Eclipse, men du kan använda den IDE du väljer, eller ingen IDE alls.

Ladda ner och installera Eclipse

Ladda först ner Eclipse från https://www.eclipse.org/. Versionen som heter Eclipse IDE for Java Developers räcker för att utveckla en plug-in, men du kan ladda ner vilken version som helst för Java-utveckling.
När Eclipse har laddats ner är installationen väldigt enkel: packa bara upp arkivet du får, öppna eclipse-mappen och beroende på ditt system, kör filen som heter eclipse.exe (under Windows), eclipse.app (under Mac OS X) eller eclipse (under Linux).
Vid första körningen kommer Eclipse att kräva att du väljer en arbetsyta, där plug-in-projekten kommer att lagras.
När du är klar, välj File > New > Project från menyn för att skapa ett nytt projekt, välj Java > Java project i guiden New project som visas, ange VolumePlugin som projektnamn och klicka på knappen Finish. Stäng slutligen fliken Welcome för att upptäcka din arbetsyta som visas i figur 1.

Ladda ner och installera Sweet Home 3D-biblioteket

Utvecklingen av en plug-in baseras på vissa klasser av Sweet Home 3D som Eclipse måste känna till för att kunna bygga ditt projekt. Det enklaste sättet att lägga till Sweet Home 3D-klasser till Eclipse är att ladda ner JAR-körbara versionen av Sweet Home 3D som finns på https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. När du har laddat ner den, dra och släpp filen SweetHome3D-7.5.jar på projektikonen VolumePlugin i vyn Package Explorer i Eclipse, och välj objektet Build Path > Add to Build Path i den kontextuella menyn i filen SweetHome3D-7.5.jar, som visas i figur 2.

Programmera en plug-in

Nu när du har installerat de verktyg som krävs, låt oss se hur du kan programmera din första plug-in för Sweet Home 3D.

Skapa plug-in-klassen

Skapa först en ny underklass av com.eteks.sweethome3d.plugin.Plugin genom att välja menyalternativet File > New > Class i Eclipse.

I dialogrutan New Java Class anger du VolumePlugin som klassnamn, anger ett paket (här var det valda paketet com.eteks.test) och väljer com.eteks.sweethome3d.plugin.Plugin som superklass för VolumePlugin. När du är klar klickar du på Finish. Eclipse skapar filen för den nya klassen med följande innehåll:

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

Som du kan gissa från TODO-kommentaren måste du nu ändra implementeringen av getActions-metoden för att returnera en plug-in-åtgärd som kan beräkna volymen av de flyttbara möblerna. Ersätt return null; med följande uttalande:

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

och välj Edition > Quick Fix från Eclipse-menyn för att skapa den saknade klassen VolumeAction, som visas i figur 4.

I dialogrutan New Java Class som visas markerar du kryssrutan Enclosing type för att skapa en inre klass av VolumePlugin och klickar på Finish. Detta skapar klassen VolumeAction som ärver från com.eteks.sweethome3d.plugin.PluginAction-klassen och innehåller en tom execute-metod:

  public class VolumeAction extends PluginAction {
 @Override
 public void execute() {
 // TODO Auto-generated method stub
 }
 }

Denna metod är den som Sweet Home 3D kommer att anropa när användaren startar plug-in-åtgärden; alltså är detta platsen där du måste implementera hur man beräknar möblernas volym och visar den:

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

Nu när du har angett vad du vill att plug-in ska göra, måste du beskriva hur användaren ska starta den här nya åtgärden. Du kan välja mellan att lägga till ett nytt menyalternativ till en meny och/eller en ny knapp till verktygsfältet. Detta val görs genom att ställa in lämpliga egenskaper för plug-in-åtgärden vid dess skapande. Om du till exempel vill att användarna ska starta volymåtgärden med menyalternativet Compute volume som finns i menyn Tools, lägger du till följande konstruktor i VolumnAction-klassen:

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

Plug-in-klassen VolumePlugin är nu programmerad och nästan redo att fungera som en plug-in i Sweet Home 3D. De två sista sakerna att göra är:

• skapa en beskrivningsfil för ApplicationPlugin.properties,
• lägga ihop filerna i en JAR-fil.
  

Skapa plug-in-beskrivningsfilen

En ApplicationPlugin.properties fil beskriver plug-in-namnet, dess klass, de lägsta versionerna av Sweet Home 3D och Java som den stöds under, och juridiska saker. Välj File > New > File från Eclipse-menyn, ange filnamnet ApplicationPlugin.properties och klicka på Finish, som visas i figur 5.

Ange sedan följande beskrivning i den nya filen och spara den:

name=Flyttbar möbelvolym
class=com.eteks.test.VolumePlugin
description=Beräknar volymen av de flyttbara möblerna i hemmet
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Skapa plug-in-JAR

Plug-in-JAR innehåller class-filerna som skapats från kompileringen av filen VolumePlugin.java, och filen ApplicationPlugin.properties. Eftersom Eclipse kompilerar en Java-fil så fort du sparar den, behöver du bara välja File > Export… från menyn och välj Java > JAR file i dialogrutan Export som visas. I guiden Jar Export som visas som visas i figur 6, markera projektets kryss ruta och ange sökvägen till en JAR-fil som placeras i Sweet Home 3D-plug-in-mappen. Den här lämpliga mappen beror på ditt system enligt följande:

• under Windows Vista / 7 / 8 / 10 / 11 är den här mappen C:\Users\användare\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• under Windows XP och tidigare versioner av Windows är den här mappen C:\Documents and Settings\användare\Application Data\eTeks\Sweet Home 3D\plugins,
• under macOS är det undermappen Library/Application Support/eTeks/Sweet Home 3D/plugins i din användarmapp,
• under Linux och andra Unix är det undermappen .eteks/sweethome3d/plugins i din användarmapp.

Testa plug-in

Den plug-in du utvecklat kommer att köras i Sweet Home 3D, antingen med Java Web Start-versionen, installationsprogrammen eller SweetHome3D-7.5.jar som du laddade ner tidigare. Eftersom den senaste är en körbar JAR kan du köra den genom att dubbelklicka på den eller med följande kommando:

Den plug-in du utvecklat kommer att köras i Sweet Home 3D, antingen med Java Web Start-versionen, installationsprogrammen eller SweetHome3D-7.5.jar som du laddade ner tidigare. Eftersom den senaste är en körbar JAR kan du köra den genom att dubbelklicka på den eller med följande kommando:

java -jar /sökväg/till/SweetHome3D-7.5.jar

Så länge du testar kommer du förmodligen att föredra att köra Sweet Home 3D med det här kommandot, för att kunna läsa i konsolen stackspårningen av de undantag som kastas under körningen av din plug-in.

När Sweet Home 3D har startats ser du den nya menyn och dess objekt visas som visas i figur 7:

Om du väljer det nya menyalternativet för hemexemplet som skapats i användarhandboken får du följande resultat:

Felsöka plug-in

Om du behöver felsöka din plug-in från Eclipse, skapa en felsökningskonfiguration genom att följa dessa steg:

• Välj Run > Debug Configurations… från menyn, välj objektet Java Application i listan över tillgängliga konfigurationer i dialogrutan Debug configurations, klicka på knappen New längst upp till vänster och ange ett namn för konfigurationen.
• Klicka på knappen Search… till höger om textfältet Main class och dubbelklicka på klassen SweetHome3DBootstrap
  bland de föreslagna klasserna.

• Klicka på fliken Classpath, välj underobjektet VolumePlugin (default classpath) för objektet User Entries i listan Classpath och klicka på knappen Remove.
• Klicka på objektet User Entries i listan Classpath, klicka på knappen Add JARs…, välj objektet SweetHome3D-7.5.jar och bekräfta ditt val.

• Välj fliken Source, klicka på knappen Add…, dubbelklicka på objektet Java Project i dialogrutan Add Source, välj objektet VolumePlugin i popup-fönstret Project Selection och bekräfta ditt val.

• Slutligen, klicka på knappen Debug för att starta Sweet Home 3D i felsökningsläge. När programmet körs, öppna filen VolumePlugin.java, ställ in en brytpunkt i metoden execute och välj Tools > Compute volume från Sweet Home 3D-menyn. Eclipse stannar vid den valda brytpunkten så att du kan köra programmet steg för steg och inspektera variablernas värde.

Distribuera plug-in

När din plug-in är klar kan den distribueras på andra Sweet Home 3D-användares datorer genom att helt enkelt kopiera den till deras plug-in-mapp. Från och med version 1.6 kan en plug-in-fil också installeras i plug-in-mappen för Sweet Home 3D genom att dubbelklicka på den, om dess filnamnstillägg är SH3P (ändra helt enkelt filnamnstillägget från .zip till .sh3p). Om dubbelklick på en .sh3p-fil inte startar Sweet Home 3D (störst chans under Linux) kan du också installera en plug-in med följande kommando i ett Terminal-fönster (där SweetHome3D är namnet på den körbara filen som medföljer Sweet Home 3D-installationsprogrammen):

/sökväg/till/SweetHome3D /sökväg/till/plugin.sh3p

För att sluta använda en plug-in, ta bort dess fil från plug-in-mappen och starta om Sweet Home 3D.

Gå vidare

Programmeringen av den första plug-in visade dig helhetsbilden. Här är lite ytterligare information som hjälper dig att gå vidare.

Sweet Home 3D API – Javadoc

Den mest användbara dokumentationen för att utveckla ett nytt plugin är Sweet Home 3D API (Application Programming Interface), genererat med javadoc-verktyget.
Använd endast klasserna i paketen com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools och com.eteks.sweethome3d.viewcontroller i ditt plugin om du vill att det ska vara uppåtkompatibelt med framtida versioner av Sweet Home 3D. Detta kommer att vara tillräckligt för att programmera alla plugins som fungerar med hemdata som finns tillgängliga i Sweet Home 3D.
Paketen som matchar de andra lagren i programmet ingår endast i Javadoc i informationssyfte. Förlita dig inte på deras API, eftersom det fortfarande kan ändras i framtiden utan garanti för uppåtkompatibilitet (du kommer ändå inte att se någon referens till en klass i paketen com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io eller com.eteks.sweethome3d i de ovannämnda paketen).

Modellklassers arkitektur

Sweet Home 3D är baserat på en MVC-arkitektur (Model View Controller), så det är viktigt att förstå hur dess modelllager är organiserat. Figur 13 (finns även i PDF-format) presenterar nästan alla klasser och gränssnitt som är tillgängliga i version 1.5 av paketet com.eteks.sweethome3d.model som matchar detta modelllager.

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

Den centrala klassen i modellagret är klassen HomeApplication (10), den abstrakta superklassen för huvudklassen för applikationen SweetHome3D. Instansen av den här klassen ger åtkomst till Home-instanserna (7) som för närvarande redigeras, och till UserPreferences-objektet (11) som lagrar den längdenhet (12) som används, möbelkatalogen (14) och texturkatalogen (15) från vilka användaren väljer möbler (17) och texturer (18).
En Home-instans (7) lagrar alla objekt som användaren har skapat i hemplanen:

• listan över HomePieceOfFurniture-objekt (13) som implementerar gränssnittet PieceOfFurniture (16),
• samlingen av Wall-objekt (9),
• listan över Room-objekt (5),
• samlingen av DimensionLine-objekt (2),
• samlingen av Label-objekt (3).

Dessa objekt implementerar gränssnittet Selectable (1) samt ObserverCamera-objektet (4), som lagrar kamerans plats i läget Virtuell besökare. All extern information som hanteras av modellobjekt, som ikonen och 3D-modellen av en möbel (16), eller bilden av en textur (20) nås via gränssnittet Content (19), implementerat av klassen URLContent och andra klasser i paketet com.eteks.sweethome3d.tools.

Detta UML-diagram bör hjälpa dig att förstå vilka klasser som är tillgängliga i Sweet Home 3D-modellen och hur du kan komma åt dem, men du kommer förmodligen att märka att inga konstruktorer och inga mutatorer (eller setters om du föredrar) nämns i det. Det är bara på grund av platsbrist, men du kan använda dem utan problem i en plugin-klass. Observera också att alla ändringar av ett befintligt objekt i modellen kommer att meddelas till de visade komponenterna antingen med PropertyChangeEvents, med CollectionEvents (8) eller med SelectionEvents (6), vilket gör att alla ändringar återspeglas omedelbart på skärmen.

Plugin-klassers arkitektur

Arkitekturen för plugin-klasser är mycket enklare att förstå än modelllagrets. Paketet com.eteks.sweethome3d.plugin innehåller bara tre klasser bland vilka du bara ska använda klasserna Plugin och PluginAction, som visas i figur 14 (finns även i PDF-format).

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

En PluginManager-instans (1) skapas vid applikationsstart och söker efter de plugins som är installerade i användarens plugin-mapp. Varje gång ett nytt hem redigeras, instansierar och konfigurerar den här hanteraren ett Plugin-objekt (3) för varje plugin som hittas vid start. Sedan anropas metoden getActions för att hämta alla åtgärder (4) som kommer att läggas till som menyalternativ och/eller verktygsfältsknappar i hemfönstret. Varje åtgärd är en instans av PluginAction, som ser ut som klassen Action, med sin execute-metod och dess modifierbara egenskaper (2).

Observera att klassen Plugin ger dig åtkomst till en UndoableEditSupport-instans via sin getUndoableEditSupport-metod. Så snart du ändrar ett hem eller dess objekt (möbler, väggar…) i execute-metoden för en PluginAction-instans, bör du också publicera ett UndoableEdit-objekt till det undoable edit-stöd som returneras av getUndoableEditSupport-metoden, annars kommer användarna inte att kunna ångra/göra om de ändringar du gjort korrekt.

Lokalisering

Om du planerar att utveckla ett plugin för Sweet Home 3D-användargemenskapen, försök att lokalisera de strängar som det visar antingen i åtgärdsnamn och meny eller i dialogrutor som du skapar (eller åtminstone förbereda dess lokalisering). Två konstruktorer för PluginAction-klassen hjälper dig att organisera översättningen av åtgärdsegenskaper med .properties-filer, och om du behöver översätta andra strängar i ditt plugin (som den i dialogrutan som visas av det testade pluginet) återanvänd dessa .properties-filer med Java-klassen ResourceBundle.
Om du föredrar att begränsa antalet egenskapsfiler kan du till och med skriva värdena för åtgärdsegenskaperna och andra strängar i beskrivningsfilen ApplicationPlugin.properties för ditt plugin.

Om du vill ha ett exempel som använder den här arkitekturen, ladda ner pluginet Exportera till SH3F som finns tillgängligt på https://test.sweethome3d.eu/plugins/ExportToSH3F-1.0.sh3p och packa upp det (den här plugin-filen innehåller även källkoden för pluginet).
Som beskrivs i hjälpforumet skapar det här pluginet en SH3F-fil som innehåller alla möbler du importerat i möbelkatalogen i Sweet Home 3D.

Bidra med plugins

Du kan publicera de plugins du har programmerat i Plug-ins Contributions Tracking System för att dela dem med Sweet Home 3D-användargemenskapen.
Många funktioner kan läggas till i Sweet Home 3D tack vare plugins, från importörer till exportörer, men även plugins som kan ändra data i ett hem som Home Rotator Plug-in utvecklat av Michel Mbem och andra listade i Tutorial for Plug-ins and Extensions (PDF) skriven av Hans Dirkse och på sidan Plug-ins and tools.