Guide för insticksmodulsutvecklare

• Introduktion
• Installera utvecklingsverktyg
• Programmera en insticksmodul
• Gå vidare

Introduktion

Från version 1.5 är det möjligt att lägga till nya funktioner i Sweet Home 3D med insticksmodulfiler som placeras i din insticksmodulsmapp. Detta gör det möjligt för Java-programmerare att utveckla och distribuera nya funktioner för Sweet Home 3D utan att ändra källfilerna i den aktuella versionen (vilket är bra för uppåtkompatibilitet) och utan att leverera en fullständig version av programmet (vilket är bra för leveransstorleken).
Detta dokument beskriver verktygen som krävs för att skapa insticksmoduler, visar sedan hur man programmerar en insticksmodul som beräknar maxvolymen av de flyttbara möblerna som lagts till i ett hem, och ger slutligen ytterligare information som hjälper dig att gå vidare.

Installera utvecklingsverktyg

Även om Sweet Home 3D riktar sig till en bred publik kräver utveckling av insticksmoduler särskilda kunskaper, och du bör kunna programmera i Java med en IDE innan du går vidare. Denna guide visar hur man bygger en insticksmodul med Eclipse, men du kan använda valfri IDE eller ingen IDE alls.

Ladda ner och installera Eclipse

Ladda först ner Eclipse från https://www.eclipse.org/. Versionen som kallas Eclipse IDE for Java Developers räcker för att utveckla en insticksmodul, men du kan ladda ner vilken version som helst för Java-utveckling.
När du har laddat ner är det mycket enkelt att installera Eclipse: packa bara upp arkivet du får, öppna Eclipse-mappen och beroende på ditt system, kör filen som heter eclipse.exe (i Windows), eclipse.app (i Mac OS X) eller eclipse (i Linux).
Vid första körningen kommer Eclipse att be dig välja en workspace-mapp där insticksmodulsprojekt kommer att lagras.
När det är klart, 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 workspace som visas i figur 1.

Ladda ner och installera Sweet Home 3D-biblioteket

Utvecklingen av en insticksmodul baseras på vissa klasser i 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 i Eclipse är att ladda ner JAR-körbar version av Sweet Home 3D som finns på https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. När den har laddats ner, dra och släpp filen SweetHome3D-7.5.jar på ikonen för projektet VolumePlugin i vyn Package Explorer i Eclipse, och välj alternativet Build Path > Add to Build Path i snabbmenyn för filen SweetHome3D-7.5.jar, som visas i figur 2.

Programmera en insticksmodul

Nu när du har installerat de nödvändiga verktygen, låt oss se hur du kan programmera din första insticksmodul för Sweet Home 3D.

