Vodnik za razvijalce vtičnikov

• Uvod
• Namestitev razvojnih orodij
• Programiranje vtičnika
• Nadaljnje raziskovanje

Uvod

Od različice 1.5 je mogoče dodajati nove funkcije v Sweet Home 3D z vtičniki, ki jih namestite v svojo mapo za vtičnike. To omogoča Java programerjem razvoj in distribucijo novih funkcij za Sweet Home 3D brez spreminjanja izvornih datotek trenutne različice (kar je dobro za združljivost navzgor) in brez dostave celotne različice 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 na koncu poda nekaj dodatnih informacij, ki ti bodo pomagale pri nadaljnjem delu.

Namestitev razvojnih orodij

Čeprav je Sweet Home 3D namenjen splošni publiki, 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, vendar lahko uporabiš IDE po lastni izbiri ali pa sploh nobenega.

Prenesi in namesti Eclipse

Najprej prenesi Eclipse s https://www.eclipse.org/. Različica z imenom Eclipse IDE for Java Developers je dovolj za razvoj vtičnika, lahko pa preneseš katerokoli različico za razvoj v Javi.
Ko preneseš, je namestitev Eclipse zelo preprosta: samo razširi arhiv, ki ga dobiš, odpri mapo eclipse in glede na svoj sistem zaženi datoteko z imenom eclipse.exe (v Windows), eclipse.app (v Mac OS X) ali eclipse (v Linux).
Ob prvem zagonu bo Eclipse zahteval, da izbereš mapo workspace, kjer bodo shranjeni projekti vtičnikov.
Ko je to opravljeno, izberi File > New > Project iz menija za ustvarjanje novega projekta, izberi Java > Java project v čarovniku New project, ki se bo prikazal, vnesi VolumePlugin kot ime projekta in klikni gumb Finish. Na koncu zapri zavihek Welcome, 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 prenos JAR izvedljive različice Sweet Home 3D, ki je na voljo na https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. Ko jo preneseš, 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 File > New > Class v Eclipse.

V pogovornem oknu New Java Class vnesi VolumePlugin kot ime razreda, vnesi paket (tukaj je bil izbran paket com.eteks.test) in izberi com.eteks.sweethome3d.plugin.Plugin kot nadrazred za VolumePlugin. Ko končaš, klikni Finish. 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 Auto-generated method stub
 return null;
 }
}

Kot lahko sklepaš 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 Edition > Quick Fix iz menija Eclipse za ustvarjanje manjkajočega razreda VolumeAction, kot je prikazano na sliki 4.

V pogovornem oknu New Java Class, ki se pojavi, označi potrditveno polje Enclosing type za ustvarjanje notranjega razreda VolumePlugin in klikni Finish. To bo ustvarilo razred VolumeAction, ki deduje od razreda com.eteks.sweethome3d.plugin.PluginAction in vsebuje prazno metodo execute:

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

Ta metoda je tista, ki jo bo Sweet Home 3D poklical, ko bo uporabnik zagnal dejanje vtičnika; torej 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 mejnega kvadra 
 // 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. Imaš možnost dodati nov element menija v meni in/ali nov gumb v orodno vrstico. To izbiro narediš z nastavljanjem ustreznih lastnosti dejanja vtičnika ob njegovem ustvarjanju. Na primer, če želiš, da uporabniki zaženejo dejanje za prostornino z elementom menija Izračunaj prostornino v meniju Orodja, boš dodal naslednji konstruktor razredu VolumeAction:

  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 moraš 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 File > New > File iz menija Eclipse, vnesi ime datoteke ApplicationPlugin.properties in klikni Finish, kot je prikazano na sliki 5.

Nato vnesi naslednji opis v novo datoteko 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 JAR vtičnika

JAR vtičnika vsebuje datoteke class, ustvarjene s prevajanjem datoteke VolumePlugin.java, in datoteko ApplicationPlugin.properties. Ker Eclipse prevede datoteko Java takoj, ko jo shraniš, samo izberi File > Export… iz menija in izberi Java > JAR file v pogovornem oknu Export, ki se bo prikazalo. V čarovniku Jar Export, ki se pojavi, kot je prikazano na sliki 6, izberi potrditveno polje projekta in vnesi pot do datoteke JAR, ki je nameščena v mapi vtičnikov Sweet Home 3D. Ta ustrezna mapa je odvisna od tvojega sistema, kot sledi:

• v Windows Vista / 7 / 8 / 10 / 11 je ta mapa C:\Users\user\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• v Windows XP in prejšnjih različicah Windows je ta mapa C:\Documents and Settings\user\Application Data\eTeks\Sweet Home 3D\plugins,
• v macOS je to podmapa Library/Application Support/eTeks/Sweet Home 3D/plugins tvoje uporabniške mape,
• v Linux in drugih Unix sistemih 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 namestitvenega programa ali SweetHome3D-7.5.jar, ki si jo prej prenesel. Ker je slednja izvedljiva datoteka JAR, jo lahko zaženeš z dvoklikom 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 namestitvenega programa ali SweetHome3D-7.5.jar, ki si jo prej prenesel. Ker je slednja izvedljiva datoteka JAR, jo lahko zaženeš z dvoklikom nanjo ali z naslednjim ukazom:

java -jar /pot/do/SweetHome3D-7.5.jar

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

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

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

Razhroščevanje vtičnika

Če moraš razhroščevati svoj vtičnik iz Eclipse, ustvari konfiguracijo za razhroščevanje z naslednjimi koraki:

• Izberi Run > Debug Configurations… iz menija, izberi element Java Application na seznamu razpoložljivih konfiguracij v pogovornem oknu Debug configurations, klikni gumb New zgoraj levo in vnesi ime za konfiguracijo.
• Klikni gumb Search… na desni strani polja Main class in dvoklikni razred SweetHome3DBootstrap
  med predlaganimi razredi.

• Klikni zavihek Classpath, izberi podelement VolumePlugin (default classpath) elementa User Entries na seznamu Classpath in klikni gumb Remove.
• Klikni element User Entries na seznamu Classpath, klikni gumb Add JARs…, izberi element SweetHome3D-7.5.jar in potrdi svojo izbiro.

• Izberi zavihek Source, klikni gumb Add…, dvoklikni element Java Project v pogovornem oknu Add Source, izberi element VolumePlugin v pojavnem oknu Project Selection in potrdi svojo izbiro.

• Na koncu klikni gumb Debug za zagon Sweet Home 3D v načinu za razhroščevanje. Ko program teče, odpri datoteko VolumePlugin.java, nastavi prekinitveno točko v metodi execute in izberi Tools > Compute volume iz menija Sweet Home 3D. Eclipse se bo ustavil na izbrani prekinitveni točki, da ti omogoči izvajanje programa po korakih in pregledovanje vrednosti spremenljivk.

Vsakič, ko spremeniš izvorno kodo svojega vtičnika, ne pozabi generirati JAR vtičnika pred zagonom konfiguracije za razhroščevanje, ki si jo ustvaril. Za pospešitev postopka izvoza JAR v eclipse pojdi na drugi korak čarovnika za izvoz JAR in izberi možnost Save the description of this JAR in the workspace. To bo dodalo nov element v projekt s kontekstnim menijem Create JAR.

Nameščanje vtičnika

Ko je pripravljen, lahko svoj vtičnik namestiš na računalnike drugih uporabnikov Sweet Home 3D preprosto tako, da ga kopiraš v njihovo mapo za vtičnike. Od različice 1.6 lahko datoteko vtičnika namestiš tudi v mapo za vtičnike Sweet Home 3D z dvoklikom nanjo, če je njena končnica SH3P (preprosto spremeni končnico datoteke iz .zip v .sh3p). Če dvoklik na datoteko .sh3p ne zažene Sweet Home 3D (najbolj verjetno v Linuxu), lahko vtičnik namestiš tudi z naslednjim ukazom v oknu Terminal (kjer SweetHome3D je ime izvedljive datoteke, ki je priložena namestitvenim programom Sweet Home 3D):

/pot/do/SweetHome3D /pot/do/plugin.sh3p

Za prenehanje uporabe vtičnika odstrani njegovo datoteko iz mape za vtičnike in ponovno zaženi Sweet Home 3D.

Če želiš, da tvoj vtičnik deluje z vsemi namestitvenimi programi Sweet Home 3D, ki so na voljo na tej spletni strani, poskrbi, da ostane združljiv z Javo 5, tako da izbereš 1.5 v polju Compiler compliance level, ki je na voljo v razdelku Java Compiler pogovornega okna, prikazanega z elementom menija Project > Properties v Eclipse.
Če uporabljaš različico prevajalnika Java, kjer združljivost z Javo 1.5 ni več na voljo, poskusi ciljati vsaj na Javo 1.8, ki se še vedno uporablja v novejših različicah Sweet Home 3D, in ustrezno nastavi javaMinimumVersion v datoteki ApplicationPlugin.properties svojega vtičnika.

