DownloadOnlineGaleria

Guia do desenvolvedor de plug-ins

Introdução

A partir da versão 1.5, é possível adicionar novas funcionalidades ao Sweet Home 3D com arquivos de plug-in colocados na sua pasta de plug-ins. Isso permite que programadores Java desenvolvam e distribuam novas funcionalidades para o Sweet Home 3D sem modificar os arquivos fonte da versão atual (o que é bom para compatibilidade futura), e sem entregar uma versão completa do programa (o que é bom para o tamanho da entrega).
Este documento descreve as ferramentas necessárias para criar plug-ins, depois mostra como programar um plug-in que calcula o volume máximo dos móveis móveis adicionados a uma casa, e finalmente fornece algumas informações adicionais que te ajudarão a ir além.

Instalando ferramentas de desenvolvimento

Se o Sweet Home 3D é destinado a um público geral, desenvolver plug-ins requer habilidades especiais, e você deve saber como programar em Java com uma IDE, antes de prosseguir. Este guia mostra como construir um plug-in com o Eclipse, mas você pode usar a IDE de sua escolha, ou nenhuma IDE.

Baixar e instalar o Eclipse

Primeiro baixe o Eclipse de https://www.eclipse.org/. A versão chamada Eclipse IDE for Java Developers é suficiente para desenvolver um plug-in, mas você pode baixar qualquer versão para desenvolvimento Java.
Uma vez baixado, instalar o Eclipse é muito simples: apenas descompacte o arquivo que você obteve, abra a pasta eclipse e dependendo do seu sistema, execute o arquivo chamado eclipse.exe (no Windows), eclipse.app (no Mac OS X) ou eclipse (no Linux).
Na primeira execução, o Eclipse solicitará que você escolha uma pasta de workspace, onde serão armazenados os projetos de plug-in.
Depois disso, escolha File > New > Project no menu para criar um novo projeto, selecione Java > Java project no assistente New project que será exibido, digite VolumePlugin como nome do projeto e clique no botão Finish. Finalmente, feche a aba Welcome para descobrir seu workspace como mostrado na figura 1.

Guia do desenvolvedor de plug-ins
Figura 1. Workspace do Eclipse

Baixar e instalar a biblioteca do Sweet Home 3D

O desenvolvimento de um plug-in é baseado em algumas classes do Sweet Home 3D que o Eclipse deve conhecer para poder construir seu projeto. A maneira mais fácil de adicionar as classes do Sweet Home 3D ao Eclipse é baixar a versão JAR executável do Sweet Home 3D disponível em https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. Uma vez baixado, arraste e solte o arquivo SweetHome3D-7.5.jar no ícone do projeto VolumePlugin na visualização Package Explorer do Eclipse, e escolha o item Build Path > Add to Build Path no menu contextual do arquivo SweetHome3D-7.5.jar, como mostrado na figura 2.

Figura 2. Adicionando SweetHome3D-7.5.jar
ao Build Path

Programando um plug-in

Agora que você instalou as ferramentas necessárias, vamos ver como você pode programar seu primeiro plug-in para o Sweet Home 3D.

Criando a classe do plug-in

Primeiro, crie uma nova subclasse de com.eteks.sweethome3d.plugin.Plugin escolhendo o item de menu File > New > Class no Eclipse.

Figura 3. Criando uma nova classe

Na caixa de diálogo New Java Class, digite VolumePlugin como nome da classe, insira um pacote (aqui o pacote escolhido foi com.eteks.test), e escolha com.eteks.sweethome3d.plugin.Plugin como a superclasse de VolumePlugin. Depois disso, clique em Finish. O Eclipse criará o arquivo da nova classe com o seguinte conteúdo: 

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 você pode adivinhar pelo comentário TODO, você deve agora alterar a implementação do método getActions para retornar uma ação de plug-in capaz de calcular o volume dos móveis móveis. Substitua return null; pela seguinte declaração: 

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

e escolha Edition > Quick Fix no menu do Eclipse para criar a classe VolumeAction ausente, como mostrado na figura 4.

Figura 4. Usando Quick fix para gerar uma classe ausente

Na caixa de diálogo New Java Class que aparece, selecione a caixa de seleção Enclosing type para criar uma classe interna de VolumePlugin e clique em Finish. Isso criará a classe VolumeAction que herda da classe com.eteks.sweethome3d.plugin.PluginAction e contém um método execute vazio: 

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

