Dodatki programowania w LibreOffice Calc

LibreOffice Calc można rozbudować o dodatki, czyli zewnętrzne moduły programistyczne udostępniające dodatkowe funkcje do pracy z arkuszami kalkulacyjnymi. Są one wymienione w Kreatorze funkcji w kategorii Dodatki. Jeśli chcesz samodzielnie zaprogramować dodatek, możesz dowiedzieć się tutaj, które funkcje muszą zostać wyeksportowane przez , aby można było pomyślnie dołączyć dodatek.

LibreOffice przeszukuje folder dodatku zdefiniowany w konfiguracji pod kątem odpowiedniej . Aby została rozpoznana przez LibreOffice, musi mieć określone właściwości, jak wyjaśniono poniżej. Informacje te umożliwiają zaprogramowanie własnego dodatku dla Kreatora funkcji programu 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.

Funkcje

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

Poniżej znajdziesz opis tych funkcji, które są wywoływane w .

W przypadku wszystkich funkcji obowiązuje następująca zasada:

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

Wyjście: wartość wynikowa

Input: dowolna liczba typów (double&, char*, double*, char**, Obszar komórki), gdzie where the obszar komórki to tablica typu Double Array, String Array lub 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: odniesienie do zmiennej, która ma zawierać liczbę funkcji dodatku. Na przykład: Jeśli dodatek udostępnia 5 funkcji dla LibreOffice Calc, wówczas 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: numer funkcji od 0 do nCount-1 włącznie.

char* pFuncName:

Output: nazwa funkcji widziana przez programistę, tak jak jest nazwana w . Nazwa ta nie określa nazwy używanej w Kreatorze funkcji.

USHORT& nParamCount:

Output: liczba parametrów w funkcji dodatku. Liczba ta musi być większa niż 0, ponieważ zawsze istnieje wartość wyniku; maksymalna wartość to 16.

Paramtype* peType:

Wyjście: wskaźnik do macierzy zawierającej dokładnie 16 zmiennych typu Paramtype. Pierwsze wpisy nParamCount są wypełniane odpowiednim typem parametru.

char* pInternalName:

Wyjście: nazwa funkcji jest widoczna dla użytkownika i wyświetlana w Kreatorze funkcji. Może zawierać znaki diakrytyczne.

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:

Wejście: numer funkcji w bibliotece; od 0 do nCount-1.

USHORT& nParam:

Wejście: wskazuje, dla jakiego parametru podany jest opis; parametry zaczynają się od 1. Jeśli nParam wynosi 0, sam opis powinien być podany w pDesc; w tym przypadku pName nie ma żadnego znaczenia.

char* pName:

Wyjście: zajmuje nazwę lub typ parametru, na przykład słowo „Numer”, „Ciąg lub „Data” i tak dalej. Zaimplementowano w LibreOffice Calc jako char[256].

char* pDesc:

Wyjście: zajmuje się opisem parametru, np. „Wartość, na jaką ma zostać obliczony wszechświat”. Zaimplementowano w LibreOffice Calc jako 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:

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

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