Obsah

# Doplňky pro programování v LibreOffice Calc

Způsob rozšiřování Calcu pomocí doplňků, který je popsán v následující části, je zastaralý. Rozhraní jsou stále platná a podporována, aby byla zajištěna kompatibilita s existujícími doplňky, ale pro programování nových doplňků byste měli použít funkce API.

LibreOffice Calc je možné rozšířit pomocí doplňků, což jsou externí programové moduly poskytující doplňující funkce pro práci se sešity. Tyto funkce se zobrazí v Průvodci funkcí v kategorii Doplňky. Pokud si chcete naprogramovat doplněk sami, dočtete se zde, které funkce musí sdílená knihovna externí DLL exportovat, aby bylo možné doplněk úspěšně připojit.

LibreOffice hledá ve složce modulů vhodnou sdílenou knihovnu DLL knihovnu. Aby LibreOffice tuto sdílenou knihovnu DLL knihovnu rozeznal, musí mít určité vlastnosti popsané dále. Tyto informace vám umožní naprogramovat si vlastní doplněk pro Průvodce funkcí v LibreOffice Calc.

## Princip doplňků

Každá knihovna doplňků poskytuje několik funkcí. Některé funkce se používají pro účely administrace. Pro své funkce můžete zvolit téměř jakýkoliv název. Musíte ovšem dodržet určitá pravidla pro předávání parametrů. Přesná konvence pojmenování a volání se liší pro různé platformy.

### Funkce sdílené knihovny DLL knihovny

Musí existovat minimálně administrativní funkce GetFunctionCount a GetFunctionData. Pomocí těchto funkcí je možné určit další funkce, typy parametrů a návratové hodnoty. Pro návratové hodnoty jsou podporovány typy Double a String. Jako parametry jsou navíc podporovány oblasti buněk Double Array, String Array a Cell Array.

Parametry se předávají odkazem. Tudíž je v podstatě možná změna jejich hodnoty. Ovšem LibreOffice Calc tuto vlastnost nepodporuje, protože v sešitech nemá smysl.

Knihovny je možné kdykoliv za běhu znovu načíst a analyzovat jejich obsah pomocí administrativních funkcí. Pro každou funkci jsou k dispozici informace o počtu a typech parametrů, interní a externí název funkce a administrativní číslo funkce.

Funkce jsou volány současně (synchronně) a výsledek vracejí okamžitě. Jsou možné i funkce reálného času (asynchronní funkce), ty zde nicméně nejsou pro svou složitost podrobněji vysvětleny.

## Obecné informace o rozhraní

Maximální počet parametrů ve funkci doplňku LibreOffice Calc je 16: jedna návratová hodnota a maximálně 15 vstupních parametrů.

Datové typy jsou definovány takto:

Datové typy | Definice
--- | ---
CALLTYPE | Systém Windows: FAR PASCAL (_far _pascal) Jiné: výchozí (podle operačního systému)
USHORT | 2bajtové celé kladné číslo
DOUBLE | 8bajtový formát podle platformy
Paramtype | Int podle platformy PTR_DOUBLE =0 ukazatel na typ double PTR_STRING =1 ukazatel na řetězec zakončený 0 PTR_DOUBLE_ARR =2 ukazatel na pole typu double PTR_STRING_ARR =3 ukazatel na pole řetězců PTR_CELL_ARR =4 ukazatel na pole buněk NONE =5

## Funkce sdílené knihovny DLL

Níže najdete popis funkcí, které jsou volány ve sdílené knihovně v externí DLL knihovně.

Pro všechny funkce sdílené knihovny DLL platí toto:

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

Výstup: Výsledná hodnota

Vstup: Libovolný počet typů (double&, char*, double*, char**, Cell area), kde Cell area je pole typů double array, string array nebo cell array.

### GetFunctionCount()

Vrací počet funkcí bez administrativní funkce referenčního parametru. Každá funkce má jedinečné číslo od 0 do nCount-1. Toto číslo je třeba pro funkce GetFunctionData a GetParameterDescription.

Syntaxe

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parametr

USHORT &nCount:

Výstup: Odkaz na proměnnou, která obsahuje počet funkcí doplňku. Příklad: pokud doplněk poskytuje 5 funkcí pro LibreOffice Calc, nCount=5.

