Guía para desarrolladores de plug-ins

• Introducción
• Instalación de herramientas de desarrollo
• Programación de un plug-in
• Yendo más allá

Introducción

A partir de la versión 1.5, es posible añadir nuevas funciones a Sweet Home 3D con archivos de plug-in colocados en su carpeta de plug-ins. Esto permite a los programadores de Java desarrollar y distribuir nuevas funciones para Sweet Home 3D sin modificar los archivos de código fuente de la versión actual (lo cual es bueno para la compatibilidad ascendente) y sin entregar una versión completa del programa (lo cual es bueno para el tamaño de la entrega).
Este documento describe las herramientas necesarias para crear plug-ins, luego muestra cómo programar un plug-in que calcula el volumen máximo de los muebles móviles añadidos a una casa, y finalmente ofrece información adicional que le ayudará a ir más allá.

Instalación de herramientas de desarrollo

Si bien Sweet Home 3D está dirigido a un público general, el desarrollo de plug-ins requiere habilidades especiales, y debe saber programar en Java con un IDE antes de seguir adelante. Esta guía muestra cómo construir un plug-in con Eclipse, pero puede utilizar el IDE de su elección, o ninguno.

Descargar e instalar Eclipse

Primero, descargue Eclipse desde https://www.eclipse.org/. La versión llamada Eclipse IDE for Java Developers es suficiente para desarrollar un plug-in, pero puede descargar cualquier versión para el desarrollo de Java.
Una vez descargado, instalar Eclipse es muy sencillo: simplemente descomprima el archivo que obtendrá, abra la carpeta eclipse y, dependiendo de su sistema, ejecute el archivo llamado eclipse.exe (en Windows), eclipse.app (en Mac OS X) o eclipse (en Linux).
En la primera ejecución, Eclipse le pedirá que elija una carpeta de workspace, donde se almacenarán los proyectos de plug-ins.
Una vez hecho esto, elija File > New > Project en el menú para crear un nuevo proyecto, seleccione Java > Java project en el asistente New project que se mostrará, introduzca VolumePlugin como nombre del proyecto y haga clic en el botón Finish. Finalmente, cierre la pestaña Welcome para descubrir su espacio de trabajo como se muestra en la figura 1.

Descargar e instalar la biblioteca de Sweet Home 3D

El desarrollo de un plug-in se basa en algunas clases de Sweet Home 3D que Eclipse debe conocer para poder construir su proyecto. La forma más fácil de añadir clases de Sweet Home 3D a Eclipse es descargar la versión ejecutable JAR de Sweet Home 3D disponible en https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. Una vez descargado, arrastre y suelte el archivo SweetHome3D-7.5.jar en el icono del proyecto VolumePlugin en la vista Package Explorer de Eclipse, y elija el elemento Build Path > Add to Build Path en el menú contextual del archivo SweetHome3D-7.5.jar, como se muestra en la figura 2.

Programación de un plug-in

Ahora que ha instalado las herramientas necesarias, veamos cómo puede programar su primer plug-in para Sweet Home 3D.

Creación de la clase de plug-in

Primero, cree una nueva subclase de com.eteks.sweethome3d.plugin.Plugin eligiendo el elemento de menú File > New > Class en Eclipse.

En el diálogo New Java Class, introduzca VolumePlugin como nombre de la clase, introduzca un paquete (aquí el paquete elegido fue com.eteks.test), y elija com.eteks.sweethome3d.plugin.Plugin como la superclase de VolumePlugin. Una vez hecho esto, haga clic en Finish. Eclipse creará el archivo de la nueva clase con el siguiente contenido:

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

Como puede adivinar por el comentario TODO, ahora debe cambiar la implementación del método getActions para devolver una acción de plug-in capaz de calcular el volumen de los muebles móviles. Reemplace return null; por la siguiente declaración:

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

y elija Edition > Quick Fix en el menú de Eclipse para crear la clase VolumeAction que falta, como se muestra en la figura 4.

En el diálogo New Java Class que aparece, seleccione la casilla de verificación Enclosing type para crear una clase interna de VolumePlugin y haga clic en Finish. Esto creará la clase VolumeAction que hereda de la clase com.eteks.sweethome3d.plugin.PluginAction y contiene un método execute vacío:

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

Este método es el que Sweet Home 3D llamará cuando el usuario lance la acción del plug-in; por lo tanto, este es el lugar donde debe implementar cómo calcular el volumen de los muebles y mostrarlo:

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

