Tartalom

# Kiegészítők programozása a LibreOffice Calc programban

A Calc kiegészítőkkel való bővítésének az alábbiakban ismertetett módszere elavult. Az illesztőfelületek a továbbiakban is érvényesek és támogatottak azért, hogy biztosítsák a kompatibilitást a létező kiegészítőkkel, azonban az új kiegészítők programozásához tanácsos az új API-függvényeket használni.

LibreOffice Calc can be expanded by Add-Ins, which are external programming modules providing additional functions for working with spreadsheets. These are listed in the Function Wizard in the Add-In category. If you would like to program an Add-In yourself, you can learn here which functions must be exported by the shared library external DLL so that the Add-In can be successfully attached.

LibreOffice searches the Add-in folder defined in the configuration for a suitable shared library DLL. To be recognized by LibreOffice, the shared library DLL must have certain properties, as explained in the following. This information allows you to program your own Add-In for Function Wizard of LibreOffice Calc.

## A Kiegészítő fogalma

Minden egyes beépülő programkönyvtár számos függvényt kínál. Bizonyos függvények adminisztrációs célokat szolgálnak. A saját függvényeknek majdnem akármilyen nevet adhat. Ennek ellenére a paraméterek átadásánál be kell tartani pár szabályt. A pontos elnevezési, illetve hívási egyezmények platformfüggőek.

### Functions of Shared Library AddIn DLL

Minimálisan a GetFunctionCount, illetve a GetFunctionData adminisztrációs függvényeknek létezniük kell. Ezek segítségével meghatározhatók a függvények, a paramétertípusok, illetve a visszatérési értékek. Visszatérési értékként a dupla pontosságú, illetve a karakterlánc típusok támogatottak. Paraméterként még a Dupla pontosságú tömb, Karakterlánc-tömb és Cellatömb cellaterület támogatott.

A paraméterek hivatkozások segítségével kerülnek átadásra. Ennek megfelelően az értékek módosítása alapvetően lehetséges. Ezt azonban a LibreOffice Calc nem támogatja, mivel a munkafüzeteken belül nem értelmezhető.

A programkönyvtárak futás közben újrabetölthetők, illetve tartalmuk - az adminisztrációs függvények segítségével - elemezhető. Minden egyes függvényre vonatkozóan rendelkezésre állnak a paraméterek típusára és számára, belső és külső függvényneveire, illetve az adminisztrációs számára vonatkozó információk.

A függvények egyidejűleg kerülnek meghívásra, eredményüket azonnal visszaadják. Valós idejű függvények (aszinkron függvények) használata is lehetséges, azonban ezek - összetettségük miatt - részletesen nem kerülnek leírásra.

## Általános információ a felületről

Maximum 16 paramétere lehet egy olyan Kiegészítő függvénynek, amelyet a LibreOffice Calc programhoz csatol: egy ezek közül a függvény visszatérési értéke, és maximum 15 bemeneti paraméter.

Az adattípusok a következők lehetnek:

Adattípusok | Meghatározás
--- | ---
CALLTYPE | Windows rendszeren: FAR PASCAL (_far _pascal) Egyéb: alapértelmezett (operációs rendszer által meghatározott alapértelmezett)
USHORT | 2 bájtos előjel nélküli egész szám
DOUBLE | 8 bájtos platformfüggő formátum
Paramtype | Platformfüggő, mint az int (egész) típus PTR_DOUBLE =0 DOUBLE típusra mutató mutató PTR_STRING =1 nullával végződő karakterláncra mutató mutató PTR_DOUBLE_ARR =2 DOUBLE típusú tömbre mutató mutató PTR_STRING_ARR =3 karaktertömbre mutató mutató. PTR_CELL_ARR =4 cellatömbre mutató mutató NONE =5

## Shared Library DLL functions

Following you will find a description of those functions, which are called at the Shared Library external DLL.

For all Shared Library DLL functions, the following applies:

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

Kimenet: A kapott érték

Input: Any number of types (double&, char*, double*, char**, Cell area), where the Cell area is an array of types double array, string array, or cell array.

### GetFunctionCount()

Eredményül a hivatkozási paraméter kezelési függvényein kívül található függvények számát adja. Minden függvény rendelkezik egy egyedi azonosító számmal 0 és nCount-1 között. Erre a számra a GetFunctionData és a GetParameterDescription függvénynek lesz szüksége később.

