Comment diffuser vos macros avec un Addon

Diffusé Par
Le Projet Documentation d'OpenOffice.org

Table des matières

1 Introduction	4

1.1 Avertissement	4

1.2 Evolution du document	4

1.3 Que peut faire un addon ?	5

2 Outil de création du fichier XML décrivant l’addon	8

2.1 Conditions préalables	8

2.2 Produire le fichier de configuration	8

2.3 Emballer l’addon	8

2.4 Notes sur les informations fournies	9

a) Contenu d’un addon	9

b) Notion d’arbre de configuration	9

c) Libellés	9

d) Sous-menus	9

e) Boutons	10

f) URL	10

g) Les icônes	10

3 Installer les addons	12

3.1 Répertoires d’installation	12

3.2 Exécuter pkgchk	12

a) Installer des addons pour un utilisateur	12

b) Installer un addon particulier pour un utilisateur	13

c) Installer des addons pour le réseau	13

d) Installer un addon particulier pour le réseau	13

e) Supprimer un addon	13

3.3 Exemple de fichier Batch	13

4 Checklist avant de créer l’addon	14

5 Le fichier XML addon.xcu	15

5.1 Les enveloppes figées	15

5.2 AddonMenu (entrée dans le menu Outils)	16

5.3 Submenu	17

a) Entrée de sous-menu	17

b) Séparateur entre deux entrées de sous-menus.	17

c) Ouverture d’un sous-menu secondaire	17

5.4 OfficeMenubar (entrée dans le Menu Principal)	18

5.5 OfficeToolbar (bouton dans la barre de fonction)	19

5.6 OfficeHelp (entrée dans le menu Aide)	20

5.7 Images	21

5.8 Structure générale d’une propriété	22

5.9 Propriété URL	22

5.10 Propriété Title	22

5.11 Propriété ImageIdentifier	23

a) Image interne de OpenOffice	23

b) Image fournie avec l’addon	23

c) Variantes d’image	23

5.12 Propriété Target	24

5.13 Propriété Context	24

5.14 Valeurs de propriétés spécifiques à Images	25

a) Propriété URL dans un noeud d’image	25

b) Propriétés Image	25

6 Crédits	26

7 Licences	27

7.1 Documentation	27

7.2 Bibliothèque de macros	27

Introduction

Quand vous réalisez des macros qui apportent une nouvelle fonctionnalité à OpenOffice, vous les déclenchez en personnalisant un menu ou en ajoutant des boutons dans une barre d’outils. L’introduction des macros et la personnalisation sur plusieurs PC représente une tâche fastidieuse et délicate. Il existe une méthode qui permet d’automatiser ceci, avec beaucoup de possibilités, et en tenant compte de l’installation (PC unique ou réseau). Cette méthode s’appelle en anglais Addon qu’on peut traduire par Ajout ou Greffon. Elle est disponible officiellement à partir de la version 1.1 d’OpenOffice (fonctionnement restreint sur OOo 1.0.3).

L’installation d’un addon dépend essentiellement d’un fichier XML qui décrit la configuration à installer. Ce fichier est assez complexe, c’est pourquoi le chapitre 2 vous donne accès à un outil en Basic qui vous permettra de générer ce fichier sans en connaître la structure.

Le chapitre suivant indique comment introduire l’addon (ou le supprimer) dans OpenOffice.

Le reste du document est, pour les curieux, une explication technique simplifiée sur la structure du fichier XML de configuration. Les informations indiquées ici proviennent de la version 1.1RC4 et de ce qu’on peut déduire du Developers Guide chapitres 4.7.3 et 4.9.1, complétés de l’analyse de quelques addons réputés fonctionner.

Avertissement

Les informations et l’outil inclus dans ce document ont été testés sous OpenOffice 1.1 et sur un PC autonome fonctionnant sous Windows XP.

Soyez prudent et vérifiez que l’addon obtenu fonctionne correctement. Soyez particulièrement prudent pour une installation réseau (voir le chapitre 3.2).

Cette bibliothèque est distribuée car potentiellement utile, mais SANS AUCUNE GARANTIE, ni explicite ni implicite, y compris les garanties de commercialisation ou d'adaptation dans un but spécifique. Reportez-vous à la Licence Publique Générale GNU Limitée pour plus de détails.

Un retour d’expérience me sera utile pour améliorer ce HowTo.

Evolution du document

Principales évolutions depuis la version du 23 Octobre 2003

Document

ch 2.4 c)	ajout : description des libellés et des raccourcis clavier

ch 2.4 e)	ajout : description des boutons et des séparateurs de boutons

ch 5.11 a)	modification

Outil ( rev 1.1 )

Boutons	Possibilité d’ajouter des séparateurs

