Průvodce pro vývojáře pluginů

• Úvod
• Instalace vývojových nástrojů
• Programování pluginu
• Další postup

Úvod

Od verze 1.5 je možné přidávat nové funkce do Sweet Home 3D pomocí souborů pluginů umístěných ve tvé složce pluginů. To umožňuje Java programátorům vyvíjet a distribuovat nové funkce pro Sweet Home 3D bez úpravy zdrojových souborů aktuální verze (což je dobré pro kompatibilitu směrem nahoru) a bez dodávání plné verze programu (což je dobré pro velikost dodávky).
Tento dokument popisuje nástroje potřebné k vytváření pluginů, poté ukazuje, jak naprogramovat plugin, který vypočítá maximální objem movitého nábytku přidaného do domova, a nakonec poskytuje některé dodatečné informace, které ti pomohou jít dál.

Instalace vývojových nástrojů

Pokud Sweet Home 3D cílí na širokou veřejnost, vývoj pluginů vyžaduje speciální dovednosti a měl bys vědět, jak programovat v Javě s IDE, než půjdeš dál. Tento průvodce ukazuje, jak sestavit plugin s Eclipse, ale můžeš použít IDE podle svého výběru, nebo žádné IDE vůbec.

Stáhni a nainstaluj Eclipse

Nejprve si stáhni Eclipse z https://www.eclipse.org/. Verze nazvaná Eclipse IDE for Java Developers stačí k vývoji pluginu, ale můžeš si stáhnout jakoukoli verzi pro vývoj v Javě.
Po stažení je instalace Eclipse velmi jednoduchá: stačí rozbalit archiv, který získáš, otevřít složku eclipse a v závislosti na tvém systému spustit soubor s názvem eclipse.exe (pod Windows), eclipse.app (pod Mac OS X) nebo eclipse (pod Linuxem).
Při prvním spuštění bude Eclipse vyžadovat, abys zvolil složku workspace, kde budou uloženy projekty pluginů.
Jakmile je to hotovo, zvol File > New > Project z menu pro vytvoření nového projektu, vyber Java > Java project v průvodci New project, který se zobrazí, zadej VolumePlugin jako název projektu a klikni na tlačítko Finish. Nakonec zavři záložku Welcome, abys objevil svůj workspace, jak je ukázáno na obrázku 1.

Stáhni a nainstaluj knihovnu Sweet Home 3D

Vývoj pluginu je založen na některých třídách Sweet Home 3D, které musí Eclipse znát, aby mohl sestavit tvůj projekt. Nejjednodušší způsob, jak přidat třídy Sweet Home 3D do Eclipse, je stáhnout JAR spustitelnou verzi Sweet Home 3D dostupnou na https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. Po stažení přetáhni soubor SweetHome3D-7.5.jar na ikonu projektu VolumePlugin v pohledu Package Explorer v Eclipse a zvol položku Build Path > Add to Build Path v kontextovém menu souboru SweetHome3D-7.5.jar, jak je ukázáno na obrázku 2.

Programování pluginu

Nyní, když jsi nainstaloval potřebné nástroje, podívejme se, jak můžeš naprogramovat svůj první plugin pro Sweet Home 3D.

Vytvoření třídy pluginu

Nejprve vytvoř novou podtřídu com.eteks.sweethome3d.plugin.Plugin výběrem položky menu File > New > Class v Eclipse.

V dialogu New Java Class zadej VolumePlugin jako název třídy, zadej balíček (zde byl zvolen balíček com.eteks.test) a zvol com.eteks.sweethome3d.plugin.Plugin jako nadtřídu VolumePlugin. Jakmile je to hotovo, klikni na Finish. 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ůžeš uhodnout z komentáře TODO, musíš nyní změnit implementaci metody getActions, aby vrátila akci pluginu schopnou vypočítat objem movitého nábytku. Nahraď return null; následujícím příkazem:

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

a zvol Edition > Quick Fix z menu Eclipse pro vytvoření chybějící třídy VolumeAction, jak je ukázáno na obrázku 4.

