Contents
Index 🔎︎

# Lisafunktsioonid programmeerimisel LibreOffice Calcis

Järgmistes lõikudes kirjeldatud Calci lisafunktsioonide abil laiendamise meetod on aegunud. Liidesed on küll endiselt sobivad ja toetatud, et tagada ühilduvus olemasolevate lisafunktsioonidega, kuid uute lisafunktsioonide programmeerimiseks tuleks kasutada uusi API-funktsioone.

LibreOffice Calci saab laiendada lisafunktsioonidega: need välised programmeerimismoodulid pakuvad arvutustabelitega töötamiseks lisavõimalusi. Lisafunktsioonid on ära toodud Funktsiooninõustaja kategoorias Lisafunktsioonid. Kui soovid lisafunktsioone ise programmeerida, saad siit teada, millised funktsioonid tuleb eksportida jagatud teegi välise DLL-ii kaudu, et lisafunktsioonid saaks edukalt lisada.

LibreOffice otsib konfiguratsioonis määratud lisafunktsioonide kaustast sobivat jagatud teeki DLL-i. Selleks, et LibreOffice selle ära tunneks, peavad jagatud teegil DLL-il olema teatud omadused, mida on kirjeldatud alljärgnevalt. Selle teabe abil saad LibreOffice Calci Funktsiooninõustaja jaoks ise lisafunktsioone programmeerida.

## Lisafunktsioonide kontseptsioon

Iga lisafunktsioonide teek hõlmab mitut funktsiooni. Mõnda funktsiooni kasutatakse administratiivsel otstarbel. Oma funktsioonide jaoks võid valida peaaegu mis tahes nime. Siiski peavad nimed järgima teatud reegleid, mis on seotud parameetrite edastamisega. Täpsed nimepaneku- ja käivitustavad on erinevate platvormide jaoks erinevad.

### Jagatud teekideLisatud DLL-ide funktsioonid

Kindlasti peavad olemas olema haldusfunktsioonid GetFunctionCount ja GetFunctionData. Nende abil saab määratleda nii funktsioonid kui ka parameetrite tüübid ja tagastatavad väärtused. Tagastatavate väärtustena on toetatud tüübid Pikad reaalarvud ja String. Parameetritena on lisaks toetatud ka pikkade reaalarvude massiivi, stringide massiivi ja lahtrite massiivi lahtrialad.

Parameetrid edastatakse viidete abil. Nende väärtuste muutmine on seetõttu sisuliselt võimalik. Siiski pole see LibreOffice Calcis toetatud, kuna see pole arvutustabelites mõttekas.

Teegid saab käitusajal uuesti laadida ja haldusfunktsioonid saavad nende sisu analüüsida. Iga funktsiooni jaoks on saadaval teave parameetrite arvu ja tüübi, sisemiste ja väliste funktsiooninimede ning administratiivnumbri kohta.

Funktsioonid kutsutakse sünkroonselt ja tulemused tagastatakse kohe. Võimalikud on ka reaalajas töötavad funktsioonid (asünkroonsed funktsioonid), mida pole siinkohal aga nende keerukuse tõttu üksikasjalikult selgitatud.

## Üldine teave kasutajaliidese kohta

LibreOffice Calci lisatud lisafunktsiooni parameetrite suurim lubatud arv on 16: üks tagastatav väärtus ja kuni 15 funktsiooni sisendparameetrit.

Andmetüübid on määratud järgnevalt:

Andmetüüp | Definitsioon
CALLTYPE | Windows'is: FAR PASCAL (_far _pascal) Mujal: vaikimisi (operatsioonisüsteemis määratud vaikeväärtus)
USHORT | 2-baidine märgita täisarv
DOUBLE | 8-baidine platvormist sõltuv vorming
Paramtype | Platvormist sõltuv nagu int PTR_DOUBLE =0 viit pikale reaalarvule PTR_STRING =1 viit nulliga lõpetatud stringile PTR_DOUBLE_ARR =2 viit pikkade reaalarvude massiivile PTR_STRING_ARR =3 viit stringide massiivile PTR_CELL_ARR =4 viit lahtrite massiivile NONE =5

## Jagatud teekide DLL-funktsioonid

Järgnevalt on toodud selliste funktsioonide kirjeldused, mis kutsutakse välja jagatud teekidestvälistest DLL-idest.

Kõikide jagatud teekideDLL-ide funktsioonide kohta kehtib järgnev:

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

Väljund: tagastatav väärtus

Sisend: mis tahes arv tüüpe (double&, char*, double*, char**, lahtrite ala), kus lahtrite ala on pikkade reaalarvude massiivi, stringide massiivi või lahtrite massiivi tüüpi massiiv.

### GetFunctionCount()