Szintaxis

void CALLTYPE GetFunctionCount(USHORT& nCount)

Paraméter

USHORT &nCount:

Output: Reference to a variable, which is supposed to contain the number of Add-In functions. For example: If the Add-In provides 5 functions for LibreOffice Calc, then nCount=5.

### GetFunctionData()

Meghatározza egy Kiegészítő függvény összes fontos információját.

Szintaxis

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

Paraméter

USHORT& nNo:

Input: Function number between 0 and nCount-1, inclusively.

char* pFuncName:

Output: Function name as seen by the programmer, as it is named in the Shared Library DLL. This name does not determine the name used in the Function Wizard.

USHORT& nParamCount:

Output: Number of parameters in AddIn function. This number must be greater than 0, because there is always a result value; the maximum value is 16.

Paramtype* peType:

Output: Pointer to an array of exactly 16 variables of type Paramtype. The first nParamCount entries are filled with the suitable type of parameter.

char* pInternalName:

Output: Function name as seen by the user, as it appears in the Function Wizard. May contain umlauts.

A pFuncName és a pInternalName paraméterek karaktertömbök, amelyek 256-os méretűek a LibreOffice Calc programban.

### GetParameterDescription()

A kiegészítő függvények, illetve azok paramétereinek rövid leírását adja. A függvény ezen kívül használható a Függvénytündér elemben található függvény-, illetve paraméterleírások megjelenítésére.

Szintaxis

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

Paraméter

USHORT& nNo:

Input: Number of the function in the library; between 0 and nCount-1.

USHORT& nParam:

Input: Indicates, for which parameter the description is provided; parameters start at 1. If nParam is 0, the description itself is supposed to be provided in pDesc; in this case, pName does not have any meaning.

char* pName:

Output: Takes up the parameter name or type, for example, the word "Number" or "String" or "Date", and so on. Implemented in LibreOffice Calc as char[256].

char* pDesc:

Output: Takes up the description of the parameter, for example, "Value, at which the universe is to be calculated." Implemented in LibreOffice Calc as char[256].

A pName és a pDesc karaktertömbök, amelyek a LibreOffice Calc programban 256 eleműek lehetnek. Ne feledje, hogy a Függvénytündérben rendelkezésre álló hely korlátozott, és a 256 karakter nem tölthető ki teljesen.

## Cellaterületek

Az alábbi táblázatok azokról az adatstruktúrákról tartalmaznak információkat, amelyeket egy külső programmodulnak kell biztosítania ahhoz, hogy átadhassa a cellaterületeket. A LibreOffice Calc az adattípustól függően különbséget tesz három különböző tömb között.

### Dupla pontosságú tömb

Paraméterként a Szám/Dupla pontosságú típusú értékeket tartalmazó cellaterületek adhatók át. A LibreOffice Calc programban a dupla pontosságú tömbök az alábbiak szerint kerülnek meghatározásra:

Eltolás | Név | Leírás
--- | --- | ---
0 | Col1 | A cellaterület bal felső sarkában található oszlop száma; a számozás 0-tól indul.
2 | Row1 | A cellaterület bal felső sarkában található sor száma; a számozás 0-tól indul.
4 | Tab1 | A táblázat száma a cellaterület bal felső sarkában; a számozás 0-tól indul.
6 | Col2 | A cellaterület jobb alsó sarkában található oszlop száma; a számozás 0-tól indul.
8 | Row2 | A cellaterület jobb alsó sarkában található sor száma; a számozás 0-tól indul.
10 | Tab2 | A táblázat száma a cellaterület jobb alsó sarkában; a számozás 0-tól indul.
12 | Count | A következő elemek száma. Az üres cellák nem számítanak, illetve nem kerülnek átadásra.
14 | Col | Az elem oszlopszáma. A számozás 0-tól indul.
16 | Sor | Az elem sorának száma; a számozás 0-tól indul.
18 | Tab | Az elem táblázatszáma; a számozás 0-tól indul.
20 | Error | Hibaszám, ahol a 0 érték a „nincs hiba”. Ha az elem egy cellaképletből származik, akkor az értéket a képlet határozza meg.
22 | Value | 8 bájtos dupla pontosságú/lebegőpontos IEEE-változó
30 | ... | Következő elem

