Vodnik za razvijalce vtičnikov

Uvod

Od različice 1.5 naprej je mogoče dodati nove funkcije v Sweet Home 3D z datotekami vtičnikov, ki so shranjene v tvoji mapi z vtičniki. To omogoča programerjem Jave, da razvijajo in distribuirajo nove funkcije za Sweet Home 3D, ne da bi spreminjali izvorne datoteke trenutne različice (kar je dobro za združljivost navzgor) in ne da bi dostavili celotno različico programa (kar je dobro za velikost dostave).
Ta dokument opisuje orodja, potrebna za ustvarjanje vtičnikov, nato pokaže, kako programirati vtičnik, ki izračuna največjo prostornino premičnega pohištva, dodanega v dom, in končno ponuja nekaj dodatnih informacij, ki ti bodo pomagale pri nadaljnjem delu.

Namestitev razvojnih orodij

Če je Sweet Home 3D namenjen splošni javnosti, razvoj vtičnikov zahteva posebne veščine in moraš znati programirati v Javi z IDE, preden nadaljuješ. Ta vodnik prikazuje, kako zgraditi vtičnik z Eclipse, lahko pa uporabiš IDE po svoji izbiri ali pa sploh nobenega IDE-ja.

Prenesi in namesti Eclipse

Najprej prenesi Eclipse z https://www.eclipse.org/. Različica z imenom Eclipse IDE for Java Developers je dovolj za razvoj vtičnika, lahko pa preneseš katero koli različico za razvoj v Javi.
Ko je prenesen, je namestitev Eclipse zelo preprosta: samo razpakiraj arhiv, ki ga boš dobil, odpri mapo eclipse in odvisno od tvojega sistema, zaženi datoteko z imenom eclipse.exe (v sistemu Windows), eclipse.app (v sistemu Mac OS X) ali eclipse (v sistemu Linux).
Ob prvem zagonu bo Eclipse zahteval, da izbereš mapo delovnega prostora, kjer bodo shranjeni projekti vtičnikov.
Ko je to storjeno, izberi Datoteka > Novo > Projekt iz menija, da ustvariš nov projekt, izberi Java > Java projekt v čarovniku Nov projekt, ki se bo prikazal, vnesi VolumePlugin kot ime projekta in klikni na gumb Dokončaj. Na koncu zapri zavihek Dobrodošli, da odkriješ svoj delovni prostor, kot je prikazano na sliki 1.

Prenesi in namesti knjižnico Sweet Home 3D

Razvoj vtičnika temelji na nekaterih razredih Sweet Home 3D, ki jih mora Eclipse poznati, da lahko zgradi tvoj projekt. Najlažji način za dodajanje razredov Sweet Home 3D v Eclipse je, da preneseš izvedljivo različico JAR Sweet Home 3D, ki je na voljo na https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. Ko je prenesen, povleci in spusti datoteko SweetHome3D-7.5.jar na ikono projekta VolumePlugin v pogledu Package Explorer v Eclipse in izberi element Build Path > Add to Build Path v kontekstnem meniju datoteke SweetHome3D-7.5.jar, kot je prikazano na sliki 2.

Programiranje vtičnika

Zdaj, ko si namestil potrebna orodja, poglejmo, kako lahko programiraš svoj prvi vtičnik za Sweet Home 3D.

Ustvarjanje razreda vtičnika

Najprej ustvari nov podrazred com.eteks.sweethome3d.plugin.Plugin tako, da izbereš element menija Datoteka > Novo > Razred v Eclipse.

V pogovornem oknu Nov razred Java vnesi VolumePlugin kot ime razreda, vnesi paket (tukaj je bil izbran paket com.eteks.test) in izberi com.eteks.sweethome3d.plugin.Plugin kot nadrazred VolumePlugin. Ko je to storjeno, klikni na Dokončaj. Eclipse bo ustvaril datoteko novega razreda z naslednjo vsebino:

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 Samodejno generirana metoda
 return null;
 }
}

