Vsebina

# Dodatek za programiranje v modulu LibreOffice Calc

V nadaljevanju opisana metoda za razširitev programa Calc s pomočjo dodatkov je zastarela. Vmesniki so še vedno veljavni in imajo podporo, tako da lahko zagotovijo ujemanje z obstoječimi dodatki, toda za programiranje novih dodatkov morate uporabiti nove funkcije API.

LibreOffice Calc se da razširiti z dodatki, ki so zunanji programski moduli. Ti omogočajo dodatne funkcije za delo s preglednicami. Te so naštete v Čarovniku za funkcije pod kategorijo Dodatek. Če bi radi sami sprogramirali svoj dodatek, se tu lahko naučite, katere funkcije morate izvoziti z deljeno knjižnico zunanjim DLL, da boste dodatek lahko uspešno pripeli.

LibreOffice preišče mapo Dodatki, ki je določena v konfiguraciji za ustrezno deljeno knjižnico DLL. Če želite, da jo aplikacija LibreOffice prepozna, mora imeti deljena knjižnica DLL določene lastnosti, kot so razložene v nadaljevanju. Te informacije vam omogočajo programiranje lastnih dodatkov za Čarovnika za funkcije v LibreOffice Calc.

## Koncept dodatkov

Vsaka knjižnica dodatkov omogoča več funkcij. Nekatere funkcije se uporabljajo za administrativne namene. Za svoje lastne funkcije lahko izberete skoraj kakršno koli ime. Vendar, pri tem morate upoštevati tudi določena pravila v zvezi s prenašanjem parametrov. Natančne konvencije za poimenovanja se v različnih računalniških okoljih razlikujejo.

### Funkcije deljene knjižnice DLL-a za dodatke

Obstajati morata vsaj administrativni funkciji GetFunctionCount in GetFunctionData. S pomočjo teh dveh lahko določite funkcije kot tudi tipe parametrov in izračunane vrednosti. Kot izračunani vrednosti imata podporo tipa dvojno in niz. Kot parametri imajo podporo tudi celična območja dvojne matrike, matrike nizov in celične matrike.

Parametri se prenesejo s pomočjo sklicev. Iz tega razloga je spreminjanje teh vrednosti v osnovi mogoče. Vendar pa za to ni podpore v programu LibreOffice Calc, saj to znotraj preglednic ni smiselno.

Knjižnice lahko ponovno naložite med izvajanjem, njihovo vsebino pa lahko analizirajo administrativne funkcije. Za vsako funkcijo so na voljo podatki o številu in tipu parametrov, notranja in zunanja imena funkcij ter administrativno število.

Te funkcije so istočasno klicane in takoj izračunajo svoje rezultate. Funkcije v realnem času (neistočasne funkcije) so prav tako možne; vendar zaradi svoje zapletenosti niso natančno razložene.

## Splošni podatki o vmesniku

Največje možno število parametrov v dodatni funkciji, priloženi v LibreOffice Calc, je 16: ena izračunana vrednost in največ 15 funkcijskih vnosnih parametrov.

Vrste podatkov so definirane tako:

Vrste podatkov | Definicija
--- | ---
CALLTYPE | V Windows: FAR PASCAL (_far _Pascal) Sicer: privzeto (kar je v operacijskem sistemu določeno za privzeto)
USHORT | 2 bajtno celo število brez predznaka
DOUBLE | 8 bajtni format, ki je odvisen od računalniškega okolja
Paramtype | Odvisno od računalniškega okolja kot int PTR_DOUBLE =0 kazalec na dvojno PTR_STRING =1 kazalec na nizu, končanem z nič PTR_DOUBLE_ARR =2 kazalec na dvojni matriki PTR_STRING_ARR =3 kazalec na matriko nizov PTR_CELL_ARR =4 kazalec na celično matriko NONE =5

## Funkcije deljene knjižnice DLL

V nadaljevanju boste našli opis tistih funkcij, klicanih iz deljene knjižnice zunanje DLL.

Za vse funkcije deljene knjižnice DLL velja naslednje:

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

Izhod: Izračunana vrednost

Vhod: Vsako število tipa (double&, char*, double*, char**, celično območje), pri čemer je območje celic tabela vrste dvojna tabela, tabela nizov ali celična tabela.

### GetFunctionCount()

Izračuna število funkcij brez upravljalnih funkcij parametra sklica. Vsaka funkcija je označena s številom med 0 in nCount-1, ki se pri nobeni ne ponovi. To število bo kasneje potrebno za funkciji GetFunctionData in GetParameterDescription.

