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.
Program LibreOffice Calc może być rozszerzany przez dodatki będące zewnętrznymi modułami programowymi dostarczającymi dodatkowych funkcji do pracy z arkuszami kalkulacyjnymi. Można je znaleźć w Kreatorze funkcji w kategorii Dodatek. Podczas samodzielnego programowania dodatku warto zapoznać się z poniższymi informacjami przedstawiającymi, jakie funkcje należy wyeksportować przez dzieloną bibliotekę zewnętrzną bibliotekę DLL w celu pomyślnego dołączenia dodatku.
W celu odnalezienia dzielonej biblioteki DLL LibreOffice przeszukuje folder zdefiniowany w ustawieniach Narzędzia - Opcje - LibreOffice - Ścieżki - Dodatki. Aby dzielona biblioteka DLL mogła zostać rozpoznana przez program LibreOffice, musi spełniać wymagania wyjaśnione poniżej. Ta informacja pozwala programować własne dodatki 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 dzielonej biblioteki biblioteki DLL dodatków
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 |
Funkcje dzielonej bibliotekibiblioteki DLL
Poniżej przedstawiono opisy funkcji wywoływanych w dzielonej bibliotecezewnętrznej bibliotece DLL.
Dla wszystkich funkcji dzielonych bibliotekbibliotek DLL obowiązują następujące zasady:
void CALLTYPE fn(out, in1, in2, ...)
Wyjście: wartość wynikowa
Wejście: dowolna liczba typów (podwójna precyzja&, znak*, podwójna precyzja*, znak**, zakres komórek), gdzie zakres komórek jest macierzą liczb typu podwójna precyzja, macierzą ciągów lub macierzą komórek.
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:
Wyjście: Odwołanie do zmiennej, która powinna zawierać liczbę funkcji dodatkowych. Przykład: Jeśli dodatek zawiera 5 funkcji programu LibreOffice Calc, wartość 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:
Wejście: numer funkcji od 0 do nCount-1 włącznie.
char* pFuncName:
Wyjście: nazwa funkcji widziana przez programistę występująca w dzielonej bibliotecebibliotece DLL. Nie określa ona nazwy używanej w Kreatorze funkcji.
USHORT& nParamCount:
Wyjście: liczba parametrów funkcji dodatkowej. Liczba musi być większa niż 0, ponieważ funkcja zawsze zwraca wartość wynikową. Maksymalna liczba wynosi 16.
Paramtype* peType:
Wyjście: Wskaźnik macierzy zawierającej dokładnie 16 zmiennych typu Paramtype. Pierwsze wpisy nParamCount są wypełnione odpowiednim typem parametrów.
char* pInternalName:
Wyjście: nazwa funkcji widoczna dla użytkownika wyświetlana w Kreatorze funkcji. Może zawierać znaki narodowe.
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 w zakresie od 0 do nCount-1.
USHORT& nParam:
Wejście: oznacza parametry z dołączonym opisem. Parametry numerowane są od 1. Jeśli nParam wynosi 0, funkcja oczekuje opisu zawartego w pDesc; w takim wypadku parametr pName nie ma znaczenia.
char* pName:
Wyjście: pobiera nazwę lub typ parametru, na przykład słowo "Liczba", "Ciąg" lub "Data" itd. Zaimplementowany w programie LibreOffice Calc jako macierz znakowa o rozmiarze [256].
char* pDesc:
Wyjście: pobiera opis parametru, na przykład "Wartość, dla której należy obliczyć wszechświat". Zaimplementowany w programie LibreOffice Calc jako macierz znakowa o rozmiarze [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 |
Liczba kolejnych elementów. Puste komórki nie są liczone i przekazywane. |
14 |
Col |
Numer kolumny elementu. Numeracja rozpoczyna się od 0. |
16 |
Wiersz |
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 |
Liczba kolejnych elementów. Puste komórki nie są liczone i przekazywane. |
14 |
Col |
Numer kolumny elementu. Numeracja rozpoczyna się od 0. |
16 |
Wiersz |
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 |
Liczba kolejnych elementów. Puste komórki nie są liczone i przekazywane. |
14 |
Col |
Numer kolumny elementu. Numeracja rozpoczyna się od 0. |
16 |
Wiersz |
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 |
Typ |
Typ zawartości komórki, 0 == podwójna precyzja, 1 == ciąg |
24 |
Wartość lub długość |
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 |