Skapa insticksmodulklassen

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, ange VolumePlugin som klassnamn, ange ett paket (här valdes paketet com.eteks.test), och välj com.eteks.sweethome3d.plugin.Plugin som superklassen för VolumePlugin. När det är klart, klicka på Finish. Eclipse kommer att skapa 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 insticksmodulsåtgärd som kan beräkna volymen av de flyttbara möblerna. Ersätt return null; med följande uttryck:

  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, markera kryssrutan Enclosing type för att skapa en innerklass av VolumePlugin och klicka på Finish. Detta kommer att skapa klassen VolumeAction som ärver från klassen com.eteks.sweethome3d.plugin.PluginAction 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 insticksmodulsåtgärden; detta är alltså platsen där du måste implementera hur volymen av möblerna ska beräknas och visas:

  public class VolumeAction extends PluginAction {  
  @Override
  public void execute() { 
  float volumeInCm3 = 0;
 // Beräkna summan av volymen av den omslutande lådan för 
 // varje flyttbar möbel i hemmet
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Visa resultatet i en meddelanderuta (³ är för 3 i upphöjt)
 String message = String. format(
 "Den maximala volymen av de flyttbara möblerna i hemmet är %.2f m³.", 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

Nu när du har specificerat vad du vill att insticksmodulen ska göra måste du beskriva hur användaren ska starta denna nya åtgärd. Du har valet mellan att lägga till ett nytt menyalternativ i en meny och/eller en ny knapp i verktygsfältet. Detta val görs genom att ställa in lämpliga egenskaper för insticksmodulsåtgärden vid dess skapande. Om du till exempel vill att användarna ska starta volymåtgärden med menyalternativet Beräkna volym som finns i menyn Verktyg, lägger du till följande konstruktor i klassen VolumeAction:

  public VolumeAction() {
           putPropertyValue(Property.NAME, "Beräkna volym");
           putPropertyValue(Property.MENU, "Verktyg");
 // Aktiverar åtgärden som standard
           setEnabled(true);
 }

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

• att skapa en beskrivningsfil ApplicationPlugin.properties
• att paketera filerna tillsammans i en JAR-fil.
  

Skapa insticksmodulens beskrivningsfil

En ApplicationPlugin.properties-fil beskriver insticksmodulens namn, dess klass, de minimiversioner av Sweet Home 3D och Java som den stöder, och juridisk information. 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=Volym för flyttbara möbler
class=com.eteks.test.VolumePlugin
description=Beräknar volymen av de flyttbara möblerna i hemmet
version=1.0
license=GNU GPL
provider=(C) Upphovsrätt 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Skapa insticksmodulens JAR

Insticksmodulens JAR innehåller klass-filerna som skapats från kompileringen av VolumePlugin.java-filen, och ApplicationPlugin.properties-filen. Eftersom Eclipse kompilerar en Java-fil så snart du sparar den behöver du bara välja File > Export… från menyn och välja Java > JAR file i dialogrutan Export som visas. I guiden Jar Export som visas som i figur 6, markera projektets kryssruta och ange sökvägen till en JAR-fil placerad i Sweet Home 3D:s insticksmodulsmapp. Denna lämpliga mapp beror på ditt system enligt följande:

• under Windows Vista / 7 / 8 / 10 / 11 är denna mapp C:UsersanvändareAppDataRoamingeTeksSweet Home 3Dplugins,
• under Windows XP och tidigare versioner av Windows är denna mapp C:Documents and SettingsanvändareApplication DataeTeksSweet Home 3Dplugins,
• 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 insticksmodulen

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

Insticksmodulen du utvecklat kommer att köras i Sweet Home 3D, antingen med Java Web Start-versionen, installerare-versionen, eller SweetHome3D-7.5.jar som du laddade ner tidigare. Eftersom den senare ä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 föredra att köra Sweet Home 3D med detta kommando för att kunna läsa stackspårningen av undantagen som kastas under körningen av din insticksmodul i konsolen.

När Sweet Home 3D har startats kommer du att se den nya menyn och dess alternativ visas som i figur 7:

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

Felsöka insticksmodulen

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

• Välj Run > Debug Configurations… från menyn, välj alternativet 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 underalternativet VolumePlugin (default classpath) för alternativet User Entries i listan Classpath och klicka på knappen Remove.
• Klicka på alternativet User Entries i listan Classpath, klicka på knappen Add JARs…, välj alternativet SweetHome3D-7.5.jar och bekräfta ditt val.

• Välj fliken Source, klicka på knappen Add…, dubbelklicka på alternativet Java Project i dialogrutan Add Source, välj alternativet VolumePlugin i popup-rutan 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, sätt en brytpunkt i metoden execute och välj Verktyg > Beräkna volym från Sweet Home 3D-menyn. Eclipse kommer att stanna vid den valda brytpunkten för att låta dig köra programmet steg för steg och inspektera variabelvärden.

Varje gång du ändrar källkoden för din insticksmodul, glöm inte att generera insticksmodulens JAR innan du startar felsökningskonfigurationen du skapade. För att snabba upp JAR-exportprocessen i Eclipse, gå till det andra steget i JAR-exportguiden och välj alternativet Save the description of this JAR in the workspace. Detta kommer att lägga till ett nytt alternativ i projektet med ett kontextuellt menyalternativ Create JAR.

Distribuera insticksmodulen

När den är klar kan din insticksmodul distribueras på andra Sweet Home 3D-användares datorer genom att helt enkelt kopiera den till deras insticksmodulsmapp. Från version 1.6 kan en insticksmodulsfil också installeras i Sweet Home 3D:s insticksmodulsmapp genom att dubbelklicka på den om dess filändelse är SH3P (ändra helt enkelt filändelsen från .zip till .sh3p). Om dubbelklickning på en .sh3p-fil inte startar Sweet Home 3D (mest sannolikt under Linux) kan du också installera en insticksmodul 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-installerare):

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

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

Om du vill att din insticksmodul ska kunna köras med alla Sweet Home 3D-installerare som finns tillgängliga på denna webbplats, se till att hålla den kompatibel med Java 5 genom att välja 1.5 i fältet Compiler compliance level som finns i avsnittet Java Compiler i dialogrutan som visas av menyalternativet Project > Properties i Eclipse.
Om du använder en Java-kompilatorversion där Java 1.5-kompatibilitet inte längre är tillgänglig, försök att sikta på minst Java 1.8 som fortfarande används i nyare versioner av Sweet Home 3D och ställ in javaMinimumVersion i ApplicationPlugin.properties-filen för din insticksmodul i enlighet med detta.

Gå vidare

Programmeringen av det första insticksprogrammet 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 insticksprogram är Sweet Home 3D API (Application Programming Interface), genererad 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 insticksprogram om du vill att det ska vara uppåtkompatibelt med framtida versioner av Sweet Home 3D. Detta kommer att vara mer än tillräckligt för att programmera vilket insticksprogram som helst som arbetar med hemdata tillgänglig i Sweet Home 3D.
Paketen som matchar de andra lagren i programmet är inkluderade i Javadoc endast 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 tidigare nämnda paketen).

Arkitektur för modellklasser

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

Den centrala klassen i modellagret är HomeApplication-klassen (10), den abstrakta superklassen för SweetHome3D-applikationens huvudklass. Instansen av denna klass ger tillgång till de Home-instanser (7) som för närvarande redigeras, och till UserPreferences-objektet (11) som lagrar den längdenhet som används (12), 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 skapade 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) liksom ObserverCamera-objektet (4), som lagrar kamerans position 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 genom 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 finns 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 brist på utrymme, men du kan använda dem utan problem i en insticksprogramklass. 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 omedelbart återspeglas på skärmen.