Kot lahko uganeš iz komentarja TODO, moraš zdaj spremeniti implementacijo metode getActions, da vrne dejanje vtičnika, ki lahko izračuna prostornino premičnega pohištva. Zamenjaj return null; z naslednjo izjavo:

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

in izberi Urejanje > Hitri popravek iz menija Eclipse, da ustvariš manjkajoči razred VolumeAction, kot je prikazano na sliki 4.

V pogovornem oknu Nov razred Java, ki se prikaže, izberi potrditveno polje Vključujoči tip, da ustvariš notranji razred VolumePlugin, in klikni na Dokončaj. To bo ustvarilo razred VolumeAction, ki podeduje od razreda com.eteks.sweethome3d.plugin.PluginAction in vsebuje prazno metodo execute:

  public class VolumeAction extends PluginAction {
 @Override
 public void execute() {
 // TODO Samodejno generirana metoda
 }
 }

To metodo bo Sweet Home 3D poklical, ko bo uporabnik zagnal dejanje vtičnika; zato je to mesto, kjer moraš implementirati, kako izračunati prostornino pohištva in jo prikazati:

  public class VolumeAction extends PluginAction {  
  @Override
  public void execute() { 
  float volumeInCm3 = 0;
 // Izračunaj vsoto prostornine omejevalnega polja 
 // vsakega premičnega kosa pohištva v domu
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Prikaži rezultat v sporočilnem oknu (³ je za 3 v nadpisu)
 String message = String. format(
 „Največja prostornina premičnega pohištva v domu je %.2f m³.“, 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

Zdaj, ko si določil, kaj želiš, da vtičnik naredi, moraš opisati, kako bo uporabnik zagnal to novo dejanje. Izbiraš lahko med dodajanjem novega elementa menija v meni in/ali novega gumba v orodno vrstico. Ta izbira se izvede z nastavitvijo ustreznih lastnosti dejanja vtičnika ob njegovi ustvaritvi. Na primer, če želiš, da uporabniki zaženejo dejanje prostornine z elementom menija Izračunaj prostornino, ki se nahaja v meniju Orodja, boš dodal naslednji konstruktor razredu VolumnAction:

  public VolumeAction() {
           putPropertyValue(Property.NAME, „Izračunaj prostornino“);
           putPropertyValue(Property.MENU, „Orodja“);
 // Privzeto omogoči dejanje
           setEnabled(true);
 }

Razred vtičnika VolumePlugin je zdaj programiran in skoraj pripravljen za delovanje kot vtičnik v Sweet Home 3D. Zadnji dve stvari, ki ju je treba narediti, sta:

• ustvarjanje opisne datoteke ApplicationPlugin.properties,
• združevanje datotek v datoteko JAR.
  

Ustvarjanje opisne datoteke vtičnika

Datoteka ApplicationPlugin.properties opisuje ime vtičnika, njegov razred, minimalne različice Sweet Home 3D in Jave, pod katerimi je podprt, in pravne zadeve. Izberi Datoteka > Novo > Datoteka iz menija Eclipse, vnesi ime datoteke ApplicationPlugin.properties in klikni na Dokončaj, kot je prikazano na sliki 5.

Nato v novo datoteko vnesi naslednji opis in jo shrani:

name=Prostornina premičnega pohištva
class=com.eteks.test.VolumePlugin
description=Izračuna prostornino premičnega pohištva v domu
version=1.0
license=GNU GPL
provider=(C) Avtorske pravice 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Ustvarjanje datoteke JAR vtičnika

Datoteka JAR vtičnika vsebuje datoteke razreda, ustvarjene s prevajanjem datoteke VolumePlugin.java, in datoteko ApplicationPlugin.properties. Ker Eclipse prevede datoteko Java takoj, ko jo shraniš, moraš samo izbrati Datoteka > Izvozi… iz menija in izbrati Java > datoteka JAR v pogovornem oknu Izvozi, ki se bo prikazalo. V čarovniku Izvoz JAR, ki se prikaže, kot je prikazano na sliki 6, izberi potrditveno polje projekta in vnesi pot do datoteke JAR, shranjene v mapi z vtičniki Sweet Home 3D. Ta ustrezna mapa je odvisna od tvojega sistema, kot sledi:

• v sistemu Windows Vista / 7 / 8 / 10 / 11, je ta mapa C:\Users\uporabnik\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• v sistemu Windows XP in prejšnjih različicah sistema Windows, je ta mapa C:\Documents and Settings\uporabnik\Application Data\eTeks\Sweet Home 3D\plugins,
• v sistemu macOS, je to podmapa Library/Application Support/eTeks/Sweet Home 3D/plugins tvoje uporabniške mape,
• v sistemu Linux in drugih sistemih Unix, je to podmapa .eteks/sweethome3d/plugins tvoje uporabniške mape.

Testiranje vtičnika

Vtičnik, ki si ga razvil, bo deloval v Sweet Home 3D, bodisi z različico Java Web Start, različico namestitvenih programov ali z datoteko SweetHome3D-7.5.jar, ki si jo prenesel prej. Ker je zadnja izvedljiva datoteka JAR, jo lahko zaženeš z dvojnim klikom nanjo ali z naslednjim ukazom:

Vtičnik, ki si ga razvil, bo deloval v Sweet Home 3D, bodisi z različico Java Web Start, različico namestitvenih programov ali z datoteko SweetHome3D-7.5.jar, ki si jo prenesel prej. Ker je zadnja izvedljiva datoteka JAR, jo lahko zaženeš z dvojnim klikom nanjo ali z naslednjim ukazom:

java -jar /path/to/SweetHome3D-7.5.jar

Dokler testiraš, boš verjetno raje zagnal Sweet Home 3D s tem ukazom, da boš lahko v konzoli prebral sled izjem, ki so se pojavile med izvajanjem tvojega vtičnika.

Ko je Sweet Home 3D zagnan, boš videl, da se prikaže nov meni in njegov element, kot je prikazano na sliki 7:

Če izbereš nov element menija za primer doma, ustvarjen v uporabniškem priročniku, boš dobil naslednji rezultat:

Odpravljanje napak v vtičniku

Če moraš odpraviti napake v svojem vtičniku iz Eclipse, ustvari konfiguracijo za odpravljanje napak tako, da slediš tem korakom:

• Izberi Zagon > Konfiguracije za odpravljanje napak… iz menija, izberi element Java Application na seznamu razpoložljivih konfiguracij v pogovornem oknu Konfiguracije za odpravljanje napak, klikni na gumb Novo zgoraj levo in vnesi ime za konfiguracijo.
• Klikni na gumb Išči… desno od besedilnega polja Glavni razred in dvoklikni na razred SweetHome3DBootstrap
  med predlaganimi razredi.

• Klikni na zavihek Classpath, izberi podpostavko VolumePlugin (privzeti classpath) elementa Uporabniški vnosi na seznamu Classpath in klikni na gumb Odstrani.
• Klikni na element Uporabniški vnosi na seznamu Classpath, klikni na gumb Dodaj JAR-e…, izberi element SweetHome3D-7.5.jar in potrdi svojo izbiro.

• Izberi zavihek Vir, klikni na gumb Dodaj…, dvoklikni na element Java Project v pogovornem oknu Dodaj vir, izberi element VolumePlugin v pojavnem oknu Izbira projekta in potrdi svojo izbiro.

• Na koncu klikni na gumb Odpravljanje napak, da zaženeš Sweet Home 3D v načinu za odpravljanje napak. Ko se program izvaja, odpri datoteko VolumePlugin.java, nastavi prelomno točko v metodi execute in izberi Orodja > Izračunaj prostornino iz menija Sweet Home 3D. Eclipse se bo ustavil na izbrani prelomni točki, da ti omogoči izvajanje programa korak za korakom in pregledovanje vrednosti spremenljivk.

Uvedba vtičnika

Ko je pripravljen, lahko tvoj vtičnik namestiš na računalnike drugih uporabnikov Sweet Home 3D tako, da ga preprosto kopiraš v njihovo mapo z vtičniki. Od različice 1.6 naprej se datoteka vtičnika lahko namesti tudi v mapo z vtičniki Sweet Home 3D z dvojnim klikom nanjo, če je njena razširitev SH3P (preprosto spremeni razširitev datoteke iz .zip v .sh3p). Če dvojni klik na datoteko .sh3p ne zažene Sweet Home 3D (najverjetneje v sistemu Linux), lahko vtičnik namestiš tudi z naslednjim ukazom v oknu Terminala (kjer SweetHome3D je ime izvedljive datoteke, ki je priložena namestitvenim programom Sweet Home 3D):

/path/to/SweetHome3D /path/to/plugin.sh3p

Če želiš prenehati uporabljati vtičnik, odstrani njegovo datoteko iz mape z vtičniki in ponovno zaženi Sweet Home 3D.

Nadaljevanje

Programiranje prvega vtičnika ti je pokazalo širšo sliko. Tukaj je nekaj dodatnih informacij, ki ti bodo pomagale pri nadaljnjem delu.

Sweet Home 3D API – Javadoc

Najbolj uporabna dokumentacija za razvoj novega vtičnika je API Sweet Home 3D (Application Programming Interface), ustvarjen z orodjem javadoc.
V svojem vtičniku uporabljaj samo razrede paketov com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools in com.eteks.sweethome3d.viewcontroller, če želiš, da bo združljiv z bodočimi različicami Sweet Home 3D. To bo v veliki meri dovolj za programiranje katerega koli vtičnika, ki deluje na podatkih o domu, ki so na voljo v Sweet Home 3D.
Paketi, ki ustrezajo drugim plastem programa, so vključeni v Javadoc samo za informativne namene. Ne zanašaj se na njihov API, saj se lahko v prihodnosti še spremeni brez garancije za združljivost navzgor (kakorkoli, v prej omenjenih paketih ne boš videl reference na razred paketov com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io ali com.eteks.sweethome3d).

Arhitektura razredov modela

Sweet Home 3D temelji na arhitekturi MVC (Model View Controller), zato je razumevanje organizacije njegove plasti modela bistveno. Slika 13 (na voljo tudi v formatu PDF) prikazuje skoraj vse razrede in vmesnike, ki so na voljo v različici 1.5 paketa com.eteks.sweethome3d.model, ki ustreza tej plasti modela.

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

Osrednji razred v plasti modela je razred HomeApplication (10), abstraktni nadrazred glavnega razreda aplikacije SweetHome3D. Instanca tega razreda omogoča dostop do trenutno urejenih instanc Home (7) in do objekta UserPreferences (11), ki shranjuje uporabljeno mersko enoto (12), katalog pohištva (14) in katalog tekstur (15), iz katerih uporabnik izbira kose pohištva (17) in teksture (18).
Instanca Home (7) shranjuje vse objekte, ki jih je uporabnik ustvaril v načrtu doma:

• seznam objektov HomePieceOfFurniture (13), ki implementirajo vmesnik PieceOfFurniture (16),
• zbirka objektov Wall (9),
• seznam objektov Room (5),
• zbirka objektov DimensionLine (2),
• zbirka objektov Label (3).

Ti objekti implementirajo vmesnik Selectable (1) ter objekt ObserverCamera (4), ki shranjuje lokacijo kamere v načinu Virtualni obiskovalec. Vse zunanje informacije, ki jih upravljajo objekti modela, kot so ikona in 3D model kosa pohištva (16) ali slika teksture (20), so dostopne preko vmesnika Content (19), ki ga implementirajo razred URLContent in drugi razredi paketa com.eteks.sweethome3d.tools.

Ta UML diagram ti naj pomaga razumeti, kateri razredi so na voljo v modelu Sweet Home 3D in kako lahko do njih dostopaš, vendar boš verjetno opazil, da v njem niso navedeni nobeni konstruktorji in mutatorji (ali setterji, če ti je ljubše). To je zgolj zaradi pomanjkanja prostora, vendar jih lahko brez težav uporabljaš v razredu vtičnika. Upoštevaj tudi, da bo vsaka sprememba obstoječega objekta modela sporočena prikazanim komponentam bodisi z PropertyChangeEventi, z CollectionEventi (8) ali z SelectionEventi (6), kar omogoča, da se vse spremembe takoj odrazijo na zaslonu.

Arhitektura razredov vtičnikov

Arhitektura razredov vtičnikov je veliko enostavnejša za razumevanje kot arhitektura plasti modela. Paket com.eteks.sweethome3d.plugin vsebuje samo tri razrede, med katerimi naj bi uporabljal le razreda Plugin in PluginAction, kot je prikazano na sliki 14 (na voljo tudi v formatu PDF).

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

Instanca PluginManager (1) se ustvari ob zagonu aplikacije in poišče vtičnike, nameščene v uporabnikovi mapi vtičnikov. Vsakič, ko se ureja nov dom, ta upravitelj instancira in konfigurira objekt Plugin (3) za vsak vtičnik, najden ob zagonu. Nato pokliče metodo getActions za pridobitev vseh dejanj (4), ki bodo dodana kot menijski elementi in/ali gumbi orodne vrstice v oknu doma. Vsako dejanje je instanca PluginAction, ki je podobna razredu Action, s svojo metodo execute in svojimi spremenljivimi lastnostmi (2).

Upoštevaj, da ti razred Plugin omogoča dostop do instance UndoableEditSupport preko svoje metode getUndoableEditSupport. Takoj ko spremeniš dom ali njegove objekte (pohištvo, stene …) v metodi execute instance PluginAction, moraš tudi objaviti objekt UndoableEdit podpori za razveljavitev urejanja, ki jo vrne metoda getUndoableEditSupport, sicer uporabniki ne bodo mogli pravilno razveljaviti/ponoviti sprememb, ki si jih naredil.

Lokalizacija

Če nameravaš razviti vtičnik za skupnost uporabnikov Sweet Home 3D, poskusi lokalizirati nize, ki jih prikazuje, bodisi v imenu dejanj in meniju ali v pogovornih oknih, ki jih boš ustvaril (ali vsaj pripravi njegovo lokalizacijo). Dva konstruktorja razreda PluginAction ti bosta pomagala organizirati prevajanje lastnosti dejanj z datotekami .properties, in če moraš prevesti druge nize v svojem vtičniku (kot je tisti v pogovornem oknu, ki ga prikazuje testirani vtičnik), ponovno uporabi te datoteke .properties z razredom Java ResourceBundle.
Če raje omejiš število datotek z lastnostmi, lahko celo zapišeš vrednosti lastnosti dejanj in drugih nizov v opisno datoteko ApplicationPlugin.properties svojega vtičnika.

Če želiš primer, ki uporablja to arhitekturo, prenesi vtičnik Export to SH3F, ki je na voljo na https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p, in ga razpakiraj (ta datoteka vtičnika vsebuje tudi izvorno kodo vtičnika).
Kot je opisano v forumu za pomoč, ta vtičnik ustvari datoteko SH3F, ki vsebuje vse pohištvo, ki si ga uvozil v katalog pohištva Sweet Home 3D.

Prispevanje vtičnikov

Vtičnike, ki si jih programiral, lahko objaviš v sistemu za sledenje Plug-ins Contributions, da jih deliš s skupnostjo uporabnikov Sweet Home 3D.
V Sweet Home 3D je mogoče dodati številne funkcije zahvaljujoč vtičnikom, od uvoznikov do izvoznikov, pa tudi vtičnike, ki lahko spreminjajo podatke o domu, kot je vtičnik Home Rotator, ki ga je razvil Michel Mbem, in drugi, navedeni v vadnici za vtičnike in razširitve (PDF), ki jo je napisal Hans Dirkse, in na strani Vtičniki in orodja.