Este método é aquele que o Sweet Home 3D chamará quando o usuário iniciar a ação do plug-in; portanto, este é o lugar onde você deve implementar como calcular o volume dos móveis e exibi-lo:

  public class VolumeAction extends PluginAction {  
  @Override
  public void execute() { 
  float volumeInCm3 = 0;
 // Calcula a soma do volume da caixa delimitadora de 
 // cada peça de móvel móvel na casa
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Exibe o resultado em uma caixa de mensagem (³ é para 3 em sobrescrito)
 String message = String. format(
 "O volume máximo dos móveis móveis na casa é %.2f m³.", 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

Agora que você especificou o que quer que o plug-in faça, você deve descrever como o usuário iniciará esta nova ação. Você tem a escolha entre adicionar um novo item de menu a um menu, e/ou um novo botão à barra de ferramentas. Esta escolha é feita definindo as propriedades apropriadas da ação do plug-in em sua criação. Por exemplo, se você quer que os usuários iniciem a ação de volume com o item de menu Calcular volume encontrado no menu Ferramentas, você adicionará o seguinte construtor à classe VolumeAction: 

  public VolumeAction() {
           putPropertyValue(Property.NAME, "Calcular volume");
           putPropertyValue(Property.MENU, "Ferramentas");
 // Habilita a ação por padrão
           setEnabled(true);
 }

A classe do plug-in VolumePlugin está agora programada e quase pronta para funcionar como um plug-in no Sweet Home 3D. As duas últimas coisas a fazer são:

Criando o arquivo de descrição do plug-in

Um arquivo ApplicationPlugin.properties descreve o nome do plug-in, sua classe, as versões mínimas do Sweet Home 3D e Java sob as quais ele é suportado, e questões legais. Escolha File > New > File do menu do Eclipse, digite o nome do arquivo ApplicationPlugin.properties e clique em Finish, como mostrado na figura 5.

Figura 5. Criando um novo arquivo

Então insira a seguinte descrição no novo arquivo e salve-o:

name=Volume de móveis móveis
class=com.eteks.test.VolumePlugin
description=Calcula o volume dos móveis móveis na casa
version=1.0
license=GNU GPL
provider=(C) Direitos autorais 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Criando o JAR do plug-in

O JAR do plug-in contém os arquivos de classe criados a partir da compilação do arquivo VolumePlugin.java, e o arquivo ApplicationPlugin.properties. Como o Eclipse compila um arquivo Java assim que você o salva, você só precisa escolher File Export… do menu e selecionar Java JAR file na caixa de diálogo Export que será exibida. No assistente Jar Export que aparece como mostrado na figura 6, selecione a caixa de seleção do projeto e digite o caminho de um arquivo JAR colocado na pasta de plug-ins do Sweet Home 3D. Esta pasta apropriada depende do seu sistema da seguinte forma:

Figura 6. Exportando para um arquivo JAR

Testando o plug-in

O plug-in que você desenvolveu funcionará no Sweet Home 3D, seja com a versão Java Web Start, a versão dos instaladores, ou o SweetHome3D-7.5.jar que você baixou anteriormente. Como o último é um JAR executável, você pode executá-lo clicando duas vezes nele ou com o seguinte comando:

O plug-in que você desenvolveu funcionará no Sweet Home 3D, seja com a versão Java Web Start, a versão dos instaladores, ou o SweetHome3D-7.5.jar que você baixou anteriormente. Como o último é um JAR executável, você pode executá-lo clicando duas vezes nele ou com o seguinte comando: 

java -jar /caminho/para/SweetHome3D-7.5.jar

Enquanto você estiver testando, você provavelmente preferirá executar o Sweet Home 3D com este comando, para poder ler no console o rastreamento de pilha das exceções lançadas durante a execução do seu plug-in.

Uma vez que o Sweet Home 3D é iniciado, você verá o novo menu e seu item aparecerem como mostrado na figura 7:

Figura 7. Menu do plug-in

Se você escolher o novo item de menu para o exemplo de casa criado no guia do usuário, você obterá o seguinte resultado:

Figura 8. Plug-in em ação

Depurando o plug-in

Se você precisar depurar seu plug-in do Eclipse, crie uma configuração de depuração seguindo estes passos:

Figura 9. Criando uma configuração de depuração
Figura 10. Configurando o classpath da configuração de depuração
Figura 11. Configurando o caminho fonte da configuração de depuração
Figura 12. Perspectiva de depuração do Eclipse

Cada vez que você modificar o código fonte do seu plug-in, não se esqueça de gerar o JAR do plug-in antes de iniciar a configuração de depuração que você criou. Para acelerar o processo de exportação do JAR no eclipse, vá para o segundo passo do assistente de exportação do JAR e selecione a opção Save the description of this JAR in the workspace. Isso adicionará um novo item no projeto com um item de menu contextual Create JAR.

Implantando o plug-in

Uma vez pronto, seu plug-in pode ser implantado no computador de outros usuários do Sweet Home 3D simplesmente copiando-o em sua pasta de plug-ins. A partir da versão 1.6, um arquivo de plug-in também pode ser instalado na pasta de plug-ins do Sweet Home 3D clicando duas vezes nele, se sua extensão for SH3P (simplesmente mude a extensão do arquivo de .zip para .sh3p). Se clicar duas vezes em um arquivo .sh3p não iniciar o Sweet Home 3D (mais chances no Linux), você também pode instalar um plug-in com o seguinte comando em uma janela do Terminal (onde SweetHome3D é o nome do arquivo executável fornecido com os instaladores do Sweet Home 3D):

/caminho/para/SweetHome3D /caminho/para/plugin.sh3p

Para parar de usar um plug-in, remova seu arquivo da pasta de plug-ins e reinicie o Sweet Home 3D.

Se você quiser que seu plug-in seja capaz de executar com todos os instaladores do Sweet Home 3D disponíveis neste site, tome cuidado para mantê-lo compatível com Java 5, selecionando 1.5 no campo Compiler compliance level disponível na seção Java Compiler da caixa de diálogo mostrada pelo item de menu Project > Properties do Eclipse.
Se você usar uma versão do compilador Java onde a compatibilidade com Java 1.5 não está mais disponível, tente direcionar pelo menos para Java 1.8 ainda usado em versões recentes do Sweet Home 3D e defina javaMinimumVersion no arquivo ApplicationPlugin.properties do seu plug-in de acordo.

Indo além

A programação do primeiro plug-in mostrou-te o panorama geral. Aqui tens algumas informações adicionais que te ajudarão a ir mais longe.

API do Sweet Home 3D – javadoc

A documentação mais útil para desenvolver um novo plug-in é a API do Sweet Home 3D (Interface de Programação de Aplicações), gerada com a ferramenta javadoc.
Usa apenas as classes dos pacotes com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools e com.eteks.sweethome3d.viewcontroller no teu plug-in se quiseres que seja compatível com versões futuras do Sweet Home 3D. Isto será amplamente suficiente para programar qualquer plug-in que trabalhe com os dados da casa disponíveis no Sweet Home 3D.
Os pacotes correspondentes às outras camadas do programa estão incluídos no Javadoc apenas para fins informativos. Não te baseies na sua API, pois pode ainda mudar no futuro sem garantia de compatibilidade ascendente (de qualquer forma, não verás nenhuma referência a uma classe dos pacotes com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io ou com.eteks.sweethome3d nos pacotes mencionados anteriormente).

Arquitetura das classes do modelo

O Sweet Home 3D baseia-se numa arquitetura MVC (Model View Controller), por isso compreender como está organizada a sua camada Model é essencial. A figura 13 (disponível também em formato PDF) apresenta quase todas as classes e interfaces disponíveis na versão 1.5 do pacote com.eteks.sweethome3d.model que corresponde a esta camada Model.

UML Diagram model-classes-diagram
Figure 13. UML diagram of com.eteks.sweethome3d.model package
(click on a class to view its javadoc)

A classe central na camada Model é a classe HomeApplication (10), a superclasse abstrata da classe principal da aplicação SweetHome3D. A instância desta classe dá acesso às instâncias Home (7) atualmente editadas, e ao objeto UserPreferences (11) que armazena a unidade de comprimento em uso (12), o catálogo de móveis (14) e o catálogo de texturas (15) a partir dos quais o utilizador escolhe peças de mobiliário (17) e texturas (18).
Uma instância Home (7) armazena todos os objetos que o utilizador criou na planta da casa:

Estes objetos implementam a interface Selectable (1) bem como o objeto ObserverCamera (4), que armazena a localização da câmara no modo Visitante virtual. Toda a informação externa gerida pelos objetos Model, como o ícone e o modelo 3D de uma peça de mobiliário (16), ou a imagem de uma textura (20) é acedida através da interface Content (19), implementada pela classe URLContent e outras classes do pacote com.eteks.sweethome3d.tools.

Este diagrama UML deve ajudar-te a compreender quais classes estão disponíveis no modelo do Sweet Home 3D e como podes aceder a elas, mas provavelmente notarás que nenhum construtor e nenhum mutador (ou setters se preferires) são citados nele. É apenas por falta de espaço, mas podes usá-los sem problema numa classe de plug-in. Nota também que qualquer modificação de um objeto existente do modelo será notificada aos componentes exibidos seja com PropertyChangeEvents, com CollectionEvents (8) ou com SelectionEvents (6), permitindo assim que todas as alterações sejam refletidas imediatamente no ecrã.

O modelo do Sweet Home 3D não é thread safe por razões de desempenho. Todas as modificações de um objeto pertencente ao modelo devem ser feitas no Event Dispatch Thread.

Arquitetura das classes de plug-in

A arquitetura das classes de plug-in é muito mais simples de compreender do que a da camada Model. O pacote com.eteks.sweethome3d.plugin contém apenas três classes entre as quais deves usar apenas as classes Plugin e PluginAction, como mostrado na figura 14 (também disponível em formato PDF).

UML Diagram plugin-classes-diagram
Figure 14. UML diagram of com.eteks.sweethome3d.plugin package
(click on a class to view its javadoc)

Uma instância PluginManager (1) é criada no arranque da aplicação e procura os plug-ins instalados na pasta de plug-ins do utilizador. Cada vez que uma nova casa é editada, este gestor instancia e configura um objeto Plugin (3) para cada plug-in encontrado no momento do arranque. Depois, chama o método getActions para recuperar todas as ações (4) que serão adicionadas como itens de menu e/ou botões da barra de ferramentas na janela da casa. Cada ação é uma instância de PluginAction, que se parece com a classe Action, com o seu método execute e as suas propriedades modificáveis (2).

Nota que a classe Plugin dá-te acesso a uma instância UndoableEditSupport através do seu método getUndoableEditSupport. Assim que modificares uma casa ou os seus objetos (móveis, paredes…) no método execute de uma instância PluginAction, deves também publicar um objeto UndoableEdit no suporte de edição anulável retornado pelo método getUndoableEditSupport, caso contrário os utilizadores não conseguirão desfazer/refazer corretamente as alterações que fizeste.

Localização

Se planeias desenvolver um plug-in para a comunidade de utilizadores do Sweet Home 3D, tenta localizar as strings que exibe seja nos nomes das ações e menu ou nos diálogos que criares (ou pelo menos prepara a sua localização). Dois construtores da classe PluginAction ajudar-te-ão a organizar a tradução das propriedades das ações com ficheiros .properties, e se precisares de traduzir outras strings no teu plug-in (como a do diálogo mostrado pelo plug-in testado) reutiliza estes ficheiros .properties com a classe Java ResourceBundle.
Se preferires limitar o número de ficheiros de propriedades, podes até escrever os valores das propriedades das ações e outras strings no ficheiro de descrição ApplicationPlugin.properties do teu plug-in.

Se quiseres um exemplo que usa esta arquitetura, descarrega o plug-in Export to SH3F disponível em https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p, e descompacta-o (este ficheiro de plug-in contém também o código fonte do plug-in).
Como descrito no fórum de Ajuda, este plug-in cria um ficheiro SH3F que contém todos os móveis que importaste no catálogo de móveis do Sweet Home 3D.

Contribuir com plug-ins

Podes publicar os plug-ins que programaste no Sistema de Rastreamento Contribuições de Plug-ins para os partilhares com a comunidade de utilizadores do Sweet Home 3D.
Muitas funcionalidades podem ser adicionadas ao Sweet Home 3D graças aos plug-ins, desde importadores a exportadores, mas também plug-ins capazes de modificar os dados de uma casa como o Home Rotator Plug-in desenvolvido por Michel Mbem e outros listados no Tutorial para Plug-ins e Extensões (PDF) escrito por Hans Dirkse e na página Plug-ins e ferramentas.

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