Bővítményfejlesztői útmutató

• Bevezetés
• Fejlesztői eszközök telepítése
• Bővítmény programozása
• Tovább

Bevezetés

Az 1.5-ös verziótól kezdve új funkciókat adhatsz hozzá a Sweet Home 3D-hez a bővítmények mappájába helyezett bővítményfájlokkal. Ez lehetővé teszi a Java programozók számára, hogy új funkciókat fejlesszenek és terjesszenek a Sweet Home 3D-hez anélkül, hogy módosítanák az aktuális verzió forrásfájljait (ami jó a felfelé kompatibilitás szempontjából), és anélkül, hogy a program teljes verzióját kellene szállítaniuk (ami jó a szállítási méret szempontjából).
Ez a dokumentum leírja a bővítmények létrehozásához szükséges eszközöket, majd bemutatja, hogyan kell programozni egy bővítményt, amely kiszámítja az otthonhoz hozzáadott mozgatható bútorok maximális térfogatát, és végül néhány további információt ad, amely segít a továbbfejlődésben.

Fejlesztői eszközök telepítése

Bár a Sweet Home 3D általános közönséget céloz meg, a bővítmények fejlesztése speciális készségeket igényel, és mielőtt továbbmennél, tudnod kell programozni Java nyelven egy IDE segítségével. Ez az útmutató bemutatja, hogyan építhetsz bővítményt az Eclipse segítségével, de használhatod a választott IDE-t, vagy akár egyáltalán nem is használsz IDE-t.

Eclipse letöltése és telepítése

Először töltsd le az Eclipse-t a https://www.eclipse.org/ címről. A Eclipse IDE for Java Developers nevű verzió elegendő egy bővítmény fejlesztéséhez, de bármilyen Java fejlesztéshez készült verziót letölthetsz.
Miután letöltötted, az Eclipse telepítése nagyon egyszerű: csak csomagold ki a kapott archívumot, nyisd meg az eclipse mappát, és a rendszeredtől függően futtasd a nevű fájlt eclipse.exe (Windows alatt), eclipse.app (Mac OS X alatt) vagy eclipse (Linux alatt).
Az első futtatáskor az Eclipse megkér, hogy válassz egy munkaterület mappát, ahol a bővítményprojektek tárolódnak majd.
Ha ez megvan, válaszd a menüből a Fájl > Új > Projekt lehetőséget egy új projekt létrehozásához, válaszd a Java > Java projekt lehetőséget a megjelenő Új projekt varázslóban, add meg a VolumePlugin nevet projektként, és kattints a Befejezés gombra. Végül zárd be az Üdvözlő fület, hogy felfedezd a munkaterületedet az 1. ábrán látható módon.

Sweet Home 3D könyvtár letöltése és telepítése

Egy bővítmény fejlesztése a Sweet Home 3D bizonyos osztályain alapul, amelyeket az Eclipse-nek ismernie kell ahhoz, hogy képes legyen felépíteni a projektedet. A Sweet Home 3D osztályok Eclipse-hez való hozzáadásának legegyszerűbb módja a Sweet Home 3D JAR futtatható verziójának letöltése, amely elérhető a https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download címen. Miután letöltötted, húzd át a SweetHome3D-7.5.jar fájlt az VolumePlugin projekt ikonjára az Eclipse Package Explorer nézetében, és válaszd a Build Path > Add to Build Path elemet a SweetHome3D-7.5.jar fájl helyi menüjében, ahogy a 2. ábrán látható.

Bővítmény programozása

Most, hogy telepítetted a szükséges eszközöket, nézzük meg, hogyan programozhatod az első bővítményedet a Sweet Home 3D-hez.

A bővítményosztály létrehozása

Először hozz létre egy új alosztályt a com.eteks.sweethome3d.plugin.Plugin-ből az Eclipse menüjében a Fájl > Új > Osztály menüpont kiválasztásával.

Az Új Java osztály párbeszédpanelen add meg a VolumePlugin nevet osztálynévként, adj meg egy csomagot (itt a választott csomag a com.eteks.test volt), és válaszd a com.eteks.sweethome3d.plugin.Plugin-t a VolumePlugin szuperosztályaként. Ha ez megvan, kattints a Befejezés gombra. Az Eclipse létrehozza az új osztály fájlját a következő tartalommal:

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 Automatikusan generált metódus csonk
 return null;
 }
}