### GetFunctionData()

Zjistí všechny důležité informace o funkci doplňku.

Syntaxe

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

Parametr

USHORT& nNo:

Vstup: Číslo funkce od 0 do nCount-1 včetně.

char* pFuncName:

Výstup: Název funkce, jak jej vidí programátor, odpovídá názvu ve sdílené knihovně v DLL. Tento název neurčuje název zobrazený v Průvodci funkcí.

USHORT& nParamCount:

Výstup: Počet parametrů funkce doplňku. Počet musí být vždy větší než 0, protože každá funkce má výslednou hodnotu. Maximální počet je 16.

Paramtype* peType:

Výstup: Ukazatel na pole sestávající přesně ze 16 proměnných typu Paramtype. První položky parametru nParamCount obsahují vhodný typ parametru.

char* pInternalName:

Výstup: Název funkce, jak jej vidí uživatel. Tento název se zobrazuje v Průvodci funkcí. Může obsahovat diakritická znaménka.

Parametry pFuncName a pInternalName jsou pole znaků, která jsou v LibreOffice Calc implementována o velikosti 256.

### GetParameterDescription()

Poskytuje krátký popis funkce doplňku a jejích parametrů. Volitelně lze tuto funkci použít k zobrazení popisu funkce a parametrů v Průvodci funkcí.

Syntaxe

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

Parametr

USHORT& nNo:

Vstup: Číslo funkce v knihovně. Číslo od 0 do nCount-1.

USHORT& nParam:

Vstup: Označuje parametr, pro který bude popis načten. Počítání parametrů začíná od čísla 1. Má-li parametr nParam hodnotu 0, předpokládá se, že je popis dán parametrem pDesc, a v tom případě nemá parametr pName žádný význam.

char* pName:

Výstup: Obsahuje název nebo typ parametru, např. slov "Číslo", "Řetězec" či "Datum" apod. V LibreOffice Calc implementováno jako char[256].

char* pDesc:

Výstup: Obsahuje popis parametru, např. "Hodnota, pro kterou chcete vyčíslit vesmír." V LibreOffice Calc implementováno jako char[256].

pName a pDesc jsou pole znaků; v LibreOffice Calc implementovány o velikosti 256. Poznámka: místo dostupné v Průvodci funkcí je omezené, není možné plně využít všech 256 znaků.

## Oblasti buněk

Následující tabulky obsahují informace o tom, jaké datové struktury musí externí programový modul poskytovat, aby bylo možné předávat oblasti buněk. LibreOffice Calc rozlišuje mezi třemi různými poli (v závislosti na datovém typu).

### Pole typu double

Jako parametr je možné předat oblast buněk s hodnotami typu Number/Double. Pole typu double je v LibreOffice Calc definováno takto:

Offset | Název | Popis
--- | --- | ---
0 | Col1 | Číslo sloupce v levém horním rohu oblasti buněk. Číslování začíná číslem 0.
2 | Row1 | Číslo řádku v levém horním rohu oblasti buněk. Číslování začíná číslem 0.
4 | Tab1 | Číslo tabulky v levém horním rohu oblasti buněk. Číslování začíná číslem 0.
6 | Col2 | Číslo sloupce v pravém dolním rohu oblasti buněk. Číslování začíná číslem 0.
8 | Row2 | Číslo řádku v pravém dolním rohu oblasti buněk. Číslování začíná číslem 0.
10 | Tab2 | Číslo tabulky v pravém dolním rohu oblasti buněk. Číslování začíná číslem 0.
12 | Počet | Počet prvků, které následují. Prázdné buňky nejsou započítány ani předávány.
14 | Sloupec | Číslo sloupce daného prvku. Číslování začíná číslem 0.
16 | Řádek | Číslo řádku daného prvku. Číslování začíná číslem 0.
18 | Tabulátor | Číslo tabulky daného prvku. Číslování začíná číslem 0.
20 | Chyba | Číslo chyby. Hodnota 0 má význam „bez chyby“. Pochází-li prvek z buňky obsahující vzorec, je hodnota chyby dána vzorcem.
22 | Hodnota | 8bajtová proměnná IEEE typu double s plovoucí desetinnou čárkou
30 | ... | Další prvek

