Chapitre 4 Introduction à l'API StarOffice

L'API StarOffice est une interface de programmation universelle d'accès à StarOffice. Vous pouvez utiliser l'API StarOffice pour créer, ouvrir, modifier et imprimer des documents StarOffice. Cette interface permet d'étendre les fonctions de StarOffice (grâce à des macros personnelles) et de concevoir des boîtes de dialogue personnalisées.

L'API StarOffice peut être utilisée avec StarOffice Basic, mais également avec d'autres langages de programmation comme Java et C++, grâce à la technique Universal Network Objects (UNO) qui fournit une interface compatible avec différents langages de programmation.

Ce chapitre se concentre sur la manière d'utiliser StarOffice dans StarOffice Basic à l'aide d'UNO. Il décrit les principaux concepts d'UNO du point de vue d'un programmeur StarOffice Basic. Vous trouverez dans les chapitres suivants des informations sur la façon de travailler avec les différents composants de l'API StarOffice.

Universal Network Objects (UNO)

StarOffice fournit une interface de programmation sous la forme d'une architecture UNO (Universal Network Objects). Il s'agit d'une interface de programmation orientée objet que StarOffice divise en différents objets permettant un accès contrôlé par programme au package Office.

StarOffice Basic étant un langage de programmation procédural, il a fallu lui ajouter plusieurs constructions linguistiques pour pouvoir utiliser UNO.

Afin de pouvoir utiliser une architecture Universal Network Object dans StarOffice Basic, vous devez déclarer une variable pour l'objet associé. Cette déclaration se fait avec l'instruction Dim (reportez-vous au Chapitre 2, Langage de StarOffice Basic). Pour déclarer une variable d'objet, vous devez utiliser la désignation du type Object :

Dim Obj As Object

Cet appel déclare une variable d'objet nommée Obj.

La variable d'objet ainsi créée doit ensuite être initialisée à l'aide de la fonction createUnoService :

Obj = createUnoService("com.sun.star.frame.Desktop")

Cet appel assigne à la variable Obj une référence à l'objet qui vient d'être créé. com.sun.star.frame.Desktop ressemble à un type d'objet, mais dans la terminologie UNO, on parle plus volontiers de service que de type. Selon la philosophie UNO, un Obj est décrit comme étant une référence à un objet prenant en charge le service com.sun.star.frame.Desktop. Le terme "service" employé dans StarOffice Basic correspond donc aux termes type et classe employés dans d'autres langages de programmation.

Il existe cependant une différence fondamentale : la technologie Universal Network Object peut prendre en charge plusieurs services simultanément. Certains services UNO prennent également en charge d'autres services, si bien qu'à travers un seul objet, vous pouvez accéder à tout un éventail de services. Il est possible, par exemple, que l'objet mentionné précédemment, basé sur le service com.sun.star.frame.Desktop, inclue également d'autres services pour charger des documents et mettre fin au programme.

---

Remarque –

Alors que dans VBA la structure d'un objet est définie par la classe à laquelle il appartient, dans StarOffice Basic sa structure est définie par les services qu'il prend en charge. Un objet VBA est toujours assigné à une classe unique. Un objet StarOffice Basic peut quant à lui prendre en charge plusieurs services.

---

Propriétés et méthodes

Les objets dans StarOffice Basic fournissent plusieurs propriétés et méthodes qui peuvent être appelées à l'aide de ces objets.

Propriétés

Les propriétés ressemblent aux propriétés d'un objet : Filename et Title pour un objet Document, par exemple.

Les propriétés sont définies grâce à une simple assignation :

Document.Title = "StarOffice 8 Basic Programmer's Guide"
Document.Filename = "progman.sxv"

Une propriété, tout comme une variable normale, possède un type définissant les valeurs qu'elle peut enregistrer. Les propriétés Filename et Title évoquées précédemment sont de type chaîne.

Propriétés réelles et propriétés imitées

