Hướng dẫn phát triển plug-in

• Giới thiệu
• Cài đặt công cụ phát triển
• Lập trình một plug-in
• Đi xa hơn

Giới thiệu

Từ phiên bản 1.5, có thể thêm các tính năng mới vào Sweet Home 3D bằng các tệp plug-in đặt trong thư mục plug-in của bạn. Điều này cho phép các lập trình viên Java phát triển và phân phối các tính năng mới cho Sweet Home 3D mà không cần sửa đổi các tệp nguồn của phiên bản hiện tại (điều này tốt cho khả năng tương thích ngược), và không cần phân phối toàn bộ phiên bản của chương trình (điều này tốt cho kích thước phân phối).
Tài liệu này mô tả các công cụ cần thiết để tạo plug-in, sau đó hướng dẫn cách lập trình một plug-in tính toán thể tích tối đa của đồ nội thất có thể di chuyển được thêm vào một ngôi nhà, và cuối cùng cung cấp một số thông tin bổ sung sẽ giúp bạn đi xa hơn.

Cài đặt công cụ phát triển

Mặc dù Sweet Home 3D hướng đến đối tượng người dùng phổ thông, việc phát triển plug-in đòi hỏi các kỹ năng đặc biệt, và bạn nên biết cách lập trình bằng Java với một IDE trước khi tiếp tục. Hướng dẫn này chỉ cách xây dựng một plug-in với Eclipse, nhưng bạn có thể sử dụng IDE mà bạn chọn, hoặc không sử dụng IDE nào cả.

Tải và cài đặt Eclipse

Đầu tiên, hãy tải Eclipse từ https://www.eclipse.org/. Phiên bản có tên Eclipse IDE for Java Developers là đủ để phát triển một plug-in, nhưng bạn có thể tải bất kỳ phiên bản nào dành cho phát triển Java.
Sau khi tải xuống, việc cài đặt Eclipse rất đơn giản: chỉ cần giải nén tệp bạn nhận được, mở thư mục eclipse và tùy thuộc vào hệ thống của bạn, chạy tệp có tên eclipse.exe (trên Windows), eclipse.app (trên Mac OS X) hoặc eclipse (trên Linux).
Khi chạy lần đầu tiên, Eclipse sẽ yêu cầu bạn chọn một thư mục workspace, nơi sẽ lưu trữ các dự án plug-in.
Sau khi hoàn thành, chọn File > New > Project từ menu để tạo một dự án mới, chọn Java > Java project trong trình hướng dẫn New project sẽ hiển thị, nhập VolumePlugin làm tên dự án và nhấp vào nút Finish. Cuối cùng, đóng tab Welcome để khám phá không gian làm việc của bạn như trong hình 1.

Tải và cài đặt thư viện Sweet Home 3D

Việc phát triển một plug-in dựa trên một số lớp của Sweet Home 3D mà Eclipse phải biết để có thể xây dựng dự án của bạn. Cách dễ nhất để thêm các lớp Sweet Home 3D vào Eclipse là tải xuống phiên bản JAR thực thi của Sweet Home 3D có sẵn tại https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download. Sau khi tải xuống, kéo và thả tệp SweetHome3D-7.5.jar vào biểu tượng dự án VolumePlugin trong khung nhìn Package Explorer của Eclipse, và chọn mục Build Path > Add to Build Path trong menu ngữ cảnh của tệp SweetHome3D-7.5.jar, như trong hình 2.

Lập trình một plug-in

Bây giờ bạn đã cài đặt các công cụ cần thiết, hãy xem cách bạn có thể lập trình plug-in đầu tiên của mình cho Sweet Home 3D.

Tạo lớp plug-in

Đầu tiên, tạo một lớp con mới của com.eteks.sweethome3d.plugin.Plugin bằng cách chọn mục menu File > New > Class trong Eclipse.