Menus	Les séparateurs sont ajoutés comme dans le dialogue pour les boutons

Que peut faire un addon ?

Un addon permet d’intégrer une ou plusieurs fonctions dans les menus et barre d’outils d’OpenOffice. Ces fonctions peuvent être réalisées avec divers langages de programmation, en particulier OpenOffice Basic. Un addon peut :

Insérer une bibliothèque de macros dans soffice (disponible pour toute application)

Ajouter une entrée supplémentaire dans le menu principal, à gauche de l’entrée Fenêtre. A réserver à des fonctionnalités particulièrement importantes et complexes. Notez que cette entrée possède obligatoirement un sous-menu.

Ajouter une entrée dans le menu Outils > Add-ons. Par défaut, l’entrée Add-ons n’apparaît que si au moins un addon utilise cette possibilité, et elle ouvre un sous-menu avec une entrée par addon.

Simultanément, une icône Add-ons apparaît dans la barre d’outils, qui ouvre le même sous-menu.

Pour ces deux possibilités, on peut définir des sous-menus en cascade, avec plusieurs entrées à chaque niveau.

Pour chaque entrée de (sous-)menu :

on peut préciser si elle ne doit apparaître que dans certaines applications, par exemple dans Writer et Calc seulement;

on peut fournir plusieurs libellés, qui seront choisis selon la langue définie par l’environnement linguistique;

on peut fournir une icône à afficher; cette icône pouvant avoir jusqu’à 4 variantes (petite ou grande icône, combiné à un contraste normal ou élevé).

On peut ajouter un ou plusieurs boutons dans la barre d’outils, là aussi avec les mêmes possibilités sur le contexte applicatif, le libellé selon la langue, l’icône associée.

On peut enfin ajouter une entrée simple dans le menu Aide, avec les mêmes possibilités.

Installation de l’addon dans OpenOffice

Il est possible d’installer de manière relativement simple un addon sur un seul PC (qu’il soit isolé ou en réseau), ou de manière centralisée sur la version réseau de OpenOffice.

Le mécanisme de l’addon facilite aussi les mises à jour. La version installée sera remplacée par la nouvelle en ré-exécutant la procédure d’installation.

Naturellement, l’outil d’installation est aussi capable de supprimer un addon.

Outil de création du fichier XML décrivant l’addon

L’outil est un ensemble de macros insérées dans ce HowTo. Bien qu’il puisse être utilisé pour réaliser différents types d’addon, nous nous limiterons à expliquer comment intégrer des macros.

Conditions préalables

On suppose comme exemple que vos macros sont regroupées dans une bibliothèque de macros de soffice ayant pour nom TATA. Cette bibliothèque est intégrée sur le PC qui a servi à mettre au point les macros. Elle se trouve dans le répertoire {installation}/user/basic/TATA/

Dans un répertoire de travail vide (exemple : Trav/ ), copiez le répertoire contenant votre bibliothèque. Vous obtenez donc un répertoire Trav/TATA/

Si vous disposez de fichiers images pour les futurs menus ou boutons, copiez-les dans le répertoire Trav/TATA/ ou mieux, dans un ou plusieurs sous-répertoires de celui-ci.

Supprimez de votre PC, avec l’outil de gestion des macros, la bibliothèque TATA. Vous pourrez toujours la ré-importer à partir de votre copie.

Vous avez décidé au moins des entrées de menu à créer, du texte de ces entrées.

Vous savez si vous allez faire apparaître des boutons avec icônes dans la barre de fonction ou si vous mettrez des icônes dans des entrées de menu.

Vous avez préparé une Checklist pour vous assurer de ne rien oublier. Voir au chapitre 4 un exemple de Checklist.

Produire le fichier de configuration

Cliquez sur le bouton ci-contre et répondez aux questions avec une grande attention, il est facile de se tromper. Quelques essais vous aideront à comprendre l’outil. Le chapitre 2.4 vous donne quelques explications complémentaires.

Pour la plupart des panneaux affichés, un cadre situé en haut affiche le journal des actions exécutées. Utilisez l’ascenseur ou la touche Ctrl-Fin pour voir les dernières actions.

A la fin de l’exécution, le journal est affiché dans une grande fenêtre. Relisez-le avec soin (fautes d’orthographes, oublis, erreurs). Si tout est bien, cliquez sur le bouton “ Zipper l’addon ” dans la fenêtre. Si vous avez un remords, il faudra fermer la fenêtre et recommencer complètement l’exécution, ou vous plonger dans le décorticage manuel du fichier addon.xcu , qui peut être modifié avec un éditeur de texte. Les fichiers addon.xcu et Journal.txt sont sauvés dans le répertoire de travail Trav/. Vous n’êtes pas obligé de créer immédiatement le zip.

