TéléchargerOnlineGalerie

Plug-in developer’s guide

Introduction

Depuis la version 1.5, il est possible d’ajouter de nouvelles fonctionnalités à Sweet Home 3D avec des fichiers plug-ins placés dans ton dossier de plug-ins. Cela permet aux programmeurs Java de développer et distribuer de nouvelles fonctionnalités pour Sweet Home 3D sans modifier les fichiers sources de la version actuelle (ce qui est bon pour la compatibilité ascendante), et sans livrer une version complète du programme (ce qui est bon pour la taille de livraison).
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 maximum des meubles déplaçables ajoutés à une maison, et donne enfin quelques informations supplémentaires qui t’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 tu dois savoir programmer en Java avec un IDE, avant d’aller plus loin. Ce guide montre comment construire un plug-in avec Eclipse, mais tu peux utiliser l’IDE de ton choix, ou ne pas utiliser d’IDE du tout.

Télécharger et installer Eclipse

Tout d’abord, télécharge Eclipse depuis https://www.eclipse.org/. La version nommée Eclipse IDE for Java Developers est suffisante pour développer un plug-in, mais tu peux 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écompresse simplement l’archive que tu obtiens, ouvre le dossier eclipse et selon ton système, exécute le fichier nommé eclipse.exe (sous Windows), eclipse.app (sous Mac OS X) ou eclipse (sous Linux).
Au premier lancement, Eclipse te demandera de choisir un dossier workspace, où seront stockés les projets de plug-ins.
Une fois fait, choisis File > New > Project dans le menu pour créer un nouveau projet, sélectionne Java > Java project dans l’assistant New project qui s’affichera, entre VolumePlugin comme nom de projet et clique sur le bouton Finish. Enfin, ferme l’onglet Welcome pour découvrir ton workspace comme montré dans la figure 1.

Guide du développeur de plug-ins
Figure 1. Espace de travail Eclipse

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 ton projet. La façon la plus simple d’ajouter les classes de Sweet Home 3D à Eclipse est de télécharger la version JAR exécutable de Sweet Home 3D disponible sur https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. Une fois téléchargé, fais glisser et dépose le fichier SweetHome3D-7.5.jar sur l’icône du projet VolumePlugin dans la vue Package Explorer d’Eclipse, et choisis l’élément Build Path > Add to Build Path dans le menu contextuel du fichier SweetHome3D-7.5.jar, comme montré dans la figure 2.

Figure 2. Ajout de SweetHome3D-7.5.jar
au Build Path

Programmer un plug-in

Maintenant que tu as installé les outils nécessaires, voyons comment tu peux programmer ton premier plug-in pour Sweet Home 3D.

Créer la classe du plug-in

D’abord, crée une nouvelle sous-classe de com.eteks.sweethome3d.plugin.Plugin en choisissant l’élément de menu File > New > Class dans Eclipse.

Figure 3. Création d’une nouvelle classe

Dans la boîte de dialogue New Java Class, entre VolumePlugin comme nom de classe, entre un package (ici le package choisi était com.eteks.test), et choisis com.eteks.sweethome3d.plugin.Plugin comme super classe de VolumePlugin. Une fois fait, clique sur Finish. Eclipse créera le fichier de la nouvelle classe avec le contenu suivant : 

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 tu peux le deviner à partir du commentaire TODO, tu dois maintenant modifier l’implémentation de la méthode getActions pour retourner une action de plug-in capable de calculer le volume des meubles déplaçables. Remplace return null; par l’instruction suivante : 

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

et choisis Edition > Quick Fix dans le menu d’Eclipse pour créer la classe manquante VolumeAction, comme montré dans la figure 4.

Figure 4. Utilisation de Quick fix pour générer une classe manquante

