Introduzione

Dalla versione 1.5, è possibile aggiungere nuove funzionalità a Sweet Home 3D con file plug-in inseriti nella cartella dei plug-in. Ciò consente ai programmatori Java di sviluppare e distribuire nuove funzionalità per Sweet Home 3D senza modificare i file sorgente della versione corrente (il che è positivo per la compatibilità verso l’alto) e senza fornire una versione completa del programma (il che è positivo per le dimensioni della distribuzione).
Questo documento descrive gli strumenti necessari per creare plug-in, quindi mostra come programmare un plug-in che calcola il volume massimo dei mobili mobili aggiunti a una casa e, infine, fornisce alcune informazioni aggiuntive che ti aiuteranno ad andare oltre.

Installazione degli strumenti di sviluppo

Se Sweet Home 3D si rivolge a un pubblico generico, lo sviluppo di plug-in richiede competenze speciali ed è necessario saper programmare in Java con un IDE, prima di procedere. Questa guida mostra come creare un plug-in con Eclipse, ma puoi utilizzare l’IDE che preferisci o non utilizzarne affatto.

Scarica e installa Eclipse

Innanzitutto, scarica Eclipse da https://www.eclipse.org/. La versione denominata Eclipse IDE for Java Developers è sufficiente per sviluppare un plug-in, ma puoi scaricare qualsiasi versione per lo sviluppo Java.
Una volta scaricato, l’installazione di Eclipse è molto semplice: basta decomprimere l’archivio che otterrai, aprire la cartella eclipse e, a seconda del sistema, eseguire il file denominato eclipse.exe (in Windows), eclipse.app (in Mac OS X) o eclipse (in Linux).
Al primo avvio, Eclipse ti chiederà di scegliere una cartella workspace, dove verranno memorizzati i progetti dei plug-in.
Una volta fatto, scegli File > Nuovo > Progetto dal menu per creare un nuovo progetto, seleziona Java > Progetto Java nella procedura guidata Nuovo progetto che verrà visualizzata, inserisci VolumePlugin come nome del progetto e fai clic sul pulsante Fine. Infine, chiudi la scheda Benvenuto per scoprire il tuo workspace come mostrato nella figura 1.

Figura 1. Workspace di Eclipse

Scarica e installa la libreria Sweet Home 3D

Lo sviluppo di un plug-in si basa su alcune classi di Sweet Home 3D che Eclipse deve conoscere per poter compilare il tuo progetto. Il modo più semplice per aggiungere le classi di Sweet Home 3D a Eclipse è scaricare la versione eseguibile JAR di Sweet Home 3D disponibile all’indirizzo https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. Una volta scaricato, trascina il file SweetHome3D-7.5.jar sull’icona del progetto VolumePlugin nella vista Package Explorer di Eclipse e scegli la voce Build Path > Add to Build Path nel menu contestuale del file SweetHome3D-7.5.jar, come mostrato nella figura 2.

Figura 2. Aggiunta di SweetHome3D-7.5.jar
al Build Path

Programmazione di un plug-in

Ora che hai installato gli strumenti necessari, vediamo come puoi programmare il tuo primo plug-in per Sweet Home 3D.

Creazione della classe plug-in

Innanzitutto, crea una nuova sottoclasse di com.eteks.sweethome3d.plugin.Plugin scegliendo la voce di menu File > Nuovo > Classe in Eclipse.

Figura 3. Creazione di una nuova classe

Nella finestra di dialogo Nuova classe Java, inserisci VolumePlugin come nome della classe, inserisci un package (qui il package scelto è stato com.eteks.test) e scegli com.eteks.sweethome3d.plugin.Plugin come superclasse di VolumePlugin. Una volta fatto, fai clic su Fine. Eclipse creerà il file della nuova classe con il seguente contenuto: 

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

Come puoi intuire dal commento TODO, ora devi modificare l’implementazione del metodo getActions per restituire un’azione plug-in in grado di calcolare il volume dei mobili mobili. Sostituisci return null; con la seguente istruzione: 

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

e scegli Modifica > Quick Fix dal menu di Eclipse per creare la classe mancante VolumeAction, come mostrato nella figura 4.

Figura 4. Utilizzo di Quick fix per generare una classe mancante

Nella finestra di dialogo Nuova classe Java che appare, seleziona la casella di controllo Enclosing type per creare una classe interna di VolumePlugin e fai clic su Fine. Questo creerà la classe VolumeAction che eredita dalla classe com.eteks.sweethome3d.plugin.PluginAction e contiene un metodo execute vuoto: 

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

Questo metodo è quello che Sweet Home 3D chiamerà quando l’utente avvierà l’azione del plug-in; quindi questo è il punto in cui devi implementare come calcolare il volume dei mobili e visualizzarlo:

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

