Doplňky pro programování v LibreOffice Calc

warning

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í exportovat, aby bylo možné doplněk úspěšně připojit.

LibreOffice hledá ve složce modulů vhodnou . Aby LibreOffice tuto 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

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

Níže najdete popis funkcí, které jsou volány .

Pro všechny funkce 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 . 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


Podpořte nás!