Trong hộp thoại New Java Class, nhập VolumePlugin làm tên lớp, nhập một gói (ở đây gói được chọn là com.eteks.test), và chọn com.eteks.sweethome3d.plugin.Plugin làm lớp cha của VolumePlugin. Sau khi hoàn thành, nhấp vào Finish. Eclipse sẽ tạo tệp của lớp mới với nội dung sau:

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

Như bạn có thể đoán từ bình luận TODO, bây giờ bạn phải thay đổi cách triển khai phương thức getActions để trả về một hành động plug-in có khả năng tính toán thể tích của đồ nội thất có thể di chuyển. Thay thế return null; bằng câu lệnh sau:

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

và chọn Edition > Quick Fix từ menu Eclipse để tạo lớp VolumeAction còn thiếu, như trong hình 4.

Trong hộp thoại New Java Class xuất hiện, chọn hộp kiểm Enclosing type để tạo một lớp nội của VolumePlugin và nhấp vào Finish. Điều này sẽ tạo lớp VolumeAction kế thừa từ lớp com.eteks.sweethome3d.plugin.PluginAction và chứa một phương thức execute trống:

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

Phương thức này là phương thức mà Sweet Home 3D sẽ gọi khi người dùng khởi chạy hành động plug-in; do đó đây là nơi bạn phải triển khai cách tính toán thể tích của đồ nội thất và hiển thị nó:

  public class VolumeAction extends PluginAction {  
  @Override
  public void execute() { 
  float volumeInCm3 = 0;
 // Tính tổng thể tích của hộp bao quanh 
 // mỗi món đồ nội thất có thể di chuyển trong nhà
 for (PieceOfFurniture piece : getHome(). getFurniture()) {
 if (piece. isMovable()) {
 volumeInCm3 += piece. getWidth() 
 * piece. getDepth() 
 * piece. getHeight();
  }
 }
            
 // Hiển thị kết quả trong một hộp thông báo (³ là cho 3 ở dạng mũ)
 String message = String. format(
 "Thể tích tối đa của đồ nội thất có thể di chuyển trong nhà là %.2f m³.", 
 volumeInCm3 / 1000000);
 JOptionPane. showMessageDialog(null, message);
  }
  }

Bây giờ bạn đã chỉ định những gì bạn muốn plug-in thực hiện, bạn phải mô tả cách người dùng sẽ khởi chạy hành động mới này. Bạn có lựa chọn giữa việc thêm một mục menu mới vào menu, và/hoặc một nút mới vào thanh công cụ. Lựa chọn này được thực hiện bằng cách đặt các thuộc tính thích hợp của hành động plug-in khi tạo nó. Ví dụ, nếu bạn muốn người dùng khởi chạy hành động tính thể tích bằng mục menu Tính thể tích trong menu Công cụ, bạn sẽ thêm hàm tạo sau vào lớp VolumeAction:

  public VolumeAction() {
           putPropertyValue(Property.NAME, "Tính thể tích");
           putPropertyValue(Property.MENU, "Công cụ");
 // Kích hoạt hành động theo mặc định
           setEnabled(true);
 }

Lớp plug-in VolumePlugin giờ đã được lập trình và gần như sẵn sàng để hoạt động như một plug-in trong Sweet Home 3D. Hai việc cuối cùng cần làm là:

• tạo một tệp mô tả ApplicationPlugin.properties,
• đóng gói các tệp vào một tệp JAR.
  

Tạo tệp mô tả plug-in

Một tệp ApplicationPlugin.properties mô tả tên plug-in, lớp của nó, các phiên bản tối thiểu của Sweet Home 3D và Java mà nó được hỗ trợ, và các vấn đề pháp lý. Chọn Tệp > Tệp Mới từ menu Eclipse, nhập tên tệp ApplicationPlugin.properties và bấm vào Hoàn tất, như được hiển thị trong hình 5.

Sau đó nhập mô tả sau vào tệp mới và lưu lại:

