Add-in de programmation de LibreOffice Calc

LibreOffice Calc peut être étendu par des Add-in qui sont dans des modules de programmation externes fournissant des fonctions supplémentaires pour travailler avec les classeurs. Ils sont listés dans l'assistant Fonction dans la catégorie Add-in. Si vous souhaitez programmer vous-même un Add-in, vous pouvez apprendre ici quelles fonctions doivent être exportées par la de façon à ce que l'Add-in puisse être attaché avec succès.

LibreOffice recherche dans le répertoire Add-in défini dans la configuration une correspondante. Pour être reconnue par LibreOffice, la doit avoir certaines propriétés, comme expliqué par la suite. Ces informations vous permettent de programmer votre propre Add-in pour l'assistant Fonction de LibreOffice Calc.

Concept de l'add-In

Chaque bibliothèque Add-In propose plusieurs fonctions. Certaines fonctions sont utilisées à des fins administratives. Dans la plupart des cas, vous pouvez donner le nom de votre choix à vos propres fonctions. Cependant, celles-ci doivent suivre certaines règles concernant la transmission des paramètres. Les conventions de nommage et d'appel varient en fonction des plates-formes.

Les fonctions de la

Dans tous les cas, les fonctions administratives GetFunctionCount et GetFunctionData doivent exister. Ces dernières permettent de déterminer les fonctions ainsi que les types de paramètres et les valeurs de retour. Les types Double et Chaîne sont supportés pour les valeurs de retour. Pour les paramètres, les plages de cellules Double Array, String Array et Cell Array sont également supportées.

Les paramètres sont transmis par référence. Il est donc possible de modifier les valeurs. Ceci n'est cependant pas pris en charge par LibreOffice Calc car sans intérêt au niveau d'un tableur.

Les bibliothèques peuvent être rechargées pendant l'exécution et les fonctions administratives peuvent en analyser le contenu. Des informations vous sont fournies pour chaque fonction : nombre et type de paramètres, noms de fonctions internes et externes et numéro administratif.

Le lancement des fonctions s'effectue de manière synchronisée et donne le résultat immédiatement. Il est également possible de lancer des fonctions en temps réel (fonctions asynchrones) mais en raison de leur complexité elles ne peuvent pas être présentées ultérieurement.

Généralités à propos de l'interface

16 est le nombre maximal de paramètres que peut contenir une fonction add-in liée à LibreOffice Calc : une valeur de retour et jusqu'à 15 paramètres de saisie de fonction.

Les types de données sont définies de la manière suivante :

