СвалянеOnlineГалерия

Ръководство за разработчици на плъгини

Въведение

От версия 1.5 е възможно да добавяш нови функции към Sweet Home 3D с файлове на плъгини, поставени в твоята папка за плъгини. Това позволява на Java програмистите да разработват и разпространяват нови функции за Sweet Home 3D, без да модифицират изходните файлове на текущата версия (което е добре за съвместимост нагоре), и без да доставят пълна версия на програмата (което е добре за размера на доставката).
Този документ описва инструментите, необходими за създаване на плъгини, след това показва как да програмираш плъгин, който изчислява максималния обем на подвижните мебели, добавени към дома, и накрая дава допълнителна информация, която ще ти помогне да продължиш напред.

Инсталиране на инструменти за разработка

Въпреки че Sweet Home 3D е насочен към широка аудитория, разработването на плъгини изисква специални умения и трябва да можеш да програмираш на Java с IDE, преди да продължиш. Това ръководство показва как да създадеш плъгин с Eclipse, но можеш да използваш IDE по твой избор или изобщо без IDE.

Изтегли и инсталирай Eclipse

Първо изтегли Eclipse от https://www.eclipse.org/. Версията, наречена Eclipse IDE for Java Developers, е достатъчна за разработване на плъгин, но можеш да изтеглиш всяка версия за Java разработка.
След като бъде изтеглен, инсталирането на Eclipse е много просто: просто разархивирай получения архив, отвори папката eclipse и в зависимост от твоята система, стартирай файла на име eclipse.exe (под Windows), eclipse.app (под Mac OS X) или eclipse (под Linux).
При първото стартиране Eclipse ще изиска от теб да избереш папка за работно пространство, където ще се съхраняват проектите за плъгини.
След като приключиш, избери File > New > Project от менюто, за да създадеш нов проект, избери Java > Java project в съветника за нов проект, който ще се покаже, въведи VolumePlugin като име на проекта и щракни върху бутона Finish. Накрая, затвори раздела Welcome, за да разгледаш работното си пространство, както е показано на фигура 1.

Ръководство за разработчици на плъгини
Фигура 1. Работно пространство на Eclipse

Изтегли и инсталирай библиотеката на Sweet Home 3D

Разработването на плъгин се основава на някои класове на Sweet Home 3D, които Eclipse трябва да познава, за да може да изгради твоя проект. Най-лесният начин да добавиш класове на Sweet Home 3D към Eclipse е да изтеглиш изпълнимата JAR версия на Sweet Home 3D, достъпна на https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. След като бъде изтеглен, плъзни и пусни файла SweetHome3D-7.5.jar върху иконата на проекта VolumePlugin в изгледа Package Explorer на Eclipse и избери елемента Build Path > Add to Build Path от контекстното меню на файла SweetHome3D-7.5.jar, както е показано на фигура 2.

Фигура 2. Добавяне на SweetHome3D-7.5.jar
към Build Path

Програмиране на плъгин

След като инсталира необходимите инструменти, нека видим как можеш да програмираш първия си плъгин за Sweet Home 3D.

Създаване на класа на плъгина

Първо, създай нов подклас на com.eteks.sweethome3d.plugin.Plugin, като избереш елемента от менюто File > New > Class в Eclipse.

Фигура 3. Създаване на нов клас

В диалоговия прозорец New Java Class въведи VolumePlugin като име на класа, въведи пакет (тук избраният пакет беше com.eteks.test) и избери com.eteks.sweethome3d.plugin.Plugin като суперклас на VolumePlugin. След като приключиш, щракни върху Finish. Eclipse ще създаде файла на новия клас със следното съдържание: 

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

Както можеш да предположиш от коментара TODO, сега трябва да промениш имплементацията на метода getActions, за да върне действие на плъгин, способно да изчисли обема на подвижните мебели. Замени return null; със следното изявление: 

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

и избери Edition > Quick Fix от менюто на Eclipse, за да създадеш липсващия клас VolumeAction, както е показано на фигура 4.

Фигура 4. Използване на Quick fix за генериране на липсващ клас

В диалоговия прозорец New Java Class, който се появява, избери отметката Enclosing type, за да създадеш вътрешен клас на VolumePlugin, и щракни върху Finish. Това ще създаде класа VolumeAction, който наследява от класа com.eteks.sweethome3d.plugin.PluginAction и съдържа празен метод execute: 

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

