Spis treści
Indeks 🔎︎

# Dodatki programowania w LibreOffice Calc

Opisana poniżej metoda rozszerzania programu Calc przez stosowanie dodatków jest przestarzała. Interfejsy są w dalszym ciągu prawidłowe i obsługiwane w celu zapewnienia zgodności z istniejącymi dodatkami, ale do programowania nowych dodatków należy używać nowych funkcji API.

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 libraryexternal DLL so that the Add-In can be successfully attached.

LibreOffice searches the Add-in folder defined in the configuration for a suitable shared libraryDLL. To be recognized by LibreOffice, the shared libraryDLL 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.

## Koncepcja dodatku

Każda biblioteka dodatków zawiera kilka funkcji. Niektóre z nich są używane w celach administracyjnych. Własne funkcje mogą mieć prawie dowolne nazwy. Jednak być muszą także zgodne z pewnymi regułami dotyczącymi przekazywania parametrów. Szczegółowe konwencje nazewnictwa i wywoływania zależą od systemu.

### Functions of Shared LibraryAddIn DLL

Funkcje administracyjne biblioteki muszą obejmować co najmniej funkcje GetFunctionCount i GetFunctionData. Służą one do określenia funkcji oraz parametrów i zwracanych wartości. Obsługiwane typy zwracanych wartości to liczby podwójnej precyzji i ciągi znakowe. Jako parametry obsługiwane są dodatkowo obszary komórek macierz podwójnej precyzji, macierz ciągów oraz macierz komórek.

Parametry są przekazywane z wykorzystaniem odwołań. W związku z tym, zasadniczo możliwa jest zmiana tych wartości. Jednak nie jest to obsługiwane przez program LibreOffice Calc, ponieważ nie ma to sensu podczas pracy z arkuszami kalkulacyjnymi.

Biblioteki można przeładowywać podczas pracy programu, a ich zawartość może być analizowana przez funkcje administracyjne Dla każdej funkcji dostępna jest informacja dotycząca liczby i typu parametrów, wewnętrznej i zewnętrznej nazwy funkcji, a także jej numeru administracyjnego.

Funkcje są wywoływane synchronicznie i natychmiast zwracają wyniki. Funkcje czasu rzeczywistego (funkcje asynchroniczne) są także możliwe, jednak nie zostały szczegółowo wyjaśnione ze względu na swoją złożoność.

## Ogólne informacje dotyczące interfejsu

Maksymalna liczba parametrów funkcji dodatkowej dołączonej do programu LibreOffice Calc wynosi 16: jedna wartość zwracana i maksymalnie 15 wejściowych parametrów funkcji.

Typy danych są zdefiniowane następująco:

Typy danych: | Definicja
--- | ---
CALLTYPE | W systemie Windows: FAR PASCAL (_far _pascal) Inne: domyślny (domyślny dla określonego systemu operacyjnego)
USHORT | 2-bajtowa całkowita bez znaku
DOUBLE | 8-bajtowy format zależny od platformy
Paramtype | Zależny od platformy, podobnie jak liczba całkowita PTR_DOUBLE = 0 wskaźnik do liczby podwójnej precyzji PTR_STRING = 1 wskaźnik do ciągu zakończonego zerem PTR_DOUBLE_ARR = 2 wskaźnik do macierzy podwójnej precyzji PTR_STRING_ARR = 3 wskaźnik do macierzy ciągów PTR_CELL_ARR = 4 wskaźnik do macierzy komórek NONE(brak) = 5

## Shared LibraryDLL functions

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

For all Shared LibraryDLL 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()

Zwraca liczbę funkcji bez funkcji zarządzających parametru odwołania. Każda funkcja ma unikatowy numer od 0 do nCount-1, który jest wykorzystywany później przez funkcje GetFunctionData i GetParameterDescription.

Składnia

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parametr

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()

Określa wszystkie istotne informacje dotyczące funkcji dodatkowej.

Składnia

void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)

Parametr

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 LibraryDLL. 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.

Parametry pFuncName i pInternalName są macierzami znakowymi o rozmiarze 256 zaimplementowanymi w programie LibreOffice Calc.

### GetParameterDescription()

Zawiera krótki opis funkcji dodatkowej wraz z jej parametrami. Opcjonalnie funkcja może być używana do wyświetlenia opisu funkcji i parametrów w Kreatorze funkcji.

Składnia

void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)

Parametr

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].

Parametry pName i pDesc są macierzami znakowymi o rozmiarze 256 zaimplementowanymi w programie LibreOffice Calc. Należy zwrócić uwagę, że miejsce dostępne w Kreatorze funkcji jest ograniczone i 256 znaków nie można wykorzystać w całości.

## Obszary komórek

Poniższa tabela zawiera informacje o danych, których struktury muszą zostać dostarczone przez zewnętrzny moduł programowy w celu przekazania obszarów komórek. Program LibreOffice Calc rozróżnia trzy typy macierzy zależnie od typu danych.

### Macierz liczb podwójnej precyzji