name=Thể tích đồ nội thất di động
class=com.eteks.test.VolumePlugin
description=Tính toán thể tích của đồ nội thất di động trong nhà
version=1.0
license=GNU GPL
provider=(C) Bản quyền 2024 Space Mushrooms
applicationMinimumVersion=1.5
javaMinimumVersion=1.5

Tạo JAR plug-in

JAR plug-in chứa các tệp class được tạo từ việc biên dịch tệp VolumePlugin.java, và tệp ApplicationPlugin.properties. Khi Eclipse biên dịch một tệp Java ngay khi bạn lưu nó, bạn chỉ cần chọn Tệp > Xuất… từ menu và chọn Java > Tệp JAR trong hộp thoại Xuất sẽ được hiển thị. Trong trình hướng dẫn Xuất JAR xuất hiện như được hiển thị trong hình 6, chọn hộp kiểm dự án và nhập đường dẫn của tệp JAR được đặt trong thư mục plug-ins của Sweet Home 3D. Thư mục phù hợp này phụ thuộc vào hệ thống của bạn như sau:

• trên Windows Vista / 7 / 8 / 10 / 11, thư mục này là C:\Users\user\AppData\Roaming\eTeks\Sweet Home 3D\plugins,
• trên Windows XP và các phiên bản Windows trước đó, thư mục này là C:\Documents and Settings\user\Application Data\eTeks\Sweet Home 3D\plugins,
• trên macOS, nó là thư mục con Library/Application Support/eTeks/Sweet Home 3D/plugins trong thư mục người dùng của bạn
• trên Linux và các Unix khác, nó là thư mục con .eteks/sweethome3d/plugins trong thư mục người dùng của bạn.

Kiểm tra plug-in

Plug-in bạn phát triển sẽ chạy trong Sweet Home 3D, với phiên bản Java Web Start, phiên bản cài đặt, hoặc SweetHome3D-7.5.jar bạn đã tải xuống trước đó. Vì cái cuối cùng là một JAR thực thi, bạn có thể chạy nó bằng cách nhấp đúp vào nó hoặc với lệnh sau:

Plug-in bạn phát triển sẽ chạy trong Sweet Home 3D, với phiên bản Java Web Start, phiên bản cài đặt, hoặc SweetHome3D-7.5.jar bạn đã tải xuống trước đó. Vì cái cuối cùng là một JAR thực thi, bạn có thể chạy nó bằng cách nhấp đúp vào nó hoặc với lệnh sau:

java -jar /đường dẫn/đến/SweetHome3D-7.5.jar

Miễn là bạn đang kiểm tra, bạn có thể thích chạy Sweet Home 3D với lệnh này, để có thể đọc trong bảng điều khiển dấu vết ngăn xếp của các ngoại lệ được ném ra trong quá trình thực thi plug-in của bạn.

Khi Sweet Home 3D được khởi chạy, bạn sẽ thấy menu mới và mục của nó xuất hiện như được hiển thị trong hình 7:

Nếu bạn chọn mục menu mới cho ví dụ về nhà được tạo trong hướng dẫn sử dụng, bạn sẽ nhận được kết quả sau:

Gỡ lỗi plug-in

Nếu bạn cần gỡ lỗi plug-in của mình từ Eclipse, hãy tạo một cấu hình gỡ lỗi bằng cách làm theo các bước sau:

• Chọn Chạy > Cấu hình Gỡ lỗi… từ menu, chọn mục Ứng dụng Java trong danh sách cấu hình có sẵn của hộp thoại Cấu hình Gỡ lỗi, nhấp vào nút Mới ở góc trên bên trái và nhập tên cho cấu hình.
• Nhấp vào nút Tìm kiếm… ở bên phải trường văn bản Lớp chính và nhấp đúp vào lớp SweetHome3DBootstrap
  trong số các lớp được đề xuất.

• Nhấp vào tab Classpath, chọn mục con VolumePlugin (classpath mặc định) của mục User Entries trong danh sách Classpath và nhấp vào nút Xóa.
• Nhấp vào mục User Entries trong danh sách Classpath, nhấp vào nút Thêm JAR…, chọn mục SweetHome3D-7.5.jar và xác nhận lựa chọn của bạn.

