Introduction
À partir de la version 1.5, il est possible d’ajouter de nouvelles fonctionnalités à Sweet Home 3D avec des fichiers de plug-in placés dans votre dossier de plug-ins. Cela permet aux programmeurs Java de développer et de distribuer de nouvelles fonctionnalités pour Sweet Home 3D sans modifier les fichiers source de la version actuelle (ce qui est bon pour la compatibilité ascendante), et sans fournir une version complète du programme (ce qui est bon pour la taille de la distribution).
Ce document décrit les outils nécessaires pour créer des plug-ins, puis montre comment programmer un plug-in qui calcule le volume maximal des meubles mobiles ajoutés à une maison, et enfin donne quelques informations supplémentaires qui vous aideront à aller plus loin.
Installation des outils de développement
Si Sweet Home 3D cible un public général, le développement de plug-ins nécessite des compétences particulières, et vous devriez savoir comment programmer en Java avec un IDE, avant d’aller plus loin. Ce guide montre comment construire un plug-in avec Eclipse, mais vous pouvez utiliser l’IDE de votre choix, ou pas d’IDE du tout.
Télécharger et installer Eclipse
Téléchargez d’abord Eclipse depuis https://www.eclipse.org/. La version nommée Eclipse IDE for Java Developers est suffisante pour développer un plug-in, mais vous pouvez télécharger n’importe quelle version pour le développement Java.
Une fois téléchargé, l’installation d’Eclipse est très simple : décompressez simplement l’archive que vous obtiendrez, ouvrez le dossier eclipse et, selon votre système, exécutez le fichier nommé eclipse.exe (sous Windows), eclipse.app (sous Mac OS X) ou eclipse (sous Linux).
Lors de la première exécution, Eclipse vous demandera de choisir un dossier workspace, où seront stockés les projets de plug-in.
Une fois cela fait, choisissez Fichier > Nouveau > Projet dans le menu pour créer un nouveau projet, sélectionnez Java > Projet Java dans l’assistant Nouveau projet qui s’affichera, entrez VolumePlugin comme nom de projet et cliquez sur le bouton Terminer. Enfin, fermez l’onglet Bienvenue pour découvrir votre espace de travail comme indiqué sur la figure 1.
Télécharger et installer la bibliothèque Sweet Home 3D
Le développement d’un plug-in est basé sur certaines classes de Sweet Home 3D qu’Eclipse doit connaître pour pouvoir construire votre projet. La façon la plus simple d’ajouter des classes Sweet Home 3D à Eclipse est de télécharger la version JAR exécutable de Sweet Home 3D disponible sur
au chemin de construction
Programmation d’un plug-in
Maintenant que vous avez installé les outils requis, voyons comment vous pouvez programmer votre premier plug-in pour Sweet Home 3D.
Création de la classe de plug-in
Tout d’abord, créez une nouvelle sous-classe de com.eteks.sweethome3d.plugin.Plugin en choisissant l’élément de menu Fichier > Nouveau > Classe dans Eclipse.
Dans la boîte de dialogue Nouvelle classe Java, entrez VolumePlugin comme nom de classe, entrez un package (ici le package choisi était com.eteks.test), et choisissez com.eteks.sweethome3d.plugin.Plugin comme super classe de VolumePlugin. Une fois cela fait, cliquez sur
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;
}
}
Comme vous pouvez le deviner d’après le commentaire TODO, vous devez maintenant modifier l’implémentation de la méthode getActions pour renvoyer une action de plug-in capable de calculer le volume des meubles mobiles. Remplacez return null ; par l’instruction suivante :
return new PluginAction [] {new VolumeAction()};
et choisissez Édition > Correction rapide dans le menu Eclipse pour créer la classe manquante VolumeAction, comme indiqué sur la figure 4.
Dans la boîte de dialogue Nouvelle classe Java qui apparaît, cochez la case Type englobant pour créer une classe interne de VolumePlugin et cliquez sur Terminer. Cela créera la classe VolumeAction qui hérite de la classe com.eteks.sweethome3d.plugin.PluginAction et contient une méthode execute vide :
public class VolumeAction extends PluginAction {
@Override
public void execute() {
// TODO Auto-generated method stub
}
}
Cette méthode est celle que Sweet Home 3D appellera lorsque l’utilisateur lancera l’action du plug-in ; c’est donc l’endroit où vous devez implémenter comment calculer le volume des meubles et l’afficher :
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);
}
}
Maintenant que vous avez spécifié ce que vous voulez que le plug-in fasse, vous devez décrire comment l’utilisateur lancera cette nouvelle action. Vous avez le choix entre ajouter un nouvel élément de menu à un menu, et/ou un nouveau bouton à la barre d’outils. Ce choix se fait en définissant les propriétés appropriées de l’action du plug-in lors de sa création. Par exemple, si vous voulez que les utilisateurs lancent l’action de volume avec l’élément de menu Calculer le volume trouvé dans le menu Outils, vous ajouterez le constructeur suivant à la classe VolumnAction :
public VolumeAction() {
putPropertyValue(Property.NAME, "Compute volume");
putPropertyValue(Property.MENU, "Tools");
// Enables the action by default
setEnabled(true);
}
La classe de plug-in VolumePlugin est maintenant programmée, et presque prête à fonctionner comme un plug-in dans Sweet Home 3D. Les deux dernières choses à faire sont :
- créer un fichier de description ApplicationPlugin.properties,
- rassembler les fichiers dans un fichier JAR.
Création du fichier de description du plug-in
Un fichier ApplicationPlugin.properties décrit le nom du plug-in, sa classe, les versions minimales de Sweet Home 3D et Java sous lesquelles il est pris en charge, et les aspects juridiques. Choisissez Fichier > Nouveau > Fichier dans le menu Eclipse, entrez le nom de fichier ApplicationPlugin.properties et cliquez sur Terminer, comme indiqué sur la figure 5.
Entrez ensuite la description suivante dans le nouveau fichier et enregistrez-le :
name=Volume des meubles mobiles
class=com.eteks.test.VolumePlugin
description=Calcule le volume des meubles mobiles dans la maison
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5
Création du JAR du plug-in
Le JAR du plug-in contient les fichiers class créés à partir de la compilation du fichier VolumePlugin.java,
et le fichier ApplicationPlugin.properties. Comme Eclipse compile un fichier Java dès que vous l’enregistrez, vous
n’avez qu’à choisir Fichier > Exporter… dans le menu et sélectionnez Java > Fichier JAR dans la boîte de dialogue Exporter
qui s’affichera. Dans l’assistant
- sous Windows Vista / 7 / 8 / 10 / 11, ce dossier est C:\Users\utilisateur\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
- sous Windows XP et les versions précédentes de Windows, ce dossier est C:\Documents and Settings\utilisateur\Application Data\eTeks\Sweet Home 3D\plugins,
- sous macOS, c’est le sous-dossier Library/Application Support/eTeks/Sweet Home 3D/plugins de votre dossier utilisateur,
- sous Linux et autres Unix, c’est le sous-dossier .eteks/sweethome3d/plugins de votre dossier utilisateur.
Test du plug-in
Le plug-in que vous avez développé s’exécutera dans Sweet Home 3D, soit avec la version Java Web Start, la version installateurs, ou le fichier SweetHome3D-7.5.jar que vous avez téléchargé précédemment. Comme ce dernier est un JAR exécutable, vous pouvez l’exécuter en double-cliquant dessus ou avec la commande suivante :
Le plug-in que vous avez développé s’exécutera dans Sweet Home 3D, soit avec la version Java Web Start, la version installateurs, ou le fichier SweetHome3D-7.5.jar que vous avez téléchargé précédemment. Comme ce dernier est un JAR exécutable, vous pouvez l’exécuter en double-cliquant dessus ou avec la commande suivante :
java -jar /chemin/vers/SweetHome3D-7.5.jar
Tant que vous testez, vous préférerez probablement exécuter Sweet Home 3D avec cette commande, pour pouvoir lire dans la console la trace de pile des exceptions levées lors de l’exécution de votre plug-in.
Une fois Sweet Home 3D lancé, vous verrez le nouveau menu et son élément apparaître comme indiqué sur la figure 7 :
Si vous choisissez le nouvel élément de menu pour l’exemple de maison créé dans le guide de l’utilisateur, vous obtiendrez le résultat suivant :
Débogage du plug-in
Si vous avez besoin de déboguer votre plug-in depuis Eclipse, créez une configuration de débogage en suivant ces étapes :
- Choisissez Exécuter > Configurations de débogage… dans le menu, sélectionnez l’élément Application Java dans la liste des configurations disponibles de la boîte de dialogue Configurations de débogage, cliquez sur le bouton Nouveau en haut à gauche et entrez un nom pour la configuration.
- Cliquez sur le bouton Rechercher… à droite du champ de texte Classe principale et double-cliquez sur la classe SweetHome3DBootstrap
parmi les classes proposées.
- Cliquez sur l’onglet Chemin de classe, sélectionnez le sous-élément VolumePlugin (chemin de classe par défaut) de l’élément Entrées utilisateur dans la liste Chemin de classe et cliquez sur le bouton Supprimer.
- Cliquez sur l’élément Entrées utilisateur dans la liste Chemin de classe, cliquez sur le bouton Ajouter des JAR…, sélectionnez l’élément SweetHome3D-7.5.jar et confirmez votre choix.
- Sélectionnez l’onglet Source, cliquez sur le bouton Ajouter…, double-cliquez sur l’élément Projet Java dans la boîte de dialogue Ajouter une source, sélectionnez l’élément VolumePlugin dans la fenêtre contextuelle Sélection du projet et confirmez votre choix.
- Enfin, cliquez sur le bouton Déboguer pour lancer Sweet Home 3D en mode débogage. Une fois le programme en cours d’exécution, ouvrez le fichier VolumePlugin.java, définissez un point d’arrêt dans la méthode execute et choisissez Outils > Calculer le volume dans le menu Sweet Home 3D. Eclipse s’arrêtera sur le point d’arrêt sélectionné pour vous permettre d’exécuter le programme étape par étape et d’inspecter la valeur des variables.
Chaque fois que vous modifiez le code source de votre plug-in, n’oubliez pas de générer le JAR du plug-in avant de lancer la configuration de débogage que vous avez créée. Pour accélérer le processus d’exportation JAR dans Eclipse, passez à la deuxième étape de l’assistant d’exportation JAR et sélectionnez l’option Enregistrer la description de ce JAR dans l’espace de travail. Cela ajoutera un nouvel élément dans le projet avec un élément de menu contextuel Créer un JAR.
Déploiement du plug-in
Une fois prêt, votre plug-in peut être déployé sur l’ordinateur d’autres utilisateurs de Sweet Home 3D en le copiant simplement dans leur dossier de plug-ins. À partir de la version 1.6, un fichier de plug-in peut également être installé dans le dossier des plug-ins de Sweet Home 3D en double-cliquant dessus, si son extension est SH3P (modifiez simplement l’extension du fichier de .zip à .sh3p). Si le fait de double-cliquer sur un fichier .sh3p ne lance pas Sweet Home 3D (le plus probable sous Linux), vous pouvez également installer un plug-in avec la commande suivante dans une fenêtre Terminal (où SweetHome3D est le nom du fichier exécutable fourni avec les installateurs de Sweet Home 3D) :
/chemin/vers/SweetHome3D /chemin/vers/plugin.sh3p
Pour cesser d’utiliser un plug-in, supprimez son fichier du dossier des plug-ins et relancez Sweet Home 3D.
Si vous voulez que votre plug-in puisse fonctionner avec tous les installateurs de Sweet Home 3D disponibles sur ce site Web, veillez à ce qu’il reste conforme à Java 5, en sélectionnant 1.5 dans le champ Niveau de conformité du compilateur disponible dans la section Compilateur Java de la boîte de dialogue affichée par l’élément de menu Projet > Propriétés d’Eclipse.
Si vous utilisez une version du compilateur Java où la compatibilité avec Java 1.5 n’est plus disponible, essayez de cibler au moins Java 1.8 toujours utilisé dans les versions récentes de Sweet Home 3D et définissez javaMinimumVersion dans le fichier ApplicationPlugin.properties de votre plug-in en conséquence.
Aller plus loin
La programmation du premier plug-in vous a montré la vue d’ensemble. Voici quelques informations supplémentaires qui vous aideront à aller plus loin.
API Sweet Home 3D – Javadoc
La documentation la plus utile pour développer un nouveau plug-in est l’API Sweet Home 3D (Interface de programmation applicative), générée avec l’outil javadoc.
Utilisez uniquement les classes des packages com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools et com.eteks.sweethome3d.viewcontroller dans votre plug-in si vous voulez qu’il soit compatible avec les versions futures de Sweet Home 3D. Cela sera largement suffisant pour programmer n’importe quel plug-in qui fonctionne sur les données de la maison disponibles dans Sweet Home 3D.
Les packages correspondant aux autres couches du programme sont inclus dans le Javadoc à titre d’information uniquement. Ne vous fiez pas à leur API, car elle pourrait encore changer à l’avenir sans garantie de compatibilité ascendante (de toute façon, vous ne verrez aucune référence à une classe des packages com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io ou com.eteks.sweethome3d dans les packages susmentionnés).
Architecture des classes de modèle
Sweet Home 3D est basé sur une architecture MVC (Model View Controller), il est donc essentiel de comprendre comment sa couche Modèle est organisée. La figure 13 (également disponible au format PDF) présente presque toutes les classes et interfaces disponibles dans la version 1.5 du package com.eteks.sweethome3d.model qui correspond à cette couche Modèle.
[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 de la couche Modèle est la classe HomeApplication (10), la superclasse abstraite de la classe principale de l’application SweetHome3D. L’instance de cette classe donne accès aux instances Home (7) actuellement éditées, et à l’objet UserPreferences (11) qui stocke l’unité de longueur utilisée (12), le catalogue de meubles (14) et le catalogue de textures (15) à partir desquels l’utilisateur choisit des meubles (17) et des textures (18).
Une instance Home (7) stocke tous les objets que l’utilisateur a créés dans le plan de la maison :
- la liste des objets HomePieceOfFurniture (13) qui implémentent l’interface PieceOfFurniture (16),
- la collection d’objets Wall (9),
- la liste des objets Room (5),
- la collection d’objets DimensionLine (2),
- la collection d’objets Label (3).
Ces objets implémentent l’interface Selectable (1) ainsi que l’objet ObserverCamera (4), qui stocke l’emplacement de la caméra dans le mode Visiteur virtuel. Toutes les informations externes gérées par les objets Modèle, comme l’icône et le modèle 3D d’un meuble (16), ou l’image d’une texture (20) sont accessibles via l’interface Content (19), implémentée par la classe URLContent et d’autres classes du package com.eteks.sweethome3d.tools.
Ce diagramme UML devrait vous aider à comprendre quelles classes sont disponibles dans le modèle Sweet Home 3D et comment vous pouvez y accéder, mais vous remarquerez probablement qu’aucun constructeur et aucun mutateur (ou setter si vous préférez) n’y sont cités. C’est juste par manque de place, mais vous pouvez les utiliser sans problème dans une classe de plug-in. Notez également que toute modification d’un objet existant du modèle sera notifiée aux composants affichés soit avec des PropertyChangeEvents, avec des CollectionEvents (8) ou avec des SelectionEvents (6), permettant ainsi à tous les changements d’être reflétés immédiatement à l’écran.
Le modèle Sweet Home 3D n’est pas thread safe pour des raisons de performance. Toutes les modifications d’un objet appartenant au modèle doivent être effectuées dans l’Event Dispatch Thread.
Architecture des classes de plug-in
L’architecture des classes de plug-in est beaucoup plus simple à comprendre que celle de la couche Modèle. Le package com.eteks.sweethome3d.plugin ne contient que trois classes parmi lesquelles vous êtes censé utiliser uniquement les classes Plugin et PluginAction, comme le montre la figure 14 (également disponible au format 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) »]
Une instance de PluginManager (1) est créée au lancement de l’application et recherche les plug-ins installés dans le dossier des plug-ins de l’utilisateur. Chaque fois qu’une nouvelle maison est éditée, ce gestionnaire instancie et configure un objet Plugin (3) pour chaque plug-in trouvé au moment du lancement. Ensuite, il appelle la méthode getActions pour récupérer toutes les actions (4) qui seront ajoutées en tant qu’éléments de menu et/ou boutons de la barre d’outils dans la fenêtre de la maison. Chaque action est une instance de PluginAction, qui ressemble à la classe Action, avec sa méthode execute et ses propriétés modifiables (2).
Notez que la classe Plugin vous donne accès à une instance UndoableEditSupport via sa méthode getUndoableEditSupport. Dès que vous modifiez une maison ou ses objets (meubles, murs…) dans la méthode execute d’une instance PluginAction, vous devez également poster un objet UndoableEdit au support d’édition annulable retourné par la méthode getUndoableEditSupport, sinon les utilisateurs ne pourront pas annuler/rétablir correctement les modifications que vous avez apportées.
Localisation
Si vous prévoyez de développer un plug-in pour la communauté des utilisateurs de Sweet Home 3D, essayez de localiser les chaînes qu’il affiche, que ce soit dans le nom des actions et le menu ou dans les boîtes de dialogue que vous créerez (ou au moins préparez sa localisation). Deux constructeurs de la classe PluginAction vous aideront à organiser la traduction des propriétés des actions avec des fichiers .properties, et si vous avez besoin de traduire d’autres chaînes dans votre plug-in (comme celles de la boîte de dialogue affichée par le plug-in testé), réutilisez ces fichiers .properties avec la classe Java ResourceBundle.
Si vous préférez limiter le nombre de fichiers de propriétés, vous pouvez même écrire les valeurs des propriétés des actions et d’autres chaînes dans le fichier de description ApplicationPlugin.properties de votre plug-in.
Si vous voulez un exemple qui utilise cette architecture, téléchargez le plug-in Export to SH3F disponible sur https://test.sweethome3d.eu/plugins/ExportToSH3F-1.0.sh3p, et dézippez-le (ce fichier de plug-in contient également le code source du plug-in).
Comme décrit dans le forum d’aide, ce plug-in crée un fichier SH3F qui contient tous les meubles que vous avez importés dans le catalogue de meubles de Sweet Home 3D.
Contribution de plug-ins
Vous pouvez publier les plug-ins que vous avez programmés dans le système de suivi des Contributions de plug-ins pour les partager avec la communauté des utilisateurs de Sweet Home 3D.
De nombreuses fonctionnalités peuvent être ajoutées à Sweet Home 3D grâce aux plug-ins, des importateurs aux exportateurs, mais aussi des plug-ins capables de modifier les données d’une maison comme le Plug-in Home Rotator développé par Michel Mbem et d’autres listés dans le Tutoriel pour les plug-ins et les extensions (PDF) écrit par Hans Dirkse et dans la page Plug-ins et outils.