Ora che hai specificato cosa vuoi che faccia il plug-in, devi descrivere come l’utente avvierà questa nuova azione. Hai la possibilità di aggiungere una nuova voce di menu a un menu e/o un nuovo pulsante alla barra degli strumenti. Questa scelta viene fatta impostando le proprietà appropriate dell’azione del plug-in al momento della sua creazione. Ad esempio, se vuoi che gli utenti avviino l’azione del volume con la voce di menu Calcola volume che si trova nel menu Strumenti, aggiungerai il seguente costruttore alla classe VolumnAction: 

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

La classe plug-in VolumePlugin è ora programmata e quasi pronta per funzionare come plug-in in Sweet Home 3D. Le ultime due cose da fare sono:

  • creare un file di descrizione ApplicationPlugin.properties,
  • mettere insieme i file in un file JAR.

Creazione del file di descrizione del plug-in

Un file ApplicationPlugin.properties descrive il nome del plug-in, la sua classe, le versioni minime di Sweet Home 3D e Java sotto le quali è supportato, e le questioni legali. Scegli File > Nuovo > File dal menu di Eclipse, inserisci il nome del file ApplicationPlugin.properties e fai clic su Fine, come mostrato nella figura 5.

Figura 5. Creazione di un nuovo file

Quindi inserisci la seguente descrizione nel nuovo file e salvalo:

name=Volume dei mobili mobili
class=com.eteks.test.VolumePlugin
description=Calcola il volume dei mobili mobili in casa
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Creazione del JAR del plug-in

Il JAR del plug-in contiene i file class creati dalla compilazione del file VolumePlugin.java, e il file ApplicationPlugin.properties. Poiché Eclipse compila un file Java non appena lo salvi, devi solo scegliere File > Esporta… dal menu e selezionare Java > File JAR nella finestra di dialogo Esporta che verrà visualizzata. Nella procedura guidata Esportazione JAR che appare come mostrato nella figura 6, seleziona la casella di controllo del progetto e inserisci il percorso di un file JAR inserito nella cartella dei plug-in di Sweet Home 3D. Questa cartella appropriata dipende dal tuo sistema come segue:

  • in Windows Vista / 7 / 8 / 10 / 11, questa cartella è C:\Users\utente\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
  • in Windows XP e versioni precedenti di Windows, questa cartella è C:\Documents and Settings\utente\Application Data\eTeks\Sweet Home 3D\plugins,
  • in macOS, è la sottocartella Library/Application Support/eTeks/Sweet Home 3D/plugins della tua cartella utente,
  • in Linux e altri Unix, è la sottocartella .eteks/sweethome3d/plugins della tua cartella utente.
Figura 6. Esportazione in un file JAR

Test del plug-in

Il plug-in che hai sviluppato verrà eseguito in Sweet Home 3D, sia con la versione Java Web Start, la versione installers o il file SweetHome3D-7.5.jar che hai scaricato in precedenza. Poiché quest’ultimo è un JAR eseguibile, puoi eseguirlo facendo doppio clic su di esso o con il seguente comando:

Il plug-in che hai sviluppato verrà eseguito in Sweet Home 3D, sia con la versione Java Web Start, la versione installers o il file SweetHome3D-7.5.jar che hai scaricato in precedenza. Poiché quest’ultimo è un JAR eseguibile, puoi eseguirlo facendo doppio clic su di esso o con il seguente comando: 

java -jar /percorso/a/SweetHome3D-7.5.jar

Finché sei in fase di test, probabilmente preferirai eseguire Sweet Home 3D con questo comando, per poter leggere nella console la stack trace delle eccezioni generate durante l’esecuzione del tuo plug-in.

Una volta avviato Sweet Home 3D, vedrai il nuovo menu e la sua voce apparire come mostrato nella figura 7:

Figura 7. Menu del plug-in

Se scegli la nuova voce di menu per l’esempio di casa creato nella guida per l’utente, otterrai il seguente risultato:

Figura 8. Plug-in in azione

Debug del plug-in

Se hai bisogno di eseguire il debug del tuo plug-in da Eclipse, crea una configurazione di debug seguendo questi passaggi:

  • Scegli Esegui > Debug Configurations… dal menu, seleziona la voce Java Application nell’elenco delle configurazioni disponibili della finestra di dialogo Debug configurations, fai clic sul pulsante New in alto a sinistra e inserisci un nome per la configurazione.
  • Fai clic sul pulsante Search… a destra del campo di testo Main class e fai doppio clic sulla classe SweetHome3DBootstrap
    tra le classi proposte.
Figura 9. Creazione di una configurazione di debug
  • Fai clic sulla scheda Classpath, seleziona la sotto voce VolumePlugin (default classpath) della voce User Entries nell’elenco Classpath e fai clic sul pulsante Remove.
  • Fai clic sulla voce User Entries nell’elenco Classpath, fai clic sul pulsante Add JARs…, seleziona la voce SweetHome3D-7.5.jar e conferma la tua scelta.