La plupart des propriétés d'un objet dans StarOffice Basic sont définies comme telles dans la description UNO du service. En plus de ces propriétés "réelles", il existe également dans StarOffice Basic des propriétés constituées de deux méthodes au niveau UNO. L'une sert à obtenir la valeur de la propriété et l'autre à la définir : il s'agit des méthodes get et set. La propriété a été virtuellement imitée à partir de deux méthodes. Les objets de caractère dans UNO, par exemple, proposent les méthodes getPosition et setPosition qui permettent de connaître et de modifier le point clé associé. Le programmeur StarOffice Basic peut ainsi accéder à ces valeurs via la propriété Position. Indépendamment de cela, les méthodes d'origine sont également disponibles (dans notre exemple, getPosition et setPosition).

Méthodes

On peut considérer les méthodes comme des fonctions directement liées à un objet qui permettent d'appeler cet objet. L'objet Document précédent, par exemple, propose une méthode Save, pouvant être appelée de la manière suivante :

Document.Save()

Les méthodes, à l'instar des fonctions, peuvent contenir des paramètres et des valeurs de retour. La syntaxe de ces appels de méthode est orientée vers les fonctions classiques. L'appel

Ok = Document.Save(True)

spécifie également le paramètre True pour l'objet Document en invoquant la méthode Save. Une fois la méthode terminée, Save enregistre une valeur de retour dans la variable Ok.

Modules, services et interfaces

StarOffice fournit des centaines de services. Afin que l'utilisateur en ait une meilleure vue générale, ils ont été regroupés en modules. Ces modules n'ont aucun autre intérêt fonctionnel pour les programmeurs StarOffice Basic. Lorsque vous spécifiez le nom d'un service, seul le nom du module importe, puisqu'il doit aussi apparaître dans le nom indiqué. Le nom complet d'un service est constitué de l'expression com.sun.star, qui spécifie qu'il s'agit d'un service StarOffice, suivie du nom du module, frame par exemple, et enfin du nom du service en lui-même, comme Desktop. Le nom complet dans ce cas serait alors :

com.sun.star.frame.Desktop

En plus des termes module et service, UNO utilise le terme interface, que les programmeurs Java connaissent certainement mais qui n'apparaît pas en Basic.

Une interface rassemble plusieurs méthodes. Au sens le plus strict du mot, un service dans UNO ne prend pas en charge des méthodes, mais plutôt des interfaces qui proposent quant à elles différentes méthodes. En d'autres termes, les méthodes sont assignées (sous forme de combinaisons) au service dans des interfaces. Ce détail peut être intéressant en particulier pour les programmeurs Java ou C++ : dans ces langages, en effet, il faut une interface pour appeler une méthode. Dans StarOffice Basic, cela n'a aucune importance. Ici, les méthodes sont appelées directement via l'objet concerné.

Pour bien comprendre le fonctionnement de l'API, il est cependant utile de maîtriser l'assignation des méthodes à différentes interfaces, car un grand nombre d'interfaces sont utilisées dans les différents services. Si vous êtes familier avec une interface, vous pourrez appliquer les connaissances acquises avec un service à un autre.

Certaines interfaces centrales sont utilisées si fréquemment qu'elles sont de nouveau traitées à la fin de ce chapitre, appelées par différents services.

Outils pour l'utilisation d'UNO

Il reste à savoir quels objets – ou services, pour employer la terminologie UNO – prennent en charge quelles propriétés, méthodes et interfaces et comment les déterminer. En plus de ce manuel, vous pouvez vous référer aux sources suivantes pour obtenir des informations complémentaires sur les objets : la méthode supportsService, les méthodes de débogage, sans oublier le Developer's Guide (Guide du développeur) et la référence de l'API.

Méthode supportsService

Certains objets UNO prennent en charge la méthode supportsService qui permet de déterminer si un objet prend en charge ou non un service spécifique. L'appel

Ok = TextElement.supportsService("com.sun.star.text.Paragraph")

détermine par exemple si l'objet TextElement prend en charge le service com.sun.star.text.Paragraph.

Propriétés de débogage

Chaque objet UNO de StarOffice Basic sait quelles propriétés, méthodes et interfaces il contient. Il dispose de propriétés qui permettent d'en renvoyer la liste. Les propriétés correspondantes sont :

DBG_properties : renvoie une chaîne contenant toutes les propriétés d'un objet.

DBG_methods : renvoie une chaîne contenant toutes les méthodes d'un objet.

DBG_supportetInterfaces : renvoie une chaîne contenant toutes les interfaces prenant en charge un objet.