V dialogu New Java Class, který se objeví, vyber zaškrtávací políčko Enclosing type pro vytvoření vnitřní třídy VolumePlugin a klikni na Finish. 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 pluginu; takže toto je místo, kde musíš implementovat, jak vypočítat objem nábytku a zobrazit ho:

  public class VolumeAction extends PluginAction {  
  @Override
  public void execute() { 
  float volumeInCm3 = 0;
 // Vypočítej součet objemu ohraničujícího boxu 
 // každého movitého kusu nábytku v domově
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Zobraz výsledek v okně se zprávou (³ je pro 3 v horním indexu)
 String message = String. format(
 "Maximální objem movitého nábytku v domově je %.2f m³.", 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

Nyní, když jsi specifikoval, co chceš, aby plugin dělal, musíš popsat, jak uživatel spustí tuto novou akci. Máš na výběr mezi přidáním nové položky menu do menu a/nebo nového tlačítka do panelu nástrojů. Tato volba se provádí nastavením příslušných vlastností akce pluginu při jejím vytvoření. Například, pokud chceš, aby uživatelé spustili akci objemu pomocí položky menu Compute volume nalezené v menu Tools, přidáš následující konstruktor do třídy VolumeAction:

  public VolumeAction() {
           putPropertyValue(Property.NAME, "Compute volume");
           putPropertyValue(Property.MENU, "Tools");
 // Povolí akci ve výchozím nastavení
           setEnabled(true);
 }

Třída pluginu VolumePlugin je nyní naprogramována a téměř připravena fungovat jako plugin v Sweet Home 3D. Poslední dvě věci, které je třeba udělat, jsou:

• vytvoření popisného souboru ApplicationPlugin.properties,
• spojení souborů do JAR souboru.
  

Vytvoření popisného souboru pluginu

Soubor ApplicationPlugin.properties popisuje název pluginu, jeho třídu, minimální verze Sweet Home 3D a Javy, pod kterými je podporován, a právní záležitosti. Zvol File > New > File z menu Eclipse, zadej název souboru ApplicationPlugin.properties a klikni na Finish, jak je ukázáno na obrázku 5.

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

name=Movable furniture volume
class=com.eteks.test.VolumePlugin
description=Computes the volume of the movable furniture in home
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Vytvoření JAR pluginu

JAR plugin obsahuje class soubory vytvořené z kompilace souboru VolumePlugin.java, a soubor ApplicationPlugin.properties. Protože Eclipse kompiluje Java soubor, jakmile ho uložíš, stačí zvolit File > Export… z menu a vybrat Java > JAR file v dialogu Export , který se zobrazí. V průvodci Jar Export, který se objeví, jak je ukázáno na obrázku 6, vyber zaškrtávací políčko projektu a zadej cestu k JAR souboru umístěnému ve složce pluginů Sweet Home 3D. Tato příslušná složka závisí na tvém systému následovně:

• pod Windows Vista / 7 / 8 / 10 / 11 je tato složka C:\Users\user\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• pod Windows XP a předchozími verzemi Windows je tato složka C:\Documents and Settings\user\Application Data\eTeks\Sweet Home 3D\plugins,
• pod macOS je to podsložka Library/Application Support/eTeks/Sweet Home 3D/plugins tvé uživatelské složky,
• pod Linuxem a jinými Unix systémy je to podsložka .eteks/sweethome3d/plugins tvé uživatelské složky.

Testování pluginu

Plugin, který jsi vyvinul, poběží v Sweet Home 3D, buď s verzí Java Web Start, verzí instalátorů, nebo s SweetHome3D-7.5.jar, který jsi předtím stáhl. Protože ten poslední je spustitelný JAR, můžeš ho spustit dvojklikem na něj nebo následujícím příkazem:

Plugin, který jsi vyvinul, poběží v Sweet Home 3D, buď s verzí Java Web Start, verzí instalátorů, nebo s SweetHome3D-7.5.jar, který jsi předtím stáhl. Protože ten poslední je spustitelný JAR, můžeš ho spustit dvojklikem na něj nebo následujícím příkazem:

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

Dokud testuješ, pravděpodobně budeš preferovat spuštění Sweet Home 3D tímto příkazem, abys mohl číst v konzoli stack trace výjimek vyhozených během provádění tvého pluginu.

Jakmile je Sweet Home 3D spuštěn, uvidíš nové menu a jeho položku, jak je ukázáno na obrázku 7:

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

Ladění pluginu

Pokud potřebuješ ladit svůj plugin z Eclipse, vytvoř konfiguraci ladění podle těchto kroků:

• Zvol Run > Debug Configurations… z menu, vyber položku Java Application v seznamu dostupných konfigurací v dialogu Debug configurations, klikni na tlačítko New vlevo nahoře a zadej název pro konfiguraci.
• Klikni na tlačítko Search… vpravo od textového pole Main class a dvojklikni na třídu SweetHome3DBootstrap
  mezi navrženými třídami.

• Klikni na záložku Classpath, vyber podpoložku VolumePlugin (default classpath) položky User Entries v seznamu Classpath a klikni na tlačítko Remove.
• Klikni na položku User Entries v seznamu Classpath, klikni na tlačítko Add JARs…, vyber položku SweetHome3D-7.5.jar a potvrď svou volbu.

• Vyber záložku Source, klikni na tlačítko Add…, dvojklikni na položku Java Project v dialogu Add Source, vyber položku VolumePlugin v popup Project Selection a potvrď svou volbu.

• Nakonec klikni na tlačítko Debug pro spuštění Sweet Home 3D v režimu ladění. Jakmile program běží, otevři soubor VolumePlugin.java, nastav breakpoint v metodě execute a zvol Tools > Compute volume z menu Sweet Home 3D. Eclipse se zastaví na vybraném breakpointu, aby ti umožnil provádět program krok za krokem a kontrolovat hodnoty proměnných.

Pokaždé, když upravíš zdrojový kód svého pluginu, nezapomeň vygenerovat JAR pluginu před spuštěním konfigurace ladění, kterou jsi vytvořil. Pro urychlení procesu exportu JAR v Eclipse jdi do druhého kroku průvodce exportem JAR a vyber možnost Save the description of this JAR in the workspace. Tím se přidá nová položka do projektu s kontextovou položkou menu Create JAR.

Nasazení pluginu

Jakmile je připraven, tvůj plugin může být nasazen na počítač jiných uživatelů Sweet Home 3D jednoduše zkopírováním do jejich složky pluginů. Od verze 1.6 může být soubor pluginu také nainstalován do složky pluginů Sweet Home 3D dvojklikem na něj, pokud má příponu SH3P (jednoduše změň příponu souboru z .zip na .sh3p). Pokud dvojklik na soubor .sh3p nespustí Sweet Home 3D (nejpravděpodobnější pod Linuxem), můžeš také nainstalovat plugin následujícím příkazem v okně Terminal (kde SweetHome3D je název spustitelného souboru poskytovaného s instalátory Sweet Home 3D):

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

Pro ukončení používání pluginu odstraň jeho soubor ze složky pluginů a znovu spusť Sweet Home 3D.

Pokud chceš, aby tvůj plugin mohl běžet se všemi instalátory Sweet Home 3D dostupnými na této webové stránce, dbej na to, aby zůstal kompatibilní s Java 5, výběrem1.5 v poli Compiler compliance level dostupném v sekci Java Compiler dialogu zobrazeného položkou menu Project > Properties v Eclipse.
Pokud používáš verzi Java kompilátoru, kde kompatibilita s Java 1.5 již není dostupná, zkus cílit alespoň na Java 1.8 stále používanou v nedávných verzích Sweet Home 3D a nastavjavaMinimumVersion v souboruApplicationPlugin.properties tvého pluginu odpovídajícím způsobem.

Další postup

Programování prvního pluginu ti ukázalo celkový přehled. Zde jsou další informace, které ti pomohou pokročit dále.

Sweet Home 3D API – javadoc

Nejužitečnější dokumentací pro vývoj nového pluginu je Sweet Home 3D API (Application Programming Interface), vygenerované nástrojem javadoc.
Ve svém pluginu používej pouze třídy z balíčků com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools a com.eteks.sweethome3d.viewcontroller, pokud chceš, aby byl kompatibilní s budoucími verzemi Sweet Home 3D. To bude více než dostačující pro programování jakéhokoli pluginu, který pracuje s daty domů dostupnými v Sweet Home 3D.
Balíčky odpovídající ostatním vrstvám programu jsou zahrnuty v Javadocu pouze pro informační účely. Nespoléhej se na jejich API, protože se může v budoucnu změnit bez záruky zpětné kompatibility (v každém případě neuvidíš žá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 zmíněných balíčcích).

Architektura tříd modelu

Sweet Home 3D je založen na architektuře MVC (Model View Controller), takže porozumění organizaci jeho vrstvy Model je zásadní. Obrázek 13 (dostupný 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.

Centrální třídou ve vrstvě Model je třída HomeApplication (10), abstraktní nadtřída hlavní třídy aplikace SweetHome3D. Instance této třídy poskytuje přístup k aktuálně upravovaným instancím Home (7) a k objektu UserPreferences (11), který ukládá používanou jednotku délky (12), katalog nábytku (14) a katalog textur (15), ze kterých 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),
• kolekci objektů Wall (9),
• seznam objektů Room (5),
• kolekci objektů DimensionLine (2),
• kolekci objektů Label (3).

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

Tento UML diagram by ti měl pomoci pochopit, které třídy jsou dostupné v modelu Sweet Home 3D a jak k nim můžeš přistupovat, ale pravděpodobně si všimneš, že v něm nejsou uvedeny žádné konstruktory ani mutátory (nebo settery, pokud preferuješ). Je to jen kvůli nedostatku místa, ale můžeš je bez problémů používat ve třídě pluginu. Všimni si také, že jakákoli modifikace existujícího objektu modelu bude oznámena zobrazeným komponentám buď pomocí PropertyChangeEventů, CollectionEventů (8) nebo SelectionEventů (6), což umožňuje okamžité zobrazení všech změn na obrazovce.

Model Sweet Home 3D není vláknově bezpečný z důvodů výkonu. Všechny modifikace objektu patřícího do modelu by měly být prováděny ve vlákně Event Dispatch Thread.

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ž by ses měl používat pouze třídy Plugin a PluginAction, jak je znázorněno na obrázku 14 (dostupném také ve formátu PDF).

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 manažer vytvoří a nakonfiguruje objekt Plugin (3) pro každý plugin nalezený při spuštění. Poté volá metodu getActions pro získání všech akcí (4), které budou přidány jako položky menu a/nebo tlačítka panelu nástrojů v okně domu. Každá akce je instancí PluginAction, která se podobá třídě Action, s její metodou execute a jejími modifikovatelnými vlastnostmi (2).

Všimni si, že třída Plugin ti poskytuje přístup k instanci UndoableEditSupport prostřednictvím její metody getUndoableEditSupport. Jakmile upravíš dům nebo jeho objekty (nábytek, zdi…) v metodě execute instance PluginAction, měl bys také odeslat objekt UndoableEdit do podpory vratných úprav vrácené metodou getUndoableEditSupport, jinak uživatelé nebudou moci správně vrátit/znovu provést změny, které jsi provedl.

Lokalizace

Pokud plánuješ vyvinout plugin pro komunitu uživatelů Sweet Home 3D, snaž se lokalizovat řetězce, které zobrazuje buď v názvech akcí a menu, nebo v dialozích, které vytvoříš (nebo alespoň připrav jeho lokalizaci). Dva konstruktory třídy PluginAction ti pomohou organizovat překlad vlastností akcí pomocí souborů .properties, a pokud potřebuješ přeložit další řetězce ve svém pluginu (jako ten v dialogu zobrazeném testovaným pluginem), znovu použij tyto soubory .properties s Java třídou ResourceBundle.
Pokud preferuješ omezit počet souborů properties, můžeš dokonce zapsat hodnoty vlastností akcí a další řetězce do popisného souboru ApplicationPlugin.properties tvého pluginu.

Pokud chceš příklad, který používá tuto architekturu, stáhni si plugin Export to SH3F dostupný na https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p a rozbal ho (tento soubor pluginu obsahuje také zdrojový kód pluginu).
Jak je popsáno v Fóru nápovědy, tento plugin vytváří soubor SH3F, který obsahuje veškerý nábytek, který jsi importoval do katalogu nábytku Sweet Home 3D.

Přispívání pluginy

Pluginy, které jsi naprogramoval, můžeš zveřejnit v systému sledování Příspěvků pluginů, abys je sdílel 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 schopné upravovat data domu, jako je Plugin pro rotaci domu vyvinutý Michelem Mbemem a další uvedené v Tutoriálu pro pluginy a rozšíření (PDF) napsaném Hansem Dirkse a na stránce Pluginy a nástroje.