Figura 10. Impostazione del classpath della configurazione di debug
  • Seleziona la scheda Source, fai clic sul pulsante Add…, fai doppio clic sulla voce Java Project nella finestra di dialogo Add Source, seleziona la voce VolumePlugin nel popup Project Selection e conferma la tua scelta.
Figura 11. Impostazione del percorso di origine della configurazione di debug
  • Infine, fai clic sul pulsante Debug per avviare Sweet Home 3D in modalità debug. Una volta che il programma è in esecuzione, apri il file VolumePlugin.java, imposta un punto di interruzione nel metodo execute e scegli Strumenti > Calcola volume dal menu di Sweet Home 3D. Eclipse si fermerà sul punto di interruzione selezionato per consentirti di eseguire il programma passo dopo passo e ispezionare il valore delle variabili.
Figura 12. Prospettiva di debug di Eclipse

Ogni volta che modifichi il codice sorgente del tuo plug-in, non dimenticare di generare il JAR del plug-in prima di avviare la configurazione di debug che hai creato. Per velocizzare il processo di esportazione JAR in Eclipse, vai al secondo passaggio della procedura guidata di esportazione JAR e seleziona l’opzione Salva la descrizione di questo JAR nel workspace. Questo aggiungerà una nuova voce nel progetto con una voce di menu contestuale Crea JAR.

Distribuzione del plug-in

Una volta pronto, il tuo plug-in può essere distribuito sul computer di altri utenti di Sweet Home 3D semplicemente copiandolo nella loro cartella dei plug-in. Dalla versione 1.6, un file plug-in può essere installato anche nella cartella dei plug-in di Sweet Home 3D facendo doppio clic su di esso, se la sua estensione è SH3P (basta cambiare l’estensione del file da .zip a .sh3p). Se fare doppio clic su un file .sh3p non avvia Sweet Home 3D (molto probabile in Linux), puoi anche installare un plug-in con il seguente comando in una finestra Terminal (dove SweetHome3D è il nome del file eseguibile fornito con i programmi di installazione di Sweet Home 3D):

/percorso/a/SweetHome3D /percorso/a/plugin.sh3p

Per smettere di usare un plug-in, rimuovi il suo file dalla cartella dei plug-in e riavvia Sweet Home 3D.

Se vuoi che il tuo plug-in sia in grado di funzionare con tutti i programmi di installazione di Sweet Home 3D disponibili su questo sito web, fai attenzione a mantenerlo conforme a Java 5, selezionando 1.5 nel campo Compiler compliance level disponibile nella sezione Java Compiler della finestra di dialogo mostrata dalla voce di menu Project > Properties di Eclipse.
Se usi una versione del compilatore Java in cui la compatibilità con Java 1.5 non è più disponibile, prova a puntare almeno a Java 1.8 ancora utilizzato nelle versioni recenti di Sweet Home 3D e imposta javaMinimumVersion nel file ApplicationPlugin.properties del tuo plug-in di conseguenza.

Andare oltre

La programmazione del primo plug-in ti ha mostrato il quadro generale. Ecco alcune informazioni aggiuntive che ti aiuteranno ad andare oltre.

Sweet Home 3D API – Javadoc

La documentazione più utile per sviluppare un nuovo plug-in è la Sweet Home 3D API (Application Programming Interface), generata con lo strumento javadoc.
Utilizza solo le classi dei pacchetti com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools e com.eteks.sweethome3d.viewcontroller nel tuo plug-in se desideri che sia compatibile con le versioni future di Sweet Home 3D. Questo sarà ampiamente sufficiente per programmare qualsiasi plug-in che funzioni sui dati della casa disponibili in Sweet Home 3D.
I pacchetti corrispondenti agli altri livelli del programma sono inclusi nel Javadoc solo a scopo informativo. Non fare affidamento sulla loro API, poiché potrebbe cambiare in futuro senza alcuna garanzia di compatibilità (in ogni caso non vedrai alcun riferimento a una classe dei pacchetti com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io o com.eteks.sweethome3d nei suddetti pacchetti).

Architettura delle classi modello

Sweet Home 3D si basa su un’architettura MVC (Model View Controller), quindi capire come è organizzato il suo livello Model è essenziale. La figura 13 (disponibile anche in formato PDF) presenta quasi tutte le classi e le interfacce disponibili nella versione 1.5 del pacchetto com.eteks.sweethome3d.model che corrisponde a questo livello 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)”]