Le chapitre 5 vous donne une description générale de la structure du fichier addon.xcu. Pour aller plus loin dans la compréhension du codage, la lecture du Developers Guide, chapitre 4.7.3 vous sera indispensable.

Emballer l’addon

Si vous êtes satisfait du fichier addon.xcu, il faut maintenant créer le fichier zip qui contiendra l’addon. Pour cela cliquez sur le bouton “ Zipper l’addon ” dans le panneau final, ou relancez l’outil en cliquant sur le bouton ci-dessous.

Dans notre exemple, vous obtiendrez le fichier TATA.zip dans le répertoire Trav/.

Lisez maintenant le chapitre : “ Installer les addons ”.

Notes sur les informations fournies

Contenu d’un addon

Vous pouvez utiliser ou non la faculté de créer des entrées de menus, et des boutons.

Vous pouvez concevoir un addon sans aucun menu, ni bouton, ni aide : seule la bibliothèque de macros sera installée, et deviendra disponible dans soffice.

Vous pouvez concevoir un addon dont certains boutons ou entrées lancent des macros d’une bibliothèque déjà installée.

Notion d’arbre de configuration

Les données de configuration d’OpenOffice sont stockées dans une arborescence. Sous un noeud donné de l’arborescence, on trouvera toutes les informations nécessaires pour un élément de configuration d’OpenOffice. Un noeud est identifié par son nom; il est nécessaire que chaque domaine de configuration ait un nom qui lui soit propre afin d’éviter un conflit avec toute autre configuration déjà introduite. On doit en particulier respecter cette règle pour chaque addon.

Un moyen recommandé pour assurer l’unicité de nom est d’utiliser une structure en “ nom qualifié ” formés de termes séparés par un point, par exemple :

org.openoffice.Office.addon.BernardMarcelly.fonction1

Avec ce choix, j’espère être le seul à utiliser la branche BernardMarcelly. Si je fournis plus tard un autre addon, je peux réutiliser mon entrée BernardMarcelly en ajoutant une autre branche appelée :

org.openoffice.Office.addon.BernardMarcelly.uneautrefonction

Notes

Le nom du noeud reste interne à OpenOffice, il n’apparaît pas pour les utilisateurs de l’addon.

Il est prudent de se limiter aux lettres non accentuées, chiffres, point, et de ne pas mettre d’espaces.

Libellés

Les libellés des entrées de menu peuvent comporter raccourci clavier (le caractère apparaît souligné). Pour choisir le caractère, ajouter devant celui-ci le caractère ~

Vous pouvez définir des libellés pour différentes langues, mais si vos macros affichent des textes, vous devez gérer leur traduction dans votre codage.

Sous-menus

Si, pour une entrée de menu, vous désirez ouvrir un niveau inférieur (un sous-menu), choisissez dans le panneau URL l’option “ URL ouvrant un sous-menu ”.

Il n’est pas possible d’afficher une icône sur une entrée qui ouvre un sous-menu.

Si vous ajoutez une entrée dans le menu Principal, l’ouverture d’un sous-menu est obligatoire.

Vous pouvez ouvrir jusqu’à 4 niveaux successifs de sous-menu, mais essayez d’être plus simple.

Boutons

Un séparateur de bouton est automatiquement ajouté avant le premier bouton de l’addon. Vous pouvez aussi ajouter un séparateur entre les boutons de l’addon.

URL

Vous pouvez lancer une macro déjà installée, et pas seulement une des macros de l’addon.

La commande de dispatch vous permet de lancer d’autres commandes.

Le “ mode d’affichage ” ne semble pas changer quoi que ce soit. Vous pouvez le laisser tel quel.

Les icônes

Utilisation par OpenOffice

Si vous affectez une image à une entrée de menu ou un bouton, OpenOffice mémorise l’URL correspondante. Si vous réutilisez le même URL pour un autre bouton ou une autre entrée de menu, la même image lui sera automatiquement affectée.

Ce comportement est assez logique, car c’est l’URL qui exécute une action, et non pas un bouton ou une entrée de menu. En utilisation courante, vous aurez une entrée de menu conduisant à un URL, et un bouton conduisant au même URL, car vous fournissez deux moyens de lancer une action; vous désignerez l’image une seule fois.

Inversement, si vous désirez deux images différentes pour deux entrées de menu conduisant à la même macro, arrangez-vous pour ne pas donner la même URL : soit en lançant une macro bis qui se contente d’appeler la macro principale, soit en lançant la même macro, mais depuis deux modules différents ! ( en Basic, les macros sont d’un module sont accessibles depuis tout autre module de la même bibliothèque).

Structure

