Edukiak

# LibreOffice Calc-en programatzeko osagarria

Osagarrien bidez Calc hedatzeko metodoa deskribatzen da jarraian, baina zaharkituta dago. Dena den, interfazeak oraindik ere baliozkoak dira eta horiei buruzko laguntza teknikoa ere eskaintzen da, lehendik dauden osagarriekiko bateragarritasuna bermatzeko, baina osagarri berriak programatzeko, API funtzio berriak erabili behar zenituzke.

LibreOffice Calc osagarriekin hedatu daiteke, alegia, kalkulu-orriekin lan egiteko funtzio gehigarriak eskaintzen dituzten kanpoko programazio-moduluekin. Osagarriak funtzioen morroian zerrendatzen dira, Osagarriak kategorian. Osagarri bat zuk zeuk programatu nahi baduzu, hemen ikasi dezakezu zein funtzio esportatu behar diren liburutegi partekatuarekin kanpoko DLLarekin, osagarria behar den moduan erantsi dakion aplikazioari.

LibreOffice aplikazioak konfigurazioan definitu den osagarrien karpeta arakatzen du liburutegi partekatu DLL egokia aurkitzeko. LibreOffice>(e)k ezagutu dezan, liburutegi partekatuak DLLak propietate jakin batzuk eduki behar ditu, ondoren azaltzen den bezala. Informazio horri esker, norberak bere osagarria programatu dezake LibreOffice Calc aplikazioaren funtzioen morroirako.

## Osagarrien kontzeptua

Osagarrien (ingelesez 'add-in') liburutegi bakoitzak funtzio batzuk eskaintzen ditu. Funtzio horietako batzuk xede administratiboetarako erabiltzen dira. Edozein izen aukera dezakezu zeure funtzioentzat. Dena den, zenbait arau jarraitu behar dituzte parametroak pasatzeari dagokionez. Izenak ipintzeko eta dei egiteko konbentzio desberdinak daude plataformen arabera.

### Osagarrien DLLaren liburutegi partekatuko funtzioak

Gutxienez, GetFunctionCount eta GetFunctionData funtzio administratiboek hor egon behar dute. Horiek erabiliz, funtzioak, parametro motak eta itzultzeko balioak determina daitezke. Emaitza balio gisa, Double eta String motak onartzen dira. Parametro gisa, gainera, Double Array, String Array eta Cell Array gelaxka-barrutiak onartzen dira.

Parametroak erreferentzia bidez pasatzen dira. Hortaz, balio horiek aldatzea ezinezkoa da funtsean. Nolanahi ere, hori ez da onartzen LibreOffice Calc-en, ez baitu zentzurik kalkulu-orrietan.

Liburutegiak birkarga daitezke exekuzioan zehar, eta funtzio administratiboek liburutegi horien edukiak azter ditzakete. Funtzio bakoitzari dagokionez, informazioa erabilgarri egongo da kopurua eta mota parametroei buruz, barneko eta kanpoko funtzioei buruz, eta zenbaki administratiboa ere bai.

Funtzioei sinkronikoki dei egiten zaie eta berehala itzultzen dituzte emaitzak. Denbora errealeko funtzioak (funtzio asinkronoak) ere posible dira; dena den, hemen ez dugu xehetasunik emango, oso konplexuak baitira.

## Interfazeari buruzko informazio orokorra

LibreOffice Calc-en erantsitako osagarri-funtzio bateko parametroen gehieneko kopurua 16 da: itzultzeko balio bat eta funtzioen sarrerako 15 parametro gehienez.

Honela definitzen dira datu motak:

