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.
A LibreOffice Calc programot kiegészítők segítségével bővítheti, amelyek a táblázatok kezeléséhez további függvényeket biztosító külső programmodulok. Ezek felsorolását a Függvénytündér Kiegészítő kategóriája tartalmazza. Ha saját kiegészítőt kíván programozni, akkor az alábbiakból megtudhatja, hogy a Megosztott programkönyvtárnakkülső DLL programkönyvtárnak mely függvényeket szükséges exportálnia ahhoz, hogy a kiegészítő sikeresen csatolható legyen.
A LibreOffice a beállítások között megadható Kiegészítők mappában keres egy megfelelő megosztott programkönyvtáratDLL-t. Ahhoz, hogy a LibreOffice felismerje, a megosztott programkönyvtárnakDLL-nek bizonyos tulajdonságokkal kell rendelkeznie, amint azt az alábbiak tartalmazzák. Az itt közölt információk segítségével létrehozhatja saját kiegészítőit a LibreOffice Calc Függvénytündére számára.
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.
A megosztott programkönyvtárAz AddIn DLL függvényei
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 |
Megosztott programkönyvtárDLL-függvények
Az alábbiakban azon függvények leírását találja, amelyek a megosztott programkönyvtárkülső DLL helyen kerülnek meghívásra.
Minden egyes megosztott programkönyvtárDLL-függvényre az alábbiak vonatkoznak:
void CALLTYPE fv(kimenet, bemenet1, bemenet2, ...)
Kimenet: Visszaadott érték
Bemenet: Tetszőleges számú típus (double&, char*, double*, char**, Cellaterület), ahol a Cellaterület dupla pontosságú tömb, karakterlánc-tömb vagy cellaterület-tömb típusú tömb.
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:
Kimenet: Változóhivatkozás, amely a kiegészítő függvények számát tartalmazza. Például: Ha a kiegészítő 5 függvényt tartalmaz a LibreOffice Calc számára, akkor az 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:
Bemenet: Függvény száma 0 és nCount-1 között, nCount-1-et beleértve.
char* pFuncName:
Kimenet: A programozó által látható függvénynév, amint az elnevezésre került a megosztott programkönyvtárbanDLL-ben. A név nem határozza meg a Függvénytündérben használt nevet.
USHORT& nParamCount:
Kimenet: A kiegészítő függvény paramétereinek száma. A számnak 0-nál nagyobbnak kell lennie, mivel mindig létezik eredmény-érték. A legnagyobb érték 16.
Paramtype* peType:
Kimenet: Egy pontosan 16 változóból álló Paramtype típusú tömböt jelölő mutató. Az első nParamCount bejegyzések a megfelelő típusú paraméterrel kerülnek kitöltésre.
char* pInternalName:
Kimenet: A felhasználó által látható függvénynév, amint az megjelenik a Függvénytündérben. Tartalmazhat ékezeteket.
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:
Bemenet: A programkönyvtárban levő függvény száma 0 és nCount-1 között.
USHORT& nParam:
Bemenet: Jelzi, hogy melyik paraméterről nyújt leírást; a paraméterek 1-től kezdődnek. Ha az nParam 0, akkor magát a leírást a pDesc-nek kell tartalmaznia, ebben az esetben, a pName semmilyen jelentéssel nem bír.
char* pName:
Kimenet: A paraméter nevét vagy típusát veszi fel, például a „Szám”, ”Karakterlánc” vagy „Dátum” stb. szót. A LibreOffice Calc programban char[256]-ként van megvalósítva.
char* pDesc:
Kimenet: A paraméter leírását tartalmazza, például „Érték, amellyel az univerzumot számolja”. A LibreOffice Calc programban char[256]-ként van megvalósítva.
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 |