La classe centrale nel livello Model è la classe HomeApplication (10), la superclasse astratta della classe principale dell’applicazione SweetHome3D. L’istanza di questa classe fornisce l’accesso alle istanze Home (7) attualmente modificate e all’oggetto UserPreferences (11) che memorizza l’unità di lunghezza in uso (12), il catalogo dei mobili (14) e il catalogo delle texture (15) da cui l’utente sceglie i mobili (17) e le texture (18).
Un’istanza Home (7) memorizza tutti gli oggetti che l’utente ha creato nella planimetria della casa:

Questi oggetti implementano l’interfaccia Selectable (1) così come l’oggetto ObserverCamera (4), che memorizza la posizione della telecamera nella modalità Visitatore virtuale. Tutte le informazioni esterne gestite dagli oggetti Model, come l’icona e il modello 3D di un mobile (16), o l’immagine di una texture (20) sono accessibili tramite l’interfaccia Content (19), implementata dalla classe URLContent e da altre classi del pacchetto com.eteks.sweethome3d.tools.

Questo diagramma UML dovrebbe aiutarti a capire quali classi sono disponibili nel modello di Sweet Home 3D e come puoi accedervi, ma probabilmente noterai che non sono citati costruttori e mutatori (o setter, se preferisci). È solo per mancanza di spazio, ma puoi usarli senza problemi in una classe plug-in. Nota anche che qualsiasi modifica di un oggetto esistente del modello sarà notificata ai componenti visualizzati tramite PropertyChangeEvent, CollectionEvent (8) o SelectionEvent (6), consentendo così a tutte le modifiche di riflettersi immediatamente sullo schermo.

Il modello di Sweet Home 3D non è thread-safe per motivi di prestazioni. Tutte le modifiche di un oggetto appartenente al modello devono essere eseguite nell’Event Dispatch Thread.

Architettura delle classi plug-in

L’architettura delle classi plug-in è molto più semplice da capire rispetto a quella del livello Model. Il pacchetto com.eteks.sweethome3d.plugin contiene solo tre classi tra cui dovresti usare solo le classi Plugin e PluginAction, come mostrato nella figura 14 (disponibile anche in formato 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)”]

Un’istanza di PluginManager (1) viene creata all’avvio dell’applicazione e cerca i plug-in installati nella cartella dei plug-in dell’utente. Ogni volta che viene modificata una nuova casa, questo gestore crea un’istanza e configura un oggetto Plugin (3) per ogni plug-in trovato all’avvio. Quindi, chiama il metodo getActions per recuperare tutte le azioni (4) che verranno aggiunte come voci di menu e/o pulsanti della barra degli strumenti nella finestra della casa. Ogni azione è un’istanza di PluginAction, che assomiglia alla classe Action, con il suo metodo execute e le sue proprietà modificabili (2).

Nota che la classe Plugin ti dà accesso a un’istanza di UndoableEditSupport tramite il suo metodo getUndoableEditSupport. Non appena modifichi una casa o i suoi oggetti (mobili, pareti…) nel metodo execute di un’istanza di PluginAction, dovresti anche pubblicare un oggetto UndoableEdit al supporto di modifica annullabile restituito dal metodo getUndoableEditSupport, altrimenti gli utenti non saranno in grado di annullare/ripetere correttamente le modifiche apportate.

Localizzazione

Se hai intenzione di sviluppare un plug-in per la comunità di utenti di Sweet Home 3D, prova a localizzare le stringhe che visualizza, sia nel nome delle azioni e nel menu, sia nelle finestre di dialogo che creerai (o almeno prepara la sua localizzazione). Due costruttori della classe PluginAction ti aiuteranno a organizzare la traduzione delle proprietà delle azioni con file .properties e, se hai bisogno di tradurre altre stringhe nel tuo plug-in (come quelle nella finestra di dialogo mostrata dal plug-in testato), riutilizza questi file .properties con la classe Java ResourceBundle.
Se preferisci limitare il numero di file di proprietà, potresti anche scrivere i valori delle proprietà delle azioni e altre stringhe nel file di descrizione ApplicationPlugin.properties del tuo plug-in.

Se vuoi un esempio che utilizzi questa architettura, scarica il plug-in Export to SH3F disponibile all’indirizzo https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p e decomprimilo (questo file plug-in contiene anche il codice sorgente del plug-in).
Come descritto nel forum di aiuto, questo plug-in crea un file SH3F che contiene tutti i mobili che hai importato nel catalogo dei mobili di Sweet Home 3D.

Contributo di plug-in

Puoi pubblicare i plug-in che hai programmato nel sistema di tracciamento Plug-ins Contributions per condividerli con la comunità di utenti di Sweet Home 3D.
Molte funzionalità possono essere aggiunte a Sweet Home 3D grazie ai plug-in, dagli importatori agli esportatori, ma anche plug-in in grado di modificare i dati di una casa come l’Home Rotator Plug-in sviluppato da Michel Mbem e altri elencati nel Tutorial for Plug-ins and Extensions (PDF) scritto da Hans Dirkse e nella pagina Plug-ins and tools.