Ahora que ha especificado lo que quiere que haga el plug-in, debe describir cómo el usuario lanzará esta nueva acción. Tiene la opción de añadir un nuevo elemento de menú a un menú, y/o un nuevo botón a la barra de herramientas. Esta elección se realiza estableciendo las propiedades apropiadas de la acción del plug-in en su creación. Por ejemplo, si quiere que los usuarios lancen la acción de volumen con el elemento de menú Compute volume que se encuentra en el menú Tools, añadirá el siguiente constructor a la clase VolumnAction:

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

La clase de plug-in VolumePlugin ya está programada, y casi lista para funcionar como un plug-in en Sweet Home 3D. Las dos últimas cosas que hay que hacer son:

• crear un archivo de descripción ApplicationPlugin.properties,
• poner los archivos juntos en un archivo JAR.
  

Creación del archivo de descripción del plug-in

Un archivo ApplicationPlugin.properties describe el nombre del plug-in, su clase, las versiones mínimas de Sweet Home 3D y Java bajo las cuales es compatible, y aspectos legales. Elija File > New > File del menú de Eclipse, introduzca el nombre de archivo ApplicationPlugin.properties y haga clic en Finish, como se muestra en la figura 5.

Luego introduzca la siguiente descripción en el nuevo archivo y guárdelo:

name=Volumen de muebles móviles
class=com.eteks.test.VolumePlugin
description=Calcula el volumen de los muebles móviles en la casa
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Creación del JAR del plug-in

El JAR del plug-in contiene los archivos class creados a partir de la compilación del archivo VolumePlugin.java, y el archivo ApplicationPlugin.properties. Como Eclipse compila un archivo Java tan pronto como lo guarda, solo tiene que elegir File > Export… del menú y seleccionar Java > JAR file en el diálogo Export que se mostrará. En el asistente Jar Export que aparece como se muestra en la figura 6, seleccione la casilla de verificación del proyecto e introduzca la ruta de un archivo JAR colocado en la carpeta de plug-ins de Sweet Home 3D. Esta carpeta apropiada depende de su sistema de la siguiente manera:

• en Windows Vista / 7 / 8 / 10 / 11, esta carpeta es C:\Users\user\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• en Windows XP y versiones anteriores de Windows, esta carpeta es C:\Documents and Settings\user\Application Data\eTeks\Sweet Home 3D\plugins,
• en macOS, es la subcarpeta Library/Application Support/eTeks/Sweet Home 3D/plugins de su carpeta de usuario,
• en Linux y otros Unix, es la subcarpeta .eteks/sweethome3d/plugins de su carpeta de usuario.

Prueba del plug-in

El plug-in que ha desarrollado se ejecutará en Sweet Home 3D, ya sea con la versión de Java Web Start, la versión de instaladores o el SweetHome3D-7.5.jar que descargó anteriormente. Como el último es un JAR ejecutable, puede ejecutarlo haciendo doble clic en él o con el siguiente comando:

El plug-in que ha desarrollado se ejecutará en Sweet Home 3D, ya sea con la versión de Java Web Start, la versión de instaladores o el SweetHome3D-7.5.jar que descargó anteriormente. Como el último es un JAR ejecutable, puede ejecutarlo haciendo doble clic en él o con el siguiente comando:

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

Mientras esté probando, probablemente preferirá ejecutar Sweet Home 3D con este comando, para poder leer en la consola el stack trace de las excepciones lanzadas durante la ejecución de su plug-in.

Una vez que se inicie Sweet Home 3D, verá el nuevo menú y su elemento aparecer como se muestra en la figura 7:

Si elige el nuevo elemento de menú para el ejemplo de casa creado en la guía del usuario, obtendrá el siguiente resultado:

Depuración del plug-in

Si necesita depurar su plug-in desde Eclipse, cree una configuración de depuración siguiendo estos pasos:

• Elija Run > Debug Configurations… del menú, seleccione el elemento Java Application en la lista de configuraciones disponibles del cuadro de diálogo Debug configurations, haga clic en el botón New en la parte superior izquierda e introduzca un nombre para la configuración.
• Haga clic en el botón Search… a la derecha del campo de texto Main class y haga doble clic en la clase SweetHome3DBootstrap
  entre las clases propuestas.

• Haga clic en la pestaña Classpath, seleccione el subelemento VolumePlugin (default classpath) del elemento User Entries en la lista Classpath y haga clic en el botón Remove.
• Haga clic en el elemento User Entries en la lista Classpath, haga clic en el botón Add JARs…, seleccione el elemento SweetHome3D-7.5.jar y confirme su elección.

• Seleccione la pestaña Source, haga clic en el botón Add…, haga doble clic en el elemento Java Project en el cuadro de diálogo Add Source, seleccione el elemento VolumePlugin en la ventana emergente Project Selection y confirme su elección.