• Chọn tab Source, nhấp vào nút Thêm…, nhấp đúp vào mục Java Project trong hộp thoại Thêm Source, chọn mục VolumePlugin trong cửa sổ bật lên Chọn Dự án và xác nhận lựa chọn của bạn.

• Cuối cùng, nhấp vào nút Gỡ lỗi để khởi chạy Sweet Home 3D ở chế độ gỡ lỗi. Khi chương trình đang chạy, mở tệp VolumePlugin.java, đặt một điểm dừng trong phương thức execute và chọn Công cụ > Tính toán thể tích từ menu Sweet Home 3D. Eclipse sẽ dừng tại điểm dừng đã chọn để cho phép bạn thực thi chương trình từng bước và kiểm tra giá trị của các biến.

Mỗi khi bạn sửa đổi mã nguồn của plug-in, đừng quên tạo tệp JAR cho plug-in trước khi khởi chạy cấu hình gỡ lỗi bạn đã tạo. Để tăng tốc quá trình xuất JAR trong eclipse, hãy đi đến bước thứ hai của trình hướng dẫn xuất JAR và chọn tùy chọn Lưu mô tả của JAR này trong không gian làm việc. Điều này sẽ thêm một mục mới trong dự án với một mục menu ngữ cảnh Tạo JAR.

Triển khai plug-in

Khi đã sẵn sàng, plug-in của bạn có thể được triển khai trên máy tính của người dùng Sweet Home 3D khác bằng cách chỉ cần sao chép nó vào thư mục plug-in của họ. Từ phiên bản 1.6, một tệp plug-in cũng có thể được cài đặt vào thư mục plug-in của Sweet Home 3D bằng cách nhấp đúp vào nó, nếu phần mở rộng của nó là SH3P (chỉ cần đổi phần mở rộng tệp từ .zip thành .sh3p). Nếu nhấp đúp vào tệp .sh3p không khởi chạy Sweet Home 3D (khả năng cao nhất là trên Linux), bạn cũng có thể cài đặt plug-in bằng lệnh sau trong cửa sổ Terminal (trong đó SweetHome3D là tên của tệp thực thi được cung cấp với bộ cài đặt Sweet Home 3D):

/đường/dẫn/đến/SweetHome3D /đường/dẫn/đến/plugin.sh3p

Để ngừng sử dụng một plug-in, hãy xóa tệp của nó khỏi thư mục plug-in và khởi động lại Sweet Home 3D.

Nếu bạn muốn plug-in của mình có thể chạy với tất cả bộ cài đặt Sweet Home 3D có sẵn trên trang web này, hãy chú ý giữ cho nó tương thích với Java 5, bằng cách chọn 1.5 trong trường Mức độ tuân thủ trình biên dịch có sẵn trong phần Java Compiler của hộp thoại hiển thị bởi mục menu Dự án > Thuộc tính của Eclipse.
Nếu bạn sử dụng phiên bản trình biên dịch Java mà không còn hỗ trợ tương thích Java 1.5, hãy cố gắng nhắm mục tiêu ít nhất là Java 1.8 vẫn được sử dụng trong các phiên bản gần đây của Sweet Home 3D và đặt javaMinimumVersion trong tệp ApplicationPlugin.properties của plug-in của bạn cho phù hợp.

Đi xa hơn

Việc lập trình plug-in đầu tiên đã cho bạn thấy bức tranh tổng thể. Dưới đây là một số thông tin bổ sung sẽ giúp bạn đi xa hơn.

API Sweet Home 3D – javadoc

