Phần bổ trợ để lập trình trong LibreOffice Calc
Phương pháp mở rộng Calc bằng cách dùng Phần bổ trợ mà được diễn tả sau đây đã cũ. Những giao diện vẫn còn hợp lệ và được hỗ trợ, để đảm bảo tương thích với các Phần bổ trợ đã có, nhưng để lập trình Phần bổ trợ mới, bạn nên sử dụng các hàm API mới.
LibreOffice Calc có thể được mở rộng dùng Phần bổ trợ, các mô-đun lập trình bên ngoài mà cung cấp các hàm thêm để thao tác bảng tính. Các hàm thêm này được liêt kê trong Trợ lý Hàm, trong phần loại Phần bổ trợ. Nếu bạn muốn lập trình một Phần bổ trợ, bạn có thể tìm biết ở đây những hàm nào phải được xuất bởi thư viện chia sẻDLL bên ngoài để gắn Phần bổ trợ vào một cách thành công.
LibreOffice tìm kiếm qua thư mục Phần bổ trợ được xác định trong cấu hình để tìm một thư viện chia sẻDLL thích hợp. Để được LibreOffice nhận ra, thư viện chia sẻDLL phải có một số thuộc tính nào đó, như được giải thích sau đây. Thông tin này cho phép bạn lập trình Phần bổ trợ riêng cho Trợ lý Hàm của LibreOffice Calc.
Ý niệm Phần bổ trợ
Mỗi thư viện Bổ trợ thì cung cấp vài hàm khác nhau. Một số hàm được sử dụng cho mục đích quản trị. Bạn có thể chọn gần bất cứ tên nào cho hàm riêng. Tuy nhiên, hàm này cũng phải tùy theo một số quy tắc nào đó về gửi tham số. Những quy ước chính xác về đặt tên và gọi hàm sẽ biến đổi trên các nền tảng khác nhau.
Các hàm của Thư viện Chia sẻ DLL bổ trợ
Ít nhất là hai hàm quản trị GetFunctionCount và GetFunctionData phải tồn tại. Sử dụng hai hàm này, có thể quyết định các hàm, kiểu tham số và giá trị trả về. Đối với giá trị trả về, hai kiểu Double (Đôi) và String (Chuỗi) được hỗ trợ. Đối với tham số, những vùng ô Double Array, String Array và Cell Array đều được hỗ trợ.
Tham số được gửi dùng tham chiếu. Vì thế, cơ bản có thể thay đổi các giá trị này. Tuy nhiên, thay đổi này không phải được hỗ trợ trong LibreOffice Calc vì nó không có ích trong bảng tính.
Thư viện có thể được nạp lại trong khi chạy, và các nội dung thư viện có thể được phân tích bởi những hàm quản trị. Đối với mỗi hàm, thông tin sẵn sàng về số đếm và kiểu của tham số, các tên hàm bên trong/ngoài, và một số thứ tự để quản trị.
Những hàm được gọi đồng bộ và trả về kết quả ngay lập tức. Cũng có thể là hàm thời gian thực (hàm không đồng bộ); tuy nhiên, hàm như vậy không được giải thích chi tiết vì tính phức tạp.
Thông tin chung vê giao diện
Số tối đa các tham số trong một hàm Bổ trợ được gắn vào LibreOffice Calc là 16: một giá trị trả về và nhiều nhất 15 tham số nhập vào hàm.
Những kiểu dữ liệu được xác định như theo đây:
|
Kiểu dữ liệu |
Định nghĩa |
|
CALLTYPE |
Dưới Windows: FAR PASCAL (_far _pascal) Khác: mặc định (giá trị mặc định đặc trưng cho hệ điều hành) |
|
USHORT |
Số nguyên không dấu 2 byte |
|
DOUBLE |
Định dạng phụ thuộc vào nền tảng 8-byte |
|
Paramtype |
Phu thuộc vào nền tăng như số nguyên PTR_DOUBLE =0 con trỏ chỉ tới một đôi PTR_STRING =1 con trỏ chỉ tới một chuỗi chấm dứt bằng số không PTR_DOUBLE_ARR =2 con trỏ chỉ tới một mảng đôi PTR_STRING_ARR =3 con trỏ chỉ tới một mảng chuỗi PTR_CELL_ARR =4 con trỏ chỉ tới một mảng ô NONE =5 |
Thư viện Chia sẻDLL functions
Theo đây có mô tả về những hàm này, mà được gọi như là Thư viện Chia sẻexternal DLL.
Cho tất cả các hàm Thư viện Chia sẻDLL, thông tin sau đây áp dụng:
void CALLTYPE fn(out, in1, in2, ...)
Kết xuất: giá trị kết quả
Nhập vào : bất cứ số kiểu nào (đôi&, ký_tự*, đôi*, ký_tự**, Vùng ô), mà Vùng ô là một mảng có kiểu mảng đôi, mảng chuỗi hay mảng ô.
GetFunctionCount()
Trả về số hàm không có các hàm quản trị của tham số tham chiếu. Mỗi hàm có một số thứ tự duy nhất nằm giữa 0 và nCount-1. Số này sẽ cần thiết về sau cho hai hàm GetFunctionData và GetParameterDescription.
Cú pháp
void CALLTYPE GetFunctionCount(USHORT& nCount)
Tham số
USHORT &nCount:
Kết xuất: tham chiếu đến một biến, mà nên chứa số các hàm Bổ trợ. Ví dụ, nếu phần bổ trợ cung cấp 5 hàm cho LibreOffice Calc, thì nCount=5.
GetFunctionData()
Quyết định tất cả thông tin quan trọng về một hàm Bổ trợ.
Cú pháp
void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)
Tham số
USHORT& nNo:
Nhập vào : số thứ tự hàm nằm giữa 0 và nCount-1, kể cả.
char* pFuncName:
Kết xuất: tên hàm như được lập trình viên thấy, như nó được đặt tên trong Thư viện Chia sẻDLL. Tên này không quyết định tên được dùng trong Trợ lý Hàm.
USHORT& nParamCount:
Kết xuất: số tham số trong hàm Bổ trợ. Số này phải lớn hơn 0, vì lúc nào cũng có một giá trị kết quả; giá trị tối đa là 16.
Paramtype* peType:
Kết xuất: con trỏ chỉ tới một mảng chứa chính xác 16 biến có kiểu Paramtype. Những nParamCount mục nhập đầu tiên được điền bằng kiểu tham số thích hợp.
char* pInternalName:
Kết xuất: tên hàm như được người dùng thấy, như nó xuất hiện trong Trợ lý Hàm. Chữ có thể có dấu hai chấm ỡ trên.
Hai tham số pFuncName và pInternalName là mảng ký tự, mà được thực hiện với kích cỡ 256 trong LibreOffice Calc.
GetParameterDescription()
Cung cấp một mô tả ngắn về hàm Bổ trợ và các tham số của nó. Tùy chọn, hàm này cũng có thể được sử dụng để hiển thị một mô tả về hàm và tham số trong Trợ lý Hàm.
Cú pháp
void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)
Tham số
USHORT& nNo:
Nhập vào : số thứ tự của hàm trong thư viện; giữa 0 và nCount-1.
USHORT& nParam:
Nhập vào : Chỉ định cho tham số nào mà mô tả được đưa ra; các tham số bắt đầu ở 1. Nếu nParam là 0, thì mô tả chính nó nên được cung cấp trong pDesc; trong trường hợp này, pName không có nghĩa.
char* pName:
Kết xuất: lấy tên hay kiểu của tham số, v.d. từ « Số », « Chuỗi », « Ngày » v.v. Thực hiện trong LibreOffice Calc như char[256].
char* pDesc:
Kết xuất: lấy mô tả của tham số, v.d. « Giá trị ở đó cần tính vũ trụ. » Thực hiện trong LibreOffice Calc như char[256].
pName và pDesc là mảng ký tự, được thực hiện trong LibreOffice Calc với kích cỡ 256. Ghi chú rằng sức chứa sẵn sàng trong Trợ lý Hàm bị hạn chế, và 256 ký tự không thể được dùng hoàn toàn.
Vùng ô
Những bảng theo đây chứa thông tin về những cấu trúc dữ liệu nào phải được cung cấp bởi một mô-đun chương trình bên ngoài để gửi vùng ô cho hàm. LibreOffice Calc phân biệt ba mảng khác nhau, phụ thuộc vào kiểu dữ liệu.
Mảng Đôi
Như một tham số, một vùng ô có giá trị kiểu Số/Đôi có thể được gửi cho hàm. Một mảng đôi trong LibreOffice Calc được định nghĩa như theo đây:
|
Bù |
Tên |
Mô tả |
|
0 |
Cột1 |
Số thứ tự cột ở góc trên bên trái vùng ô. Đánh số từ 0. |
|
2 |
Hàng1 |
Số thứ tự hàng ở góc trên bên trái vùng ô. Đánh số từ 0. |
|
4 |
Bảng1 |
Số thứ tự bảng ở góc trên bên trái vùng ô. Đánh số từ 0. |
|
6 |
Cột2 |
Số thứ tự cột ở góc dưới bên phải vùng ô. Đánh số từ 0. |
|
8 |
Hàng2 |
Số thứ tự hàng ở góc dưới bên phải vùng ô. Đánh số từ 0. |
|
10 |
Bảng2 |
Số thứ tự bảng ở góc dưới bên phải vùng ô. Đánh số từ 0. |
|
12 |
Đếm |
Số các phần tử theo sau. Ô rỗng không phải được đếm hay gửi cho hàm. |
|
14 |
Cột |
Số thứ tự cột của phần tử. Đánh số từ 0. |
|
16 |
Hàng |
Số thứ tự hàng của phần tử. Đánh số từ 0. |
|
18 |
Bảng |
Số thứ tự bảng của phần tử. Đánh số từ 0. |
|
20 |
Lỗi |
Số thứ tự lỗi, mà giá trị 0 được định nghĩa là « không có lỗi ». Nếu phần tử thuộc về một ô công thưc, thì giá trị được công thức quyết định. |
|
22 |
Giá trị |
Biến IEEE 8-byte có kiểu chấm động/đôi. |
|
30 |
... |
Phần tử sau |
Mảng chuỗi
Một vùng ô, mà chứa giá trị kiểu dữ liệu Văn bản và được gửi cho hàm dưới dạng một mảng chuỗi. Một mảng chuỗi trong LibreOffice Calc được định nghĩa như theo đây:
|
Bù |
Tên |
Mô tả |
|
0 |
Cột1 |
Số thứ tự cột ở góc trên bên trái vùng ô. Đánh số từ 0. |
|
2 |
Hàng1 |
Số thứ tự hàng ở góc trên bên trái vùng ô. Đánh số từ 0. |
|
4 |
Bảng1 |
Số thứ tự bảng ở góc trên bên trái vùng ô. Đánh số từ 0. |
|
6 |
Cột2 |
Số thứ tự cột ở góc dưới bên phải vùng ô. Đánh số từ 0. |
|
8 |
Hàng2 |
Số thứ tự hàng ở góc dưới bên phải vùng ô. Đánh số từ 0. |
|
10 |
Bảng2 |
Số thứ tự bảng ở góc dưới bên phải vùng ô. Đánh số từ 0. |
|
12 |
Đếm |
Số các phần tử theo sau. Ô rỗng không phải được đếm hay gửi cho hàm. |
|
14 |
Cột |
Số thứ tự cột của phần tử. Đánh số từ 0. |
|
16 |
Hàng |
Số thứ tự hàng của phần tử. Đánh số từ 0. |
|
18 |
Bảng |
Số thứ tự bảng của phần tử. Đánh số từ 0. |
|
20 |
Lỗi |
Số thứ tự lỗi, mà giá trị 0 được định nghĩa là « không có lỗi ». Nếu phần tử thuộc về một ô công thưc, thì giá trị được công thức quyết định. |
|
22 |
Dài |
Chiều dài của chuỗi theo sau, gồm có byte số không đóng. Nếu chiều dài gồm có byte số không đóng bằng với một giá trị lẻ, thì một byte số không thứ hai được thêm vào chuỗi để làm một giá trị chẵn. Vì thế, « Dài » được tníh dùng ((StrLen+2)&~1). |
|
24 |
Chuỗi |
Chuỗi có byte số không đóng |
|
24+Dài |
... |
Phần tử sau |
Mảng ô
Mảng ô được dùng để gọi vùng ô chứa văn bản cũng như số. Một mảng ô trong LibreOffice Calc được xác định như theo đây:
|
Bù |
Tên |
Mô tả |
|
0 |
Cột1 |
Số thứ tự cột ở góc trên bên trái vùng ô. Đánh số từ 0. |
|
2 |
Hàng1 |
Số thứ tự hàng ở góc trên bên trái vùng ô. Đánh số từ 0. |
|
4 |
Bảng1 |
Số thứ tự bảng ở góc trên bên trái vùng ô. Đánh số từ 0. |
|
6 |
Cột2 |
Số thứ tự cột ở góc dưới bên phải vùng ô. Đánh số từ 0. |
|
8 |
Hàng2 |
Số thứ tự hàng ở góc dưới bên phải vùng ô. Đánh số từ 0. |
|
10 |
Bảng2 |
Số thứ tự bảng ở góc dưới bên phải vùng ô. Đánh số từ 0. |
|
12 |
Đếm |
Số các phần tử theo sau. Ô rỗng không phải được đếm hay gửi cho hàm. |
|
14 |
Cột |
Số thứ tự cột của phần tử. Đánh số từ 0. |
|
16 |
Hàng |
Số thứ tự hàng của phần tử. Đánh số từ 0. |
|
18 |
Bảng |
Số thứ tự bảng của phần tử. Đánh số từ 0. |
|
20 |
Lỗi |
Số thứ tự lỗi, mà giá trị 0 được định nghĩa là « không có lỗi ». Nếu phần tử thuộc về một ô công thưc, thì giá trị được công thức quyết định. |
|
22 |
Kiểu |
Kiểu nội dung: 0 == Đôi, 1 == Chuỗi |
|
24 |
Giá trị hay Dài |
Nếu kiểu == 0: biến IEEE 8-byte có kiểu chấm động/đôi Nếu kiểu == 1: chiều dài của chuỗi theo sau, gồm có byte số không đóng. Nếu chiều dài gồm có byte số không đóng bằng với một giá trị lẻ, thì một byte số không đóng thứ hai được thêm vào chuỗi để tạo một giá trị chẵn. Vì thế, chiều Dài được tính dùng ((StrLen+2)&~1). |
|
26 nếu kiểu == 1 |
Chuỗi |
Nếu kiểu == 1: chuỗi có byte số không đóng |
|
32 or 26+Dài |
... |
Phần tử sau |