### Karaktertömb

Olyan cellaterület, amely Szöveg adattípussal rendelkező értékeket tartalmaz, és karakterlánc-tömbként kerül átadásra. A LibreOffice Calc programban a karakterlánc-tömbök az alábbiak szerint kerülnek meghatározásra:

Eltolás | Név | Leírás
--- | --- | ---
0 | Col1 | A cellaterület bal felső sarkában található oszlop száma; a számozás 0-tól indul.
2 | Row1 | A cellaterület bal felső sarkában található sor száma; a számozás 0-tól indul.
4 | Tab1 | A táblázat száma a cellaterület bal felső sarkában; a számozás 0-tól indul.
6 | Col2 | A cellaterület jobb alsó sarkában található oszlop száma; a számozás 0-tól indul.
8 | Row2 | A cellaterület jobb alsó sarkában található sor száma; a számozás 0-tól indul.
10 | Tab2 | A táblázat száma a cellaterület jobb alsó sarkában; a számozás 0-tól indul.
12 | Count | A következő elemek száma. Az üres cellák nem számítanak, illetve nem kerülnek átadásra.
14 | Col | Az elem oszlopszáma. A számozás 0-tól indul.
16 | Sor | Az elem sorának száma; a számozás 0-tól indul.
18 | Tab | Az elem táblázatszáma; a számozás 0-tól indul.
20 | Error | Hibaszám, ahol a 0 érték a „nincs hiba”. Ha az elem egy cellaképletből származik, akkor az értéket a képlet határozza meg.
22 | Len | A következő karakterlánc hossza, beleértve a lezáró nulla bájtot. Ha a lezáró nulla bájttal együtt számított hossz páratlan értéket ad, akkor egy második nulla bájt is hozzáadásra kerül a karakterlánchoz annak érdekében, hogy az érték páros legyen. Ennek megfelelően a Len paraméter a ((StrLen+2)&~1) képlet segítségével kerül kiszámításra.
24 | String | Karakterlánc 0-s lezáró bájttal
24+Len | ... | Következő elem

### Cellatömb

A cellatömbök segítségével hívhatók meg szöveget, illetve számokat tartalmazó cellaterületek. A LibreOffice Calc programban a cellatömbök az alábbiak szerint kerülnek meghatározásra:

Eltolás | Név | Leírás
--- | --- | ---
0 | Col1 | A cellaterület bal felső sarkában található oszlop száma; a számozás 0-tól indul.
2 | Row1 | A cellaterület bal felső sarkában található sor száma; a számozás 0-tól indul.
4 | Tab1 | A táblázat száma a cellaterület bal felső sarkában; a számozás 0-tól indul.
6 | Col2 | A cellaterület jobb alsó sarkában található oszlop száma; a számozás 0-tól indul.
8 | Row2 | A cellaterület jobb alsó sarkában található sor száma; a számozás 0-tól indul.
10 | Tab2 | A táblázat száma a cellaterület jobb alsó sarkában; a számozás 0-tól indul.
12 | Count | A következő elemek száma. Az üres cellák nem számítanak, illetve nem kerülnek átadásra.
14 | Col | Az elem oszlopszáma. A számozás 0-tól indul.
16 | Sor | Az elem sorának száma; a számozás 0-tól indul.
18 | Tab | Az elem táblázatszáma; a számozás 0-tól indul.
20 | Error | Hibaszám, ahol a 0 érték a „nincs hiba”. Ha az elem egy cellaképletből származik, akkor az értéket a képlet határozza meg.
22 | Type | A cella tartalmának típusa, 0 == Dupla, 1 == Karakterlánc
24 | Value vagy Len | Ha type == 0: 8 bájtos dupla pontosságú/lebegőpontos IEEE-változó Ha type == 1: A következő karakterlánc hossza, beleértve a lezáró nulla bájtot. Ha a lezáró nulla bájttal együtt számított hossz páratlan értéket ad, akkor egy második nulla bájt is hozzáadásra kerül a karakterlánchoz annak érdekében, hogy az érték páros legyen. Ennek megfelelően a Len paraméter a ((StrLen+2)&~1) képlet segítségével kerül kiszámításra.
26 ha type==1 | String | Ha type == 1: Karakterlánc 0-s lezáró bájttal
32 vagy 26+Len | ... | Következő elem