Příručka pro vývojáře zásuvných modulů

Úvod

Od verze 1.5 je možné přidávat nové funkce do Sweet Home 3D pomocí souborů zásuvných modulů umístěných ve složce zásuvných modulů. To umožňuje programátorům v Javě vyvíjet a distribuovat nové funkce pro Sweet Home 3D bez úpravy zdrojových souborů aktuální verze (což je dobré pro zpětnou kompatibilitu) a bez dodávání plné verze programu (což je dobré pro velikost dodávky).
Tento dokument popisuje nástroje potřebné k vytvoření zásuvných modulů, poté ukazuje, jak naprogramovat zásuvný modul, který vypočítá maximální objem pohyblivého nábytku přidaného do domu, a nakonec uvádí některé další informace, které vám pomohou jít dál.

Instalace vývojových nástrojů

Zatímco Sweet Home 3D je určen pro širokou veřejnost, vývoj zásuvných modulů vyžaduje speciální dovednosti a měli byste vědět, jak programovat v Javě s IDE, než budete pokračovat. Tato příručka ukazuje, jak vytvořit zásuvný modul pomocí Eclipse, ale můžete použít IDE dle vlastního výběru, nebo žádné IDE.

Stáhněte a nainstalujte Eclipse

Nejprve si stáhněte Eclipse z https://www.eclipse.org/. Verze s názvem Eclipse IDE for Java Developers stačí k vývoji zásuvného modulu, ale můžete si stáhnout libovolnou verzi pro vývoj v Javě.
Po stažení je instalace Eclipse velmi jednoduchá: stačí rozbalit archiv, který získáte, otevřít složku eclipse a v závislosti na vašem systému spustit soubor s názvem eclipse.exe (v systému Windows), eclipse.app (v systému Mac OS X) nebo eclipse (v systému Linux).
Při prvním spuštění bude Eclipse vyžadovat, abyste si vybrali složku pracovního prostoru, kde budou uloženy projekty zásuvných modulů.
Jakmile to uděláte, vyberte z nabídky Soubor > Nový > Projekt pro vytvoření nového projektu, vyberte Java > Java project v průvodci Nový projekt, který se zobrazí, zadejte VolumePlugin jako název projektu a klikněte na tlačítko Dokončit. Nakonec zavřete kartu Vítejte a objevte svůj pracovní prostor, jak je znázorněno na obrázku 1.

Stáhněte a nainstalujte knihovnu Sweet Home 3D

Vývoj zásuvného modulu je založen na některých třídách Sweet Home 3D, které Eclipse musí znát, aby mohl sestavit váš projekt. Nejjednodušší způsob, jak přidat třídy Sweet Home 3D do Eclipse, je stáhnout spustitelnou verzi JAR Sweet Home 3D, která je k dispozici na https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. Po stažení přetáhněte soubor SweetHome3D-7.5.jar na ikonu projektu VolumePlugin v zobrazení Package Explorer v Eclipse a vyberte položku Build Path > Add to Build Path v kontextové nabídce souboru SweetHome3D-7.5.jar, jak je znázorněno na obrázku 2.

Programování zásuvného modulu

Nyní, když jste nainstalovali požadované nástroje, se podívejme, jak můžete naprogramovat svůj první zásuvný modul pro Sweet Home 3D.

Vytvoření třídy zásuvného modulu

Nejprve vytvořte novou podtřídu com.eteks.sweethome3d.plugin.Plugin výběrem položky nabídky Soubor > Nový > Třída v Eclipse.

V dialogovém okně Nová třída Java zadejte VolumePlugin jako název třídy, zadejte balíček (zde byl zvolen balíček com.eteks.test) a vyberte com.eteks.sweethome3d.plugin.Plugin jako nadtřídu VolumePlugin. Jakmile to uděláte, klikněte na Dokončit. Eclipse vytvoří soubor nové třídy s následujícím obsahem:

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

Jak můžete odvodit z komentáře TODO, musíte nyní změnit implementaci metody getActions, aby vracela akci zásuvného modulu, která je schopna vypočítat objem pohyblivého nábytku. Nahraďte return null; následujícím příkazem:

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

a vyberte Úpravy > Rychlá oprava z nabídky Eclipse pro vytvoření chybějící třídy VolumeAction, jak je znázorněno na obrázku 4.

V dialogovém okně Nová třída Java, které se zobrazí, zaškrtněte políčko Uzavírající typ pro vytvoření vnitřní třídy VolumePlugin a klikněte na Dokončit. Tím se vytvoří třída VolumeAction, která dědí z třídy com.eteks.sweethome3d.plugin.PluginAction a obsahuje prázdnou metodu execute:

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

