Add-in de programmation de LibreOffice Calc

warning

La méthode décrite ci-après pour l'extension de Calc via des add-ins n'est pas à jour. Pour assurer la compatibilité avec les add-ins existants, les interfaces restent valides et sont toujours prises en charge, mais la programmation d'add-ins supplémentaires requiert l'utilisation des nouvelles fonctions API.


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


Aidez-nous !