Nadaljnje raziskovanje

Programiranje prvega vtičnika ti je pokazalo celotno 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 Sweet Home 3D API (Application Programming Interface), ustvarjen z orodjem javadoc.
V svojem vtičniku uporabljaj samo razrede iz paketov com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools in com.eteks.sweethome3d.viewcontroller, če želiš, da bo združljiv s prihodnjimi različicami Sweet Home 3D. To bo več kot dovolj za programiranje katerega koli vtičnika, ki deluje s podatki 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 zagotovila o združljivosti navzgor (v vsakem primeru ne boš videl nobene reference na razred iz paketov com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io ali com.eteks.sweethome3d v prej omenjenih paketih).

Arhitektura razredov modela

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

Osrednji razred v plasti Model je razred HomeApplication (10), abstraktni nadrazred glavnega razreda aplikacije SweetHome3D. Instanca tega razreda omogoča dostop do trenutno urejanih instanc Home (7) in do objekta UserPreferences (11), ki shranjuje enoto dolžine v uporabi (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),
• zbirko objektov Wall (9),
• seznam objektov Room (5),
• zbirko objektov DimensionLine (2),
• zbirko objektov Label (3).

Ti objekti implementirajo vmesnik Selectable (1), prav tako kot objekt ObserverCamera (4), ki shranjuje lokacijo kamere v načinu Virtualni obiskovalec. Do vseh zunanjih informacij, ki jih upravljajo objekti Model, kot sta ikona in 3D model kosa pohištva (16) ali slika teksture (20), dostopamo prek vmesnika Content (19), ki ga implementira razred URLContent in drugi razredi iz paketa com.eteks.sweethome3d.tools.

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

Model Sweet Home 3D ni varen za niti zaradi razlogov zmogljivosti. Vse spremembe objekta, ki pripada modelu, je treba izvesti v niti Event Dispatch Thread.

Arhitektura razredov vtičnikov

Arhitekturo razredov vtičnikov je veliko lažje razumeti kot arhitekturo plasti Model. Paket com.eteks.sweethome3d.plugin vsebuje samo tri razrede, od katerih naj bi uporabljal samo razreda Plugin in PluginAction, kot je prikazano na sliki 14 (na voljo tudi v PDF formatu).

Instanca PluginManager (1) se ustvari ob zagonu aplikacije in išče vtičnike, nameščene v uporabnikovi mapi vtičnikov. Vsakič, ko se ureja nov dom, ta upravitelj ustvari in konfigurira objekt Plugin (3) za vsak vtičnik, najden ob zagonu. Nato pokliče metodo getActions, da pridobi vse akcije (4), ki bodo dodane kot elementi menija in/ali gumbi v orodni vrstici v oknu doma. Vsaka akcija je instanca PluginAction, ki je podobna razredu Action, s svojo metodo execute in spremenljivimi lastnostmi (2).

Upoštevaj, da razred Plugin omogoča dostop do instance UndoableEditSupport prek svoje metode getUndoableEditSupport. Takoj ko spremeniš dom ali njegove objekte (pohištvo, stene …) v metodi execute instance PluginAction, moraš tudi poslati 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 načrtuješ razvoj vtičnika za skupnost uporabnikov Sweet Home 3D, poskusi lokalizirati nize, ki jih prikazuje bodisi v imenih akcij in menijih ali v dialogih, ki jih boš ustvaril (ali vsaj pripravi njegovo lokalizacijo). Dva konstruktorja razreda PluginAction ti bosta pomagala organizirati prevod lastnosti akcij z datotekami .properties, in če moraš prevesti druge nize v svojem vtičniku (kot je tisti v dialogu, ki ga prikazuje preizkušeni vtičnik), ponovno uporabi te datoteke .properties z Javinim razredom ResourceBundle.
Če želiš omejiti število datotek properties, lahko celo zapišeš vrednosti lastnosti akcij in druge nize 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 razširi (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 Prispevki vtičnikov, da jih deliš s skupnostjo uporabnikov Sweet Home 3D.
Številne funkcije je mogoče dodati v Sweet Home 3D s pomočjo vtičnikov, od uvoznikov do izvoznikov, pa tudi vtičnikov, ki lahko spreminjajo podatke doma, kot je Vtičnik za rotacijo doma, ki ga je razvil Michel Mbem, in drugi, navedeni v Priročniku za vtičnike in razširitve (PDF), ki ga je napisal Hans Dirkse, in na strani Vtičniki in orodja.