♪
I. Introduction▲
Cet outil a été développé sur OpenOffice.org, puis Apache OpenOffice.
Le fonctionnement de Xray 6.0 a été vérifié sur :
- OpenOffice.org (version 2.4.3 et version 3.3) ;
- Apache OpenOffice version 3.4 ;
- LibreOffice 3.4.
Ce tutoriel est extrait du document Description de l'outil Xray, disponible ici.
II. À quoi sert Xray ?▲
Le point le plus gênant pour un programmeur habitué de VBA est que l'EDI d'OpenOffice.org ne propose pas automatiquement des noms de méthode ou de propriété en cours de frappe. Ceci provient d'une différence de principe de réalisation de l'API OpenOffice.org. Il ne comporte pas d'objets prédéfinis, mais tous les objets Uno nécessaires sont instanciés à mesure des besoins, les uns à partir des autres, en commençant par un ServiceManager. Il n'est pas possible de connaître statiquement (à la compilation) les propriétés et méthodes disponibles sur une variable objet Uno. On ne peut le savoir qu'à l'exécution du codage, et c'est pour cela qu'on doit lancer la macro Xray en lui transmettant en argument l'objet à analyser.
Xray est un outil pour le programmeur de macros Basic qui utilise l'API Apache OpenOffice. Il a pour but de visualiser les propriétés, méthodes, services, interfaces disponibles sur une variable objet. Il utilise pour cela les fonctions d'introspection et de réflexion disponibles pour tout objet Uno.
Xray est capable d'afficher dans un navigateur web la documentation officielle de l'API concernant une propriété, une méthode, un service ou une interface de l'objet.
Xray peut effectuer une analyse récursive sur l'objet en cours, si une propriété contient un objet API, ou si une méthode renvoie un objet API.
Xray est une aide, mais il ne peut pas remplacer la lecture de la documentation existante (le Basic Programming Guide, le Developer's Guide et la description IDL du SDK).
Le livre Programmation OpenOffice.org et LibreOffice aux éditions Eyrolles, décrit le Basic OpenOffice et l'API d'OpenOffice avec de très nombreux exemples. Il est d'un abord plus facile que la documentation officielle, et souvent plus complet.
III. Installation▲
Le document Description de l'outil Xray, qui contient des macros, comporte dans le texte un bouton pour installer Xray sur l'ordinateur, et un bouton pour le désinstaller.
IV. Utilisation▲
Xray ne change rien à l'EDI. C'est un sous-programme que vous devez appeler depuis votre codage.
IV-A. Lancement▲
Dans votre macro en cours de mise au point, vous devez insérer (temporairement) un appel de la macro Xray. La plupart des écrans affichés au chapitre 3.2 ont été réalisés sur un document Writer en exécutant cette simple macro :
Sub Main
Xray ThisComponent
End SubDans cet autre exemple d'une macro d'un document Calc, l'objet correspondant à la première feuille va être visualisé :
Document = ThisComponent
Feuilles = Document.getSheets()
Feuille1 = Feuilles.getByIndex(0)
Xray Feuille1Si la ligne de code Xray déclenche une erreur d'exécution, c'est que la bibliothèque n'est pas chargée ; lisez les sections IV.A.1Chargement manuel de la bibliothèque XrayTool et 2Chargement automatique de la bibliothèque XrayTool.
IV-A-1. Chargement manuel de la bibliothèque XrayTool▲
Pour que la macro principale Xray soit reconnue, il est nécessaire que la bibliothèque XrayTool soit chargée. Celle-ci se trouve dans « Mes Macros ». Le panneau affiche la bibliothèque XrayTool non colorée si elle n'est pas chargée :
Pour charger la bibliothèque XrayTool, il suffit de faire un double-clic sur son nom. La branche de ses modules se développe :
IV-A-2. Chargement automatique de la bibliothèque XrayTool▲
Pour éviter d'effectuer la petite manipulation précédente à chaque démarrage d'OpenOffice, installez la macro ci-dessous dans Mes Macros.Standard.
Sub LoadingLibraries
BasicLibraries.LoadLibrary(« XrayTool »)
End SubAssignez-la à l'événement « Démarrage de l'application ». Vérifiez bien ce qu'indique la case du bas « Enregistrer dans » :
La même macro peut vous servir à charger d'autres bibliothèques de l'application.
IV-B. Affichages▲
À l'exécution de votre macro, un panneau va afficher des informations sur l'objet. Vous pouvez visualiser :
- Ses propriétés ;
- Ses méthodes ;
- Ses services ;
- Ses interfaces ;
- Ses listeners.
Les barres de défilement en haut à droite vous permettent d'augmenter la surface d'affichage :
Le tableau suivant liste des raccourcis utiles.
|
Raccourci |
Utilisation |
|
touches Ctrl-F1 |
Affiche la documentation concernant la ligne pointée par le curseur. |
|
touches Ctrl-F |
Recherche un texte dans l'information affichée. |
|
touche F2 |
Sélectionne / désélectionne la ligne pointée par le curseur. |
|
touche F4 |
Affiche des détails concernant la ligne pointée par le curseur. |
|
touche F5 |
Analyse par Xray l'élément dans la ligne pointée par le curseur. |
|
Double-clic |
Comme F5. Ce raccourci peut être désactivé. |
IV-B-1. Affichage Propriétés▲
Par défaut, les propriétés sont affichées dans l'ordre fourni par l'introspection. Vous pouvez les afficher en ordre alphabétique en cliquant la case Affichage « A … Z ».
Si le type de la propriété est précédé de [], cette propriété contient un tableau (une séquence API) dont chaque élément est du type indiqué. L'indication struct signifie que la propriété est une structure Uno. L'indication object correspond aux autres objets de l'API.
La valeur de chaque propriété est affichée, lorsque c'est possible. Cas particuliers :
- l'indication <empty> ou <null> signifie que la propriété n'a pas de valeur dans ce contexte ; si un tableau est vide, il est indiqué <empty> ;
- le contenu d'un string, est affiché entouré de guillemets ; si l'affichage direct n'est pas possible (par exemple un texte trop long) l'indication <…> est affichée à la place ; la touche F4 vous affiche le texte complet ;
- aucune valeur n'est indiquée pour un type object, struct, ou un tableau ; mais il est possible de demander un Xray sur cet élément (touche F5).
Après avoir positionné le curseur sur une ligne, appuyez sur la touche F4 ou le bouton [?] : vous obtiendrez souvent des informations plus complètes sur la propriété.
IV-B-2. Structure UNO▲
Une structure UNO est affichée comme un panneau de propriétés. Chaque ligne décrit un élément de la structure. Un objet structure UNO ne possède ni méthodes, ni services, ni interfaces, ni listeners.
IV-B-3. Affichage Méthodes▲
Par défaut, les méthodes sont affichées dans l'ordre fourni par l'introspection. Vous pouvez les afficher par ordre alphabétique en cliquant la case Affichage « A … Z ».
La deuxième colonne liste les paramètres de la méthode, en reprenant la syntaxe Basic. Le nom de chaque argument est fourni par l'introspection de l'objet. Le type de chaque argument est affiché comme dans l'onglet Propriétés.
Si la méthode renvoie une valeur, son type est indiqué en troisième colonne, après AS. Sinon, rien n'est affiché dans cette colonne.
L'interface exportant la méthode est indiquée dans la colonne la plus à droite (augmentez la largeur ou utilisez l'ascenseur horizontal).
Si une méthode vous semble peu claire, appuyez sur la touche F4 ou le bouton [?] après avoir positionné le curseur sur la ligne. Par exemple, sur le cliché ci-dessus, les méthodes addEventListener() et removeEventListener() sont marquées avec un point d'interrogation. La raison est expliquée dans le panneau affiché par F4.
IV-B-4. Affichage détaillé▲
La case à cocher « Détails » donne un affichage détaillé des propriétés et méthodes. Ce mode d'affichage est plus difficile à lire, mais plus utile au programmeur expérimenté.
Les informations sont nombreuses, il sera utile d'élargir le panneau. Pour mieux voir la ligne courante, appuyez sur la touche F2 pour la sélectionner, et utilisez l'ascenseur horizontal.
Le raccourci clavier Ctrl-F vous permet de rechercher un terme particulier dans le panneau. Si un terme est déjà sélectionné, il sera recherché plus loin dans le texte, à chaque Ctrl-F. Si rien n'est sélectionné un panneau vous demandera le terme à rechercher.
La touche F4 ou le bouton « ? » affichent une fenêtre détaillant plus clairement la ligne pointée par le curseur. Le raccourci Ctrl-F fonctionne aussi dans cette fenêtre.
Vous pouvez choisir l'affichage par défaut : normal ou détaillé, en ordre naturel ou alphabétique, avec un panneau principal élargi à votre convenance.
Si vous avez un grand écran …
IV-B-5. Affichage Services▲
On obtient deux listes de services :
- les services supportés systématiquement par l'objet ;
- les services disponibles, qui peuvent être obtenus par la méthode createInstance() de l'objet.
Chaque liste est affichée par ordre alphabétique. La documentation API de chaque service peut être recherchée.
IV-B-6. Affichage Interfaces▲
Les noms des interfaces exportées par l'objet sont listés par ordre alphabétique. La documentation API de chaque interface peut être recherchée.
IV-B-7. Affichage listeners▲
Les listeners sont des interfaces permettant de surveiller des événements. Pour chaque listener, Xray affiche :
- les événements qu'il traite ;
- les méthodes de l'objet qui utilisent ce listener dans un des arguments.
La documentation API de chaque méthode et chaque événement peut être recherchée en pointant la ligne souhaitée.
La documentation d'un événement décrit une méthode dont l'argument, lui-même documenté, contient les données associées à l'événement.
IV-B-8. Affichage d'autres valeurs▲
Xray peut afficher aussi bien une valeur simple (un nombre, une chaîne de caractères, etc.) qu'un tableau quelconque. Les manipulations possibles sont identiques à celles pour un objet de l'API.
Xray peut afficher le contenu de tous les éléments d'un tableau, dans la limite du panneau d'affichage et pour un tableau ayant jusqu'à cinq dimensions.
IV-C. Analyse en cascade▲
En affichage « Propriétés », vous pouvez demander à analyser le contenu d'une des lignes affichées en la pointant par un clic de souris, puis en cliquant sur le bouton [Xray], ou en appuyant sur la touche F5, ou par un double-clic dans la ligne.
De cette manière, vous pouvez analyser différents objets inclus dans l'objet originel, aussi bien que des objets d'objet d'objet d'objet, etc.
En affichage « Méthodes » vous pouvez demander à analyser la valeur renvoyée par une méthode, à condition qu'elle n'utilise aucun argument, ou un seul argument simple.
Pour analyser le résultat d'une méthode utilisant des arguments plus complexes, il est nécessaire de fermer Xray, revenir dans l'éditeur sur votre macro, et modifier l'appel de Xray en utilisant des arguments corrects, par exemple :
xray Feuille1.getCellByPosition(3,5)Le premier bouton à droite de la liste déroulante permet de revenir à l'objet parent de celui actuellement affiché. Le second bouton sert à revenir à l'objet initial.
Pour revenir sur un des objets déjà analysés, cliquez sur la liste de choix présente dans le cadre « Objet Affiché », et choisissez une des entrées existantes :
IV-D. Documentation API▲
Xray peut afficher dans votre navigateur la documentation de l'API OpenOffice.org concernant :
- une propriété, un attribut, une structure UNO ;
- une méthode ;
- un service, une interface ou un listener.
Pour cela, Xray doit être configuré pour utiliser la documentation API.
IV-D-1. La documentation API▲
La documentation API existe seulement en anglais.
Cette documentation se trouve soit sur un serveur Web d'Apache OpenOffice ou LibreOffice, soit dans le SDK, qu'on doit alors télécharger puis installer en local ou sur votre réseau.
Il est bien préférable d'utiliser le SDK afin de s'affranchir des temps de réponse du serveur Web. Le SDK contient d'autres documentations qui pourront intéresser le programmeur chevronné.
Télécharger le SDK :
Les adresses indiquées étaient valides à la date du document.
- Le plus récent SDK d'Apache OpenOffice est téléchargeable depuis cette page.
- Le plus récent SDK de LibreOffice est téléchargeable depuis cette page.
Depuis la version 4.2 de LibreOffice, la documentation du SDK fournie par
LibreOffice a changé de format. Ce nouveau format étant inadapté à une analyse automatique, Xray ne peut plus explorer le SDK de LibreOffice pour rechercher la documentation d'un objet de l'API.
IV-D-2. Afficher la documentation sur un objet▲
Pointez la ligne dans laquelle se trouve la propriété, la méthode, le service ou l'interface dont vous voulez voir la documentation. Cliquez ensuite sur le bouton [Doc API] ou appuyez sur les touches Ctrl-F1.
Remarque : les lignes commençant par une ou plusieurs espaces sont ignorées.
Il arrive qu'aucune page n'existe. Soit il s'agit d'un détail interne volontairement non documenté, soit la documentation est incomplète sur ce point.
V. Xray Menu▲
Cette fenêtre est lancée par la macro XrayMenu qui se trouve dans la bibliothèque XrayTool, module XUtils. Elle permet de lancer Xray sur des objets courants : le document en cours, la feuille Calc ou la page Draw en cours, un élément sélectionné dans le document (figure, image, cellule, mot ou curseur, etc). Elle peut aussi convertir une adresse système en adresse URL ou l'inverse.
Conseil :
Configurez OpenOffice pour appeler XrayMenu depuis un raccourci clavier comme Alt-F5 :
VI. Utiliser Xray avec d'autres langages de programmation▲
L'API d'OpenOffice dispose d'un mécanisme de lancement de script. Xray n'est pas autre chose qu'un script en Basic, ainsi tout langage de programmation permettant d'utiliser l'API peut l'appeler. C'est le cas des autres langages de script intégrés dans OpenOffice : Python, BeanShell, JavaScript. La plupart des langages modernes disponibles sous MS-Windows peuvent manipuler l'API Apache OpenOffice en utilisant COM, ils peuvent donc appeler le script Basic Xray.
Le document Description de l'outil Xray fournit des exemples d'appel de Xray depuis des scripts OpenOffice en Python, BeanShell, JavaScript, et depuis les langages externes VBA et Delphi en utilisant COM.
VII. Remerciements▲
Nous remercions Bernard Marcelly de nous avoir autorisés à publier son manuel sur son formidable outil Xray.
Et pour la correction orthographique et syntaxique : ced.