Les icônes qu’on peut afficher sur une entrée de menu ou un bouton sont des images “ Windows bitmap ”, d’extension bmp. Attention, ce ne sont pas des fichiers .ico !

OpenOffice gère 4 variantes d’images :

petites icônes de 16x16 pixels,

grandes icônes de 26x26 pixels,

petites icônes de 16x16 pixels avec un contraste élevé,

grandes icônes de 26x26 pixels avec un contraste élevé.

Selon la documentation officielle, en l’absence d’image à contraste élevé, OpenOffice utilise l’image à contraste normal (non vérifié).

Pour que OpenOffice affiche une image 16x16 pixels, vous devez fournir une image et affirmer qu’elle est bien 16x16. De même pour que OpenOffice affiche une image 26x26 (utilisée avec l’option grandes icônes), vous devez fournir une autre image et affirmer qu’elle est bien 26x26. Si l’image que vous avez fournie n’a pas la taille indiquée, elle sera redimensionnée à l’affichage. Mais le résultat est moins bon qu’une image bien dessinée pour le format.

La couleur RGB(255, 0, 255) représente en fait un pixel transparent : la couleur de fond sera affichée à la place.

Il y a plusieurs manières de réaliser un addon avec une icône sur une entrée de menu, ou sur un bouton. L’outil autorise des images de type 1 ou de type 2.

Image de type 1

Ces images doivent exister dans le répertoire de l’addon, ou un sous-répertoire.

Elles ont le même nom de base suivi d’un suffixe qui indique la variante d’image.

Taille en pixels	Contraste	Suffixe	Exemple de fichier image
16x16	normal	_16.bmp	iconeExecuter_16.bmp
16x16	élevé	_16h.bmp	iconeExecuter_16h.bmp
26x26	normal	_26.bmp	iconeExecuter_26.bmp
26x26	élevé	_26h.bmp	iconeExecuter_26h.bmp

Il suffit de désigner une de ces images pour que OpenOffice retrouve les autres variantes dans le même répertoire. Les images de type 1 sont recommandées car plus simples à gérer.

Image de type 2

Ces images peuvent avoir un nom quelconque. Elles peuvent être fournies :

soit comme fichier dans le répertoire de l’addon, ou un sous-répertoire,

soit sous forme binaire codé hexadécimal dans le fichier addon.xcu; dans ce cas le fichier original peut se trouver à un endroit quelconque, puisqu’il ne sera pas joint à l’addon.

A la différence des images de type 1, vous devez indiquer le fichier de chacune des variantes. Vous pouvez panacher des images i) et des images ii).

Le fichier addon.xcu est plus complexe avec des images de type 2. Il devient assez gros si de nombreuses images de type 2 ii) sont définies.

Installer les addons

OpenOffice peut être installé :

sur un PC particulier

ou en réseau, avec un noyau sur le serveur et un client réduit dans chaque PC.
Dans ce cas on peut installer un addon

pour certains utilisateurs,

ou pour tous les utilisateurs d’OpenOffice.

Répertoires d’installation

L’outil en ligne de commande : pkgchk est utilisé pour installer les addons. Il peut installer :

soit un addon particulier, désigné en ligne de commande

soit tous les addons qu’il trouve dans un répertoire par défaut. Il en existe deux :

Pour les addons spécifiques à un utilisateur, le répertoire par défaut est
{installation}/user/uno_packages
ce qui se traduit, pour une installation Windows XP par
C:\Program Files\OpenOffice.org1.1\user\uno_packages

Pour les addons mis à disposition sur le réseau, le répertoire par défaut est
{installation}/share/uno_packages

L’outil pkgchk se trouve dans le répertoire :
{installation}/program
ce qui se traduit, pour une installation locale sous Windows XP par
C:\Program Files\OpenOffice.org1.1\program

Exécuter pkgchk

Vous devez travailler en ligne de commande pour lancer pkgchk. Il est préférable de préparer un fichier batch (MS-Windows) ou un script shell (Unix).

Le répertoire courant doit être {installation}/program

Vous devez impérativement supprimer toute exécution de OpenOffice avant de lancer pkgchk. Arrêtez aussi le lanceur OpenOffice (version MS-Windows). Sur le réseau, tout OpenOffice doit être arrêté. Sans ces précautions, l’installation OpenOffice peut être endommagée. La commande pkgchk teste si OpenOffice est exécuté en local, mais ne peut pas effectuer cette détection sur une installation réseau.

Installer des addons pour un utilisateur

Placez le ou les addons dans {installation}/user/uno_packages

Lancez la commande toute simple :

pkgchk

Ou bien, pour afficher un compte-rendu d’exécution ajoutez l’option -v :

pkgchk -v

