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

• Введение
• Установка инструментов разработки
• Программирование плагина
• Двигаемся дальше

Введение

Начиная с версии 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 предложит вам выбрать папку рабочей области, в которой будут храниться проекты плагинов.
После этого выберите Файл > Создать > Проект в меню, чтобы создать новый проект, выберите Java > Java project в мастере Новый проект, который отобразится, введите VolumePlugin в качестве имени проекта и нажмите кнопку Готово. Наконец, закройте вкладку Приветствие, чтобы увидеть свою рабочую область, как показано на рисунке 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, выбрав пункт меню Файл > Создать > Класс в Eclipse.

В диалоговом окне Новый класс Java введите VolumePlugin в качестве имени класса, введите пакет (здесь выбран пакет com.eteks.test) и выберите com.eteks.sweethome3d.plugin.Plugin в качестве суперкласса VolumePlugin. После этого нажмите кнопку Готово. 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.

В появившемся диалоговом окне Новый класс Java установите флажок Enclosing type, чтобы создать внутренний класс VolumePlugin, и нажмите кнопку Готово. Это создаст класс 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);
  }
  }

Теперь, когда вы указали, что вы хотите, чтобы плагин делал, вы должны описать, как пользователь будет запускать это новое действие. У вас есть выбор между добавлением нового пункта меню в меню и/или новой кнопки на панель инструментов. Этот выбор делается путем установки соответствующих свойств действия плагина при его создании. Например, если вы хотите, чтобы пользователи запускали действие volume с помощью пункта меню 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, под которыми он поддерживается, и юридические вопросы. Выберите Файл > Создать > Файл из меню Eclipse, введите имя файла ApplicationPlugin.properties и нажмите кнопку Готово, как показано на рисунке 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-файл плагина содержит файлы class, созданные из компиляции файла VolumePlugin.java, и файл ApplicationPlugin.properties. Поскольку Eclipse компилирует файл Java, как только вы его сохраняете, вам просто нужно выбрать Файл > Экспорт… из меню и выбрать Java > JAR file в диалоговом окне Экспорт , которое отобразится. В мастере Jar Export, который появится, как показано на рисунке 6, установите флажок проекта и введите путь к JAR-файлу, помещенному в папку плагинов Sweet Home 3D. Эта подходящая папка зависит от вашей системы следующим образом:

• в Windows Vista / 7 / 8 / 10 / 11 эта папка C:\Users\user\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• в Windows XP и предыдущих версиях Windows эта папка C:\Documents and Settings\user\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 остановится на выбранной точке останова, чтобы позволить вам выполнять программу шаг за шагом и проверять значение переменных.

Каждый раз, когда вы изменяете исходный код своего плагина, не забывайте создавать 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), вы также можете установить плагин с помощью следующей команды в окне Terminal (где SweetHome3D — это имя исполняемого файла, поставляемого с установщиками Sweet Home 3D):

/путь/к/SweetHome3D /путь/к/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.

Центральным классом в слое 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), что позволит немедленно отразить все изменения на экране.

Модель Sweet Home 3D не является потокобезопасной по соображениям производительности. Все изменения объекта, принадлежащего модели, должны выполняться в Event Dispatch Thread.

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

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

Экземпляр 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 благодаря плагинам, от импортеров до экспортеров, а также плагины, способные изменять данные дома, такие как Плагин поворота дома, разработанный Michel Mbem, и другие, перечисленные в Руководстве по плагинам и расширениям (PDF), написанном Hans Dirkse, и на странице Плагины и инструменты.