• Finalmente, haga clic en el botón Debug para iniciar Sweet Home 3D en modo de depuración. Una vez que el programa se está ejecutando, abra el archivo VolumePlugin.java, establezca un punto de interrupción en el método execute y elija Tools > Compute volume del menú de Sweet Home 3D. Eclipse se detendrá en el punto de interrupción seleccionado para permitirle ejecutar el programa paso a paso e inspeccionar el valor de las variables.

Cada vez que modifique el código fuente de su plug-in, no olvide generar el JAR del plug-in antes de iniciar la configuración de depuración que creó. Para acelerar el proceso de exportación de JAR en Eclipse, vaya al segundo paso del asistente de exportación de JAR y seleccione la opción Save the description of this JAR in the workspace. Esto añadirá un nuevo elemento en el proyecto con un elemento de menú contextual Create JAR.

Implementación del plug-in

Una vez listo, su plug-in puede ser implementado en el ordenador de otros usuarios de Sweet Home 3D simplemente copiándolo en su carpeta de plug-ins. A partir de la versión 1.6, un archivo de plug-in también puede instalarse en la carpeta de plug-ins de Sweet Home 3D haciendo doble clic en él, si su extensión es SH3P (simplemente cambie la extensión del archivo de .zip a .sh3p). Si hacer doble clic en un archivo .sh3p no inicia Sweet Home 3D (lo más probable es que ocurra en Linux), también puede instalar un plug-in con el siguiente comando en una ventana de Terminal (donde SweetHome3D es el nombre del archivo ejecutable proporcionado con los instaladores de Sweet Home 3D):

/ruta/a/SweetHome3D /ruta/a/plugin.sh3p

Para dejar de usar un plug-in, elimine su archivo de la carpeta de plug-ins y reinicie Sweet Home 3D.

Si quiere que su plug-in pueda ejecutarse con todos los instaladores de Sweet Home 3D disponibles en este sitio web, tenga cuidado de mantenerlo compatible con Java 5, seleccionando 1.5 en el campo Compiler compliance level disponible en la sección Java Compiler del cuadro de diálogo que muestra el elemento de menú Project > Properties de Eclipse.
Si utiliza una versión del compilador de Java donde la compatibilidad con Java 1.5 ya no está disponible, intente dirigirse al menos a Java 1.8 que todavía se utiliza en las versiones recientes de Sweet Home 3D y establezca javaMinimumVersion en el archivo ApplicationPlugin.properties de su plug-in en consecuencia.

Yendo más allá

La programación del primer *plug-in* te mostró la idea general. Aquí tienes información adicional que te ayudará a ir más allá.

API de Sweet Home 3D – javadoc

La documentación más útil para desarrollar un nuevo *plug-in* es la API de Sweet Home 3D (Interfaz de Programación de Aplicaciones), generada con la herramienta javadoc.
Utiliza solo las clases de los paquetes com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools y com.eteks.sweethome3d.viewcontroller en tu *plug-in* si quieres que sea compatible con versiones futuras de Sweet Home 3D. Esto será suficiente para programar cualquier *plug-in* que funcione con los datos de la casa disponibles en Sweet Home 3D.
Los paquetes que coinciden con las otras capas del programa se incluyen en el Javadoc solo con fines informativos. No confíes en su API, ya que aún puede cambiar en el futuro sin garantía de compatibilidad (de todos modos, no verás ninguna referencia a una clase de los paquetes com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io o com.eteks.sweethome3d en los paquetes mencionados).

Arquitectura de las clases del modelo

Sweet Home 3D se basa en una arquitectura MVC (Modelo Vista Controlador), por lo que es esencial comprender cómo está organizada su capa de Modelo. La figura 13 (también disponible en formato PDF) presenta casi todas las clases e interfaces disponibles en la versión 1.5 del paquete com.eteks.sweethome3d.model que coincide con esta capa de Modelo.

La clase central en la capa de Modelo es la clase HomeApplication (10), la superclase abstracta de la clase principal de la aplicación SweetHome3D. La instancia de esta clase da acceso a las instancias de Home (7) que se están editando actualmente, y al objeto UserPreferences (11) que almacena la unidad de longitud en uso (12), el catálogo de muebles (14) y el catálogo de texturas (15) desde el cual el usuario elige muebles (17) y texturas (18).
Una instancia de Home (7) almacena todos los objetos que el usuario creó en el plano de la casa:

• la lista de objetos HomePieceOfFurniture (13) que implementan la interfaz PieceOfFurniture (16),
• la colección de objetos Wall (9),
• la lista de objetos Room (5),
• la colección de objetos DimensionLine (2),
• la colección de objetos Label (3).

Estos objetos implementan la interfaz Selectable (1) así como el objeto ObserverCamera (4), que almacena la ubicación de la cámara en el modo Visitante virtual. Se accede a toda la información externa gestionada por los objetos del Modelo, como el icono y el modelo 3D de un mueble (16), o la imagen de una textura (20) a través de la interfaz Content (19), implementada por la clase URLContent y otras clases del paquete com.eteks.sweethome3d.tools.

Este diagrama UML debería ayudarte a comprender qué clases están disponibles en el modelo de Sweet Home 3D y cómo puedes acceder a ellas, pero probablemente notarás que no se citan constructores ni mutadores (o *setters* si lo prefieres). Es solo por falta de espacio, pero puedes usarlos sin problema en una clase de *plug-in*. Ten en cuenta también que cualquier modificación de un objeto existente del modelo se notificará a los componentes mostrados ya sea con PropertyChangeEvents, con CollectionEvents (8) o con SelectionEvents (6), lo que permitirá que todos los cambios se reflejen inmediatamente en la pantalla.

El modelo de Sweet Home 3D no es seguro para subprocesos por razones de rendimiento. Todas las modificaciones de un objeto que pertenece al modelo deben realizarse en el hilo de despacho de eventos.

Arquitectura de las clases de *plug-in*

La arquitectura de las clases de *plug-in* es mucho más sencilla de entender que la de la capa de Modelo. El paquete com.eteks.sweethome3d.plugin contiene solo tres clases entre las cuales se supone que debes usar solo las clases Plugin y PluginAction, como se muestra en la figura 14 (también disponible en formato PDF).

Se crea una instancia de PluginManager (1) al iniciar la aplicación y busca los *plug-ins* instalados en la carpeta de *plug-ins* del usuario. Cada vez que se edita una nueva casa, este administrador crea instancias y configura un objeto Plugin (3) para cada *plug-in* encontrado en el momento del inicio. Luego, llama al método getActions para recuperar todas las acciones (4) que se agregarán como elementos de menú y/o botones de la barra de herramientas en la ventana de la casa. Cada acción es una instancia de PluginAction, que se parece a la clase Action, con su método execute y sus propiedades modificables (2).

Ten en cuenta que la clase Plugin te da acceso a una instancia de UndoableEditSupport a través de su método getUndoableEditSupport. Tan pronto como modifiques una casa o sus objetos (muebles, paredes…) en el método *execute* de una instancia de PluginAction, también debes publicar un objeto UndoableEdit en el soporte de edición deshacible devuelto por el método *getUndoableEditSupport*, de lo contrario, los usuarios no podrán deshacer/rehacer correctamente los cambios que hayas realizado.

Localización

Si planeas desarrollar un *plug-in* para la comunidad de usuarios de Sweet Home 3D, intenta localizar las cadenas que muestra, ya sea en el nombre de las acciones y el menú o en los diálogos que crearás (o al menos prepara su localización). Dos constructores de la clase PluginAction te ayudarán a organizar la traducción de las propiedades de las acciones con archivos .properties, y si necesitas traducir otras cadenas en tu *plug-in* (como la del diálogo que muestra el *plug-in* probado) reutiliza estos archivos .properties con la clase Java ResourceBundle.
Si prefieres limitar el número de archivos de propiedades, incluso podrías escribir los valores de las propiedades de la acción y otras cadenas en el archivo de descripción ApplicationPlugin.properties de tu *plug-in*.

Si quieres un ejemplo que utilice esta arquitectura, descarga el *plug-in* Export to SH3F disponible en https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p, y descomprímelo (este archivo de *plug-in* también contiene el código fuente del *plug-in*).
Como se describe en el foro de ayuda, este *plug-in* crea un archivo SH3F que contiene todos los muebles que importaste en el catálogo de muebles de Sweet Home 3D.

Contribución de *plug-ins*

Puedes publicar los *plug-ins* que programaste en el Sistema de Seguimiento de Contribuciones de *Plug-ins* para compartirlos con la comunidad de usuarios de Sweet Home 3D.
Se pueden agregar muchas funciones a Sweet Home 3D gracias a los *plug-ins*, desde importadores hasta exportadores, pero también *plug-ins* capaces de modificar los datos de una casa como el *Home Rotator Plug-in* desarrollado por Michel Mbem y otros enumerados en el Tutorial para *Plug-ins* y Extensiones (PDF) escrito por Hans Dirkse y en la página *Plug-ins* y herramientas.