Introdução
A partir da versão 1.5, é possível adicionar novos recursos ao Sweet Home 3D com arquivos de plug-in colocados na sua pasta de plug-ins. Isso permite que programadores Java desenvolvam e distribuam novos recursos para o Sweet Home 3D sem modificar os arquivos de origem da versão atual (o que é bom para a compatibilidade ascendente) e sem fornecer 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 o ajudarão a ir mais longe.
Instalando ferramentas de desenvolvimento
Se o Sweet Home 3D for destinado a um público geral, o desenvolvimento de plug-ins requer habilidades especiais, e você deve saber como programar em Java com um IDE, antes de prosseguir. Este guia mostra como construir um plug-in com o Eclipse, mas você pode usar o IDE de sua escolha ou nenhum IDE.
Baixe e instale o Eclipse
Primeiro, baixe o Eclipse em 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.
Depois de baixado, instalar o Eclipse é muito simples: basta descompactar o arquivo que você receberá, abrir a pasta do Eclipse e, dependendo do seu sistema, executar o arquivo chamado eclipse.exe (no Windows), eclipse.app (no Mac OS X) ou eclipse (no Linux).
Na primeira execução, o Eclipse exigirá que você escolha uma pasta de workspace, onde os projetos de plug-in serão armazenados.
Depois de feito, escolha Arquivo > Novo > Projeto no menu para criar um novo projeto, selecione Java > Projeto Java no assistente Novo projeto que será exibido, insira VolumePlugin como nome do projeto e clique no botão Concluir. Finalmente, feche a guia Bem-vindo para descobrir seu workspace, como mostrado na figura 1.
Baixe e instale a biblioteca 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 classes do Sweet Home 3D ao Eclipse é baixar a versão JAR executável do Sweet Home 3D disponível em
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 Sweet Home 3D.
Criando a classe de plug-in
Primeiro, crie uma nova subclasse de com.eteks.sweethome3d.plugin.Plugin escolhendo o item de menu Arquivo > Novo > Classe no Eclipse.
Na caixa de diálogo Nova Classe Java, insira VolumePlugin como o 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 de feito, clique em
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 imaginar pelo comentário TODO, agora você deve 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 Edição > Correção Rápida no menu do Eclipse para criar a classe VolumeAction ausente, como mostrado na figura 4.
Na caixa de diálogo Nova Classe Java que aparece, marque a caixa de seleção Tipo delimitador para criar uma classe interna de VolumePlugin e clique em Concluir. 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;
// 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);
}
}
Agora que você especificou o que deseja que o plug-in faça, você deve descrever como o usuário iniciará esta nova ação. Você tem a opção de 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ê quiser 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 VolumnAction:
public VolumeAction() {
putPropertyValue(Property.NAME, "Compute volume");
putPropertyValue(Property.MENU, "Tools");
// Enables the action by default
setEnabled(true);
}
A classe de plug-in VolumePlugin agora está programada e quase pronta para funcionar como um plug-in no Sweet Home 3D. As duas últimas coisas a fazer são:
- criar um arquivo de descrição ApplicationPlugin.properties,
- colocar os arquivos juntos em um arquivo JAR.
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 informações legais. Escolha Arquivo > Novo > Arquivo no menu do Eclipse, insira o nome do arquivo ApplicationPlugin.properties e clique em Concluir, como mostrado na figura 5.
Em seguida, insira a descrição a seguir 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 em casa
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5
Criando o JAR do plug-in
O JAR do plug-in contém os arquivos class 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ê
- no Windows Vista / 7 / 8 / 10 / 11, esta pasta é C:\Users\usuário\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
- no Windows XP e versões anteriores do Windows, esta pasta é C:\Documents and Settings\usuário\Application Data\eTeks\Sweet Home 3D\plugins,
- no macOS, é a subpasta Library/Application Support/eTeks/Sweet Home 3D/plugins da sua pasta de usuário,
- no Linux e outros Unix, é a subpasta .eteks/sweethome3d/plugins da sua pasta de usuário.
Testando o plug-in
O plug-in que você desenvolveu será executado no Sweet Home 3D, seja com a versão Java Web Start, a versão 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 será executado no Sweet Home 3D, seja com a versão Java Web Start, a versão 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, 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.
Depois que o Sweet Home 3D for iniciado, você verá o novo menu e seu item aparecerem como mostrado na figura 7:
Se você escolher o novo item de menu para o exemplo de casa criado no guia do usuário, você obterá o seguinte resultado:
Depurando o plug-in
Se você precisar depurar seu plug-in no Eclipse, crie uma configuração de depuração seguindo estas etapas:
- Escolha Executar > Configurações de depuração… no menu, selecione o item Aplicativo Java na lista de configurações disponíveis da caixa de diálogo Configurações de depuração, clique no botão Novo na parte superior esquerda e insira um nome para a configuração.
- Clique no botão Pesquisar… à direita do campo de texto Classe principal e clique duas vezes na classe SweetHome3DBootstrap
entre as classes propostas.
- Clique na guia Classpath, selecione o subitem VolumePlugin (classpath padrão) do item Entradas do usuário na lista Classpath e clique no botão Remover.
- Clique no item Entradas do usuário na lista Classpath, clique no botão Adicionar JARs…, selecione o item SweetHome3D-7.5.jar e confirme sua escolha.
- Selecione a guia Origem, clique no botão Adicionar…, clique duas vezes no item Projeto Java na caixa de diálogo Adicionar Origem, selecione o item VolumePlugin no popup Seleção de Projeto e confirme sua escolha.
- Finalmente, clique no botão Depurar para iniciar o Sweet Home 3D no modo de depuração. Depois que o programa estiver em execução, abra o arquivo VolumePlugin.java, defina um ponto de interrupção no método execute e escolha Ferramentas > Calcular volume no menu do Sweet Home 3D. O Eclipse parará no ponto de interrupção selecionado para permitir que você execute o programa passo a passo e inspecione o valor das variáveis.
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 a segunda etapa do assistente de exportação do JAR e selecione a opção Salvar a descrição deste JAR no workspace. Isso adicionará um novo item no projeto com um item de menu contextual Criar JAR.
Implantando o plug-in
Depois de 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 altere a extensão do arquivo de .zip para .sh3p). Se clicar duas vezes em um arquivo .sh3p não iniciar o Sweet Home 3D (maior probabilidade no Linux), você também pode instalar um plug-in com o seguinte comando em uma janela de 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 possa ser executado com todos os instaladores do Sweet Home 3D disponíveis neste site, tome cuidado para mantê-lo compatível com o Java 5, selecionando 1.5 no campo Nível de conformidade do compilador disponível na seção Compilador Java da caixa de diálogo mostrada pelo item de menu Projeto > Propriedades 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 o 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 mais longe
A programação do primeiro plug-in mostrou a você o panorama geral. Aqui estão algumas informações adicionais que o 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.
Use apenas as classes dos pacotes com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools e com.eteks.sweethome3d.viewcontroller no seu plug-in se quiser que ele seja compatível com versões futuras do Sweet Home 3D. Isso será suficiente para programar qualquer plug-in que funcione com os dados da casa disponíveis no Sweet Home 3D.
Os pacotes que correspondem às outras camadas do programa estão incluídos no Javadoc apenas para fins informativos. Não confie na API deles, pois ela ainda pode mudar no futuro sem garantia de compatibilidade (de qualquer forma, você não verá 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).
Arquitetura das classes do modelo
O Sweet Home 3D é baseado em uma arquitetura MVC (Model View Controller), portanto, entender como sua camada de Modelo é organizada é 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 de Modelo.
[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)”]
A classe central na camada de Modelo é a classe HomeApplication (10), a superclasse abstrata da classe principal do aplicativo SweetHome3D. A instância desta classe dá acesso às instâncias de 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 usuário escolhe peças de mobiliário (17) e texturas (18).
Uma instância de Home (7) armazena todos os objetos que o usuário criou na planta da casa:
- a lista de objetos HomePieceOfFurniture (13) que implementam a interface PieceOfFurniture (16),
- a coleção de objetos Wall (9),
- a lista de objetos Room (5),
- a coleção de objetos DimensionLine (2),
- a coleção de objetos Label (3).
Esses objetos implementam a interface Selectable (1), bem como o objeto ObserverCamera (4), que armazena a localização da câmera no modo Visitante virtual. Todas as informações externas gerenciadas por objetos do Modelo, como o ícone e o modelo 3D de uma peça de mobiliário (16), ou a imagem de uma textura (20) são acessadas através da interface Content (19), implementada pela classe URLContent e outras classes do pacote com.eteks.sweethome3d.tools.
Este diagrama UML deve ajudá-lo a entender quais classes estão disponíveis no modelo do Sweet Home 3D e como você pode acessá-las, mas você provavelmente notará que nenhum construtor e nenhum mutador (ou setters, se preferir) são citados nele. É apenas por falta de espaço, mas você pode usá-los sem problema em uma classe de plug-in. Observe também que qualquer modificação de um objeto existente do modelo será notificada aos componentes exibidos com PropertyChangeEvents, com CollectionEvents (8) ou com SelectionEvents (6), permitindo assim que todas as alterações sejam refletidas imediatamente na tela.
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 na Event Dispatch Thread.
Arquitetura das classes de plug-in
A arquitetura das classes de plug-in é muito mais simples de entender do que a da camada de Modelo. O pacote com.eteks.sweethome3d.plugin contém apenas três classes, entre as quais você deve usar apenas as classes Plugin e PluginAction, como mostrado na figura 14 (também disponível em formato 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)”]
Uma instância de PluginManager (1) é criada na inicialização do aplicativo e procura os plug-ins instalados na pasta de plug-ins do usuário. Cada vez que uma nova casa é editada, este gerenciador instancia e configura um objeto Plugin (3) para cada plug-in encontrado no momento da inicialização. Em seguida, ele 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 seu método execute e suas propriedades modificáveis (2).
Observe que a classe Plugin lhe dá acesso a uma instância de UndoableEditSupport através de seu método getUndoableEditSupport. Assim que você modificar uma casa ou seus objetos (móveis, paredes…) no método execute de uma instância de PluginAction, você também deve postar um objeto UndoableEdit para o suporte de edição desfazível retornado pelo método getUndoableEditSupport, caso contrário, os usuários não poderão desfazer/refazer corretamente as alterações que você fez.
Localização
Se você planeja desenvolver um plug-in para a comunidade de usuários do Sweet Home 3D, tente localizar as strings que ele exibe, seja no nome e menu das ações ou nas caixas de diálogo que você criar (ou pelo menos prepare sua localização). Dois construtores da classe PluginAction irão ajudá-lo a organizar a tradução das propriedades das ações com arquivos .properties, e se você precisar traduzir outras strings em seu plug-in (como a mostrada na caixa de diálogo do plug-in testado), reutilize esses arquivos .properties com a classe Java ResourceBundle.
Se você preferir limitar o número de arquivos de propriedade, você pode até mesmo escrever os valores das propriedades da ação e outras strings no arquivo de descrição ApplicationPlugin.properties do seu plug-in.
Se você quiser um exemplo que use esta arquitetura, baixe o plug-in Export to SH3F disponível em https://test.sweethome3d.eu/plugins/ExportToSH3F-1.0.sh3p e descompacte-o (este arquivo de plug-in também contém o código-fonte do plug-in).
Conforme descrito no Fórum de Ajuda, este plug-in cria um arquivo SH3F que contém todos os móveis que você importou para o catálogo de móveis do Sweet Home 3D.
Contribuindo com plug-ins
Você pode postar os plug-ins que você programou no Sistema de Rastreamento de Contribuições de Plug-ins para compartilhá-los com a comunidade de usuários do Sweet Home 3D.
Muitos recursos podem ser adicionados ao Sweet Home 3D graças aos plug-ins, de importadores a exportadores, mas também plug-ins capazes de modificar os dados de uma casa como o Plug-in Home Rotator 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.