Dans la boîte de dialogue New Java Class qui apparaît, coche la case Enclosing type pour créer une classe interne de VolumePlugin et clique sur Finish. 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 quand l’utilisateur lancera l’action du plug-in ; c’est donc ici que tu dois implémenter comment calculer le volume des meubles et l’afficher :

  public class VolumeAction extends PluginAction {  
  @Override
  public void execute() { 
  float volumeInCm3 = 0;
 // Calcule la somme du volume de la boîte englobante de 
 // chaque meuble déplaçable dans la maison
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Affiche le résultat dans une boîte de message (³ est pour 3 en exposant)
 String message = String. format(
 "Le volume maximum des meubles déplaçables dans la maison est de %.2f m³.", 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

Maintenant que tu as spécifié ce que tu veux que le plug-in fasse, tu dois décrire comment l’utilisateur lancera cette nouvelle action. Tu as 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 à sa création. Par exemple, si tu veux que les utilisateurs lancent l’action de volume avec l’élément de menu Calculer le volume trouvé dans le menu Outils, tu ajouteras le constructeur suivant à la classe VolumeAction : 

  public VolumeAction() {
           putPropertyValue(Property.NAME, "Calculer le volume");
           putPropertyValue(Property.MENU, "Outils");
 // Active l'action par défaut
           setEnabled(true);
 }

La classe 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 le 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 supporté, et les aspects légaux. Choisis File > New > File dans le menu d’Eclipse, entre le nom de fichier ApplicationPlugin.properties et clique sur Finish, comme montré dans la figure 5.

Figure 5. Création d’un nouveau fichier

Puis entre la description suivante dans le nouveau fichier et sauvegarde-le :

name=Volume des meubles déplaçables
class=com.eteks.test.VolumePlugin
description=Calcule le volume des meubles déplaçables dans la maison
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Créer le 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 tu le sauvegardes, tu dois simplement choisir File > Export… dans le menu et sélectionner Java > JAR file dans la boîte de dialogue Export qui s’affichera. Dans l’assistant Jar Export qui apparaît comme montré dans la figure 6, coche la case du projet et entre le chemin d’un fichier JAR placé dans le dossier des plug-ins de Sweet Home 3D. Ce dossier approprié dépend de ton système comme suit :

Figure 6. Exportation vers un fichier JAR

Tester le plug-in

Le plug-in que tu as développé fonctionnera dans Sweet Home 3D, soit avec la version Java Web Start, la version des installeurs, ou le SweetHome3D-7.5.jar que tu as téléchargé précédemment. Comme ce dernier est un JAR exécutable, tu peux l’exécuter en double-cliquant dessus ou avec la commande suivante :

Le plug-in que tu as développé fonctionnera dans Sweet Home 3D, soit avec la version Java Web Start, la version des installeurs, ou le SweetHome3D-7.5.jar que tu as téléchargé précédemment. Comme ce dernier est un JAR exécutable, tu peux l’exécuter en double-cliquant dessus ou avec la commande suivante : 

java -jar /chemin/vers/SweetHome3D-7.5.jar

Tant que tu testes, tu préféreras probablement exécuter Sweet Home 3D avec cette commande, pour pouvoir lire dans la console la trace des exceptions lancées pendant l’exécution de ton plug-in.

Une fois Sweet Home 3D lancé, tu verras le nouveau menu et son élément apparaître comme montré dans la figure 7 :

Figure 7. Menu du plug-in

Si tu choisis le nouvel élément de menu pour l’exemple de maison créé dans le guide de l’utilisateur, tu obtiendras le résultat suivant :

Figure 8. Plug-in en action

Déboguer le plug-in

Si tu dois déboguer ton plug-in depuis Eclipse, crée une configuration de débogage en suivant ces étapes :

Figure 9. Création d’une configuration de débogage
Figure 10. Configuration du classpath de la configuration de débogage
Figure 11. Configuration du chemin source de la configuration de débogage
Figure 12. Perspective de débogage Eclipse

Chaque fois que tu modifies le code source de ton plug-in, n’oublie pas de générer le JAR du plug-in avant de lancer la configuration de débogage que tu as créée. Pour accélérer le processus d’exportation JAR dans Eclipse, va à la deuxième étape de l’assistant d’exportation JAR et sélectionne l’option Save the description of this JAR in the workspace. Cela ajoutera un nouvel élément dans le projet avec un élément de menu contextuel Create JAR.

Déployer le plug-in

Une fois prêt, ton 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 plug-in peut aussi être installé dans le dossier de plug-ins de Sweet Home 3D en double-cliquant dessus, si son extension est SH3P (change simplement l’extension du fichier de .zip à .sh3p). Si double-cliquer sur un fichier .sh3p ne lance pas Sweet Home 3D (plus de chances sous Linux), tu peux aussi 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 installeurs Sweet Home 3D) :

/chemin/vers/SweetHome3D /chemin/vers/plugin.sh3p

Pour arrêter d’utiliser un plug-in, retire son fichier du dossier de plug-ins et relance Sweet Home 3D.

Si tu veux que ton plug-in puisse fonctionner avec tous les installeurs Sweet Home 3D disponibles sur ce site web, prends soin de le garder compatible avec Java 5, en sélectionnant 1.5 dans le champ Compiler compliance level disponible dans la section Java Compiler de la boîte de dialogue affichée par l’élément de menu Project > Properties d’Eclipse.
Si tu utilises une version du compilateur Java où la compatibilité Java 1.5 n’est plus disponible, essaie de cibler au moins Java 1.8 toujours utilisé dans les versions récentes de Sweet Home 3D et définis javaMinimumVersion dans le fichier ApplicationPlugin.properties de ton plug-in en conséquence.

Aller plus loin

La programmation du premier plug-in t’a donné une vue d’ensemble. Voici des informations supplémentaires qui t’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 d’Application), générée avec l’outil javadoc.
Utilise uniquement les classes des packages com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools et com.eteks.sweethome3d.viewcontroller dans ton plug-in si tu veux qu’il soit compatible avec les futures versions de Sweet Home 3D. Ce sera largement suffisant pour programmer n’importe quel plug-in qui travaille sur les données du logement disponibles dans Sweet Home 3D.
Les packages correspondant aux autres couches du programme sont inclus dans la Javadoc à titre informatif uniquement. Ne te fie pas à leur API, car elle pourrait encore changer à l’avenir sans garantie de compatibilité ascendante (de toute façon, tu ne verras 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 mentionnés précédemment).

Architecture des classes du modèle

Sweet Home 3D est basé sur une architecture MVC (Modèle Vue Contrôleur), donc comprendre comment est organisée sa couche Modèle est essentiel. 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 model-classes-diagram
Figure 13. UML diagram of com.eteks.sweethome3d.model package
(click on a class to view its javadoc)

La classe centrale de la couche Modèle est la classe HomeApplication (10), la super classe abstraite de la classe principale de l’application SweetHome3D. L’instance de cette classe donne accès aux instances de 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 les meubles (17) et les textures (18).
Une instance de Home (7) stocke tous les objets que l’utilisateur a créés dans le plan de la maison :

Ces objets implémentent l’interface Selectable (1) ainsi que l’objet ObserverCamera (4), qui stocke l’emplacement de la caméra en mode Visiteur virtuel. Toutes les informations externes gérées par les objets du 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 t’aider à comprendre quelles classes sont disponibles dans le modèle Sweet Home 3D et comment tu peux y accéder, mais tu remarqueras probablement qu’aucun constructeur ni mutateur (ou setter si tu préfères) n’y est cité. C’est juste par manque de place mais tu peux les utiliser sans problème dans une classe de plug-in. Note aussi que toute modification d’un objet existant du modèle sera notifiée aux composants affichés soit avec des PropertyChangeEvents, des CollectionEvents (8) ou des SelectionEvents (6), permettant ainsi que tous les changements soient immédiatement reflétés à 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 contient seulement trois classes parmi lesquelles tu es supposé utiliser uniquement les classes Plugin et PluginAction, comme montré dans la figure 14 (également disponible au format PDF).

UML Diagram plugin-classes-diagram
Figure 14. UML diagram of com.eteks.sweethome3d.plugin package
(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’un nouveau logement est édité, 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 comme éléments de menu et/ou boutons de barre d’outils dans la fenêtre du logement. Chaque action est une instance de PluginAction, qui ressemble à la classe Action, avec sa méthode execute et ses propriétés modifiables (2).

Note que la classe Plugin te donne accès à une instance d’UndoableEditSupport via sa méthode getUndoableEditSupport. Dès que tu modifies un logement ou ses objets (meubles, murs…) dans la méthode execute d’une instance de PluginAction, tu dois aussi 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 changements que tu as effectués.

Localisation

Si tu prévois de développer un plug-in pour la communauté d’utilisateurs de Sweet Home 3D, essaie de localiser les chaînes qu’il affiche, que ce soit dans le nom des actions et menus ou dans les boîtes de dialogue que tu créeras (ou au moins prépare sa localisation). Deux constructeurs de la classe PluginAction t’aideront à organiser la traduction des propriétés des actions avec des fichiers .properties, et si tu as besoin de traduire d’autres chaînes dans ton plug-in (comme celle dans la boîte de dialogue affichée par le plug-in testé) réutilise ces fichiers .properties avec la classe Java ResourceBundle.
Si tu préfères limiter le nombre de fichiers properties, tu peux même écrire les valeurs des propriétés d’action et d’autres chaînes dans le fichier de description ApplicationPlugin.properties de ton plug-in.

Si tu veux un exemple qui utilise cette architecture, télécharge le plug-in Export to SH3F disponible sur https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p, et décompresse-le (ce fichier de plug-in contient aussi 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 tu as importés dans le catalogue de meubles de Sweet Home 3D.

Contribution de plug-ins

Tu peux poster les plug-ins que tu as programmés dans le système de suivi des Contributions de Plug-ins pour les partager avec la communauté d’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’un logement comme le Plug-in Home Rotator développé par Michel Mbem et d’autres listés dans le Tutoriel pour les Plug-ins et Extensions (PDF) écrit par Hans Dirkse et dans la page Plug-ins et outils.

This site is registered on wpml.org as a development site. Switch to a production site key to remove this banner.