Installer un addon particulier pour un utilisateur

Placez le fichier zip de l’addon dans un répertoire quelconque. Donnez en argument de la commande le chemin d’accès à ce fichier. Exemple pour MS-Windows :

pkgchk C:\essais\MonAddonAmoi.zip

Toujours pour Windows, s’il y a des espaces dans les noms de répertoire ou fichier, le chemin doit être écrit entre guillemets, exemple :

pkgchk "C:\Mes Documents\MonAddonAmoi.zip"

Installer des addons pour le réseau

Placez le ou les addons dans {installation}/share/uno_packages

Lancez la commande :

pkgchk --shared

Installer un addon particulier pour le réseau

Placez le fichier zip de l’addon dans un répertoire quelconque. Donnez en argument de la commande le chemin d’accès à ce fichier. Exemple pour MS-Windows :

pkgchk --shared C:\essais\MonAddonAmoi.zip

Supprimer un addon

Supprimez cet addon du répertoire par défaut. Notez que si vous avez installé l’addon de la manière b) ou d) vous le retrouverez aussi dans le répertoire par défaut.

Lancez la commande a) ou c)

Explication : pkgchk va mettre à jour tous les addons en fonction du contenu du répertoire par défaut. Ceux qui n’existent plus seront supprimés.

Exemple de fichier Batch

Voici un fichier batch simple, valable sous Windows XP, qui installe un addon particulier, uniquement sur le PC qui exécute le batch. La séquence copy ... packages\" doit être en une seule ligne.

@echo off

echo ATTENTION : arrêter tout OpenOffice, y compris le lanceur !! **

echo taper une touche quand c'est fait

pause

copy C:\Travail\TestAddon.zip "C:\Program Files\OpenOffice.org1.1.0\user\ uno_packages\"

pause

c:

cd "c:\Program Files"

cd "OpenOffice.org1.1.0\Program"

pkgchk -v

pause

Checklist avant de créer l’addon

Pour un addon complexe, il est fortement recommandé de mettre par écrit les éléments de réponses, avant de lancer la macro de création.

Choisir un “ nom unique ” qui sera spécifique à votre addon. Il ne doit pas être susceptible d’être identique à celui d’un autre addon écrit ou non par vous.

Passez en revue chacune des possibilités de base :

entrée au niveau du menu principal, sous-menus

entrée au niveau du menu Outils, sous-menus

bouton(s) dans la barre d’outils

entrée au niveau du menu Aide

Décidez des libellés d’entrée de menu, nom de macro, image associée.

Si votre addon ne doit apparaître que pour certains contextes, décidez du(des) contexte(s) pour chaque entrée et chaque bouton.

Pour chaque libellé, prévoyez éventuellement des traductions en différentes langues

Pour chaque image associée vous devez décider si elle sera en fichier dans l’addon et sous quel nom, ou intégrée dans le fichier xml; chaque image associée peut être fournie en plusieurs variantes, à prévoir.

Après avoir exécuté l’outil, si vous avez fait une erreur imprimez le journal et notez ce qui doit être différent. Ce papier vous servira de checklist pour le prochain essai.

Le fichier XML addon.xcu

Le fichier addon.xcu est un fichier texte en syntaxe XML qui décrit comment l’addon doit être intégré à OpenOffice. Pour plus d’information sur XML vous pouvez lire le livre : Introduction à XML publié en français par O’Reilly & Associates ( version original anglaise : Learning XML ).

Le but de ce chapitre est de vous aider à lire et éventuellement modifier ce fichier.

Le fichier utilise des balises qui ont une signification, et une syntaxe pour leur emploi.

Le fichier est structuré en “ poupées russes ”. La description implique de présenter des concepts en cascade.

Chacun des éléments listés est constitué d’une balise de début , d’un contenu, et d’une balise de fin, suivant un principe qu’on retrouve entre autres dans les documents HTML.

Les enveloppes figées

Les trois premières couches sont des textes figés, pour ce qui concerne les descriptions d’addons.

La couche “ Addon pour l’interface utilisateur ” contient un ou plusieurs composants. Le dessin montre les 5 composants possibles. L’ordre des composants est sans importance, chacun ne peut apparaître qu’une fois. Nous allons étudier chaque composant. Mais auparavant, quelques mots sur le principe de stockage des configurations dans OpenOffice.

Les données de configuration d’OpenOffice sont stockées dans une arborescence. Sous un noeud donné de l’arborescence, on trouvera toutes les informations nécessaires pour un élément de configuration d’OpenOffice. Un noeud est identifié par son nom; il est nécessaire que chaque domaine de configuration ait un nom qui lui soit propre afin d’éviter un conflit avec toute autre configuration déjà introduite. On doit en particulier respecter cette règle pour chaque addon.

