Add-in de programmation de LibreOffice Calc

LibreOffice Calc peut être étendu grâce à des add-ins : il s'agit de modules de programmation externes fournissant des fonctions complémentaires pour l'utilisation des classeurs. Ils sont répertoriés dans l'assistant Fonctions, dans la catégorie Add-in. Si vous souhaitez programmer vous-même un add-in, vous trouverez ici des informations sur les fonctions devant être exportées par la pour que l'add-in puisse être joint correctement.

LibreOffice recherche dans le dossier Add-in définit dans la configuration une appropriée. Pour être reconnue par LibreOffice, la doit posséder certaines propriétés, comme expliqué ci-dessous. Grâce à  ces informations, vous pourrez programmer votre propre add-in pour l'assistant Fonctions 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.

Fonctions de

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

Vous trouverez ci-après une description de ces fonctions, appelées par la .

Les règles suivantes s'appliquent à toutes les fonctions de :

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

Résultat : valeur résultante

Saisie : n'importe quel nombre de types (double&, car*, double*, car**, plage de cellules), où plage de cellules est une matrice de type double, chaîne ou 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:

Résultat : référence une variable qui est supposée contenir le nombre de fonctions Add-in. Par exemple : si l'Add-In fournit 5 fonctions à LibreOffice Calc, on a donc 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:

Entrée : numéro de fonction compris entre 0 et nCount-1 compris.

char* pFuncName:

Sortie : noms de fonction tels qu'ils sont vus par le programmeur et tels qu'indiqués dans la . Ce nom n'a pas d'influence sur celui utilisé dans l'assistant Fonctions.

USHORT& nParamCount:

Résultat : nombre de paramètres de la fonction AddIn. Ce nombre doit être supérieur à 0 puisqu'il existe toujours un code de sortie dont la valeur maximale est égale à 16.

Paramtype* peType:

Résultat : pointeur sur une matrice présentant exactement 16 variables de type Paramtype. Les premières entrées nParamCount sont complétées avec le type du paramètre correspondant.

char* pInternalName:

Sortie : nom de fonction tel qu'il est visualisé par l'utilisateur et tel qu'il s'affiche dans l'assistant Fonctions. 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:

Entrée : numéro de la fonction compris entre 0 et nCount-1 dans la bibliothèque.

USHORT& nParam:

Entrée : indique pour quel paramètre la description est nécessaire, les paramètres commencent par 1. Si nParam commence par 0, la description de la fonction doit être dans pDesc et pName est dans ce cas inutile.

char* pName:

Résultat : ajoute le nom ou le type de paramètre, par exemple le mot "Nombre" ou "Chaîne de caractères" ou "Date" ou autre. Est défini dans LibreOffice Calc sous la forme char[256].

char* pDesc:

Résultat : ajoute la description du paramètre, par exemple "Valeur pour laquelle la somme doit être calculée". Implémentée dans LibreOffice sous la forme 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 :

Offset	A	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écaler	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