Tato metoda je ta, kterou Sweet Home 3D zavolá, když uživatel spustí akci zásuvného modulu; proto je to místo, kde musíte implementovat, jak vypočítat objem nábytku a zobrazit jej:

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

Nyní, když jste určili, co má zásuvný modul dělat, musíte popsat, jak uživatel spustí tuto novou akci. Máte na výběr mezi přidáním nové položky nabídky do nabídky a/nebo nového tlačítka na panel nástrojů. Tato volba se provádí nastavením příslušných vlastností akce zásuvného modulu při jeho vytvoření. Například, pokud chcete, aby uživatelé spouštěli akci objemu pomocí položky nabídky Vypočítat objem, která se nachází v nabídce Nástroje, přidáte následující konstruktor do třídy VolumnAction:

  public VolumeAction() {
           putPropertyValue(Property.NAME, "Compute volume");
           putPropertyValue(Property.MENU, "Tools");
 // Enables the action by default
           setEnabled(true);
 }

Třída zásuvného modulu VolumePlugin je nyní naprogramována a téměř připravena k práci jako zásuvný modul v Sweet Home 3D. Poslední dvě věci, které je třeba udělat, jsou:

• vytvoření popisného souboru ApplicationPlugin.properties,
• umístění souborů dohromady do souboru JAR.
  

Vytvoření popisného souboru zásuvného modulu

Soubor ApplicationPlugin.properties popisuje název zásuvného modulu, jeho třídu, minimální verze Sweet Home 3D a Java, pod kterými je podporován, a právní záležitosti. Vyberte Soubor > Nový > Soubor z nabídky Eclipse, zadejte název souboru ApplicationPlugin.properties a klikněte na Dokončit, jak je znázorněno na obrázku 5.

Poté zadejte následující popis do nového souboru a uložte jej:

name=Objem pohyblivého nábytku
class=com.eteks.test.VolumePlugin
description=Vypočítá objem pohyblivého nábytku v domě
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Vytvoření souboru JAR zásuvného modulu

Soubor JAR zásuvného modulu obsahuje soubory tříd vytvořené z kompilace souboru VolumePlugin.java, a soubor ApplicationPlugin.properties. Protože Eclipse kompiluje soubor Java, jakmile jej uložíte, stačí vybrat Soubor > Exportovat… z nabídky a vybrat Java > Soubor JAR v dialogovém okně Exportovat , které se zobrazí. V průvodci Export JAR, který se zobrazí, jak je znázorněno na obrázku 6, zaškrtněte políčko projektu a zadejte cestu k souboru JAR umístěnému ve složce zásuvných modulů Sweet Home 3D. Tato příslušná složka závisí na vašem systému takto:

• v systémech Windows Vista / 7 / 8 / 10 / 11 je tato složka C:\Users\uživatel\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• v systémech Windows XP a starších verzích Windows je tato složka C:\Documents and Settings\uživatel\Application Data\eTeks\Sweet Home 3D\plugins,
• v systému macOS je to podsložka Library/Application Support/eTeks/Sweet Home 3D/plugins vaší uživatelské složky,
• v systémech Linux a jiných Unixech je to podsložka .eteks/sweethome3d/plugins vaší uživatelské složky.

Testování zásuvného modulu

Zásuvný modul, který jste vyvinuli, bude spuštěn v Sweet Home 3D, buď s verzí Java Web Start, verzí instalačních programů, nebo SweetHome3D-7.5.jar, kterou jste si dříve stáhli. Protože nejnovější je spustitelný soubor JAR, můžete jej spustit dvojitým kliknutím na něj nebo pomocí následujícího příkazu:

Zásuvný modul, který jste vyvinuli, bude spuštěn v Sweet Home 3D, buď s verzí Java Web Start, verzí instalačních programů, nebo SweetHome3D-7.5.jar, kterou jste si dříve stáhli. Protože nejnovější je spustitelný soubor JAR, můžete jej spustit dvojitým kliknutím na něj nebo pomocí následujícího příkazu:

java -jar /cesta/k/SweetHome3D-7.5.jar

Dokud testujete, pravděpodobně budete preferovat spouštění Sweet Home 3D pomocí tohoto příkazu, abyste si mohli v konzoli přečíst trasování zásobníku výjimek vyvolaných během provádění vašeho zásuvného modulu.

Jakmile je Sweet Home 3D spuštěn, uvidíte novou nabídku a její položku, jak je znázorněno na obrázku 7:

Pokud zvolíte novou položku nabídky pro domácí příklad vytvořený v uživatelské příručce, získáte následující výsledek:

Ladění zásuvného modulu

Pokud potřebujete ladit svůj zásuvný modul z Eclipse, vytvořte konfiguraci ladění pomocí následujících kroků:

• Z nabídky vyberte Spustit > Konfigurace ladění…, vyberte položku Aplikace Java v seznamu dostupných konfigurací v dialogovém okně Konfigurace ladění, klikněte na tlačítko Nový v levém horním rohu a zadejte název konfigurace.
• Klikněte na tlačítko Hledat… vpravo od textového pole Hlavní třída a dvakrát klikněte na třídu SweetHome3DBootstrap
  mezi navrhovanými třídami.

• Klikněte na kartu Classpath, vyberte dílčí položku VolumePlugin (výchozí classpath) položky Položky uživatele v seznamu Classpath a klikněte na tlačítko Odebrat.
• Klikněte na položku Položky uživatele v seznamu Classpath, klikněte na tlačítko Přidat JAR…, vyberte položku SweetHome3D-7.5.jar a potvrďte svou volbu.

• Vyberte kartu Zdroj, klikněte na tlačítko Přidat…, dvakrát klikněte na položku Projekt Java v dialogovém okně Přidat zdroj, vyberte položku VolumePlugin ve vyskakovacím okně Výběr projektu a potvrďte svou volbu.

• Nakonec klikněte na tlačítko Ladit pro spuštění Sweet Home 3D v režimu ladění. Jakmile je program spuštěn, otevřete soubor VolumePlugin.java, nastavte bod přerušení v metodě execute a vyberte Nástroje > Vypočítat objem z nabídky Sweet Home 3D. Eclipse se zastaví na vybraném bodu přerušení, abyste mohli program spouštět krok za krokem a kontrolovat hodnotu proměnných.

Nasazení zásuvného modulu

Jakmile je váš zásuvný modul připraven, může být nasazen na počítači jiných uživatelů Sweet Home 3D jednoduše zkopírováním do jejich složky zásuvných modulů. Od verze 1.6 lze soubor zásuvného modulu také nainstalovat do složky zásuvných modulů Sweet Home 3D dvojitým kliknutím na něj, pokud má příponu SH3P (jednoduše změňte příponu souboru z .zip na .sh3p). Pokud dvojité kliknutí na soubor .sh3p nespustí Sweet Home 3D (nejčastěji v systému Linux), můžete také nainstalovat zásuvný modul pomocí následujícího příkazu v okně Terminálu (kde SweetHome3D je název spustitelného souboru dodávaného s instalačními programy Sweet Home 3D):

/cesta/k/SweetHome3D /cesta/k/plugin.sh3p

Chcete-li přestat používat zásuvný modul, odeberte jeho soubor ze složky zásuvných modulů a znovu spusťte Sweet Home 3D.

Jít dál

Programování prvního zásuvného modulu vám ukázalo celkový obraz. Zde jsou některé další informace, které vám pomohou jít dál.

Sweet Home 3D API – Javadoc

Nejužitečnější dokumentací pro vývoj nového pluginu je Sweet Home 3D API (Application Programming Interface), generované nástrojem javadoc.
Používejte ve svém pluginu pouze třídy z balíčků com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools a com.eteks.sweethome3d.viewcontroller, pokud chcete, aby byl zpětně kompatibilní s budoucími verzemi Sweet Home 3D. To bude z velké části stačit k naprogramování jakéhokoli pluginu, který pracuje s daty o domě dostupnými v Sweet Home 3D.
Balíčky odpovídající ostatním vrstvám programu jsou zahrnuty v Javadoc pouze pro informační účely. Nespoléhejte se na jejich API, protože se v budoucnu může změnit bez záruky zpětné kompatibility (každopádně neuvidíte žádný odkaz na třídu z balíčků com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io nebo com.eteks.sweethome3d ve výše uvedených balíčcích).

Architektura tříd modelu

Sweet Home 3D je založen na architektuře MVC (Model View Controller), takže pochopení organizace vrstvy Model je zásadní. Obrázek 13 (k dispozici také ve formátu PDF) představuje téměř všechny třídy a rozhraní dostupné ve verzi 1.5 balíčku com.eteks.sweethome3d.model, který odpovídá této vrstvě Model.

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

Centrální třídou ve vrstvě Model je třída HomeApplication (10), abstraktní super třída hlavní třídy aplikace SweetHome3D. Instance této třídy poskytuje přístup k instancím Home (7), které jsou aktuálně upravovány, a k objektu UserPreferences (11), který ukládá používanou jednotku délky (12), katalog nábytku (14) a katalog textur (15), ze kterého si uživatel vybírá kusy nábytku (17) a textury (18).
Instance Home (7) ukládá všechny objekty, které uživatel vytvořil v plánu domu:

• seznam objektů HomePieceOfFurniture (13), které implementují rozhraní PieceOfFurniture (16),
• kolekce objektů Wall (9),
• seznam objektů Room (5),
• kolekce objektů DimensionLine (2),
• kolekce objektů Label (3).

Tyto objekty implementují rozhraní Selectable (1) stejně jako objekt ObserverCamera (4), který ukládá umístění kamery v režimu Virtuální návštěvník. Veškeré externí informace spravované objekty Model, jako je ikona a 3D model kusu nábytku (16) nebo obrázek textury (20), jsou přístupné prostřednictvím rozhraní Content (19), implementovaného třídou URLContent a dalšími třídami z balíčku com.eteks.sweethome3d.tools.

Tento UML diagram by vám měl pomoci pochopit, které třídy jsou dostupné v modelu Sweet Home 3D a jak k nim můžete přistupovat, ale pravděpodobně si všimnete, že v něm nejsou uvedeny žádné konstruktory ani mutátory (nebo settery, chcete-li). Je to jen z nedostatku místa, ale můžete je bez problémů použít ve třídě pluginu. Všimněte si také, že jakákoli úprava existujícího objektu modelu bude oznámena zobrazeným komponentám buď pomocí PropertyChangeEvent, pomocí CollectionEvent (8) nebo pomocí SelectionEvent (6), což umožní, aby se všechny změny okamžitě projevily na obrazovce.

Architektura tříd pluginu

Architektura tříd pluginu je mnohem jednodušší na pochopení než architektura vrstvy Model. Balíček com.eteks.sweethome3d.plugin obsahuje pouze tři třídy, z nichž byste měli používat pouze třídy Plugin a PluginAction, jak je znázorněno na obrázku 14 (k dispozici také ve formátu 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)“]

Instance PluginManager (1) je vytvořena při spuštění aplikace a vyhledává pluginy nainstalované ve složce pluginů uživatele. Pokaždé, když je upravován nový dům, tento správce vytvoří a nakonfiguruje objekt Plugin (3) pro každý plugin nalezený při spuštění. Poté zavolá metodu getActions, aby načetl všechny akce (4), které budou přidány jako položky nabídky a/nebo tlačítka panelu nástrojů v okně domu. Každá akce je instance PluginAction, která vypadá jako třída Action, s její metodou execute a jejími modifikovatelnými vlastnostmi (2).

Všimněte si, že třída Plugin vám poskytuje přístup k instanci UndoableEditSupport prostřednictvím její metody getUndoableEditSupport. Jakmile upravíte dům nebo jeho objekty (nábytek, stěny…) v metodě execute instance PluginAction, měli byste také odeslat objekt UndoableEdit do podpory undoable edit vrácené metodou getUndoableEditSupport, jinak uživatelé nebudou moci správně vrátit/znovu provést provedené změny.

Lokalizace

Pokud plánujete vyvinout plugin pro komunitu uživatelů Sweet Home 3D, pokuste se lokalizovat řetězce, které zobrazuje, ať už v názvu akcí a nabídce, nebo v dialozích, které vytvoříte (nebo alespoň připravte jeho lokalizaci). Dva konstruktory třídy PluginAction vám pomohou uspořádat překlad vlastností akcí pomocí souborů .properties, a pokud potřebujete přeložit další řetězce ve vašem pluginu (jako například v dialogu zobrazeném testovaným pluginem), znovu použijte tyto soubory .properties pomocí třídy Java ResourceBundle.
Pokud chcete omezit počet souborů vlastností, můžete dokonce zapsat hodnoty vlastností akcí a dalších řetězců do souboru s popisem ApplicationPlugin.properties vašeho pluginu.

Pokud chcete příklad, který používá tuto architekturu, stáhněte si plugin Export to SH3F, který je k dispozici na https://test.sweethome3d.eu/plugins/ExportToSH3F-1.0.sh3p, a rozbalte jej (tento soubor pluginu obsahuje také zdrojový kód pluginu).
Jak je popsáno ve Fóru nápovědy, tento plugin vytvoří soubor SH3F, který obsahuje veškerý nábytek, který jste importovali do katalogu nábytku Sweet Home 3D.

Přispívání pluginy

Pluginy, které naprogramujete, můžete zveřejnit v systému sledování Plug-ins Contributions a sdílet je s komunitou uživatelů Sweet Home 3D.
Díky pluginům lze do Sweet Home 3D přidat mnoho funkcí, od importérů po exportéry, ale také pluginy, které dokážou upravit data domu, jako například Home Rotator Plug-in vyvinutý Michelem Mbemem a dalšími uvedenými v Tutoriálu pro pluginy a rozšíření (PDF) od Hanse Dirkseho a na stránce Pluginy a nástroje.