Un même nom qualifié peut être employé pour désigner les différents composants de l’addon, car chaque composant (OfficeMenubar, OfficeToolbar, etc) est lui-même un noeud supérieur. Cas particulier : le composant Images comporte autant de sous-composants que d’images à insérer. On distinguera ces sous-composants en rajoutant un qualificateur, exemple :

org.openoffice.Office.addon.BernardMarcelly.fonction1.img02

AddonMenu (entrée dans le menu Outils)

AddonMenu définit une entrée de menu dans Outils > Addons. Il se compose d’une enveloppe ayant pour but de nommer de manière non-ambiguë cette configuration dans l’arbre des configurations OpenOffice. Dans cette enveloppe, on trouve plusieurs propriétés, décrites plus loin, dont l’ordre est sans importance.

Submenu est un élément composite qui peut exister ou non. Il permet de définir un niveau inférieur de menu. Sa structure est décrite au chapitre suivant.

Noter que si Submenu existe, la propriété URL peut être omise ou avoir un contenu quelconque, car aucune macro ne sera déclenchée. La propriété ImageIdentifier peut aussi être omise car elle sera ignorée, aucune image ne sera affichée.

Submenu

Un Submenu définit des entrées de sous-menu. Il contient une ou plusieurs entrées.

Chaque entrée se compose d’une enveloppe ayant pour but de nommer de manière non-ambiguë cette configuration dans le Submenu. L’outil décide du nom de noeud interne unique. Le contenu d’une entrée se présente sous trois variantes.

Entrée de sous-menu

C’est le cas le plus courant. L’ordre des propriétés est sans importance.

Séparateur entre deux entrées de sous-menus.

Ouverture d’un sous-menu secondaire

On retrouve la structure du chapitre précédent : la définition est récursive. L’outil se limite à 4 niveaux, ce qui devrait être bien suffisant.

OfficeMenubar (entrée dans le Menu Principal)

OfficeMenuBar définit une entrée de menu au plus haut niveau, qui se placera à gauche du menu Fenêtre.Il se compose d’une enveloppe ayant pour but de nommer de manière non-ambiguë cette configuration dans l’arbre des configurations OpenOffice. Dans cette enveloppe, on trouve deux propriétés, décrites plus loin, et un élément composite appelé Submenu, décrit précédemment. L’ordre des propriétés est sans importance. Notez que pour OfficeMenubar, le Submenu est obligatoire, c’est le seul moyen de déclencher une macro.

OfficeToolbar (bouton dans la barre de fonction)

OfficeToolbar définit un ou plusieurs boutons dans la barre de fonction (la barre d’outils avec les boutons Ouvrir , Enregistrer un fichier).

Il se compose d’une enveloppe ayant pour but de nommer de manière non-ambiguë cette configuration dans l’arbre des configurations OpenOffice. Dans cette enveloppe, on trouve un ou plusieurs descripteurs de bouton.Chaque descripteur se compose d’une enveloppe ayant pour but de nommer de manière non-ambiguë ce bouton dans le noeud englobant. L’outil décide du nom de noeud interne unique.

Dans chaque enveloppe de bouton on trouve plusieurs propriétés. L’ordre des propriétés est sans importance.

OfficeHelp (entrée dans le menu Aide)

OfficeHelp définit une entrée d’aide, qui sera insérée dans le menu Aide, après l’entrée “ Enregistrement... ”. Il se compose d’une enveloppe ayant pour but de nommer de manière non-ambiguë cette configuration dans l’arbre des configurations OpenOffice.

Dans cette enveloppe on trouve plusieurs propriétés. L’ordre des propriétés est sans importance.

Images

Images définit une ou plusieurs images de type 2 (dans notre cas ce sont des icônes), en listant leur contenu binaire. Le composant Images n’existe pas si les images sont toutes de type 1, ou s’il n’y a aucune image.

L’enveloppe Images est figée, et contient un ou plusieurs descripteurs d’image.Chaque descripteur se compose d’une enveloppe ayant pour but de nommer de manière non-ambiguë cette image dans l’arbre des configurations OpenOffice. L’outil décide du nom de noeud interne unique.

Chaque noeud d’image comporte une propriété URL, et un noeud interne qui sert ce conteneur à plusieurs variantes de la même image. Il peut y avoir jusqu’à 4 variantes.

Ces propriétés, particulières aux images, sont expliquées plus loin.

Structure générale d’une propriété

Une propriété commence par une balise <prop...> et finit par une balise </prop>

La balise d’ouverture contient le nom de la propriété. Elle indique aussi que la valeur de la propriété est de type “ chaîne de caractères ”.