Skladnja

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parameter

USHORT &nCount:

Izhod: Sklic na spremenljivko, ki naj bi vsebovala število dodatnih funkcij. Primer: Če dodatek ponuja 5 funkcij za LibreOffice Calc, potem iz tega sledi nCount=5.

### GetFunctionData()

Določi vse pomembne podatke o dodatni funkciji.

Skladnja

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

Parameter

USHORT& nNo:

Vhod: Število funkcije med 0 in vključno nCount-1.

char* pFuncName:

Izhod: Ime funkcije, kot ga določi prgramer, in ga ima funkcija tudi v deljena knjižnica DLL. To ime ne določa imana, ki je v uporabi v Čarovniku za funkcije.

USHORT& nParamCount:

Izhod: Število parametrov v dodatni funkciji. To število mora biti vedno višje od 0, ker vedno obstaja izračunana vrednost; najvišja možna vrednost je 16.

Paramtype* peType:

Izhod: Kazalec na matriko z natanko 16 spremenljivkami tipa Paramtype. Prvi vnosi ParamCount se napolnijo z ustreznim tipom parametra.

char* pInternalName:

Izhod: Ime funkcije, kot ga vidi uporabnik in se pojavi v Čarovniku za funkcije. Lahko vsebuje preglase.

Parametra pFuncName in pInternalName sta znakovni matriki, ki imata v modulu LibreOffice Calc velikost 256.

### GetParameterDescription()

Poda kratek opis dodatne funkcije in njenih parametrov. To funkcijo se lahko uporabi za prikaz opisa funkcij in parametrov v Čarovniku za funkcije.

Skladnja

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

Parameter

USHORT& nNo:

Vhod: Številka funkcije v knjižnici; med 0 in nCount-1.

USHORT& nParam:

Vhod: Pokaže, kateri parameter v opisu je na voljo; parametri se začnejo pri 1. Če je nParam 0, bi opis sam moral biti na voljo v pDesc; v tem primeru pName nima nobenega pomena.

char* pName:

Izhod: Vsebuje ime ali tip parametra, npr. besede »Število« ali »Niz« ali »Datum« in tako naprej. V programu LibreOffice Calc se izvrši kot char[256].

char* pDesc:

Izhod: Vsebuje opis parametra, npr. »Vrednost, po kateri se izračuna velikost vesolja.«, ki se v programu LibreOffice Calc izvrši kot char[256].

pName in pDesc sta znakovni matriki, ki sta v programu LibreOffice Calc izvršljivi z velikostjo 256. Bodite pozorni na to, da je prostor, ki je na voljo v Čarovniku za funkcije, omejen, in da 256 znakov ne morete v celoti izrabiti.

## Celična območja

Sledeče tabele vsebujejo podatke o tem, katere strukture podatkov mora ponuditi zunanji programski modul, da se lahko prenesejo v celična območja. LibreOffice Calc razlikuje med tremi različnimi matrikami glede na tip podatkov.

### Dvojna matrika

Kot parameter se lahko prenese celično območje z vrednostni tipa število/dvojno. Dvojna matrika je pri modulu LibreOffice Calc definirana tako:

Odmik | Ime | Opis
--- | --- | ---
0 | Col1 | Številka stolpca v zgornjem levem kotu celičnega območja. Številčenje se začne pri 0.
2 | Row1 | Številka vrstice v zgornjem levem kotu celičnega območja; številčenje se začne pri 0.
4 | Tab1 | Številka tabele v zgornjem levem kotu celičnega območja; številčenje se začne pri 0.
6 | Col2 | Številka stolpca v spodnjem desnem kotu celičnega območja. Številčenje se začne pri 0.
8 | Row2 | Številka vrstice v spodnjem desnem kotu celičnega območja; številčenje se začne pri 0.
10 | Tab2 | Številka tabele v spodnjem desnem kotu celičnega območja; številčenje se začne pri 0.
12 | Števec | Število sledečih elementov. Prazne celice se ne štejejo ali prenesejo.
14 | Sto | Številka stolpca, v katerem se nahaja element. Številčenje se začne pri 0.
16 | Vrstica | Številka vrstice, v kateri se nahaja element; številčenje se začne pri 0.
18 | Tabulator | Številka tabele, v kateri se nahaja element; številčenje se začne pri 0.
20 | Napaka | Številka napake, pri kateri je vrednost 0 definirana kot »ni napake«. Če je element iz celice s formulo, napačno vrednost določi formula.
22 | Vrednost | 8 bajtna IEEE spremenljivka tipa dvojna/premična točka
30 | ... | Naslednji element