Sweet Home 3D-modellen är inte trådsäker av prestandaskäl. Alla ändringar av ett objekt som tillhör modellen bör göras i Event Dispatch Thread.

Arkitektur för insticksprogramklasser

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

En PluginManager-instans (1) skapas vid programstart och söker efter insticksprogram installerade i användarens insticksprogrammapp. Varje gång ett nytt hem redigeras, instansierar och konfigurerar denna hanterare ett Plugin-objekt (3) för varje insticksprogram som hittades vid starttiden. Sedan anropar den metoden getActions för att hämta alla åtgärder (4) som kommer att läggas till som menyobjekt och/eller verktygsfältknappar i hemfönstret. Varje åtgärd är en instans av PluginAction, som liknar klassen Action, med sin execute-metod och sina modifierbara egenskaper (2).

Observera att klassen Plugin ger dig tillgång till en UndoableEditSupport-instans genom sin metod getUndoableEditSupport. 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å posta ett UndoableEdit-objekt till det ångringsbara redigeringsstödet som returneras av getUndoableEditSupport-metoden, annars kommer användarna inte att kunna ångra/göra om korrekt de ändringar du gjorde.

Lokalisering

Om du planerar att utveckla ett insticksprogram för Sweet Home 3D:s användargrupp, försök att lokalisera strängarna det visar antingen i åtgärdsnamn och menyer eller i dialogrutor du skapar (eller åtminstone förbereda dess lokalisering). Två konstruktorer i 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 insticksprogram (som den i dialogrutan som visas av det testade insticksprogrammet) å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 ApplicationPlugin.properties beskrivningsfilen för ditt insticksprogram.

Om du vill ha ett exempel som använder denna arkitektur, ladda ner insticksprogrammet Export to SH3F som finns på https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p, och packa upp det (denna insticksprogramfil innehåller även källkoden för insticksprogrammet).
Som beskrivs i Hjälpforumet, skapar detta insticksprogram en SH3F-fil som innehåller alla möbler du importerat i möbelkatalogen i Sweet Home 3D.

Bidra med insticksprogram

Du kan posta insticksprogrammen du programmerat i Plug-ins Contributions Tracking System för att dela dem med Sweet Home 3D:s användargrupp.
Många funktioner kan läggas till i Sweet Home 3D tack vare insticksprogram, från importörer till exportörer, men även insticksprogram 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.