Le code de programme suivant montre comment utiliser DBG_properties et DBG_methods dans des applications réelles. Il commence par créer le service com.sun.star.frame.Desktop, puis affiche les propriétés et les méthodes prises en charge dans des boîtes de message.

Dim Obj As Object Obj = createUnoService("com.sun.star.frame.Desktop")

MsgBox Obj.DBG_Propierties MsgBox Obj.DBG_methods

Lorsque vous utilisez DBG_properties, n'oubliez pas que la fonction renvoie l'ensemble des propriétés qu'un service donné peut théoriquement prendre en charge. Vous n'avez cependant aucune garantie que l'objet concerné puisse également les utiliser. Avant d'appeler une propriété, vous devez donc utiliser la fonction IsEmpty pour vérifier qu'elle est effectivement disponible.

Référence de l'API

Vous trouverez des informations complémentaires sur les services disponibles ainsi que leurs interfaces, méthodes et propriétés dans la référence pour l'API StarOffice, sur le site www.openoffice.org :

http://api.openoffice.org/docs/common/ref/com/sun/star/module-ix.html

Présentation de quelques interfaces centrales

Certaines interfaces de StarOffice se retrouvent dans de nombreux composants de l'API StarOffice. Elles définissent des ensembles de méthodes pour des tâches abstraites pouvant s'appliquer à différents types de problèmes. Voici une présentation des interfaces les plus courantes.

L'origine des objets sera expliquée plus loin dans ce manuel. Nous nous contentons pour l'instant de traiter certains aspects abstraits des objets pour lesquels l'API StarOffice propose certaines interfaces centrales.

Création d'objets contextuels

L'API StarOffice propose deux options de création d'objets. La première se trouve dans la fonction createUnoService mentionnée au début de ce chapitre. createUnoService crée un objet qui peut être utilisé de manière universelle. Ces objets et services sont également connus sous le nom de services indépendants du contexte.

Il existe également des services contextuels dont les objets ne sont utiles que s'ils sont utilisés conjointement avec un autre objet. Un objet de dessin de classeur, par exemple, ne peut exister que conjointement avec ce document précis.

Interface com.sun.star.lang.XMultiServiceFactory

Les objets contextuels sont généralement créés par une méthode d'objet dont dépend l'objet. La méthode createInstance, définie dans l'interface XMultiServiceFactory, est notamment utilisée dans les objets Document.

L'objet de dessin mentionné précédemment peut, par exemple, être créé de la manière suivante en utilisant un objet Spreadsheet :

Dim RectangleShape As Object

RectangleShape = _ 
   Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")

Vous pouvez créer un modèle de paragraphe dans un document texte de la même manière :

Dim Style as Object
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")

Accès nommé aux objets subordonnés

Les interfaces XNameAccess et XNameContainer sont utilisées dans des objets contenant des objets subordonnés, qui peuvent être adressés par un nom en langage naturel.

Alors que XNamedAccess permet d'accéder aux objets individuels, XNameContainer se charge d'insérer, de modifier et de supprimer des éléments.

Interface com.sun.star.container.XNameAccess

L'objet Sheet d'un classeur fournit un bon exemple d'utilisation de XNameAccess. Il regroupe les différentes pages du classeur. Il accède aux différentes pages grâce à la méthode getByName de XNameAccess :

Dim Sheets As Object Dim Sheet As Object

Sheets = Spreadsheet.Sheets Sheet = Sheets.getByName("Sheet1")

La méthode getElementNames permet d'obtenir un aperçu des noms de tous les éléments. Elle renvoie comme résultat un champ de données contenant les différents noms. L'exemple suivant montre comment déterminer de cette manière les noms de tous les éléments d'un classeur et les afficher dans une boucle :

Dim Sheets As Object Dim SheetNames Dim I As Integer

Sheets = Spreadsheet.Sheets SheetNames = Sheets.getElementNames

For I=LBound(SheetNames) To UBound(SheetNames) MsgBox SheetNames(I) Next I

La méthode hasByName de l'interface XNameAccess indique si un objet subordonné portant un nom donné existe dans l'objet de base. L'exemple suivant affiche un message indiquant à l'utilisateur si l'objet Spreadsheet contient une page nommée Feuille1.