Ahogy a TODO megjegyzésből sejtheted, most módosítanod kell a getActions metódus implementációját, hogy egy olyan bővítményakciót adjon vissza, amely képes kiszámítani a mozgatható bútorok térfogatát. Cseréld le a return null; sort a következő utasításra:

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

és válaszd az Eclipse menüjéből az Szerkesztés > Gyorsjavítás lehetőséget a hiányzó VolumeAction osztály létrehozásához, ahogy a 4. ábrán látható.

A megjelenő Új Java osztály párbeszédpanelen jelöld be az Befoglaló típus jelölőnégyzetet a VolumePlugin belső osztályának létrehozásához, majd kattints a Befejezés gombra. Ez létrehozza a VolumeAction osztályt, amely a com.eteks.sweethome3d.plugin.PluginAction osztályból öröklődik, és tartalmaz egy üres execute metódust:

  public class VolumeAction extends PluginAction {
 @Override
 public void execute() {
 // TODO Automatikusan generált metódus csonk
 }
 }

Ezt a metódust fogja meghívni a Sweet Home 3D, amikor a felhasználó elindítja a bővítményakciót; tehát itt kell implementálnod, hogyan számítsd ki és jelenítsd meg a bútorok térfogatát:

  public class VolumeAction extends PluginAction {  
  @Override
  public void execute() { 
  float volumeInCm3 = 0;
 // Számolja ki az otthonban lévő minden mozgatható bútordarab
 // határoló dobozának térfogatösszegét
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Az eredmény megjelenítése egy üzenetdobozban (³ a felső indexben lévő 3-at jelöli)
 String message = String. format(
 "Az otthonban lévő mozgatható bútorok maximális térfogata %.2f m³.", 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

Most, hogy meghatároztad, mit szeretnél, hogy a bővítmény csináljon, le kell írnod, hogyan indítja el a felhasználó ezt az új akciót. Választhatsz, hogy új menüpontot adsz egy menühöz, és/vagy új gombot az eszköztárhoz. Ezt a választást a bővítményakció megfelelő tulajdonságainak beállításával teheted meg a létrehozásakor. Például, ha azt szeretnéd, hogy a felhasználók a Térfogat számítása menüponttal indítsák el a térfogatszámító akciót, amely a Eszközök menüben található, akkor a következő konstruktort adod hozzá a VolumnAction osztályhoz:

  public VolumeAction() {
           putPropertyValue(Property.NAME, "Térfogat számítása");
           putPropertyValue(Property.MENU, "Eszközök");
 // Alapértelmezetten engedélyezi az akciót
           setEnabled(true);
 }

A VolumePlugin bővítményosztály most már be van programozva, és majdnem készen áll arra, hogy bővítményként működjön a Sweet Home 3D-ben. Az utolsó két dolog, amit meg kell tenni:

• egy ApplicationPlugin.properties leíró fájl létrehozása,
• a fájlok egy JAR fájlba való összeállítása.
  

A bővítmény leíró fájl létrehozása

Egy ApplicationPlugin.properties fájl leírja a bővítmény nevét, osztályát, a Sweet Home 3D és Java minimális verzióit, amelyek alatt támogatott, valamint jogi információkat. Válaszd az Fájl > Új > Fájl menüpontot az Eclipse menüjéből, add meg a fájlnevet ApplicationPlugin.properties-ként, és kattints a Befejezés gombra, ahogy az 5. ábrán látható.

Ezután írd be a következő leírást az új fájlba, és mentsd el:

name=Mozgatható bútorok térfogata
class=com.eteks.test.VolumePlugin
description=Kiszámítja az otthonban lévő mozgatható bútorok térfogatát
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

A bővítmény JAR létrehozása

A bővítmény JAR tartalmazza a class fájlokat, amelyek a VolumePlugin.java fájl fordításából jöttek létre, valamint az ApplicationPlugin.properties fájlt. Mivel az Eclipse azonnal lefordítja a Java fájlt, amint elmented, neked csak annyit kell tenned, hogy kiválasztod a menüből a Fájl > Exportálás… lehetőséget, és kiválasztod a Java > JAR fájl lehetőséget a megjelenő Exportálás párbeszédpanelen . A 6. ábrán látható Jar Exportálás varázslóban jelöld be a projekt jelölőnégyzetet , és add meg egy JAR fájl elérési útját, amelyet a Sweet Home 3D bővítmények mappájába helyezel. Ez a megfelelő mappa a rendszeredtől függően a következő:

• Windows Vista / 7 / 8 / 10 / 11 alatt ez a mappa: C:\Users\felhasználó\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• Windows XP és korábbi Windows verziók alatt ez a mappa: C:\Documents and Settings\felhasználó\Application Data\eTeks\Sweet Home 3D\plugins,
• macOS alatt a Library/Application Support/eTeks/Sweet Home 3D/plugins almappa a felhasználói mappádban,
• Linux és más Unix rendszerek alatt a .eteks/sweethome3d/plugins almappa a felhasználói mappádban.

A bővítmény tesztelése

Az általad fejlesztett bővítmény futni fog a Sweet Home 3D-ben, akár a Java Web Start verzióval, az telepítők verziójával, vagy a korábban letöltött SweetHome3D-7.5.jar fájllal. Mivel az utóbbi egy futtatható JAR, futtathatod rá duplán kattintva, vagy a következő paranccsal:

Az általad fejlesztett bővítmény futni fog a Sweet Home 3D-ben, akár a Java Web Start verzióval, az telepítők verziójával, vagy a korábban letöltött SweetHome3D-7.5.jar fájllal. Mivel az utóbbi egy futtatható JAR, futtathatod rá duplán kattintva, vagy a következő paranccsal:

java -jar /útvonal/ide/SweetHome3D-7.5.jar

Amíg tesztelsz, valószínűleg inkább ezzel a paranccsal fogod futtatni a Sweet Home 3D-t, hogy a konzolon el tudd olvasni a bővítményed futása során dobott kivételek stack trace-ét.

Miután elindult a Sweet Home 3D, látni fogod az új menüt és annak elemét, ahogy a 7. ábrán látható:

Ha kiválasztod az új menüpontot a otthon példához létrehozott felhasználói útmutatóban, a következő eredményt kapod:

A bővítmény hibakeresése

Ha hibakeresést szeretnél végezni a bővítményeden az Eclipse-ből, hozz létre egy hibakeresési konfigurációt a következő lépésekkel:

• Válaszd a menüből a Futtatás > Hibakeresési konfigurációk… lehetőséget, válaszd a Java alkalmazás elemet a Hibakeresési konfigurációk párbeszédpanel elérhető konfigurációinak listájában, kattints a Új gombra a bal felső sarokban, és adj meg egy nevet a konfigurációnak.
• Kattints a Keresés… gombra a Fő osztály szövegmező jobb oldalán, és kattints duplán a SweetHome3DBootstrap osztályra
  a javasolt osztályok közül.

• Kattints a Classpath fülre, válaszd ki a VolumePlugin (alapértelmezett classpath) alpontot a Felhasználói bejegyzések elemből a Classpath listában, majd kattints az Eltávolítás gombra.
• Kattints a Felhasználói bejegyzések elemre a Classpath listában, kattints az JAR-ok hozzáadása… gombra, válaszd ki a SweetHome3D-7.5.jar elemet, és erősítsd meg a választásodat.

• Válaszd ki a Forrás fület, kattints az Hozzáadás… gombra, kattints duplán a Java projekt elemre az Forrás hozzáadása párbeszédpanelen, válaszd ki a VolumePlugin elemet a Projekt kiválasztása felugró ablakban, és erősítsd meg a választásodat.

• Végül kattints a Hibakeresés gombra a Sweet Home 3D hibakeresési módban történő elindításához. Miután a program fut, nyisd meg a VolumePlugin.java fájlt, állíts be egy töréspontot az execute metódusban, és válaszd az Eszközök Térfogat számítása lehetőséget a Sweet Home 3D menüjéből. Az Eclipse megáll a kiválasztott törésponton, hogy lépésről lépésre végrehajthasd a programot és ellenőrizhesd a változók értékét.

Minden alkalommal, amikor módosítod a bővítményed forráskódját, ne felejtsd el generálni a bővítmény JAR-t, mielőtt elindítanád a létrehozott hibakeresési konfigurációt. Az Eclipse-ben a JAR exportálási folyamat felgyorsításához lépj a JAR exportálási varázsló második lépésére, és válaszd az A JAR leírásának mentése a munkaterületre opciót. Ez egy új elemet ad hozzá a projekthez egy helyi menüvel, amelyben szerepel a JAR létrehozása menüpont.

A bővítmény telepítése

Ha elkészült, a bővítményed telepíthető más Sweet Home 3D felhasználók számítógépére egyszerűen úgy, hogy bemásolod a bővítmények mappájukba. Az 1.6-os verziótól kezdve egy bővítményfájl a Sweet Home 3D bővítmények mappájába is telepíthető rá duplán kattintva, ha a kiterjesztése SH3P (egyszerűen változtasd meg a fájlkiterjesztést .zip-ről .sh3p-re). Ha egy .sh3p fájlra duplán kattintva nem indul el a Sweet Home 3D (leginkább Linux alatt), akkor a bővítményt a következő paranccsal is telepítheted egy Terminál ablakban (ahol SweetHome3D a Sweet Home 3D telepítőkkel együtt szállított futtatható fájl neve):

/útvonal/ide/SweetHome3D /útvonal/ide/plugin.sh3p

Egy bővítmény használatának leállításához távolítsd el a fájlját a bővítmények mappájából, és indítsd újra a Sweet Home 3D-t.

Ha azt szeretnéd, hogy a bővítményed futni tudjon az összes, ezen a weboldalon elérhető Sweet Home 3D telepítővel, ügyelj arra, hogy kompatibilis maradjon a Java 5-tel, a 1.5 kiválasztásával az Fordító kompatibilitási szintje mezőben, amely az Eclipse Projekt > Tulajdonságok menüpontja által megjelenített párbeszédpanel Java fordító szakaszában található.
Ha olyan Java fordító verziót használsz, ahol a Java 1.5 kompatibilitás már nem elérhető, próbálj meg legalább Java 1.8-at célozni, amelyet még mindig használnak a Sweet Home 3D legújabb verzióiban, és állítsd be javaMinimumVersion a bővítményed ApplicationPlugin.properties fájljában ennek megfelelően.

Tovább

Az első bővítmény programozása átfogó képet adott. Íme néhány további információ, ami segít a továbbfejlődésben.

Sweet Home 3D API – javadoc

A leghasznosabb dokumentáció egy új bővítmény fejlesztéséhez a javadoc eszközzel generált Sweet Home 3D API (alkalmazásprogramozási felület).
Csak a com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools és com.eteks.sweethome3d.viewcontroller csomagok osztályait használd a bővítményedben, ha azt szeretnéd, hogy kompatibilis legyen a Sweet Home 3D jövőbeli verzióival. Ez nagyrészt elegendő lesz bármilyen olyan bővítmény programozásához, amely a Sweet Home 3D-ben elérhető otthoni adatokkal dolgozik.
A program többi rétegének megfelelő csomagok csak tájékoztató jelleggel szerepelnek a Javadocban. Ne támaszkodj az API-jukra, mivel az a jövőben még változhat felfelé kompatibilitási garancia nélkül (egyébként sem fogsz hivatkozást találni a com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io vagy com.eteks.sweethome3d csomagok osztályaira az említett csomagokban).

Modell osztályok architektúrája

A Sweet Home 3D MVC (Model View Controller) architektúrán alapul, ezért elengedhetetlen megérteni, hogyan épül fel a modell rétege. A 13. ábra (elérhető PDF formátumban is) bemutatja a com.eteks.sweethome3d.model csomag 1.5-ös verziójában elérhető szinte összes osztályt és interfészt, amelyek ehhez a modell réteghez tartoznak.

A modell réteg központi osztálya a HomeApplication osztály (10), a SweetHome3D alkalmazás fő osztályának absztrakt szuperosztálya. Ennek az osztálynak a példánya hozzáférést biztosít az éppen szerkesztett Home példányokhoz (7), valamint a UserPreferences objektumhoz (11), amely tárolja a használt hosszmértékegységet (12), a bútor katalógust (14) és a textúra katalógust (15), amelyekből a felhasználó bútorokat (17) és textúrákat (18) választhat.
Egy Home példány (7) tárolja az összes objektumot, amelyet a felhasználó az otthoni tervben létrehozott:

• az HomePieceOfFurniture objektumok (13) listája, amelyek implementálják a PieceOfFurniture interfészt (16),
• a Wall objektumok (9) gyűjteménye,
• a Room objektumok (5) listája,
• a DimensionLine objektumok (2) gyűjteménye,
• a Label objektumok (3) gyűjteménye.

Ezek az objektumok implementálják a Selectable interfészt (1), valamint az ObserverCamera objektumot (4), amely a kamera helyzetét tárolja a Virtuális látogató módban. A modell objektumok által kezelt összes külső információ, mint például egy bútor (16) ikonja és 3D modellje, vagy egy textúra (20) képe, a Content interfészen (19) keresztül érhető el, amelyet az URLContent osztály és a com.eteks.sweethome3d.tools csomag más osztályai implementálnak.

Ez az UML diagram segíthet megérteni, mely osztályok érhetők el a Sweet Home 3D modellben, és hogyan férhetsz hozzájuk, de valószínűleg észreveszed majd, hogy nincsenek benne konstruktorok és mutátorok (vagy setterek, ha úgy tetszik) említve. Ez csak helyhiány miatt van, de gond nélkül használhatod őket egy bővítmény osztályban. Vedd figyelembe azt is, hogy a modell egy meglévő objektumának bármilyen módosítása értesítésre kerül a megjelenített komponensek felé, akár PropertyChangeEvent-ekkel, CollectionEvent-ekkel (8) vagy SelectionEvent-ekkel (6), így minden változás azonnal megjelenik a képernyőn.

A Sweet Home 3D modell teljesítménybeli okokból nem szálbiztos. A modellhez tartozó objektumok minden módosítását az Event Dispatch Thread-ben kell elvégezni.

Bővítmény osztályok architektúrája

A bővítmény osztályok architektúrája sokkal egyszerűbben érthető, mint a modell rétegé. A com.eteks.sweethome3d.plugin csomag mindössze három osztályt tartalmaz, amelyek közül csak a Plugin és PluginAction osztályokat kellene használnod, ahogy a 14. ábra is mutatja (elérhető PDF formátumban is).

Az alkalmazás indításakor létrejön egy PluginManager példány (1), amely megkeresi a felhasználó bővítmények mappájában telepített bővítményeket. Valahányszor új otthont szerkesztesz, ez a kezelő példányosít és konfigurál egy Plugin objektumot (3) minden indításkor talált bővítményhez. Ezután meghívja a getActions metódust, hogy lekérje az összes műveletet (4), amelyek menüpontként és/vagy eszköztár gombként kerülnek hozzáadásra az otthoni ablakban. Minden művelet egy PluginAction példány, amely az Action osztályhoz hasonlóan rendelkezik az execute metódusával és módosítható tulajdonságaival (2).

Vedd figyelembe, hogy a Plugin osztály hozzáférést biztosít egy UndoableEditSupport példányhoz a getUndoableEditSupport metódusán keresztül. Amint módosítasz egy otthont vagy annak objektumait (bútorok, falak…) egy PluginAction példány execute metódusában, egy UndoableEdit objektumot is el kell küldened a getUndoableEditSupport metódus által visszaadott visszavonható szerkesztési támogatásnak, különben a felhasználók nem tudják majd helyesen visszavonni/újra megtenni az általad végrehajtott változtatásokat.

Lokalizáció

Ha bővítményt szeretnél fejleszteni a Sweet Home 3D felhasználói közösség számára, próbáld meg lokalizálni a megjelenített szövegeket, akár a műveletek nevében és menüjében, akár az általad létrehozott párbeszédpanelekben (vagy legalább készítsd elő a lokalizációját). A PluginAction osztály két konstruktora segít majd a műveletek tulajdonságainak fordítását .properties fájlokkal megszervezni, és ha más szövegeket is le kell fordítanod a bővítményedben (mint például a tesztelt bővítmény által mutatott párbeszédpanelben), használd újra ezeket a .properties fájlokat a ResourceBundle Java osztállyal.
Ha inkább korlátoznád a .properties fájlok számát, akár az akciótulajdonságok és egyéb szövegek értékeit is beírhatod a bővítményed ApplicationPlugin.properties leíró fájljába.

Ha szeretnél egy példát, amely ezt az architektúrát használja, töltsd le az Export to SH3F bővítményt, amely elérhető a https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p címen, és csomagold ki (ez a bővítményfájl tartalmazza a bővítmény forráskódját is).
Ahogy a Súgó fórumban is le van írva, ez a bővítmény létrehoz egy SH3F fájlt, amely tartalmazza az összes bútort, amit importáltál a Sweet Home 3D bútorkatalógusába.

Bővítmények beküldése

A programozott bővítményeidet közzéteheted a Bővítmények beküldése nyomkövető rendszerben, hogy megoszd őket a Sweet Home 3D felhasználói közösségével.
Számos funkcióval bővíthető a Sweet Home 3D a bővítményeknek köszönhetően, az importálóktól az exportálókig, de olyan bővítményekkel is, amelyek képesek módosítani egy otthon adatait, mint például a Michel Mbem és mások által fejlesztett Home Rotator Plug-in, amelyek Hans Dirkse által írt Bővítmények és kiterjesztések oktatóanyagában (PDF) és a Bővítmények és eszközök oldalon vannak felsorolva.