Lisafunktsioonid programmeerimisel LibreOffice Calcis

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 so that the Add-In can be successfully attached.

LibreOffice searches the Add-in folder defined in the configuration for a suitable . To be recognized by LibreOffice, the 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.

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.

Functions of

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

functions

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

For all functions, the following applies:

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

Output: Resulting value

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()

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:

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()

Tuvastab kogu olulise teabe lisafunktsiooni kohta.

Süntaks

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

Parameeter

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 . 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.

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:

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].

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:

Offset	Name	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	Veerg	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:

Offset	Name	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	Veerg	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+Len	...	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:

Offset	Name	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	Veerg	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