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.

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

Poniżej przedstawiono opisy funkcji wywoływanych w dzielonej bibliotece zewnętrznej bibliotece DLL.

Dla wszystkich funkcji dzielonych bibliotek bibliotek 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 bibliotece bibliotece 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