### Pole řetězců

Oblast buněk, která obsahuje hodnoty typu Text a předává se jako pole řetězců. Pole typu string je v LibreOffice Calc definováno takto:

Offset | Název | Popis
--- | --- | ---
0 | Col1 | Číslo sloupce v levém horním rohu oblasti buněk. Číslování začíná číslem 0.
2 | Row1 | Číslo řádku v levém horním rohu oblasti buněk. Číslování začíná číslem 0.
4 | Tab1 | Číslo tabulky v levém horním rohu oblasti buněk. Číslování začíná číslem 0.
6 | Col2 | Číslo sloupce v pravém dolním rohu oblasti buněk. Číslování začíná číslem 0.
8 | Row2 | Číslo řádku v pravém dolním rohu oblasti buněk. Číslování začíná číslem 0.
10 | Tab2 | Číslo tabulky v pravém dolním rohu oblasti buněk. Číslování začíná číslem 0.
12 | Počet | Počet prvků, které následují. Prázdné buňky nejsou započítány ani předávány.
14 | Sloupec | Číslo sloupce daného prvku. Číslování začíná číslem 0.
16 | Řádek | Číslo řádku daného prvku. Číslování začíná číslem 0.
18 | Tabulátor | Číslo tabulky daného prvku. Číslování začíná číslem 0.
20 | Chyba | Číslo chyby. Hodnota 0 má význam „bez chyby“. Pochází-li prvek z buňky obsahující vzorec, je hodnota chyby dána vzorcem.
22 | Len | Délka následujícího řetězce včetně závěrečného nulového bajtu. Má-li délka včetně závěrečného nulového bajtu lichou hodnotu, je k řetězci přidán druhý nulový bajt, aby měla délka sudou hodnotu. Parametr Len se tedy vypočítá podle vzorce ((StrLen+2)&~1).
24 | Řetězec | Řetězec, který je zakončen nulovým bajtem.
24+Len | ... | Další prvek

### Pole buněk

Pole buněk se používají k odkazu na buňky, které obsahují text i čísla. Pole buněk je v LibreOffice Calc definováno takto:

Offset | Název | Popis
--- | --- | ---
0 | Col1 | Číslo sloupce v levém horním rohu oblasti buněk. Číslování začíná číslem 0.
2 | Row1 | Číslo řádku v levém horním rohu oblasti buněk. Číslování začíná číslem 0.
4 | Tab1 | Číslo tabulky v levém horním rohu oblasti buněk. Číslování začíná číslem 0.
6 | Col2 | Číslo sloupce v pravém dolním rohu oblasti buněk. Číslování začíná číslem 0.
8 | Row2 | Číslo řádku v pravém dolním rohu oblasti buněk. Číslování začíná číslem 0.
10 | Tab2 | Číslo tabulky v pravém dolním rohu oblasti buněk. Číslování začíná číslem 0.
12 | Počet | Počet prvků, které následují. Prázdné buňky nejsou započítány ani předávány.
14 | Sloupec | Číslo sloupce daného prvku. Číslování začíná číslem 0.
16 | Řádek | Číslo řádku daného prvku. Číslování začíná číslem 0.
18 | Tabulátor | Číslo tabulky daného prvku. Číslování začíná číslem 0.
20 | Chyba | Číslo chyby. Hodnota 0 má význam „bez chyby“. Pochází-li prvek z buňky obsahující vzorec, je hodnota chyby dána vzorcem.
22 | Typ | Typ obsahu buňky. 0 == typ double, 1 == řetězec.
24 | Value nebo Len | Jestliže Type == 0: 8bajtová proměnná IEEE typu double s plovoucí desetinnou čárkou Jestliže Type == 1: Délka následujícího řetězce včetně závěrečného nulového bajtu. Má-li délka včetně závěrečného nulového bajtu lichou hodnotu, je k řetězci přidán druhý nulový bajt, aby měla délka sudou hodnotu. Parametr Len se tedy vypočítá podle vzorce ((StrLen+2)&~1).
26 jestliže Type==1 | Řetězec | Jestliže Type == 1: Řetězec, který je zakončen nulovým bajtem.
32 nebo 26+Len | ... | Další prvek