### Matrika nizov

Celično območje, ki vsebuje vrednosti tipa podatkov besedilo in se prenese kot matrika nizov. Matrika nizov je v modulu LibreOffice Calc definirana tako:

Odmik | Ime | Opis
--- | --- | ---
0 | Col1 | Številka stolpca v zgornjem levem kotu celičnega območja. Številčenje se začne pri 0.
2 | Row1 | Številka vrstice v zgornjem levem kotu celičnega območja; številčenje se začne pri 0.
4 | Tab1 | Številka tabele v zgornjem levem kotu celičnega območja; številčenje se začne pri 0.
6 | Col2 | Številka stolpca v spodnjem desnem kotu celičnega območja. Številčenje se začne pri 0.
8 | Row2 | Številka vrstice v spodnjem desnem kotu celičnega območja; številčenje se začne pri 0.
10 | Tab2 | Številka tabele v spodnjem desnem kotu celičnega območja; številčenje se začne pri 0.
12 | Števec | Število sledečih elementov. Prazne celice se ne štejejo ali prenesejo.
14 | Sto | Številka stolpca, v katerem se nahaja element. Številčenje se začne pri 0.
16 | Vrstica | Številka vrstice, v kateri se nahaja element; številčenje se začne pri 0.
18 | Tabulator | Številka tabele, v kateri se nahaja element; številčenje se začne pri 0.
20 | Napaka | Številka napake, pri kateri je vrednost 0 definirana kot »ni napake«. Če je element iz celice s formulo, napačno vrednost določi formula.
22 | Len | Dolžina sledečega niza, ki vključuje zaključni nični bajt. Če je dolžina, ki vsebuje zaključni nični bajt, enaka lihi vrednosti, se nizu doda drugi nični bajt, tako da se doseže soda vrednost. Iz tega razloga se Len računa z uporabo ((StrLen+2)&~1).
24 | Niz | Niz z zaključnim ničnim bajtom
24+Len | ... | Naslednji element

### Celična matrika

Celične matrike se uporabljajo za klicanje celičnih območij, ki vsebujejo tako besedilo kot tudi števila. Celična matrika je pri modulu LibreOffice Calc definirana tako:

Odmik | Ime | Opis
--- | --- | ---
0 | Col1 | Številka stolpca v zgornjem levem kotu celičnega območja. Številčenje se začne pri 0.
2 | Row1 | Številka vrstice v zgornjem levem kotu celičnega območja; številčenje se začne pri 0.
4 | Tab1 | Številka tabele v zgornjem levem kotu celičnega območja; številčenje se začne pri 0.
6 | Col2 | Številka stolpca v spodnjem desnem kotu celičnega območja. Številčenje se začne pri 0.
8 | Row2 | Številka vrstice v spodnjem desnem kotu celičnega območja; številčenje se začne pri 0.
10 | Tab2 | Številka tabele v spodnjem desnem kotu celičnega območja; številčenje se začne pri 0.
12 | Števec | Število sledečih elementov. Prazne celice se ne štejejo ali prenesejo.
14 | Sto | Številka stolpca, v katerem se nahaja element. Številčenje se začne pri 0.
16 | Vrstica | Številka vrstice, v kateri se nahaja element; številčenje se začne pri 0.
18 | Tabulator | Številka tabele, v kateri se nahaja element; številčenje se začne pri 0.
20 | Napaka | Številka napake, pri kateri je vrednost 0 definirana kot »ni napake«. Če je element iz celice s formulo, napačno vrednost določi formula.
22 | Vrsta | Tip vsebine celice, 0 == dvojno, 1 == niz
24 | Value ali Len | Če tip == 0: 8 bajtna IEEE spremenljivka tipa dvojna/premična točka Če tip == 1: Dolžina sledečega niza, ki vključuje zaključni nični bajt. Če je dolžina, ki vsebuje zaključni nični bajt, enaka lihi vrednosti, se nizu doda drugi nični bajt, tako da se doseže soda vrednost. Zato se Len računa z uporabo ((StrLen+2)&~1).
26 če tip ==1 | Niz | Če tip == 1: Niz z zaključnim ničnim bajtom
32 ali 26+Len | ... | Naslednji element