Przekazany parametr może być obszarem komórek o wartościach liczbowych/podwójnej precyzji. Macierz liczb podwójnej precyzji jest zdefiniowana w programie LibreOffice Calc w następujący sposób:

Offset | Name | Description
--- | --- | ---
0 | Col1 | Numer kolumny w lewym górnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
2 | Row1 | Numer wiersza w lewym górnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
4 | Tab1 | Numer tabeli w lewym górnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
6 | Col2 | Numer kolumny w prawym dolnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
8 | Row2 | Numer wiersza w prawym dolnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
10 | Tab2 | Numer tabeli w prawym dolnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
12 | Count | Numer kolejnych elementów. Puste komórki nie są liczone i przekazywane.
14 | Col | Numer kolumny elementu. Numeracja rozpoczyna się od 0.
16 | Row | Numer wiersza elementu. Numeracja rozpoczyna się od 0.
18 | Tab | Numer tabeli elementu. Numeracja rozpoczyna się od 0.
20 | Error | Numer błędu, gdzie wartość 0 została zdefiniowana jako "brak błędu". Jeśli element pochodzi z komórki zawierającej formułę, błąd jest określany przez formułę.
22 | Value | 8-bajtowa zmienna IEEE podwójnej precyzji lub zmiennoprzecinkowa
30 | ... | Następny element

### Macierz ciągów znakowych

Macierz komórek zawierająca wartości typu tekstowego przekazywana jako macierz ciągów znakowych. Macierz ciągów znakowych jest zdefiniowana w programie LibreOffice Calc w następujący sposób:

Przesunięcie | Nazwa | Opis
--- | --- | ---
0 | Col1 | Numer kolumny w lewym górnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
2 | Row1 | Numer wiersza w lewym górnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
4 | Tab1 | Numer tabeli w lewym górnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
6 | Col2 | Numer kolumny w prawym dolnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
8 | Row2 | Numer wiersza w prawym dolnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
10 | Tab2 | Numer tabeli w prawym dolnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
12 | Count | Numer kolejnych elementów. Puste komórki nie są liczone i przekazywane.
14 | Col | Numer kolumny elementu. Numeracja rozpoczyna się od 0.
16 | Row | Numer wiersza elementu. Numeracja rozpoczyna się od 0.
18 | Tab | Numer tabeli elementu. Numeracja rozpoczyna się od 0.
20 | Error | Numer błędu, gdzie wartość 0 została zdefiniowana jako "brak błędu". Jeśli element pochodzi z komórki zawierającej formułę, błąd jest określany przez formułę.
22 | Len | Długość następującego ciągu uwzględniająca zamykający bajt zerowy. Jeśli długość ciągu uwzględniająca zamykający bajt zerowy jest nieparzysta, dodawany jest kolejny bajt zerowy w celu osiągnięcia długości parzystej. Zatem parametr Len jest obliczany w następujący sposób: ((StrLen+2)&~1).
24 | String | Ciąg wraz z zamykającym bajtem zerowym
24+Len | ... | Następny element

### Macierz komórek

Macierze komórek służą do wywoływania obszarów komórek zawierających tekst lub liczby. Macierz komórek jest zdefiniowana w programie LibreOffice Calc w następujący sposób:

Offset | Name | Description
--- | --- | ---
0 | Col1 | Numer kolumny w lewym górnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
2 | Row1 | Numer wiersza w lewym górnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
4 | Tab1 | Numer tabeli w lewym górnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
6 | Col2 | Numer kolumny w prawym dolnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
8 | Row2 | Numer wiersza w prawym dolnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
10 | Tab2 | Numer tabeli w prawym dolnym rogu obszaru komórek. Numeracja rozpoczyna się od 0.
12 | Count | Numer kolejnych elementów. Puste komórki nie są liczone i przekazywane.
14 | Col | Numer kolumny elementu. Numeracja rozpoczyna się od 0.
16 | Row | Numer wiersza elementu. Numeracja rozpoczyna się od 0.
18 | Tab | Numer tabeli elementu. Numeracja rozpoczyna się od 0.
20 | Error | Numer błędu, gdzie wartość 0 została zdefiniowana jako "brak błędu". Jeśli element pochodzi z komórki zawierającej formułę, błąd jest określany przez formułę.
22 | Type | Typ zawartości komórki, 0 == podwójna precyzja, 1 == ciąg
24 | Value lub Len | Jeśli typ == 0: 8-bajtowa zmienna IEEE podwójnej precyzji/zmiennoprzecinkowa Jeśli typ == 1: Długość następującego ciągu uwzględniająca zamykający bajt zerowy. Jeśli długość ciągu uwzględniająca zamykający bajt zerowy jest nieparzysta, dodawany jest kolejny bajt zerowy w celu osiągnięcia długości parzystej. Zatem parametr Len jest obliczany w następujący sposób: ((StrLen+2)&~1).
26 jeśli typ ==1 | String | Jeśli typ == 1: Ciąg wraz z zamykającym bajtem zerowym
32 lub 26+Len | ... | Następny element