Tài liệu hữu ích nhất để phát triển một plug-in mới là API Sweet Home 3D (Giao diện Lập trình Ứng dụng), được tạo ra bằng công cụ javadoc.
Chỉ sử dụng các lớp của các gói com.eteks.sweethome3d.plugin, com.eteks.sweethome3d.model, com.eteks.sweethome3d.tools và com.eteks.sweethome3d.viewcontroller trong plug-in của bạn nếu bạn muốn nó tương thích với các phiên bản tương lai của Sweet Home 3D. Điều này sẽ là đủ để lập trình bất kỳ plug-in nào hoạt động trên dữ liệu nhà có sẵn trong Sweet Home 3D.
Các gói khớp với các lớp khác của chương trình được bao gồm trong Javadoc chỉ với mục đích thông tin. Đừng dựa vào API của chúng, vì nó có thể vẫn thay đổi trong tương lai mà không có bảo đảm về tính tương thích ngược (dù sao bạn sẽ không thấy tham chiếu nào đến một lớp của các gói com.eteks.sweethome3d.swing, com.eteks.sweethome3d.j3d, com.eteks.sweethome3d.io hoặc com.eteks.sweethome3d trong các gói đã đề cập trước đó).

Kiến trúc các lớp Model

Sweet Home 3D dựa trên kiến trúc MVC (Model View Controller), vì vậy việc hiểu cách tổ chức lớp Model của nó là rất quan trọng. Hình 13 (cũng có sẵn ở định dạng PDF) trình bày gần như tất cả các lớp và giao diện có sẵn trong phiên bản 1.5 của gói com.eteks.sweethome3d.model khớp với lớp Model này.

Lớp trung tâm trong lớp Model là lớp HomeApplication (10), lớp cha trừu tượng của lớp chính của ứng dụng SweetHome3D. Thể hiện của lớp này cho phép truy cập vào các thể hiện Home (7) đang được chỉnh sửa, và đối tượng UserPreferences (11) lưu trữ đơn vị độ dài đang sử dụng (12), danh mục nội thất (14) và danh mục kết cấu (15) mà từ đó người dùng chọn các món đồ nội thất (17) và kết cấu (18).
Một thể hiện Home (7) lưu trữ tất cả các đối tượng mà người dùng đã tạo trong bản vẽ nhà:

• danh sách các đối tượng HomePieceOfFurniture (13) thực hiện giao diện PieceOfFurniture (16),
• bộ sưu tập các đối tượng Wall (9),
• danh sách các đối tượng Room (5),
• bộ sưu tập các đối tượng DimensionLine (2),
• bộ sưu tập các đối tượng Label (3).

Các đối tượng này thực hiện giao diện Selectable (1) cũng như đối tượng ObserverCamera (4), lưu trữ vị trí của camera trong chế độ Khách tham quan ảo. Tất cả thông tin bên ngoài được quản lý bởi các đối tượng Model, như biểu tượng và mô hình 3D của một món đồ nội thất (16), hoặc hình ảnh của một kết cấu (20) được truy cập thông qua giao diện Content (19), được thực hiện bởi lớp URLContent và các lớp khác của gói com.eteks.sweethome3d.tools.

Sơ đồ UML này sẽ giúp bạn hiểu các lớp nào có sẵn trong mô hình Sweet Home 3D và cách bạn có thể truy cập chúng, nhưng có lẽ bạn sẽ nhận thấy rằng không có constructor và không có mutator (hoặc setter nếu bạn thích) nào được đề cập trong đó. Đó chỉ là do thiếu không gian nhưng bạn có thể sử dụng chúng mà không gặp vấn đề gì trong một lớp plug-in. Cũng lưu ý rằng bất kỳ sửa đổi nào của một đối tượng hiện có của mô hình sẽ được thông báo cho các thành phần hiển thị bằng PropertyChangeEvent, CollectionEvent (8) hoặc SelectionEvent (6), do đó cho phép tất cả các thay đổi được phản ánh ngay lập tức trên màn hình.

Mô hình Sweet Home 3D không an toàn luồng vì lý do hiệu suất. Tất cả sửa đổi của một đối tượng thuộc mô hình nên được thực hiện trong Luồng Phân phối Sự kiện.

Kiến trúc lớp plug-in