Type de données	Définition
CALLTYPE	sous Windows : FAR PASCAL (_far _pascal) sinon : par défaut (données par défaut spécifiques au système d'exploitation)
USHORT	Entier sans signe de 2 octets
DOUBLE	Format dépendant de la plateforme occupant 8 octets
Paramtype	Dépendant de la plate-forme comme entier PTR_DOUBLE =0 pointeur sur un double PTR_STRING =1 pointeur sur une chaîne de caractère qui se termine par zéro PTR_DOUBLE_ARR =2 pointeur sur une matrice double PTR_DOUBLE_ARR =3 pointeur sur une matrice de chaîne PTR_DOUBLE_ARR =4 pointeur sur une matrice de cellule AUCUN =5

Fonctions de la

Ci-dessous, vous trouverez une description de ces fonctions qui sont appelées à la

Pour toutes les fonctions de la , les actions suivantes s'appliquent :

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

Output: valeur résultante

Input: n'importe quel nombre du type (double&, char*, double*, char**, zone de cellule), où la zone de cellule est une matrice du type double matrice, matrice de chaîne ou matrice de cellule.

GetFunctionCount()

Indique le nombre de fonctions sans les fonctions de gestion dans le paramètre de référence. À chaque fonction est associé un numéro unique compris entre 0 et nCount-1. Ce numéro est utilisé ultérieurement pour les fonctions GetFunctionData et GetParameterDescription.

Syntaxe

void CALLTYPE GetFunctionCount(USHORT& nCount)

Paramètre

USHORT &nCount:

Output: référence à une variable qui est supposée contenir le nombre de fonctions d'Add-in. Par exemple : si l'Add-in fournit 5 fonctions pour LibreOffice Calc, alors nCount=5.

GetFunctionData()

Détermine toutes les informations importantes relatives à une fonction Add-In.

Syntaxe

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

Paramètre

USHORT& nNo:

Input : Numéro de fonction compris entre 0 et nCount-1, inclusivement.

char* pFuncName:

Output : nom de fonction tel que vu par le programmeur, tel qu'elle est nommée dans la . Ce nom ne détermine pas le nom utilisé dans l'Assistant Fonction.

USHORT& nParamCount:

Output : nombre de paramètres dans les fonctions Addin. Ce nombre doit être supérieur à 0 parce qu'il y a toujours une valeur de résultat, la valeur maximale est 16.

Paramtype* peType:

Output : pointeur vers une matrice d'exactement 16 variable du type Paramtype. Les premières entrées nParamCount sont remplis avec les types de paramètres appropriés.

char* pInternalName:

Output : nom de fonction tel que vu par l'utilisateur, tel qu'elle apparaît dans l'assistant Fonction. Il peut contenir des trémas.

Les paramètres pFuncName et pInternalName sont des matrices de caractères implémentées dans LibreOffice Calc avec la taille 256.

GetParameterDescription()

Fournit une brève description de la fonction Add-In et de ses paramètres. En option, cette fonction peut être utilisée pour afficher la description d'une fonction et de ses paramètres dans l'assistant Fonctions.

Syntaxe

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

Paramètre

USHORT& nNo:

Input : nombre de fonctions dans la bibliothèque ; entre 0 et nCount-1.

USHORT& nParam:

Input : indique pour quel paramètre la description est fourni ; les paramètres commencent à 1. Si nParam est 0, la description elle même est supposée être supposé être fournie dans pDesc ; dans ce cas pName n'a aucune signification.

char* pName:

Output : prend le nom du paramètre ou son type, par exemple, le mot "Nombre" ou "Chaîne" ou "Date" et ainsi de suite. Implémenté dans LibreOffice Calc comme char[256].

char* pDesc:

Output : prend la description du paramètre, par exemple, "Valeur à laquelle l'univers doit être calculé." Implémenté dans LibreOffice Calc comme char [256]

Disponibles dans LibreOffice Calc, les matrices de caractères pName et pDesc comportent 256 caractères. Notez que l'espace disponible dans l'assistant Fonctions est limité et que vous ne pourrez pas entièrement utiliser ces 256 caractères.

Plages de cellules

Les tableaux qui suivent vous renseignent sur les structures de données qu'un module de programme externe doit avoir pour permettre la soumission de plages de cellules. Pour chaque type de données, LibreOffice Calc distingue trois matrices.

Matrice double

Vous pouvez appliquer une plage de cellules ayant des valeurs du type Nombre/Double en guise de paramètre. La définition d'une matrice double s'effectue de la manière suivante dans LibreOffice Calc :

Décalage	Nom	Description
0	Col1	Numéro de colonne du coin supérieur gauche de la plage de cellules. La numérotation commence par 0.
2	Ligne1	Numéro de ligne du coin supérieur gauche de la plage de cellules, numérotation à partir de 0.
4	Tab1	Numéro de table du coin supérieur gauche de la plage de cellules ; la numérotation démarre à 0.
6	Col2	Numéro de colonne du coin inférieur droit de la plage de cellules. La numérotation démarre à 0.
8	Ligne2	Numéro de ligne du coin inférieur droit de la plage de cellules ; la numérotation démarre à 0.
10	Tab2	Numéro de table du coin inférieur droit de la plage de cellules, numérotation à partir de 0.
12	Nombre	Nombre des éléments suivants. Les cellules vides ne sont ni prises en compte ni passées.
14	Col	Numéro de colonne de l'élément. La numérotation commence par 0.
16	Ligne	Numéro de ligne de l'élément ; la numérotation démarre à 0.
18	Tab	Numéro de table de l'élément ; la numérotation démarre à 0.
20	Erreur	Numéro d'erreur où la valeur 0 vaut pour "Aucune erreur". Si l'élément provient d'une cellule de formule, la valeur de l'erreur est déterminée via la formule.
22	Valeur	Variable IEEE de type Double/Virgule flottante de 8 octets
30	...	Élément suivant

Matrice de chaîne

Une plage de cellules qui comprend des valeurs de type Texte, est soumise en tant que matrice de chaîne. La définition d'une matrice de chaîne s'effectue de la manière suivante dans LibreOffice Calc :

Décalage	Nom	Description
0	Col1	Numéro de colonne du coin supérieur gauche de la plage de cellules. La numérotation commence par 0.
2	Ligne1	Numéro de ligne du coin supérieur gauche de la plage de cellules ; la numérotation démarre à 0.
4	Tab1	Numéro de table du coin supérieur gauche de la plage de cellules ; la numérotation démarre à 0.
6	Col2	Numéro de colonne du coin inférieur droit de la plage de cellules. La numérotation commence à 0.
8	Ligne2	Numéro de ligne du coin inférieur droit de la plage de cellules ; la numérotation démarre à 0.
10	Tab2	Numéro de table du coin inférieur droit de la plage de cellules ; la numérotation démarre à 0.
12	Nombre	Nombre des éléments suivants. Les cellules vides ne sont ni prises en compte ni soumises.
14	Col	Numéro de colonne de l'élément. La numérotation commence par 0.
16	Ligne	Numéro de ligne de l'élément ; la numérotation démarre à 0.
18	Tab	Numéro de table de l'élément ; la numérotation démarre à 0.
20	Erreur	Numéro d'erreur où la valeur 0 vaut pour "Aucune erreur". Si l'élément provient d'une cellule de formule, la valeur de l'erreur est déterminée via la formule.
22	Len	Longueur de la chaîne suivante, y compris l'octet de fin. Lorsque la longueur y compris l'octet de fin ne renvoie pas à une valeur exacte, un deuxième octet nul est inséré à la chaîne afin d'obtenir une valeur précise. Len se calcule via ((StrLen+2)&~1).
24	Chaîne	Chaîne se terminant par 0 octet
24+Len	...	Élément suivant

Matrice de cellule

Les matrices de cellules sont utilisées pour appeler des plages de cellules contenant aussi bien du texte que des nombres. Dans LibreOffice Calc, une matrice de cellules est définie comme suit :

Décalage	Nom	Description
0	Col1	Numéro de colonne du coin supérieur gauche de la plage de cellules. La numérotation commence par 0.
2	Ligne1	Numéro de ligne au coin supérieur gauche de la plage de cellules, la numérotation commence par 0.
4	Tab1	Numéro de table au coin supérieur gauche de la plage de cellules, la numérotation commence par 0.
6	Col2	Numéro de colonne au coin inférieur droit de la plage de cellules. La numérotation commence par 0.
8	Ligne2	Numéro de ligne au coin inférieur droit de la plage de cellules, la numérotation commence 0.
10	Tab2	Numéro de table au coin inférieur droit de la plage de cellules, la numérotation commence par 0.
12	Nombre	Nombre des éléments suivants. Les cellules vides ne sont ni comptées ni soumises.
14	Col	Numéro de colonne de l'élément. La numérotation commence par 0.
16	Ligne	Numéro de ligne de l'élément, la numérotation commence par 0.
18	Tab	Numéro de table de l'élément, la numérotation commence par 0.
20	Erreur	Numéro d'erreur où la valeur 0 vaut pour "Aucune erreur". Si l'élément provient d'une cellule de formule, la valeur de l'erreur est déterminée via la formule.
22	Type	Type de contenu de cellule, 0 == double, 1 == chaîne
24	Valeur or Nbcar	Si Type == 0 : variable IEEE de type double/virgule flottante de 8 octets Si Type == 1 : longueur de la chaîne suivante, y compris l'octet de fin. Lorsque la longueur y compris l'octet de fin ne renvoie pas à une valeur exacte, un deuxième octet nul est inséré à la chaîne afin d'obtenir une valeur précise. Nbcar se calcule via ((StrLen+2)&~1).
26 if Type==1	Chaîne	Si Type == 1 : chaîne se terminant par 0
32 ou 26+Nbcar	...	Élément suivant