Dim Sheets As Object

Sheets = Spreadsheet.Sheets 
If Sheets.HasByName("Sheet1") Then 
   MsgBox " Sheet1 available" 
Else MsgBox "Sheet1 not available" 
End If

Interface com.sun.star.container.XNameContainer

L'interface XNameContainer permet d'insérer, de supprimer et de modifier des éléments subordonnés dans un objet de base. Les fonctions concernées sont insertByName, removeByName et replaceByName.

Voici un exemple pratique : un document texte contenant un objet StyleFamilies est appelé et l'objet est utilisé pour rendre les modèles de paragraphe (ParagraphStyles) du document disponibles.

Dim StyleFamilies As Objects 
Dim ParagraphStyles As Objects 
Dim NewStyle As Object

StyleFamilies = Textdoc.StyleFamilies 
ParagraphStyles = StyleFamilies.getByName("ParagraphStyles")

ParagraphStyles.insertByName("NewStyle", NewStyle) 
ParagraphStyles.replaceByName("ChangingStyle", NewStyle) 
ParagraphStyles.removeByName("OldStyle")

La ligne insertByName insère le style NewStyle sous le même nom dans l'objet ParagraphStyles. La ligne replaceByName change l'objet derrière ChangingStyle en NewStyle. Enfin, l'appel removeByName supprime l'objet derrière OldStyle de ParagraphStyles.

Accès par index aux objets subordonnés

Les interfaces XIndexAccess et XIndexContainer sont utilisées dans les objets contenant des objets subordonnés pouvant être adressés par index.

XIndexAccess fournit les méthodes d'accès aux différents objets. XIndexContainer fournit les méthodes d'insertion et de suppression des éléments.

Interface com.sun.star.container.XIndexAccess

XIndexAccess propose les méthodes getByIndex et getCount pour appeler les objets subordonnés : getByIndex renvoie un objet avec un index donné et getCount renvoie le nombre d'objets disponibles.

Dim Sheets As Object Dim Sheet As Object Dim I As Integer

Sheets = Spreadsheet.Sheets

For I = 0 to Sheets.getCount() - 1 
  Sheet = Sheets.getByIndex(I) 

L'exemple montre une boucle parcourant toutes les feuilles d'un classeur l'une après l'autre et enregistrant une référence pour chaque feuille dans la variable d'objet Sheet. Notez que lorsque vous travaillez avec des index, getCount renvoie le nombre d'éléments. Les éléments de getByIndex sont numérotés à partir de 0. La variable servant de compteur à la boucle oscille donc entre 0 et getCount()-1.

Interface com.sun.star.container.XIndexContainer

L'interface XIndexContainer propose les fonctions insertByIndex et removeByIndex. Les paramètres sont structurés de la même manière que les fonctions correspondantes dans XNameContainer.

Accès itératif aux objets subordonnés

Dans certaines instances, un objet peut contenir une liste d'objets subordonnés qui ne peuvent pas être adressés au moyen d'un nom ou d'un index. C'est alors que les interfaces XEnumeration et XenumerationAccess se révèlent utiles. Elles proposent un mécanisme permettant d'atteindre les différents éléments subordonnés d'un objet, l'un après l'autre, sans recourir à une méthode d'adressage direct.

Interfaces com.sun.star.container.XEnumeration et XenumerationAccess

L'objet de base doit proposer l'interface XEnumerationAccess, qui contient uniquement la méthode createEnumeration. Elle renvoie un objet auxiliaire, qui fournit à son tour l'interface XEnumeration avec les méthodes hasMoreElements et nextElement. Ces méthodes permettent d'accéder aux objets subordonnés.

L'exemple suivant parcourt les différents paragraphes d'un texte :

Dim ParagraphEnumeration As Object Dim Paragraph As Object

ParagraphEnumeration = Textdoc.Text.createEnumeration

While ParagraphEnumeration.hasMoreElements() 
      Paragraph = ParagraphElements.nextElement() 
Wend

L'exemple commence par créer un objet auxiliaire ParagraphEnumeration. Il renvoie les paragraphes du texte individuellement, dans une boucle. La boucle se termine dès que la méthode hasMoreElements renvoie la valeur False, qui signale que la fin du texte a été atteinte.