Kiến trúc của các lớp plug-in đơn giản hơn nhiều để hiểu so với lớp Mô hình. Gói com.eteks.sweethome3d.plugin chỉ chứa ba lớp trong đó bạn chỉ nên sử dụng các lớp Plugin và PluginAction, như được hiển thị trong hình 14 (cũng có sẵn ở định dạng PDF).

Một phiên bản PluginManager (1) được tạo khi khởi chạy ứng dụng và tìm kiếm các plug-in được cài đặt trong thư mục plug-ins của người dùng. Mỗi khi một ngôi nhà mới được chỉnh sửa, trình quản lý này sẽ khởi tạo và cấu hình một đối tượng Plugin (3) cho mỗi plug-in được tìm thấy khi khởi chạy. Sau đó, nó gọi phương thức getActions để lấy tất cả hành động (4) sẽ được thêm làm mục menu và/hoặc nút thanh công cụ trong cửa sổ nhà. Mỗi hành động là một phiên bản của PluginAction, trông giống như lớp Action, với phương thức execute và thuộc tính có thể chỉnh sửa của nó (2).

Lưu ý rằng lớp Plugin cung cấp cho bạn quyền truy cập vào một phiên bản UndoableEditSupport thông qua phương thức getUndoableEditSupport. Ngay khi bạn sửa đổi một ngôi nhà hoặc các đối tượng của nó (đồ nội thất, tường…) trong phương thức thực thi của một phiên bản PluginAction, bạn cũng nên đăng một đối tượng UndoableEdit vào hỗ trợ chỉnh sửa có thể hoàn tác được trả về bởi phương thức getUndoableEditSupport, nếu không người dùng sẽ không thể hoàn tác/làm lại chính xác các thay đổi bạn đã thực hiện.

Bản địa hóa

Nếu bạn dự định phát triển một plug-in cho cộng đồng người dùng Sweet Home 3D, hãy cố gắng bản địa hóa các chuỗi mà nó hiển thị trong tên hành động và menu hoặc trong các hộp thoại bạn sẽ tạo (hoặc ít nhất là chuẩn bị bản địa hóa của nó). Hai hàm tạo của lớp PluginAction sẽ giúp bạn tổ chức việc dịch các thuộc tính hành động với các tệp .properties, và nếu bạn cần dịch các chuỗi khác trong plug-in của mình (như chuỗi trong hộp thoại được hiển thị bởi plug-in đã thử nghiệm) hãy tái sử dụng các tệp .properties này với lớp Java ResourceBundle.
Nếu bạn muốn giới hạn số lượng tệp thuộc tính, bạn thậm chí có thể viết các giá trị của các thuộc tính hành động và các chuỗi khác trong tệp mô tả ApplicationPlugin.properties của plug-in của bạn.

Nếu bạn muốn một ví dụ sử dụng kiến trúc này, hãy tải xuống plug-in Export to SH3F có sẵn tại https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p, và giải nén nó (tệp plug-in này cũng chứa mã nguồn của plug-in).
Như được mô tả trong Diễn đàn trợ giúp, plug-in này tạo ra một tệp SH3F chứa tất cả đồ nội thất bạn đã nhập vào danh mục đồ nội thất của Sweet Home 3D.

Đóng góp plug-in

Bạn có thể đăng các plug-in bạn đã lập trình trong Hệ thống Theo dõi Đóng góp Plug-ins để chia sẻ chúng với cộng đồng người dùng Sweet Home 3D.
Nhiều tính năng có thể được thêm vào Sweet Home 3D nhờ các plug-in, từ các trình nhập đến các trình xuất, nhưng cũng có các plug-in có thể sửa đổi dữ liệu của một ngôi nhà như Plug-in Xoay Nhà được phát triển bởi Michel Mbem và các plug-in khác được liệt kê trong Hướng dẫn về Plug-ins và Tiện ích mở rộng (PDF) được viết bởi Hans Dirkse và trong trang Plug-ins và công cụ.