Tagastab funktsioonide arvu ilma viiteparameetri haldusfunktsioonideta. Igal funktsioonil on unikaalne arv vahemikus 0 ja nCount-1. Seda arvu läheb hiljem vaja funktsioonide GetFunctionData ja GetParameterDescription jaoks.

Süntaks

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parameeter

USHORT &nCount:

Väljund: viide muutjale, millest otsitakse lisafunktsioonide arvu. Näiteks: kui lisa pakub LibreOffice Calci jaoks 5 funktsiooni, siis nCount=5.

### GetFunctionData()

Tuvastab kogu olulise teabe lisafunktsiooni kohta.

Süntaks

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

Parameeter

USHORT& nNo:

Sisend: funktsiooni number vahemikus 0 kuni nCount-1 (kaasa arvatud).

char* pFuncName:

Väljund: funktsiooni nimi nii, nagu näeb seda programmeerija, ehk nimi, mis on funktsioonil jagatud teegisDLL-is. See nimi ei ole seotud Funktsiooninõustajas kasutatava nimega.

USHORT& nParamCount:

Väljund: lisafunktsiooni parameetrite arv. See arv peab alati olema suurem kui 0, sest alati on olemas vähemalt tulemuse väärtus, maksimaalne arv on 16.

Paramtype* peType:

Väljund: viit massiivile, mis koosneb täpselt 16 muutujast tüübiga Paramtype. Esimesed nParamCount kirjed täidetakse sobiva parameetri tüübiga.

char* pInternalName:

Väljund: funktsiooni nimi nii, nagu seda näeb kasutaja, ehk nagu see ilmub Funktsiooninõustajas. Võib sisaldada täppidega tähti.

Parameetrid pFuncName ja pInternalName on char-massiivid, mis on LibreOffice Calcis kasutusele võetud suurusega 256.

### GetParameterDescription()

Lisafunktsiooni ja tema parameetrite lühikirjeldus. Soovi korral saab seda funktsiooni kasutada ka funktsiooni ja parameetrite kirjelduse kuvamiseks Funktsiooninõustajas.

Süntaks

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

Parameeter

USHORT& nNo:

Sisend: funktsiooni number teegis vahemikus 0 kuni nCount-1.

USHORT& nParam:

Sisend: näitab, millise parameetri jaoks kirjeldus on esitatud; parameetrid algavad numbrist 1. Kui nParam on 0, peaks kirjeldus olema esitatud parameetris pDesc; sel juhul pole parameetril pName mingit tähendust.

char* pName:

Väljund: võtab parameetri nime või tüübi, näiteks sõna "Arv" või "String" või "Kuupäev" jne. LibreOffice Calcis on see kasutusele võetud kujul char[256].

char* pDesc:

Väljund: võtab parameetri kirjelduse, näiteks "Väärtus, mille põhjal universum arvutatakse." LibreOffice Calcis on see kasutusele võetud kujul char[256].

pName ja pDesc on char-massiivid; LibreOffice Calcis on need kasutusele võetud suurusega 256. Pane tähele, et Funktsiooninõustajas saadaolev ruum on piiratud ja kõiki 256 märki ei saa kasutada.

## Lahtrite alad

Järgmised tabelid sisaldavad teavet selle kohta, milliseid andmestruktuure peab väline programmimoodul lahtrialade edastamiseks sisaldama. LibreOffice Calc eristab sõltuvalt andmete tüübist kolme erinevat massiivi.

### Pikkade reaalarvude massiiv

Parameetrina saab edastada lahtrite ala väärtustega, mille tüüp on Arv või Pikad reaalarvud. Pikkade reaalarvude massiiv määratakse LibreOffice Calcis järgmiselt:

Nihe | Nimi | Kirjeldus
0 | Vrg1 | Veeru number lahtrite ala ülemises vasakpoolses nurgas. Nummerdus algab 0-st.
2 | Rd1 | Rea number lahtrite ala ülemises vasakpoolses nurgas. Nummerdus algab 0-st.
4 | Tab1 | Tabeli number lahtrite ala ülemises vasakpoolses nurgas. Nummerdus algab 0-st.
6 | Vrg2 | Veeru number lahtrite ala alumises parempoolses nurgas. Nummerdus algab 0-st.
8 | Rd2 | Rea number lahtrite ala alumises parempoolses nurgas. Nummerdus algab 0-st.
10 | Tab2 | Tabeli number lahtrite ala alumises parempoolses nurgas. Nummerdus algab 0-st.
12 | Arv | Järgnevate elementide arv. Tühje lahtreid ei loendata ega käsitleta.
14 | Vrg | Elemendi veeru number. Nummerdus algab 0-st.
16 | Rida | Elemendi rea number. Nummerdus algab 0-st.
18 | Tab | Elemendi tabeli number. Nummerdus algab 0-st.
20 | Viga | Vea kood, kusjuures väärtus 0 tähendab, et "viga puudub". Kui element pärineb valemiga lahtrist, määrab vea koodi valem.
22 | Väärtus | 8-baidine IEEE muutuja tüübiga pikk reaalarv / ujukomaarv
30 | ... | Järgmine element