Datu motak | Definizioa
--- | ---
CALLTYPE | Windowsen: FAR PASCAL (_far _pascal) Bestelakoetan: lehenetsia (sistema eragilearen lehenespen espezifikoa)
USHORT | 2 byte-ko osoko zenbaki sinatu gabea
DOUBLE | Plataformari lotutako 8 byte-ko formatua
Paramtype | Plataformari lotua, int gisa PTR_DOUBLE =0, double baten erakuslea PTR_STRING =1, zeroz amaitutako karaktere-kate baten erakuslea PTR_DOUBLE_ARR =2, double motako matrize baten erakuslea PTR_STRING_ARR =3, string motako matrize baten erakuslea PTR_CELL_ARR =4, cell motako matrize baten erakuslea NONE =5

## DLL Liburutegi partekatuaren funtzioak

Ondoren, liburutegi partekatuan deitzen diren funtzio horiek deskribapena dago.

DLL Liburutegi partekatuaren funtzioen kasuan, honakoa aplikatzen da:

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

Irteera: Emaitzatzat lortutako balioa

Sarrera: Edozein mota kopuru (bikoitza&, kar*, bikoitza*, kar**, gelaxka-area), non gelaxka-area moten matrize bat den: bikoitzen matrizea, kateen matrizea edo gelaxken matrizea.

### GetFunctionCount()

Erreferentzia-parametroaren kudeaketa-funtziorik gabeko funtzioen kopurua ematen du. Funtzio bakoitzak 0 eta nCount-1 bitarteko zenbaki bakar bat dauka. Gero zenbaki hori beharko da GetFunctionData eta GetParameterDescription funtzioentzat.

Sintaxia

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parametroa

USHORT &nCount:

Irteera: Osagarri-funtzioen kopurua omen duen aldagai baten erreferentzia. Adibidez: Osagarriak 5 funtzioa ematen badizkio LibreOffice Calc-i, orduan nCount=5.

### GetFunctionData()

Osagarri-funtzio bati buruzko informazio esanguratsu guztia zehazten du.

Sintaxia

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

Parametroa

USHORT& nNo:

Sarrera: 0 eta nCount-1 (biak barne) arteko funtzio-zenbakia.

char* pFuncName:

Irteera: Funtzioaren izena programatzaileak ikusten duen eran, liburutegi partekatuan DLLan izendatuta dagoen moduan. Izen horrek ez du mugatzen funtzioen morroian erabilitako izena.

USHORT& nParamCount:

Irteera: Osagarrien funtzioaren parametro kopurua. Zenbakiak 0 baino handiagoa izan behar du, beti baitago emaitzako balio bat; gehieneko balioa 16 da.

Paramtype* peType:

Irteera: Paramtype motako 16 aldagai dituen matrize baten erakuslea. Lehen nParamCount sarrerak parametro mota egokiarekin beteta daude.

char* pInternalName:

Irteera: Funtzioaren izena, erabiltzaileak ikusten duen eran, funtzioen morroian agertzen diren moduan. Dieresiak eduki ditzake.

pFuncName eta pInternalName parametroak char matrizeak dira; 256 tamainarekin inplementatzen dira LibreOffice Calc-en.

### GetParameterDescription()

Osagarri-funtzioaren eta bere parametroen deskribapen labur bat ematen du. Nahi izanez gero, Funtzioen morroian funtzioen eta parametroen azalpen bat erakusteko erabil daiteke funtzio hau.

Sintaxia

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

Parametroa

USHORT& nNo:

Sarrera: Funtzioaren zenbakia liburutegian: 0 eta nCount-1 artean.

USHORT& nParam:

Sarrera: Deskribapena zein parametrotarako ematen den adierazten du; parametroak 1 balioan hasten dira. nParam 0 bada, deskribapena bera suposatzen da pDesc parametroan ematen dela; kasy horretan, pName parametroak ez du esanahirik.

char* pName:

Irteera: Parametroaren mota edo izena hartzen du, adibidez "Zenbakia" edo "Katea" edo "Data" hitza, eta abar. LibreOffice Calc aplikazioan char[256] modura inplementatua.

char* pDesc:

