Kromprogramo por programi en LibreOffice Calc
La sekva metodo priskribita por etendigi je Calc per kromprogramoj estas eksmoda. La interfacoj ankoraŭ estas validaj kaj subtenataj, por certigi pri kongrueco kun ekzistantaj kromprogramoj, sed por programi novajn kromprogramojn oni devus uzi la novajn API-funkciojn.
Eblas etendigi je LibreOffice Calc per kromprogramoj, kiuj estas eksteraj programaj moduloj kiuj donas pluajn funkciojn por prilabori kalkultabelojn. Tiuj estas listigitaj en la Funkcia Assistanto en la kategorio kromprogramo. Se vi volas programi kromprogramon, vi povas lerni ĉi tie kiuj devas esti eksportitaj de la dividata kodoteko ekstera DLL por sukcese kunligi la kromprogramon.
LibreOffice serĉas la kromprograman dosierujon difinitan en la agordaro por taŭga dividata biblioteko DLL. Por ke LibreOffice rekonu ĝin, la dividata biblioteko DLL bezonas specifajn atributojn, kiel sekve klarigita. Ĉi tiu informo ebligas al vi programi propran kromprogramon por Funkcia Asistanto de LibreOffice Calc.
La koncepto de kromprogramo
Ĉiu kromprograma biblioteko provizas kelkajn funkciojn. Iuj funkcioj estas uzeblaj por administraj celoj. Vi povas elekti preskaŭ ajnan nomon por viaj propraj funkcioj. Tamen, ili devas kongrui al la rilataj reguloj pri pasi parametrojn. La ekzaktaj nomadaj kaj vokaj konvencioj varias laŭ platformon.
Funkcioj de Dividata Biblioteko Kromprograma DLL
Minimume, la administaj funkcioj GetFunctionCount kaj GetFunctionData devas ekzisti. Uzante tiujn, eblas komputi la funkciojn kaj la parametrajn tipojn kaj liverajn valorojn. Tipoj Duoblaj kaj Ĉenaj estas subtenataj. Kiel parametroj, subtenataj estas Double Array, String Array, and Cell Array.
Parametroj estas paseblaj per referencoj. Tial eblas ŝanĝi tiun valorojn. Tamen tion LibreOffice Calc ne subtenas, ĉar tio ne havas sencon en kalkultabeloj.
Eblas reŝargi bibliotekojn rultempe kaj eblas analizi ties enhavon per administraj funkcioj. Por ĉiu funkcio, informo disponeblas pri la nombro kaj tipo de parametroj, internaj kaj eksteraj funkciaj nomoj kaj adminstra nombro.
Oni vokas la funkciojn sinkrone kaj ili tuj liveras siajn rezultojn. Realtempaj funkcioj (nesinkronaj funkcioj) eblas; tamen, pro ilia komplekseco, ili ne estas detale priskribitaj.
Ĝenerala informo pri la interfaco
La maksimuma nombro da parametroj en kromprograma funkcio ligita al LibreOffice Calc estas 16: unu livera valoro kaj ĝis 15 funkciaj enigaj parametroj.
La datumaj tipoj estas difinitaj jene:
Datumaj tipoj |
Difino |
CALLTYPE |
Under Windows: FAR PASCAL (_far _pascal) Alia: apriora (specife por la mastruma sistemo) |
USHORT |
Dubajta sensignuma entjero |
DUOBLA |
8-bita platform-dependa formato |
Paramtype |
Platform-dependa kiel entjero PTR_DOUBLE =0 pointer to a double PTR_STRING =1 pointer to a zero-terminated string PTR_DOUBLE_ARR =2 pointer to a double array PTR_STRING_ARR =3 pointer to a string array PTR_CELL_ARR =4 pointer to a cell array NENIU =5 |
Dividata Biblioteko DLL funkcioj
Sekve troviĝas priskribo de tiuj funkcioj, kiuj estas vokeblaj ĉe la Dividata Biblioteko ekstera DLL.
Por ĉiuj funkcioj de Dividata Biblioteko DLL, rilatas la jena:
void CALLTYPE fn(out, in1, in2, ...)
Eligo: Rezulta valoro
Enigo: Ajna nombro da tipoj (double&, char*, double*, char**, ĉelaro), kie la Ĉelaro estas tabelo de tipoj duobla tabelo, ĉena tabelo, aŭ ĉela tabelo.
GetFunctionCount()
Liveras la nombron da funkcioj sen administraj funkcioj de la referenca parametro. Ĉiu funkcio havas unikan nombron inter 0 kaj nCount-1. Ĉi tiu nombro estos poste bezonata por la funkcioj GetFunctionData kaj GetParameterDescription.
Sintakso
void CALLTYPE GetFunctionCount(USHORT& nCount)
Parametro
USHORT &nCount:
Eligo: Referenco al variablo, kiu devus enhavi la nombron da kromprogramaj funkcioj. Ekzemple: Se la kromprogramo donas 5 funkciojn por LibreOffice Calc, tiam nCount=5.
GetFunctionData()
Liveras ĉiujn gravajn informojn pri kromprograma funkcio.
Sintakso
void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)
Parametro
USHORT& nNo:
Enigo: Funkcia nombro inter 0 kaj nCount-1, inkluzive.
char* pFuncName:
Eligo: Funkcia nomo kiel vidata de la programanto, kiel nomita en la Dividata Biblioteko DLL. Ĉi tiu nomo ne difinas la nomon uzotan en la Funkcia Asistanto.
USHORT& nParamCount:
Eligo: Nombro da parametroj en kromprograma funkcio. Tiu nombro devas esti pli ol 0, ĉar ĉiam estas rezulta valoro; la maksimumo estas 16.
Paramtype* peType:
Eligo: Adresmontrilo al tabelo de precize 16 variabloj de tipo ParamType (tipo de parametro). La unua nParamCount elementoj estas plenigitaj per la taŭga tipo de parametroj.
char* pInternalName:
Eligo: Funkcia nomo kie lvidata de la uzanto, kiel ĝi aperas en la Funkcia Asistanto. Eble enhavas umlaŭtojn.
La parametroj pFuncName kaj pInteralName estas tabeloj de signoj, kiujn realigas kun grando 256 en LibreOffice Calc.
GetParameterDescription()
Liveras mallongan priskribon de la kromprograma funkcio kaj ties parametroj. Plue oni povas uzi ĉi tiun funkcion por vidigi funkcian kaj parametran priskribojn en la Funkcia Asistanto.
Sintakso
void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)
Parametro
USHORT& nNo:
Enigo: Nombro de la funkcio en la biblioteko; inter 0 kaj nCount-1.
USHORT& nParam:
Enigo: Montras por kiu parametro la priskribo rilatas; parametroj komencas ĉe 1. Se nParam estas 0, la priskribo mem devus disponiĝi en pDesc; en tiu kazo, pName ne havas sencon.
char* pName:
Eligo: prenas la parametran nomon aŭ tipon, ekzemple, la vorto "Nombro" aŭ "Ĉeno" aŭ "Dato", kaj tiel plu. Realigita en LibreOffice Calc kiel char[256].
char* pDesc:
Eligo: Prenas la priskribon de la parametro, ekzemple, "Valoro, ĉe kiu kalkuli la universon." Realigita en LibreOffice Calc kiel char[256].
pName kaj pDesc estas signaj tabeloj; realigita en LibreOffice Calc kun grando 256. Notu ke la spaco disponebla en la Funkcia Asistanto havas limon kaj ke ne eblas uzi ĉiujn 256 signojn.
Ĉelaroj
La sekvaj tabeloj enhavas informon pri tiuj datumaj strukturoj, kiujn ekstera programa modulo devas provizi por pasi ĉelarojn. LibreOffice Calc distingas inter tri malsamaj tabeloj, depende de la datuma tipo.
Duobla tabelo
Kiel parametron, eblas pasi ĉelaron kun valoroj de la tipo Numero/Duobla. En LibreOffice Calc duobla tabelo estas difinita jene:
Deŝovo |
Nomo |
Priskribo |
0 |
Kol1 |
Kolumna nombro en la supra-maldekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
2 |
Vic1 |
Vica nombro en la supra-maldekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
4 |
Tab1 |
Tabela nombro en la supra-maldekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
6 |
Kol2 |
Kolumna nombro en la malsupra-dekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
8 |
Vic2 |
Vica nombro en la malsupra-dekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
10 |
Tab2 |
Tabela nombro en la malsupra-dekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
12 |
Nombri |
Nombro da sekvaj elementoj. Malplenaj ĉeloj estas nek nombritaj nek pasitaj. |
14 |
Kol |
Kolumna nombro de la elemento. Nombrado komenciĝas de 0. |
16 |
Vico |
Vica nombro de la elemento. Nombrado komenciĝas de 0. |
18 |
Tabo |
Tabela nombro de la elemento. Nombrado komenciĝas de 0. |
20 |
Eraro |
Prierara nombro, kie la valoro 0 signifas "sen eraro". Se la elemento venas de formula ĉelo, la formulo difinas la prieraran valoron. |
22 |
Valoro |
8-bita IEEE-valoro de la tipo duobla/glitkoma |
30 |
... |
Sekva elemento |
Ĉena tabelo
Ĉelaro kiu enhavas valorojn de la tipo Teksto kaj pasita kiel ĉena tabelo. LibreOffice Calc difinas ĉenan tabelon jene:
Deŝovo |
Nomo |
Priskribo |
0 |
Kol1 |
Kolumna nombro en la supra-maldekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
2 |
Vic1 |
Vica nombro en la supra-maldekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
4 |
Tab1 |
Tabela nombro en la supra-maldekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
6 |
Kol2 |
Kolumna nombro en la malsupra-dekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
8 |
Vic2 |
Vica nombro en la malsupra-dekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
10 |
Tab2 |
Tabela nombro en la malsupra-dekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
12 |
Nombri |
Nombro da sekvaj elementoj. Malplenaj ĉeloj estas nek nombritaj nek pasitaj. |
14 |
Kol |
Kolumna nombro de la elemento. Nombrado komenciĝas de 0. |
16 |
Vico |
Vica nombro de la elemento. Nombrado komenciĝas de 0. |
18 |
Tabo |
Tabela nombro de la elemento. Nombrado komenciĝas de 0. |
20 |
Eraro |
Prierara nombro, kie la valoro 0 signifas "sen eraro". Se la elemento venas de formula ĉelo, la formulo difinas la prieraran valoron. |
22 |
Longo |
Longo de la sekva ĉeno, inkluzive la finan nul-biton. Se la longo havas malparan valoron, aldonas duan nul-biton al la ĉeno por atingi paran valoron. Tial, Longo estas kalkulebla laŭ ((StrLen+2)&~1). |
24 |
Ĉeno |
Ĉeno kun fina nul-bito |
24+Longo |
... |
Sekva elemento |
Ĉelaro
Ĉelaroj estas uzeblaj por voki ĉelajn areojn kiuj enhavas tekston kaj numerojn. LibreOffice Calc difinas ĉelaron jene:
Deŝovo |
Nomo |
Priskribo |
0 |
Kol1 |
Kolumna nombro en la supra-maldekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
2 |
Vic1 |
Vica nombro en la supra-maldekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
4 |
Tab1 |
Tabela nombro en la supra-maldekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
6 |
Kol2 |
Kolumna nombro en la malsupra-dekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
8 |
Vic2 |
Vica nombro en la malsupra-dekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
10 |
Tab2 |
Tabela nombro en la malsupra-dekstra angulo de la ĉelaro. Nombrado komenciĝas de 0. |
12 |
Nombri |
Nombro da sekvaj elementoj. Malplenaj ĉeloj estas nek nombritaj nek pasitaj. |
14 |
Kol |
Kolumna nombro de la elemento. Nombrado komenciĝas de 0. |
16 |
Vico |
Vica nombro de la elemento. Nombrado komenciĝas de 0. |
18 |
Tabo |
Tabela nombro de la elemento. Nombrado komenciĝas de 0. |
20 |
Eraro |
Prierara nombro, kie la valoro 0 signifas "sen eraro". Se la elemento venas de formula ĉelo, la formulo difinas la prieraran valoron. |
22 |
Tipo |
Tipo de ĉelenhavo, 0 == Duobla, 1 == Ĉena |
24 |
Valoro aŭ Longo |
Se tipo == 0; 8-bita variablo de tipo duobla/glitkoma Se tipo == 1; Longo de la sekva ĉeno, inkluzive la finan nul-biton. Se la longo havas malparan valoron, aldonas duan nul-biton al la ĉeno por atingi paran valoron. Tial, Longo estas kalkulebla laŭ ((StrLen+2)&~1). |
26 se tipo==1 |
Ĉeno |
Se tipo == 1: ĉeno kun fina nul-bito |
32 aŭ 26+Longo |
... |
Sekva elemento |