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

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 a jelenlegi verzió forrásfájljait (ami jó a felfelé kompatibilitás szempontjából), és anélkül, hogy a program teljes verzióját szállítanák (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 programozz 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, amelyek segítenek a továbbfejlődésben.

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

Bár a Sweet Home 3D széles közönséget céloz meg, a bővítmények fejlesztése speciális készségeket igényel, és tudnod kell Java nyelven programozni egy IDE segítségével, mielőtt továbbmennél. Ez az útmutató bemutatja, hogyan készíthetsz bővítményt az Eclipse-szel, de használhatod a választott IDE-t, vagy 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/ oldalról. A Java fejlesztőknek szánt Eclipse IDE nevű verzió elegendő egy bővítmény fejlesztéséhez, de bármilyen Java fejlesztéshez készült verziót letölthetsz.
A letöltés után 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 következő 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.
Ha ez megtörtént, válaszd a Fájl > Új > Projekt menüpontot egy új projekt létrehozásához, válaszd a Java > Java projekt lehetőséget a megjelenő Új projekt varázslóban, írd be a VolumePlugin nevet projektként, és kattints a Befejezés gombra. Végül zárd be az Üdvözlő lapot, 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 néhány osztályán alapul, amelyeket az Eclipse-nek ismernie kell ahhoz, hogy képes legyen a projektet felépíteni. 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 a https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download címen érhető el. A letöltés után húzd a SweetHome3D-7.5.jar fájlt az Eclipse VolumePlugin projekt ikonra a Csomagkezelő nézetében, majd válaszd a Build Path > Add to Build Path elemet a SweetHome3D-7.5.jar fájl helyi menüjéből, 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ény osztály létrehozása

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

Az Új Java osztály párbeszédpanelen írd be a VolumePlugin nevet osztálynévként, adj meg egy csomagot (itt a com.eteks.test csomagot választottuk), és válaszd a com.eteks.sweethome3d.plugin.Plugin-t a VolumePlugin szuperosztályaként. Ha ez megtörtént, 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 Auto-generated method stub
 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 Szerkesztés > Gyorsjavítás menüpontot az Eclipse menüjéből 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 egy üres execute metódust tartalmaz:

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

Ezt a metódust hívja meg 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 a bútorok térfogatát és jelenítsd meg:

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

Most, hogy meghatároztad, mit szeretnél, hogy a bővítmény tegyen, le kell írnod, hogyan indítja el a felhasználó ezt az új műveletet. Választhatsz, hogy új menüpontot adsz egy menühöz, és/vagy új gombot az eszköztárhoz. Ez a választás a bővítmény művelet megfelelő tulajdonságainak beállításával történik 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érfogat műveletet, 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értelmezés szerint engedélyezi a műveletet
           setEnabled(true);
 }

A VolumePlugin bővítmény osztály most már programozva van, és majdnem készen áll arra, hogy bővítményként működjön a Sweet Home 3D-ben. A két utolsó 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

Az 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 a jogi információkat. Válaszd a Fájl > Új > Fájl menüpontot az Eclipse menüjéből, írd be a fájl nevét ApplicationPlugin.properties, é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:

név=Mozgatható bútor térfogata
osztály=com.eteks.test.VolumePlugin
leírás=Kiszámítja a mozgatható bútorok térfogatát az otthonban
verzió=1.0
licenc=GNU GPL
szolgáltató=(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 VolumePlugin.java fájl fordításából létrehozott osztály fájlokat, és az ApplicationPlugin.properties fájlt. Mivel az Eclipse azonnal lefordítja a Java fájlt, amint elmented, csak a Fájl > Exportálás… menüpontot kell kiválasztanod, és a Java > JAR fájl lehetőséget kell választanod 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 ez a Library/Application Support/eTeks/Sweet Home 3D/plugins almappa a felhasználói mappádban,
• Linux és más Unix rendszerek alatt ez 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, duplán kattintva vagy a következő paranccsal futtathatod:

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, duplán kattintva vagy a következő paranccsal futtathatod:

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

Amíg tesztelsz, valószínűleg inkább ezzel a paranccsal futtatod a Sweet Home 3D-t, hogy a konzolon elolvashasd a bővítmény futása során dobott kivételek veremkövetését.

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

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

A bővítmény hibakeresése

Ha hibakeresést kell végezned 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 Futtatás > Hibakeresési konfigurációk… menüpontot, válaszd a Java alkalmazás elemet a Hibakeresési konfigurációk párbeszédpanelen elérhető konfigurációk listájából, 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 elem alatt a Classpath listában, és 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 a Hozzáadás… gombra, kattints duplán a Java projekt elemre a 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 menüpontot 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.

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

Ha elkészültél, a bővítményedet telepítheted más Sweet Home 3D felhasználók számítógépére egyszerűen a bővítmények mappájába másolva. 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ő duplán kattintva, ha a kiterjesztése SH3P (egyszerűen változtasd meg a fájl kiterjesztését .zip-ről .sh3p-re). Ha a .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

A 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.

Tovább

Az első bővítmény programozása megmutatta a nagy képet. Íme néhány további információ, amelyek segítenek a továbbfejlődésben.

Sweet Home 3D API – Javadoc

Egy új bővítmény fejlesztéséhez a leghasznosabb dokumentáció 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 látni 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 modellré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 modellréteghez tartoznak.

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

A modellréteg központi osztálya a `HomeApplication` osztály (10), a `SweetHome3D` alkalmazás fő osztályának absztrakt ősosztá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:

• a `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 tárolja a kamera helyzetét a `Virtuális látogató` módban. A modellobjektumok á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, 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ényosztályban. Vedd figyelembe azt is, hogy a modell egy létező objektumának bármilyen módosítása értesítésre kerül a megjelenített komponensek felé, akár `PropertyChangeEvent`-ekkel, akár `CollectionEvent`-ekkel (8) vagy `SelectionEvent`-ekkel (6), így minden változás azonnal megjelenik a képernyőn.

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

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

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

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. Minden alkalommal, amikor egy új otthont szerkesztenek, 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 a `PluginAction` egy példánya, amely a `Action` osztályhoz hasonló, a `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 elvégezni az általad végrehajtott változtatásokat.

Honosítás

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 honosítani a megjelenített szövegeket, akár a műveletek nevében és menüjében, akár az általad létrehozott párbeszédpaneleken (vagy legalább készítsd elő a honosításá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 (például azokat, amelyek a `tesztelt bővítmény` által mutatott párbeszédpanelen szerepelnek), használd újra ezeket a .properties fájlokat a `ResourceBundle` Java osztállyal.
Ha inkább korlátozni szeretnéd a tulajdonságfá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 példát szeretnél látni erre az architektúrára, 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 a Sweet Home 3D bútorkatalógusába importáltál.

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

A programozott bővítményeidet beküldheted a `Bővítmények beküldése` nyomkövető rendszerbe, hogy megoszd őket a Sweet Home 3D felhasználói közösségével.
Számos funkció hozzáadható a Sweet Home 3D-hez bővítmények segítségével, az importálóktól az exportálókig, de olyan bővítmények is, amelyek képesek módosítani egy otthon adatait, mint például a Michel Mbem által fejlesztett `Home Rotator Plug-in` és mások, amelyek szerepelnek a 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.