Entre les deux balises se trouve la valeur de la propriété. Elle peut prendre plusieurs aspects :

<value/>

signifie: pas de valeur

<value>blabla blabla etc</value>

la chaîne de caractères entre les deux balises value est codée en Unicode UTF-8, les caractères accentués ou nationaux sont ainsi convertis en couples de caractères;

les caractères apostrophe, guillemet, et commercial, inférieur, supérieur, sont transcodés en leur entité caractères prédéfinie, exemple : < devient &lt;

D’autre manières de préciser la valeur sont utilisées selon les propriétés.

Propriété URL

En général, l’URL sert à lancer une macro quand on déclenche une entrée de menu ou un bouton de la barre de fonction. La valeur pour URL est alors de la forme :

<value>macro:///MyLib.Module1.Function1</value>

Dans l’exemple ci-dessus la macro à lancer s’appelle Function1 et se trouve dans le module Module1 de la bibliothèque MyLib.

Un séparateur de menu ou un séparateur de boutons se déclare avec la valeur conventionnelle :

<value>private:separator</value>

Propriété Title

C’est un libellé visible dans l’interface utilisateur, par exemple le libellé d’une entrée de menu.

Il est possible de préciser pour quelle langue s’applique le libellé. Exemple :

<value>erase</value>

<value xml:lang="en-UK">rub out</value>

<value xml:lang="fr">gommer</value>

La première ligne s’applique si la langue en cours ne fait pas partie des langues prévues.

La deuxième ligne s’applique pour l’anglais parlé au Royaume-Uni.

La troisième ligne s’applique pour le français, quelque soit le pays (France, Canada, Belgique, Suisse...)

Quelques combinaisons courantes de langues-Pays :

langue-PAYS	Idiome
en-US	Anglais américain
en-GB	Anglais britannique
fr-FR	Français de France
de-DE	Allemand d'Allemagne
it-IT	Italien
es-ES	Espagnol (Castillan)
pt-PT	Portugais du Portugal
nl-NL	Hollandais
da-DK	Danois
sv-SE	Suédois
hu-HU	Hongrois

Les codes de langues à 2 caractères sont normalisés ( ISO 639), on trouve sur internet la liste en français et en anglais.

Les codes de pays à 2 caractères sont normalisés ( ISO 3166), on trouve sur internet la liste en français et en anglais.

Propriété ImageIdentifier

La valeur d’ImageIdentifier est l’adresse URL d’une image qui va être associée au composant.

L’image peut être une des ressources internes d’OpenOffice, ou un fichier fourni avec l’addon.

Image interne de OpenOffice

Ce type d’image n’est pas supporté par l’outil macro du présent document.

La valeur d’ImageIdentifier est de la forme :

<value>private:image/1</value>

Le /1 indique qu’on utilise l’image interne numéro 1.

Je n’ai pas réussi à faire fonctionner ce type d’image.

Image fournie avec l’addon

La valeur d’ImageIdentifier est de la forme :

<value>%origin%/TATA/titi/iconeExecuter</value>

Dans cet exemple le répertoire principal de l’addon est TATA/ , et le(s) fichier(s) image est(sont) stocké(s) dans le sous-répertoire /titi/

Le nom %origin% représente le chemin d’accès au répertoire TATA/

Pourquoi plusieurs images ? A cause des variantes d’image...

Variantes d’image

OpenOffice peut gérer 4 types d’images. Seule la partie commune gauche des noms de fichiers images est indiquée dans l’URL. Le nom complet de fichier de chacun de ces types est déduit du nom fourni en lui rajoutant un suffixe.

Taille en pixels	Contraste	Suffixe	Exemple de fichier image
16x16	normal	_16.bmp	iconeExecuter_16.bmp
16x16	élevé	_16h.bmp	iconeExecuter_16h.bmp
26x26	normal	_26.bmp	iconeExecuter_26.bmp
26x26	élevé	_26h.bmp	iconeExecuter_26h.bmp

La conséquence de cette règle est que les fichiers image doivent avoir un suffixe autorisé, et en particulier une extension “ .bmp ”.

Propriété Target

La valeur de Target est un des quatre mots-clé suivants :

_top	_parent	_self	_blank

La seule utilisation que j’aie vue est _self :

<value>_self</value>

Propriété Context

Context indique que le composant ne doit être disponible que sur une ou certaines des applications OpenOffice. Une entrée vide signifie que le composant est disponible pour toutes les applications.

Application	Nom de service
Writer	com.sun.star.text.TextDocument
Calc	com.sun.star.sheet.SpreadsheetDocument
Impress	com.sun.star.presentation.PresentationDocument
Draw	com.sun.star.drawing.DrawingDocument
Formule	com.sun.star.formula.FormulaProperties
Diagramme	com.sun.star.chart.ChartDocument
Base bibliographique	com.sun.star.frame.Bibliography

