Guida per sviluppatori di plug-in

• Introduzione
• Installazione degli strumenti di sviluppo
• Programmazione di un plug-in
• Andare oltre

Introduzione

Dalla versione 1.5, è possibile aggiungere nuove funzionalità a Sweet Home 3D con file plug-in posizionati nella tua 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 e dovresti sapere come programmare in Java con un IDE, prima di andare oltre. Questa guida mostra come creare un plug-in con Eclipse, ma puoi usare l’IDE che preferisci o nessun IDE.

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, installare 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 archiviati 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.

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 creare 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 Esplora pacchetti di Eclipse e scegli la voce Percorso di build > Aggiungi al percorso di build nel menu contestuale del file SweetHome3D-7.5.jar, come mostrato nella figura 2.

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.

Nella finestra di dialogo Nuova classe Java, inserisci VolumePlugin come nome della classe, inserisci un pacchetto (qui il pacchetto 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 > Correzione rapida dal menu di Eclipse per creare la classe mancante VolumeAction, come mostrato nella figura 4.

Nella finestra di dialogo Nuova classe Java che appare, seleziona la casella di controllo Tipo contenitore 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;
 // Calcola la somma del volume del bounding box di 
 // ogni mobile mobile in casa
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Visualizza il risultato in una finestra di messaggio (³ è per 3 in apice)
 String message = String. format(
 "Il volume massimo dei mobili mobili in casa è %.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");
 // Abilita l'azione per impostazione predefinita
           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.

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 posizionato 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.

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 programmi di installazione 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 programmi di installazione 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é stai testando, probabilmente preferirai eseguire Sweet Home 3D con questo comando, per poter leggere nella console la traccia dello stack delle eccezioni generate durante l’esecuzione del tuo plug-in.

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

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

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 > Configurazioni di debug… dal menu, seleziona la voce Applicazione Java nell’elenco delle configurazioni disponibili della finestra di dialogo Configurazioni di debug, fai clic sul pulsante Nuovo in alto a sinistra e inserisci un nome per la configurazione.
• Fai clic sul pulsante Cerca… a destra del campo di testo Classe principale e fai doppio clic sulla classe SweetHome3DBootstrap
  tra le classi proposte.

• Fai clic sulla scheda Classpath, seleziona la sottovoce VolumePlugin (classpath predefinito) della voce Voci utente nell’elenco Classpath e fai clic sul pulsante Rimuovi.
• Fai clic sulla voce Voci utente nell’elenco Classpath, fai clic sul pulsante Aggiungi JAR…, seleziona la voce SweetHome3D-7.5.jar e conferma la tua scelta.

• Seleziona la scheda Origine, fai clic sul pulsante Aggiungi…, fai doppio clic sulla voce Progetto Java nella finestra di dialogo Aggiungi origine, seleziona la voce VolumePlugin nel popup Selezione progetto e conferma la tua scelta.

• Infine, fai clic sul pulsante Debug per avviare Sweet Home 3D in modalità di 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.

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ò anche essere installato 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 probabilmente sotto Linux), puoi anche installare un plug-in con il seguente comando in una finestra di Terminale (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 Livello di conformità del compilatore disponibile nella sezione Compilatore Java della finestra di dialogo mostrata dalla voce di menu Progetto > Proprietà 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.

API di Sweet Home 3D – javadoc

La documentazione più utile per sviluppare un nuovo plug-in è l’API di Sweet Home 3D (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 vuoi 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 nella Javadoc a scopo puramente informativo. Non fare affidamento sulle loro API, poiché potrebbero ancora cambiare in futuro senza alcuna garanzia di compatibilità con le versioni future (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 pacchetti summenzionati).

Architettura delle classi del modello

Sweet Home 3D si basa su un’architettura MVC (Model View Controller), quindi è essenziale capire come è organizzato il suo livello Model. 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.

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

• l’elenco degli oggetti HomePieceOfFurniture (13) che implementano l’interfaccia PieceOfFurniture (16),
• la collezione di oggetti Wall (9),
• l’elenco degli oggetti Room (5),
• la collezione di oggetti DimensionLine (2),
• la collezione di oggetti Label (3).

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 pezzo di arredamento (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 verrà notificata ai componenti visualizzati tramite PropertyChangeEvent, CollectionEvent (8) o SelectionEvent (6), consentendo così che tutte le modifiche vengano riflesse 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 dovrebbero essere eseguite nel Thread di Dispatch degli Eventi.

Architettura delle classi dei plug-in

L’architettura delle classi dei plug-in è molto più semplice da capire rispetto a quella del livello Model. Il pacchetto com.eteks.sweethome3d.plugin contiene solo tre classi, tra le quali si suppone che tu debba usare solo le classi Plugin e PluginAction, come mostrato nella figura 14 (disponibile anche in formato PDF).

Un’istanza 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 istanzia 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à (2) modificabili.

Nota che la classe Plugin ti dà accesso a un’istanza UndoableEditSupport tramite il suo metodo getUndoableEditSupport. Non appena modifichi una casa o i suoi oggetti (mobili, pareti…) nel metodo execute di un’istanza 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 che hai apportato.

Localizzazione

Se intendi sviluppare un plug-in per la community di utenti di Sweet Home 3D, prova a localizzare le stringhe che visualizza sia nel nome e nel menu delle azioni che nelle finestre di dialogo che creerai (o almeno preparane la 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 quella 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 persino scrivere i valori delle proprietà dell’azione 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 Esporta in SH3F disponibile su 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 di mobili di Sweet Home 3D.

Contribuire con i plug-in

Puoi pubblicare i plug-in che hai programmato nel sistema di tracciamento Contributi Plug-in per condividerli con la community 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 il Plug-in Rotatore Casa sviluppato da Michel Mbem e altri elencati nel Tutorial per Plug-in ed Estensioni (PDF) scritto da Hans Dirkse e nella pagina Plug-in e strumenti.