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 sám, dočtete se zde, které funkce musí sdílená knihovnaexterní DLL exportovat, aby bylo možné doplněk úspěšně připojit.
LibreOffice hledá ve složce modulů vhodnou sdílenou knihovnuDLL knihovnu. Aby LibreOffice tuto sdílenou knihovnuDLL 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é knihovnyDLL 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é knihovnyDLL
Níže najdete popis funkcí, které jsou volány ve sdílené knihovněv externí DLL knihovně.
Pro všechny funkce sdílené knihovnyDLL platí toto:
void CALLTYPE funkce(výstup, vstup1, vstup2, …)
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 |