Exemple 1

<value>com.sun.star.drawing.DrawingDocument</value>

Exemple 2

Ici, le composant est disponible dans deux applications :

<value>com.sun.star.drawing.DrawingDocument,com.sun.star.presentation.PresentationDocument</value>

Exemple 3

Ici, le composant est visible dans toute application :

<value/>

Valeurs de propriétés spécifiques à Images

Le composant Images sert à décrire des images qui n’ont pas été décrites avec la propriété ImageIdentifier vue ci-dessus.

Le composant Images utilise des valeurs particulières pour les propriétés.

Propriété URL dans un noeud d’image

La valeur de URL est exactement la même chaine de caractères que celle utilisée pour l’URL du composant qui en a besoin. Par exemple un composant AddonMenu déclenche une macro sur une entrée de menu; l’URL du noeud d’image reprendra la même séquence d’appel de macro.

Dans un composant pour lequel ImageIdentifier est vide, OpenOffice recherchera dans chaque noeud Image une URL identique. S’il en trouve une, cette image sera ajoutée à l’entrée de menu.

Propriétés Image

Il existe 8 variantes de cette propriété, car OpenOffice peut gérer 4 variantes d’image, soit définie dans le fichier XML, soit définies en tant que fichier image fourni dans l’addon.

Taille en pixels	Contraste	Nom de la propriété image intégrée image fournie
16x16	normal	ImageSmall	ImageSmallURL
16x16	élevé	ImageSmallHC	ImageSmallHCURL
26x26	normal	ImageBig	ImageBigURL
26x26	élevé	ImageBigHC	ImageBigHCURL

Valeur pour une image intégrée dans le fichier XML

La valeur du paramètre est le contenu binaire (non compressé) de l’image, présenté sous forme hexadécimale, exemple pour une image 16x16 :

<value>424df80000000000000076000000280000001000000010000000010004000000000000000000120b0000120b000000000000000000000000ff0000ffff0000ff0000ffff0000ff000000ff00ff00ffffff00c0c0c000808080000000000000008000008080000080000080800000800000008000800055555555555555555665565555556556556656555655656655566656565566655666668666586655555586686556666655555566556685555566655656686655555556555556655555566866565566655555866556655555566666556866855555566856668666665566655656566655566565565556566556556555555655660000</value>

Notez que, pour un même nombre de pixels, deux images bmp ont des contenus de taille différentes si les images sont codées avec une précision de couleur différente (16 couleurs, 16 millions de couleurs, etc).

Valeur pour une image fournie dans l’addon

La valeur sera de la forme :

<value>%origin%/TATA/titi/iconeExecuter.bmp</value>

Dans cet exemple, vos fichiers *.xlb *.xdl et *.xba sont rassemblés dans un répertoire, par exemple TATA/ , et le fichier image est stocké dans le sous-répertoire /titi/

Le nom %origin% représente le chemin d’accès au répertoire TATA/

Crédits

Auteur : Bernard Marcelly

Remerciements à : Laurent Godard pour ses conseils et son aide, en particulier pour zipper l’addon.

Intégré par : Sophie Gautier

Dernière modification: 19 Novembre 2003

Contacts : Projet Documentation OpenOffice.org http://fr.openoffice.org

Traduction :

Licences

Documentation

Appendix

Public Documentation License Notice

The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the "License"); you may only use this Documentation if you comply with the terms of this License. A copy of the License is available at http://www.openoffice.org/licenses/PDL.html.

The Original Documentation is : Comment diffuser vos macros avec un Addon

The Initial Writer of the Original Documentation is Bernard Marcelly

Copyright (C) 2003. All Rights Reserved. (Initial Writer contact(s): marcelly@club-internet.fr )

Contributor(s): ______________________________________.

Portions created by ______ are Copyright (C)_________[Insert year(s)].

All Rights Reserved. (Contributor contact(s):________________[Insert hyperlink/alias]).

NOTE: The text of this Appendix may differ slightly from the text of the notices in the files of the Original Documentation. You should use the text of this Appendix rather than the text found in the Original Documentation for Your Modifications.

Bibliothèque de macros

General information on LGPL is available on this Web site.

Une traduction non-officielle de la license LGPL est disponible sur ce site.

The standard library included in this document is a tool which produces files for an OpenOffice.org Add-on. Copyright (C) 2003 Bernard Marcelly

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

OpenOffice.org Documentation Project How-To

http://fr.openoffice.org	27

Comment diffuser vos macros avec un Addon

macro API OPenOffice

Bernard M.

2003-10-14T23:21:23