Enhavo

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

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

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

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

### Functions of Shared Library AddIn 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
DOUBLE | 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

## Shared Library DLL functions

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

For all Shared Library DLL 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()

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:

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

Liveras ĉiujn gravajn informojn pri kromprograma funkcio.

Sintakso

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

Parametro

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 Shared Library DLL. 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.

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:

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

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

Offset | Name | 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+Len | ... | Sekva elemento

### Ĉelaro

Ĉelaroj estas uzeblaj por voki ĉelajn areojn kiuj enhavas tekston kaj numerojn. LibreOffice Calc difinas ĉelaron jene:

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