Installazione degli strumenti di sviluppo<\/h2>\n\n
Se Sweet Home 3D si rivolge a un pubblico generico, lo sviluppo di plug-in richiede competenze speciali ed \u00e8 necessario saper programmare in Java<\/a> con un IDE<\/a>, prima di procedere. Questa guida mostra come creare un plug-in con Eclipse<\/a>, ma puoi utilizzare l’IDE che preferisci o non utilizzarne affatto. <\/p>\n\n Innanzitutto, scarica Eclipse da https:\/\/www.eclipse.org\/<\/a>. La versione denominata Eclipse IDE for Java Developers<\/em> \u00e8 sufficiente per sviluppare un plug-in, ma puoi scaricare qualsiasi versione per lo sviluppo Java. 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\u00f9 semplice per aggiungere le classi di Sweet Home 3D a Eclipse \u00e8 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<\/a>. Una volta scaricato, trascina il file SweetHome3D-7.5.jar sull’icona del progetto VolumePlugin<\/em> nella vista Package Explorer<\/em> di Eclipse e scegli la voce Build Path > Add to Build Path<\/em> nel menu contestuale del file SweetHome3D-7.5.jar, come mostrato nella figura 2. <\/p>\n\n Ora che hai installato gli strumenti necessari, vediamo come puoi programmare il tuo primo plug-in per Sweet Home 3D.<\/p>\n\n Innanzitutto, crea una nuova sottoclasse di com.eteks.sweethome3d.plugin.Plugin scegliendo la voce di menu File > Nuovo > Classe<\/em> in Eclipse.<\/p>\n\n Nella finestra di dialogo Nuova classe Java<\/em>, inserisci VolumePlugin come nome della classe, inserisci un package (qui il package scelto \u00e8 stato com.eteks.test) e scegli com.eteks.sweethome3d.plugin.Plugin come superclasse di VolumePlugin. Una volta fatto, fai clic su Fine<\/em>. Eclipse creer\u00e0 il file della nuova classe con il seguente contenuto: <\/p>\n\n 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: <\/p>\n\n e scegli Modifica > Quick Fix<\/em> dal menu di Eclipse per creare la classe mancante VolumeAction, come mostrato nella figura 4.<\/p>\n\n Nella finestra di dialogo Nuova classe Java<\/em> che appare, seleziona la casella di controllo Enclosing type<\/em> per creare una classe interna di VolumePlugin e fai clic su Fine<\/em>. Questo creer\u00e0 la classe VolumeAction che eredita dalla classe com.eteks.sweethome3d.plugin.PluginAction e contiene un metodo execute vuoto: <\/p>\n\n Questo metodo \u00e8 quello che Sweet Home 3D chiamer\u00e0 quando l’utente avvier\u00e0 l’azione del plug-in; quindi questo \u00e8 il punto in cui devi implementare come calcolare il volume dei mobili e visualizzarlo:<\/p>\n\n Ora che hai specificato cosa vuoi che faccia il plug-in, devi descrivere come l’utente avvier\u00e0 questa nuova azione. Hai la possibilit\u00e0 di aggiungere una nuova voce di menu<\/strong> a un menu e\/o un nuovo pulsante<\/strong> alla barra degli strumenti. Questa scelta viene fatta impostando le propriet\u00e0 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<\/em> che si trova nel menu Strumenti<\/em>, aggiungerai il seguente costruttore alla classe VolumnAction: <\/p>\n\n La classe plug-in VolumePlugin<\/a> \u00e8 ora programmata e quasi pronta per funzionare come plug-in in Sweet Home 3D. Le ultime due cose da fare sono: <\/p>\n\n Un file ApplicationPlugin.properties<\/tt>\n descrive il nome del plug-in, la sua classe, le versioni minime di Sweet Home 3D e Java sotto le quali \u00e8 supportato,\n e le questioni legali. Scegli File > Nuovo > File<\/i> dal\n menu di Eclipse, inserisci il nome del file ApplicationPlugin.properties<\/tt> e fai clic su Fine<\/i>, come mostrato\n nella figura 5. <\/p>\n\n Quindi inserisci la seguente descrizione<\/a> nel nuovo file e salvalo:<\/p>\n\n Il JAR del plug-in contiene i file class<\/tt> creati dalla compilazione del file VolumePlugin.java<\/tt>,\n e il file ApplicationPlugin.properties<\/tt>. Poich\u00e9 Eclipse compila un file Java non appena lo salvi, devi\n solo scegliere File > Esporta…<\/i> dal menu e selezionare Java > File JAR<\/i> nella finestra di dialogo Esporta<\/i>\n che verr\u00e0 visualizzata. Nella procedura guidata Il plug-in<\/a> che hai sviluppato verr\u00e0 eseguito in Sweet Home 3D, sia con la versione Java Web Start<\/a>, la versione installers<\/a> o il file SweetHome3D-7.5.jar<\/a> che hai scaricato in precedenza. Poich\u00e9 quest’ultimo \u00e8 un JAR eseguibile, puoi eseguirlo facendo doppio clic su di esso o con il seguente comando: <\/p>\n\n Il plug-in<\/a> che hai sviluppato verr\u00e0 eseguito in Sweet Home 3D, sia con la versione Java Web Start<\/a>, la versione installers<\/a> o il file SweetHome3D-7.5.jar<\/a> che hai scaricato in precedenza. Poich\u00e9 quest’ultimo \u00e8 un JAR eseguibile, puoi eseguirlo facendo doppio clic su di esso o con il seguente comando: <\/p>\n\n Finch\u00e9 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.<\/p>\n\n Una volta avviato Sweet Home 3D, vedrai il nuovo menu e la sua voce apparire come mostrato nella figura 7:<\/p>\n\n Se scegli la nuova voce di menu per l’esempio di casa<\/a> creato nella guida per l’utente<\/a>, otterrai il seguente risultato:<\/p>\n\n Se hai bisogno di eseguire il debug del tuo plug-in da Eclipse, crea una configurazione di debug seguendo questi passaggi:<\/p>\n\n Ogni volta che modifichi il codice sorgente del tuo plug-in, non dimenticare di generare il JAR del plug-in<\/a> 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<\/em>. Questo aggiunger\u00e0 una nuova voce nel progetto con una voce di menu contestuale Crea JAR<\/em>. <\/p>\n<\/div>\n\n Una volta pronto, il tuo plug-in pu\u00f2 essere distribuito sul computer di altri utenti di Sweet Home 3D semplicemente copiandolo nella loro cartella dei plug-in<\/a>. Dalla versione 1.6, un file plug-in pu\u00f2 essere installato anche nella cartella dei plug-in di Sweet Home 3D facendo doppio clic su di esso, se la sua estensione \u00e8 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<\/em> (dove Per smettere di usare un plug-in, rimuovi il suo file dalla cartella dei plug-in e riavvia Sweet Home 3D.<\/p>\n\n Se vuoi che il tuo plug-in sia in grado di funzionare con tutti i programmi di installazione di Sweet Home 3D<\/a> disponibili su questo sito web, fai attenzione a mantenerlo conforme a Java 5, selezionando La programmazione del primo plug-in ti ha mostrato il quadro generale. Ecco alcune informazioni aggiuntive che ti aiuteranno ad andare oltre. <\/p>\n\n La documentazione pi\u00f9 utile per sviluppare un nuovo plug-in \u00e8 la Sweet Home 3D API<\/a> (Application Programming Interface), generata con lo strumento javadoc. Sweet Home 3D si basa su un’architettura MVC (Model View Controller), quindi capire come \u00e8 organizzato il suo livello Model \u00e8 essenziale. La figura 13 (disponibile anche in formato PDF<\/a>) presenta quasi tutte le classi e le interfacce disponibili nella versione 1.5 del pacchetto com.eteks.sweethome3d.model<\/a> che corrisponde a questo livello Model. <\/p>\n\n [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)”]<\/p>\n\n La classe centrale nel livello Model \u00e8 la classe HomeApplication<\/a> (10), la superclasse astratta della classe principale dell’applicazione SweetHome3D<\/a>. L’istanza di questa classe fornisce l’accesso alle istanze Home<\/a> (7) attualmente modificate e all’oggetto UserPreferences<\/a> (11) che memorizza l’unit\u00e0 di lunghezza<\/a> in uso (12), il catalogo dei mobili<\/a> (14) e il catalogo delle texture<\/a> (15) da cui l’utente sceglie i mobili<\/a> (17) e le texture<\/a> (18). Questi oggetti implementano l’interfaccia Selectable<\/a> (1) cos\u00ec come l’oggetto ObserverCamera<\/a> (4), che memorizza la posizione della telecamera nella modalit\u00e0 Visitatore virtuale<\/em>. Tutte le informazioni esterne gestite dagli oggetti Model, come l’icona e il modello 3D di un mobile<\/a> (16), o l’immagine di una texture<\/a> (20) sono accessibili tramite l’interfaccia Content<\/a> (19), implementata dalla classe URLContent<\/a> e da altre classi del pacchetto com.eteks.sweethome3d.tools<\/a>. <\/p>\n\n 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). \u00c8 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\u00e0 notificata ai componenti visualizzati tramite PropertyChangeEvent<\/a>, CollectionEvent<\/a> (8) o SelectionEvent<\/a> (6), consentendo cos\u00ec a tutte le modifiche di riflettersi immediatamente sullo schermo. <\/p>\n\n Il modello di Sweet Home 3D non \u00e8<\/strong> thread-safe per motivi di prestazioni. Tutte le modifiche<\/strong> di un oggetto appartenente al modello devono essere eseguite nell’Event Dispatch Thread. <\/p>\n<\/div>\n\n L’architettura delle classi plug-in \u00e8 molto pi\u00f9 semplice da capire rispetto a quella del livello Model. Il pacchetto com.eteks.sweethome3d.plugin<\/a> contiene solo tre classi tra cui dovresti usare solo le classi Plugin<\/a> e PluginAction<\/a>, come mostrato nella figura 14 (disponibile anche in formato PDF<\/a>). <\/p>\n\n [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)”]<\/p>\n\n Un’istanza di PluginManager<\/a> (1) viene creata all’avvio dell’applicazione e cerca i plug-in installati nella cartella dei plug-in<\/a> dell’utente. Ogni volta che viene modificata una nuova casa, questo gestore crea un’istanza e configura un oggetto Plugin<\/a> (3) per ogni plug-in trovato all’avvio. Quindi, chiama il metodo getActions<\/a> per recuperare tutte le azioni<\/a> (4) che verranno aggiunte come voci di menu e\/o pulsanti della barra degli strumenti nella finestra della casa. Ogni azione \u00e8 un’istanza di PluginAction<\/a>, che assomiglia alla classe Action<\/a>, con il suo metodo execute<\/a> e le sue propriet\u00e0<\/a> modificabili (2). <\/p>\n\n Nota che la classe Plugin<\/a> ti d\u00e0 accesso a un’istanza di UndoableEditSupport<\/a> tramite il suo metodo getUndoableEditSupport<\/a>. Non appena modifichi una casa o i suoi oggetti (mobili, pareti…) nel metodo execute di un’istanza di PluginAction<\/a>, dovresti anche pubblicare un oggetto UndoableEdit<\/a> al supporto di modifica annullabile restituito dal metodo getUndoableEditSupport, altrimenti gli utenti non saranno in grado di annullare\/ripetere correttamente le modifiche apportate. <\/p>\n\n Se hai intenzione di sviluppare un plug-in per la comunit\u00e0 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<\/a> ti aiuteranno a organizzare la traduzione delle propriet\u00e0 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<\/a>), riutilizza questi file .properties con la classe Java ResourceBundle<\/a>.Scarica e installa Eclipse<\/h3>\n\n
eclipse.exe<\/code> (in Windows), eclipse.app<\/code> (in Mac OS X) o eclipse<\/code> (in Linux).![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/eclipse.png\")
Scarica e installa la libreria Sweet Home 3D<\/h3>\n\n
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/addToBuildPath.png\")
Programmazione di un plug-in<\/h2>\n\n
Creazione della classe plug-in<\/h3>\n\n
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/newJavaClass.png\")
package com.eteks.test;
return new PluginAction<\/strong> [] {new VolumeAction<\/strong>()}; <\/pre>\n\n![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/quickFix.png\")
public class VolumeAction<\/strong> extends PluginAction<\/strong> { public class
public VolumeAction<\/strong>() {\n
Creazione del file di descrizione del plug-in<\/h3>\n\n
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/newFile.png\")
name<\/strong>=Volume dei mobili mobili
Creazione del JAR del plug-in<\/h3>\n\n
\n
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/jarExport.png\")
Test del plug-in<\/h3>\n\n
java -jar \/percorso<\/em>\/a<\/em>\/SweetHome3D-7.5.jar<\/pre>\n\n
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/pluginMenu.png\")
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/pluginInAction.png\")
Debug del plug-in<\/h3>\n\n
\n
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/debugConfiguration.png\")
\n
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/classpathConfiguration.png\")
\n
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/sourcepathConfiguration.png\")
\n
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/eclipseDebug.png\")
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/09\/warning-1.gif\")
<\/figure>\n\n\n\nDistribuzione del plug-in<\/h3>\n\n
SweetHome3D<\/code> \u00e8 il nome del file eseguibile fornito con i programmi di installazione di Sweet Home 3D):<\/p>\n\n\/percorso\/a\/<\/em>SweetHome3D \/percorso\/a\/<\/em>plugin.sh3p<\/pre>\n\n
<\/figure>\n\n\n\n1.5<\/code> nel campo Compiler compliance level<\/em> disponibile nella sezione Java Compiler<\/em> della finestra di dialogo mostrata dalla voce di menu Project > Properties<\/em> di Eclipse.javaMinimumVersion<\/code> nel file ApplicationPlugin.properties<\/code> del tuo plug-in di conseguenza.<\/p>\n<\/div>\n\nAndare oltre<\/h2>\n\n
Sweet Home 3D API – Javadoc<\/h3>\n\n
Architettura delle classi modello<\/h3>\n\n
\n
![\"\"](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/11\/Frame-281.png\")
<\/figure>\n\n\n\nArchitettura delle classi plug-in<\/h3>\n\n
Localizzazione<\/h3>\n\n
![formato PDF<\/a>) presenta quasi tutte le classi e le interfacce disponibili nella versione 1.5 del pacchetto](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/modelClassesDiagram.png\"){kind=link}
![formato PDF<\/a>). <\/p>\n\n[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)”]<\/p>\n\nUn’istanza di PluginManager<\/a> (1) viene creata all’avvio dell’applicazione e cerca i plug-in installati nella cartella dei plug-in<\/a> dell’utente. Ogni volta che viene modificata una nuova casa, questo gestore crea un’istanza e configura un oggetto Plugin<\/a> (3) per ogni plug-in trovato all’avvio. Quindi, chiama il metodo getActions<\/a> per recuperare tutte le azioni<\/a> (4) che verranno aggiunte come voci di menu e\/o pulsanti della barra degli strumenti nella finestra della casa. Ogni azione \u00e8 un’istanza di PluginAction<\/a>, che assomiglia alla classe Action<\/a>, con il suo metodo execute<\/a> e le sue propriet\u00e0<\/a> modificabili (2). <\/p>\n\nNota che la classe Plugin<\/a> ti d\u00e0 accesso a un’istanza di UndoableEditSupport<\/a> tramite il suo metodo getUndoableEditSupport<\/a>. Non appena modifichi una casa o i suoi oggetti (mobili, pareti…) nel metodo execute di un’istanza di PluginAction<\/a>, dovresti anche pubblicare un oggetto UndoableEdit<\/a> al supporto di modifica annullabile restituito dal metodo getUndoableEditSupport, altrimenti gli utenti non saranno in grado di annullare\/ripetere correttamente le modifiche apportate. <\/p>\n\nLocalizzazione<\/h3>\n\nSe hai intenzione di sviluppare un plug-in per la comunit\u00e0 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<\/a> ti aiuteranno a organizzare la traduzione delle propriet\u00e0 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<\/a>), riutilizza questi file .properties con la classe Java ResourceBundle<\/a>.](\"https:\/\/www.sweethome3d.com\/wp-content\/uploads\/2025\/12\/pluginClassesDiagram.png\"){kind=link}