### Stringide massiiv

Lahtrite ala, mis sisaldab väärtusi andmetüübiga tekst ja mida käsitletakse kui stringide massiivi. Stringide massiiv on LibreOffice Calcis defineeritud järgnevalt:

Nihe | Nimi | Kirjeldus
0 | Vrg1 | Veeru number lahtrite ala ülemises vasakpoolses nurgas. Nummerdus algab 0-st.
2 | Rd1 | Rea number lahtrite ala ülemises vasakpoolses nurgas. Nummerdus algab 0-st.
4 | Tab1 | Tabeli number lahtrite ala ülemises vasakpoolses nurgas. Nummerdus algab 0-st.
6 | Vrg2 | Veeru number lahtrite ala alumises parempoolses nurgas. Nummerdus algab 0-st.
8 | Rd2 | Rea number lahtrite ala alumises parempoolses nurgas. Nummerdus algab 0-st.
10 | Tab2 | Tabeli number lahtrite ala alumises parempoolses nurgas. Nummerdus algab 0-st.
12 | Arv | Järgnevate elementide arv. Tühje lahterid ei loendata ega jäeta vahele.
14 | Vrg | Elemendi veeru number. Nummerdus algab 0-st.
16 | Rida | Elemendi rea number. Nummerdus algab 0-st.
18 | Tab | Elemendi tabeli number. Nummerdus algab 0-st.
20 | Viga | Vea kood, kusjuures väärtus 0 tähendab, et "viga puudub". Kui element pärineb valemiga lahtrist, määrab vea koodi valem.
22 | Pikkus | Järgmise stringi pikkus koos sulgeva null-baidiga. Kui pikkus koos sulgeva null-baidiga on paaritu väärtus, lisatakse stringile veel teinegi null-bait, et tulemuseks oleks paarisväärtus. Seetõttu kasutatakse pikkuse arvutamiseks valemit ((stringipikkus+2)&~1).
24 | String | String sulgeva null-baidiga
24+pikkus | ... | Järgmine element

### Lahtrite massiiv

Lahtrite massiive kasutatakse nii teksti kui ka arve sisaldavate lahtrialade kutsumiseks. Lahtrite massiiv on LibreOffice Calcis määratud järgmiselt:

Nihe | Nimi | Kirjeldus
0 | Vrg1 | Veeru number lahtrite ala ülemises vasakpoolses nurgas. Nummerdus algab 0-st.
2 | Rd1 | Rea number lahtrite ala ülemises vasakpoolses nurgas. Nummerdus algab 0-st.
4 | Tab1 | Tabeli number lahtrite ala ülemises vasakpoolses nurgas. Nummerdus algab 0-st.
6 | Vrg2 | Veeru number lahtrite ala alumises parempoolses nurgas. Nummerdus algab 0-st.
8 | Rd2 | Rea number lahtrite ala alumises parempoolses nurgas. Nummerdus algab 0-st.
10 | Tab2 | Tabeli number lahtrite ala alumises parempoolses nurgas. Nummerdus algab 0-st.
12 | Arv | Järgnevate elementide arv. Tühje lahterid ei loendata ega jäeta vahele.
14 | Vrg | Elemendi veeru number. Nummerdus algab 0-st.
16 | Rida | Elemendi rea number. Nummerdus algab 0-st.
18 | Tab | Elemendi tabeli number. Nummerdus algab 0-st.
20 | Viga | Vea kood, kusjuures väärtus 0 tähendab, et "viga puudub". Kui element pärineb valemiga lahtrist, määrab vea koodi valem.
22 | Tüüp | Lahtri tüüp, 0 == pikk reaalarv, 1 == string
24 | Pikkuse väärtus | Kui tüüp == 0: 8-baidine IEEE muutuja tüübiga pikk reaalarv / ujukomaarv Kui tüüp == 1: järgmise stringi pikkus koos sulgeva null-baidiga. Kui pikkus koos sulgeva null-baidiga on paaritu väärtus, lisatakse stringile veel teinegi null-bait, et tulemuseks oleks paarisväärtus. Seetõttu kasutatakse pikkuse arvutamiseks valemit ((stringipikkus+2)&~1).
26 kui tüüp==1 | String | Kui tüüp == 1: string sulgeva null-baidiga
32 või 26+pikkus | ... | Järgmine element