Irteera: Parametroaren deskribapena hartzen du, adibidez "Balioa, unibertsioa kalkulatzeko erabiliko dena". LibreOffice Calc aplikazioan char[256] modura inplementatua.

pName eta pDesc char matrizeak dira; LibreOffice Calc-en 256 tamainarekin inplementatuak. Kontuan izan Funtzioen morroian erabilgarri dagoen lekua mugatua dela eta 256 karaktereak ezin direla osorik erabili.

## Gelaxka-barrutiak

Ondorengo taulan azaltzen da, besteak beste, zein datu-egitura eman behar dituen kanpoko programa-modulu batek gelaxka-barrutiak pasatu ahal izateko. LibreOffice Calc-ek hiru matrize mota desberdintzen ditu, datu motaren arabera.

### Double motako matrizea

Parametro gisa, Number/Double motako balioak dituen gelaxka-barruti bat pasatu daiteke. Double motako matrize bat honela definitzen da LibreOffice Calc-en:

Desplazamendua | Izena | Deskribapena
--- | --- | ---
0 | Zutabea1 | Gelaxka-barrutiko goi-ezkerraldeko ertzeko zutabearen zenbakia. Zenbakitzea 0n hasten da.
2 | Errenkada1 | Gelaxka-barrutiko goi-ezkerraldeko ertzeko errenkada-zenbakia; zenbakitzea 0n hasten da.
4 | Taula1 | Gelaxka-barrutiko goi-ezkerraldeko ertzeko taula-zenbakia; zenbakitzea 0n hasten da.
6 | Zutabea2 | Gelaxka-barrutiko behe-eskuinaldeko ertzeko zutabearen zenbakia. Zenbakitzea 0n hasten da.
8 | Errenkada2 | Gelaxka-barrutiko behe-eskuinaldeko ertzeko errenkada-zenbakia; zenbakitzea 0n hasten da.
10 | Taula2 | Gelaxka-barrutiko behe-eskuinaldeko ertzeko taula-zenbakia; zenbakitzea 0n hasten da.
12 | Kopurua | Ondorengo elementuen kopurua. Gelaxka hutsak ez dira kontatzen edo pasatzen.
14 | Zutabea | Elementuaren zutabe-zenbakia. Zenbakitzea 0n hasten da.
16 | Errenkada | Elementuaren errenkada-zenbakia; zenbakitzea 0n hasten da.
18 | Taula | Elementuaren taula-zenbakia; zenbakitzea 0n hasten da.
20 | Errorea | Errore-zenbakia (0 balioa "no error." gisa definitua). Elementua formula-gelaxka batetik badator, errore-balioa formulak determinatzen du.
22 | Balioa | 8 byte-ko IEEE aldagaia, double/koma mugikorrekoa motakoa
30 | ... | Hurrengo elementua

### String motako matrizea

Gelaxka-barruti bat, testu motako datu-balioak dituena eta string motako matrize gisa pasatzen dena. String motako matrize bat honela definitzen da LibreOffice Calc-en:

Desplazamendua | Izena | Deskribapena
--- | --- | ---
0 | Zutabea1 | Gelaxka-barrutiko goi-ezkerraldeko ertzeko zutabearen zenbakia. Zenbakitzea 0n hasten da.
2 | Errenkada1 | Gelaxka-barrutiko goi-ezkerraldeko ertzeko errenkada-zenbakia; zenbakitzea 0n hasten da.
4 | Taula1 | Gelaxka-barrutiko goi-ezkerraldeko ertzeko taula-zenbakia; zenbakitzea 0n hasten da.
6 | Zutabea2 | Gelaxka-barrutiko behe-eskuinaldeko ertzeko zutabearen zenbakia. Zenbakitzea 0n hasten da.
8 | Errenkada2 | Gelaxka-barrutiko behe-eskuinaldeko ertzeko errenkada-zenbakia; zenbakitzea 0n hasten da.
10 | Taula2 | Gelaxka-barrutiko behe-eskuinaldeko ertzeko taula-zenbakia; zenbakitzea 0n hasten da.
12 | Kopurua | Ondorengo elementuen kopurua. Gelaxka hutsak ez dira kontatzen edo pasatzen.
14 | Zutabea | Elementuaren zutabe-zenbakia. Zenbakitzea 0n hasten da.
16 | Errenkada | Elementuaren errenkada-zenbakia; zenbakitzea 0n hasten da.
18 | Taula | Elementuaren taula-zenbakia; zenbakitzea 0n hasten da.
20 | Errorea | Errore-zenbakia (0 balioa "no error." gisa definitua). Elementua formula-gelaxka batetik badator, errore-balioa formulak determinatzen du.
22 | Luzera | Ondorengo karaktere-katearen luzera, itxierako 0 byte-a barne. Luzera, itxierako 0a barne, zenbaki bakoiti bat bada, bigarren 0 byte bat gehituko zaio karaktere-kateari, balio bikoitia lortzeko. Beraz, honela kalkulatzen da Luzera: ((StrLen+2)&~1).
24 | Karaktere-katea | Karaktere-katea itxierako zero byte-arekin
24+Len | ... | Hurrengo elementua

### Cell motako matrizea

Testua nahiz zenbakiak dituzten gelaxka-areei dei egiteko erabiltzen dira Cell motako matrizeak. Cell motako matrize bat honela definitzen da LibreOffice Calc-en:

Desplazamendua | Izena | Deskribapena
--- | --- | ---
0 | Zutabea1 | Gelaxka-barrutiko goi-ezkerraldeko ertzeko zutabearen zenbakia. Zenbakitzea 0n hasten da.
2 | Errenkada1 | Gelaxka-barrutiko goi-ezkerraldeko ertzeko errenkada-zenbakia; zenbakitzea 0n hasten da.
4 | Taula1 | Gelaxka-barrutiko goi-ezkerraldeko ertzeko taula-zenbakia; zenbakitzea 0n hasten da.
6 | Zutabea2 | Gelaxka-barrutiko behe-eskuinaldeko ertzeko zutabearen zenbakia. Zenbakitzea 0n hasten da.
8 | Errenkada2 | Gelaxka-barrutiko behe-eskuinaldeko ertzeko errenkada-zenbakia; zenbakitzea 0n hasten da.
10 | Taula2 | Gelaxka-barrutiko behe-eskuinaldeko ertzeko taula-zenbakia; zenbakitzea 0n hasten da.
12 | Kopurua | Ondorengo elementuen kopurua. Gelaxka hutsak ez dira kontatzen edo pasatzen.
14 | Zutabea | Elementuaren zutabe-zenbakia. Zenbakitzea 0n hasten da.
16 | Errenkada | Elementuaren errenkada-zenbakia; zenbakitzea 0n hasten da.
18 | Taula | Elementuaren taula-zenbakia; zenbakitzea 0n hasten da.
20 | Errorea | Errore-zenbakia (0 balioa "no error." gisa definitua). Elementua formula-gelaxka batetik badator, errore-balioa formulak determinatzen du.
22 | Mota | Gelaxka-edukiaren mota, 0 == Double, 1 == String
24 | Balioa edo Luzera | Mota == 0 bada: 8 byte-ko IEEE aldagaia, double/koma mugikorrekoa motakoa Mota == 1 bada: Ondorengo karaktere-katearen luzera, itxierako 0 byte-a barne. Luzera, itxierako 0a barne, zenbaki bakoiti bat bada, bigarren 0 byte bat gehituko zaio karaktere-kateari, balio bikoitia lortzeko. Beraz, honela kalkulatzen da Len: ((StrLen+2)&~1).
26 if Mota==1 | Karaktere-katea | Mota == 1 bada: Karaktere-katea itxierako zero byte-arekin
32 edo 26+Luzera | ... | Hurrengo elementua