Contents

# 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 can be expanded by Add-Ins, which are external programming modules providing additional functions for working with spreadsheets. These are listed in the Function Wizard in the Add-In category. If you would like to program an Add-In yourself, you can learn here which functions must be exported by the shared library external DLL so that the Add-In can be successfully attached.

LibreOffice searches the Add-in folder defined in the configuration for a suitable shared library DLL. To be recognized by LibreOffice, the shared library DLL must have certain properties, as explained in the following. This information allows you to program your own Add-In for Function Wizard of 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.

### Functions of Shared Library AddIn DLL

Í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

## Shared Library DLL functions

Following you will find a description of those functions, which are called at the Shared Library external DLL.

For all Shared Library DLL functions, the following applies:

void CALLTYPE fn(out, in1, in2, ...)

Output: Resulting value

Input: Any number of types (double&, char*, double*, char**, Cell area), where the Cell area is an array of types double array, string array, or cell array.

### 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:

Output: Reference to a variable, which is supposed to contain the number of Add-In functions. For example: If the Add-In provides 5 functions for LibreOffice Calc, then 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:

Input: Function number between 0 and nCount-1, inclusively.

char* pFuncName:

Output: Function name as seen by the programmer, as it is named in the Shared Library DLL. This name does not determine the name used in the Function Wizard.

USHORT& nParamCount:

Output: Number of parameters in AddIn function. This number must be greater than 0, because there is always a result value; the maximum value is 16.

Paramtype* peType:

Output: Pointer to an array of exactly 16 variables of type Paramtype. The first nParamCount entries are filled with the suitable type of parameter.

char* pInternalName:

Output: Function name as seen by the user, as it appears in the Function Wizard. May contain umlauts.

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:

Input: Number of the function in the library; between 0 and nCount-1.

USHORT& nParam:

Input: Indicates, for which parameter the description is provided; parameters start at 1. If nParam is 0, the description itself is supposed to be provided in pDesc; in this case, pName does not have any meaning.

char* pName:

Output: Takes up the parameter name or type, for example, the word "Number" or "String" or "Date", and so on. Implemented in LibreOffice Calc as char[256].

char* pDesc:

Output: Takes up the description of the parameter, for example, "Value, at which the universe is to be calculated." Implemented in LibreOffice Calc as 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:

Offset | Name | Description
--- | --- | ---
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:

Offset | Name | Description
--- | --- | ---
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+Len | ... | 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:

Offset | Name | Description
--- | --- | ---
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

Please support us!