Този метод е този, който Sweet Home 3D ще извика, когато потребителят стартира действието на плъгина; следователно това е мястото, където трябва да имплементираш как да изчислиш обема на мебелите и да го покажеш:

  public class VolumeAction extends PluginAction {  
  @Override
  public void execute() { 
  float volumeInCm3 = 0;
 // Изчисли сумата от обема на ограничителната кутия на 
 // всяка подвижна мебел в дома
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Покажи резултата в съобщение (³ е за 3 като горен индекс)
 String message = String. format(
 „Максималният обем на подвижните мебели в дома е %.2f m³.“, 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

След като си посочил какво искаш да прави плъгинът, трябва да опишеш как потребителят ще стартира това ново действие. Имаш избор между добавяне на нов елемент от менюто към меню и/или нов бутон към лентата с инструменти. Този избор се прави чрез задаване на подходящите свойства на действието на плъгина при неговото създаване. Например, ако искаш потребителите да стартират действието за обем с елемента от менюто Compute volume, намиращ се в менюто Tools, ще добавиш следния конструктор към класа VolumnAction: 

  public VolumeAction() {
           putPropertyValue(Property.NAME, „Изчисли обем“);
           putPropertyValue(Property.MENU, „Инструменти“);
 // Активира действието по подразбиране
           setEnabled(true);
 }

Класът на плъгина VolumePlugin вече е програмиран и почти готов да работи като плъгин в Sweet Home 3D. Последните две неща, които остават да се направят, са:

Създаване на описателния файл на плъгина

Файлът ApplicationPlugin.properties описва името на плъгина, неговия клас, минималните версии на Sweet Home 3D и Java, под които се поддържа, и правни неща. Избери File > New > File от менюто на Eclipse, въведи името на файла ApplicationPlugin.properties и щракни върху Finish, както е показано на фигура 5.

Фигура 5. Създаване на нов файл

След това въведи следното описание в новия файл и го запази:

name=Обем на подвижни мебели
class=com.eteks.test.VolumePlugin
description=Изчислява обема на подвижните мебели в дома
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Създаване на JAR на плъгина

JAR файлът на плъгина съдържа class файловете, създадени от компилацията на файла VolumePlugin.java, и файла ApplicationPlugin.properties. Тъй като Eclipse компилира Java файл веднага щом го запазиш, ти просто трябва да избереш File > Export… от менюто и да избереш Java > JAR file в диалоговия прозорец Export, който ще се покаже. В съветника за Jar Export, който се появява, както е показано на фигура 6, избери отметката за проекта и въведи пътя до JAR файл, поставен в папката за плъгини на Sweet Home 3D. Тази подходяща папка зависи от твоята система, както следва:

Фигура 6. Експортиране към JAR файл

Тестване на плъгина

Разработеният от теб плъгин ще работи в Sweet Home 3D, или с версията Java Web Start, версията на инсталаторите, или с SweetHome3D-7.5.jar, който си изтеглил преди това. Тъй като последният е изпълним JAR, можеш да го стартираш, като щракнеш два пъти върху него или със следната команда:

Разработеният от теб плъгин ще работи в Sweet Home 3D, или с версията Java Web Start, версията на инсталаторите, или с SweetHome3D-7.5.jar, който си изтеглил преди това. Тъй като последният е изпълним JAR, можеш да го стартираш, като щракнеш два пъти върху него или със следната команда: 

java -jar /path/to/SweetHome3D-7.5.jar

Докато тестваш, вероятно ще предпочетеш да стартираш Sweet Home 3D с тази команда, за да можеш да четеш в конзолата стека на изключенията, хвърлени по време на изпълнението на твоя плъгин.

След като Sweet Home 3D бъде стартиран, ще видиш новото меню и неговия елемент да се появяват, както е показано на фигура 7:

Фигура 7. Меню на плъгина

Ако избереш новия елемент от менюто за примерния дом, създаден в ръководството за потребителя, ще получиш следния резултат:

Фигура 8. Плъгин в действие

Отстраняване на грешки в плъгина

Ако трябва да отстраниш грешки в плъгина си от Eclipse, създай конфигурация за отстраняване на грешки, като следваш тези стъпки:

Фигура 9. Създаване на конфигурация за отстраняване на грешки
Фигура 10. Задаване на classpath на конфигурацията за отстраняване на грешки
Фигура 11. Задаване на изходния път на конфигурацията за отстраняване на грешки
Фигура 12. Перспектива за отстраняване на грешки в Eclipse

Всеки път, когато модифицираш изходния код на твоя плъгин, не забравяй да генерираш JAR файла на плъгина, преди да стартираш създадената от теб конфигурация за отстраняване на грешки. За да ускориш процеса на експортиране на JAR в Eclipse, отиди на втората стъпка от съветника за експортиране на JAR и избери опцията Save the description of this JAR in the workspace. Това ще добави нов елемент в проекта с контекстен елемент от менюто Create JAR.

Разгръщане на плъгина

След като е готов, твоят плъгин може да бъде разгърнат на компютъра на други потребители на Sweet Home 3D, като просто го копираш в тяхната папка за плъгини. От версия 1.6, файл на плъгин може да бъде инсталиран и в папката за плъгини на Sweet Home 3D чрез двойно щракване върху него, ако разширението му е SH3P (просто промени разширението на файла от .zip на .sh3p). Ако двойното щракване върху .sh3p файл не стартира Sweet Home 3D (най-вероятно под Linux), можеш също да инсталираш плъгин със следната команда в прозорец на терминал (където SweetHome3D е името на изпълнимия файл, предоставен с инсталаторите на Sweet Home 3D):

/path/to/SweetHome3D /path/to/plugin.sh3p

За да спреш да използваш плъгин, премахни файла му от папката за плъгини и рестартирай Sweet Home 3D.

Ако искаш твоят плъгин да може да работи с всички инсталатори на Sweet Home 3D, налични на този уебсайт, погрижи се да го поддържаш съвместим с Java 5, като избереш 1.5 в полето Compiler compliance level, налично в секцията Java Compiler на диалоговия прозорец, показан от елемента от менюто Project > Properties на Eclipse.
Ако използваш версия на Java компилатор, където съвместимостта с Java 1.5 вече не е налична, опитай се да таргетираш поне Java 1.8, която все още се използва в по-новите версии на Sweet Home 3D, и задай javaMinimumVersion в ApplicationPlugin.properties файла на твоя плъгин съответно.

Продължаваме напред

Програмирането на първия плъгин ви показа общата картина. Ето малко допълнителна информация, която ще ви помогне да продължите напред.

Sweet Home 3D API – javadoc

Най-полезната документация за разработване на нов плъгин е Sweet Home 3D API (Application Programming Interface), генерирана с инструмента javadoc.
Използвайте само класовете от пакетите com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools и com.eteks.sweethome3d.viewcontroller във вашия плъгин, ако искате той да бъде съвместим с бъдещи версии на Sweet Home 3D. Това ще бъде напълно достатъчно за програмиране на всеки плъгин, който работи с данните на дома, налични в Sweet Home 3D.
Пакетите, съответстващи на другите слоеве на програмата, са включени в Javadoc само за информационни цели. Не разчитайте на техния API, тъй като той може да се промени в бъдеще без гаранция за съвместимост (все пак няма да видите препратка към клас от пакетите com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io или com.eteks.sweethome3d в споменатите пакети).

Архитектура на класовете на модела

Sweet Home 3D е базиран на архитектура MVC (Model View Controller), така че разбирането на организацията на слоя Model е от съществено значение. Фигура 13 (налична също и в PDF формат) представя почти всички класове и интерфейси, налични във версия 1.5 на пакета com.eteks.sweethome3d.model, който съответства на този слой Model.

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

Централният клас в слоя Model е класът HomeApplication (10), абстрактният супер клас на основния клас на приложението SweetHome3D. Инстанцията на този клас дава достъп до инстанциите Home (7), които се редактират в момента, и до обекта UserPreferences (11), който съхранява използваната мерна единица (12), каталога с мебели (14) и каталога с текстури (15), от които потребителят избира мебели (17) и текстури (18).
Инстанцията Home (7) съхранява всички обекти, които потребителят е създал в плана на дома:

Тези обекти реализират интерфейса Selectable (1), както и обекта ObserverCamera (4), който съхранява местоположението на камерата в режим Виртуален посетител. Цялата външна информация, управлявана от обектите на модела, като иконата и 3D модела на мебел (16) или изображението на текстура (20), се достъпва чрез интерфейса Content (19), реализиран от класа URLContent и други класове от пакета com.eteks.sweethome3d.tools.

Тази UML диаграма трябва да ви помогне да разберете кои класове са налични в модела на Sweet Home 3D и как можете да получите достъп до тях, но вероятно ще забележите, че в нея не са цитирани конструктори и мутатори (или сетъри, ако предпочитате). Това е просто поради липса на място, но можете да ги използвате без проблем в клас на плъгин. Обърнете внимание също, че всяка промяна на съществуващ обект от модела ще бъде уведомена на показаните компоненти или с PropertyChangeEvent събития, с CollectionEvent събития (8) или с SelectionEvent събития (6), което позволява всички промени да бъдат отразени незабавно на екрана.

Моделът на Sweet Home 3D не е безопасен за работа с нишки поради причини, свързани с производителността. Всички промени на обект, принадлежащ към модела, трябва да се извършват в нишката за изпращане на събития.

Архитектура на класовете на плъгините

Архитектурата на класовете на плъгините е много по-проста за разбиране от тази на слоя Model. Пакетът com.eteks.sweethome3d.plugin съдържа само три класа, сред които се предполага, че ще използвате само класовете Plugin и PluginAction, както е показано на фигура 14 (налична също и в PDF формат).

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

Инстанция PluginManager (1) се създава при стартиране на приложението и търси инсталираните плъгини в папката с плъгини на потребителя. Всеки път, когато се редактира нов дом, този мениджър инстанцира и конфигурира обект Plugin (3) за всеки плъгин, намерен при стартиране. След това извиква метода getActions, за да извлече всички действия (4), които ще бъдат добавени като елементи от менюто и/или бутони на лентата с инструменти в прозореца на дома. Всяко действие е инстанция на PluginAction, която изглежда като клас Action, с метода си execute и модифицируемите си свойства (2).

Обърнете внимание, че класът Plugin ви дава достъп до инстанция UndoableEditSupport чрез метода си getUndoableEditSupport. Веднага щом модифицирате дом или неговите обекти (мебели, стени…) в метода execute на инстанция PluginAction, трябва също да публикувате обект UndoableEdit към поддръжката за отменяеми редакции, върната от метода getUndoableEditSupport, в противен случай потребителите няма да могат да отменят/възстановят правилно промените, които сте направили.

Локализация

Ако планирате да разработите плъгин за общността на потребителите на Sweet Home 3D, опитайте се да локализирате низовете, които той показва, както в имената на действията и менюто, така и в диалозите, които ще създадете (или поне подгответе неговата локализация). Два конструктора на класа PluginAction ще ви помогнат да организирате превода на свойствата на действията с .properties файлове, и ако трябва да преведете други низове във вашия плъгин (като този в диалога, показан от тествания плъгин), използвайте отново тези .properties файлове с Java класа ResourceBundle.
Ако предпочитате да ограничите броя на файловете със свойства, можете дори да напишете стойностите на свойствата на действията и други низове в описателния файл ApplicationPlugin.properties на вашия плъгин.

Ако искате пример, който използва тази архитектура, изтеглете плъгина Export to SH3F, наличен на https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p, и го разархивирайте (този плъгин файл съдържа също и изходния код на плъгина).
Както е описано в Форум за помощ, този плъгин създава SH3F файл, който съдържа всички мебели, които сте импортирали в каталога с мебели на Sweet Home 3D.

Принос на плъгини

Можете да публикувате плъгините, които сте програмирали, в Система за проследяване на приноси на плъгини, за да ги споделите с общността на потребителите на Sweet Home 3D.
Много функции могат да бъдат добавени към Sweet Home 3D благодарение на плъгини, от импортери до експортери, но също така и плъгини, които могат да модифицират данните на дома, като Home Rotator Plug-in, разработен от Michel Mbem и други, изброени в Ръководство за плъгини и разширения (PDF), написано от Hans Dirkse и на страницата Плъгини и инструменти.

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