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

Въведение

От версия 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 в съветника New project, който ще се покаже, въведете VolumePlugin като име на проекта и щракнете върху бутона Finish. Накрая затворете раздела Welcome, за да откриете работното си пространство, както е показано на фигура 1.

Изтеглете и инсталирайте библиотеката 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.

Програмиране на приставка

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

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

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

В диалоговия прозорец 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.

В диалоговия прозорец 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;
 // 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);
  }
  }

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

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

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

• създаване на ApplicationPlugin.properties файл с описание,
• поставяне на файловете заедно в JAR файл.
  

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

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

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

name=Movable furniture volume
class=com.eteks.test.VolumePlugin
description=Computes the volume of the movable furniture in home
version=1.0
license=GNU GPL
provider=(C) Copyrights 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Създаване на JAR на приставката

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

• под Windows Vista / 7 / 8 / 10 / 11, тази папка е C:\Users\потребител\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• под Windows XP и предишни версии на Windows, тази папка е C:\Documents and Settings\потребител\Application Data\eTeks\Sweet Home 3D\plugins,
• под macOS, това е подпапката Library/Application Support/eTeks/Sweet Home 3D/plugins на вашата потребителска папка,
• под Linux и други Unix, това е подпапката .eteks/sweethome3d/plugins на вашата потребителска папка.

Тестване на приставката

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

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

java -jar /път/до/SweetHome3D-7.5.jar

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

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

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

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

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

• Изберете Run > Debug Configurations… от менюто, изберете елемента Java Application в списъка с налични конфигурации на Debug configurations диалогов прозорец, щракнете върху бутона New в горния ляв ъгъл и въведете име за конфигурацията.
• Щракнете върху бутона Search… вдясно от текстовото поле Main class и щракнете двукратно върху класа SweetHome3DBootstrap
  сред предложените класове.

• Щракнете върху раздела Classpath, изберете под елемента VolumePlugin (default classpath) на елемента User Entries в списъка Classpath и щракнете върху бутона Remove.
• Щракнете върху елемента User Entries в списъка Classpath, щракнете върху бутона Add JARs…, изберете елемента SweetHome3D-7.5.jar и потвърдете избора си.

• Изберете раздела Source, щракнете върху бутона Add…, щракнете двукратно върху елемента Java Project в диалоговия прозорец Add Source, изберете елемента VolumePlugin в изскачащия прозорец Project Selection и потвърдете избора си.

• Накрая щракнете върху бутона Debug, за да стартирате Sweet Home 3D в режим на отстраняване на грешки. След като програмата работи, отворете файла VolumePlugin.java, задайте точка на прекъсване в метода execute и изберете Tools > Compute volume от менюто на Sweet Home 3D. Eclipse ще спре на избраната точка на прекъсване, за да ви позволи да изпълните програмата стъпка по стъпка и да инспектирате стойността на променливите.

Разгръщане на приставката

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

/път/до/SweetHome3D /път/до/plugin.sh3p

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

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

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

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 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)“]

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

• списъкът с обекти HomePieceOfFurniture (13), които имплементират интерфейса PieceOfFurniture (16),
• колекцията от обекти Wall (9),
• списъкът с обекти Room (5),
• колекцията от обекти DimensionLine (2),
• колекцията от обекти Label (3).

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

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

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

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

Един 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://test.sweethome3d.eu/plugins/ExportToSH3F-1.0.sh3p, и го разархивирайте (този файл на плъгина съдържа и изходния код на плъгина).
Както е описано във форума за помощ, този плъгин създава SH3F файл, който съдържа всички мебели, които сте импортирали в каталога с мебели на Sweet Home 3D.

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

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