Difference between revisions of "Extensions development basic fr"

From Apache OpenOffice Wiki
Jump to: navigation, search
(L'API OpenOffice.org)
m (L'Outil Xray)
 
(16 intermediate revisions by 6 users not shown)
Line 39: Line 39:
 
Pour commencer, nous allons utiliser le Module1 de la bibliothèque Standard, présente pour l'utilisateur courant uniquement.  
 
Pour commencer, nous allons utiliser le Module1 de la bibliothèque Standard, présente pour l'utilisateur courant uniquement.  
  
Entrons un nom pour notre nouvelle macro : '''HelloWorld'''  
+
Saisissons un nom pour notre nouvelle macro : '''HelloWorld'''  
  
Dans la macro, sélectionnons '''Standard''' dans la boîte de liste.
+
Dans la macro, sélectionnons '''Standard''' dans la zone de liste.
  
Cliquons '''Nouveau'''  
+
Cliquons sur '''Nouveau'''  
  
Nous devons maintenant trouver quelque chose comme çà :  
+
Nous devons maintenant trouver quelque chose comme ça :  
  
<code>[oobas]
+
<source lang="oobas">
 
REM  *****  BASIC  *****
 
REM  *****  BASIC  *****
 
   
 
   
Line 57: Line 57:
 
   
 
   
 
End Sub
 
End Sub
</code>
+
</source>
 
Le curseur est positionné au début de la ligne <tt>Sub HelloWorld</tt>.  
 
Le curseur est positionné au début de la ligne <tt>Sub HelloWorld</tt>.  
  
Line 67: Line 67:
  
 
=Saisie de code=
 
=Saisie de code=
Selectionnons et effaçons :  
+
Sélectionnons et effaçons :  
  
<code>[oobas]
+
<source lang="oobas">
 
REM  *****  BASIC  *****
 
REM  *****  BASIC  *****
 
   
 
   
Line 75: Line 75:
 
   
 
   
 
End Sub
 
End Sub
</code>
+
</source>
Au-dessous de la ligne "Sub HelloWorld" entrons <tt>msgbox "Hello World!"</tt>, de manière que l'éditeur ressemble à ceci :  
+
Au-dessous de la ligne "Sub HelloWorld" entrons <tt>msgbox "Hello World!"</tt>, de manière à ce que l'éditeur ressemble à ceci :  
  
<code>[oobas]
+
<source lang="oobas">
 
Sub HelloWorld
 
Sub HelloWorld
 
   msgbox "Hello World!"
 
   msgbox "Hello World!"
 
End Sub
 
End Sub
</code>
+
</source>
 
{| border="1"
 
{| border="1"
 
|'''Notes:'''
 
|'''Notes:'''
|L'IDE ne fournit aucune fonctionnalité de code completion ni d'aide sur la syntaxe des commandes lors de la frappe. Pour obtenir de l'aide sur une commande Basic, plaçons le curseur dans la commande et tapons F1.<br> Les commandes OpenOffice.org Basic ne sont pas sensibles à la casse. C'est pourquoi msgbox, MSGBOX et Msgbox sont équivalents.<br> Les chaînes sont entourées de guillemets doubles.
+
|L'IDE ne fournit aucune fonctionnalité de complétion du code, ni d'aide sur la syntaxe des commandes lors de la frappe. Pour obtenir de l'aide sur une commande Basic, plaçons le curseur dans la commande et tapons F1.<br> Les commandes OpenOffice.org Basic ne sont pas sensibles à la casse. C'est pourquoi msgbox, MSGBOX et Msgbox sont équivalents.<br> Les chaînes sont entourées de guillemets doubles.
 
|-
 
|-
 
|}
 
|}
Line 102: Line 102:
 
*Par assignation de la macro à une [[ touche]].  
 
*Par assignation de la macro à une [[ touche]].  
  
*Par assignation de la macro à une [[ entrée de menu]].  
+
*Par assignation de la macro à une [[ option de menu]].  
  
 
*Par assignation de la macro à un bouton de barre d'outil.  
 
*Par assignation de la macro à un bouton de barre d'outil.  
Line 110: Line 110:
 
*Par assignation de la macro à un évènement.  
 
*Par assignation de la macro à un évènement.  
  
Pour l'instant essayons de lancer la procédure "HelloWorld" en cliquant le bouton '''Exécuter'''. Un dialogue intitulé "soffice" et comportant le texte "Hello World!" ainsi qu'un bouton OK doit s'afficher.
+
Pour l'instant essayons de lancer la procédure "HelloWorld" en cliquant sur le bouton '''Exécuter'''. Un dialogue intitulé "soffice" et comportant le texte "Hello World!" ainsi qu'un bouton OK doit s'afficher.
  
 
=Enregistrement du code=
 
=Enregistrement du code=
Le code est enregistré automatiquement chaque fois que son conteneur est lui-même enregistré. Par conséquent, si le code se trouve dans une bibliothèque OpenOffice (partagée ou de l'utilisateur), il est automatiquement enregistré lorsque OpenOffice est refermé. Si le code se trouve dans une bilbiothèque qui fait partie d'un document, alors il est enregistré lorsque le document l'est.  
+
Le code est enregistré automatiquement chaque fois que son conteneur est lui-même enregistré. Par conséquent, si le code se trouve dans une bibliothèque OpenOffice.org (partagée ou de l'utilisateur), il est automatiquement enregistré lorsque OpenOffice.org est refermé. Si le code se trouve dans une bilbiothèque qui fait partie d'un document, alors il est enregistré lorsque le document l'est.  
  
Un bouton Enregistrer figure sur la barre d'outils Standard (celle du haut par défaut). Si le code se trouve à l'intérieur d'un document ou modèle, alors la totalité du document est enregistrée. Si le code se trouve à l'intérieur d'une bibliothèque OpenOffice.org alors seule la bilbiothèque courante est enregistrée.
+
Un bouton Enregistrer figure dans la barre d'outils Standard (celle du haut par défaut). Si le code se trouve à l'intérieur d'un document ou modèle, alors la totalité du document est enregistrée. Si le code se trouve à l'intérieur d'une bibliothèque OpenOffice.org alors seule la bilbiothèque courante est enregistrée.
  
 
=Les variables=
 
=Les variables=
Line 173: Line 173:
 
Editons la routine sub HelloWorld de manière qu'elle ressemble à ceci et exécutons-la :  
 
Editons la routine sub HelloWorld de manière qu'elle ressemble à ceci et exécutons-la :  
  
<code>[oobas]
+
<source lang="oobas">
 
sub HelloWorld
 
sub HelloWorld
 
dim i as integer 'ligne optionnelle
 
dim i as integer 'ligne optionnelle
Line 182: Line 182:
 
   next i
 
   next i
 
end sub
 
end sub
</code>
+
</source>
 
Pour plus d'informations sur les variables, reportons-nous à l'aide en ligne, rubrique "variables;utilisation".
 
Pour plus d'informations sur les variables, reportons-nous à l'aide en ligne, rubrique "variables;utilisation".
  
Line 190: Line 190:
 
Essayons d'exécuter le code ci-dessous lorsque différents types de documents sont ouverts.
 
Essayons d'exécuter le code ci-dessous lorsque différents types de documents sont ouverts.
  
<code>[oobas]
+
<source lang="oobas">
 
sub main
 
sub main
 
'BasicLibraries.loadLibrary("XrayTool")
 
'BasicLibraries.loadLibrary("XrayTool")
Line 215: Line 215:
 
end if
 
end if
 
End function
 
End function
</code>
+
</source>
  
 
==Convention de nommage des routines==
 
==Convention de nommage des routines==
Line 252: Line 252:
 
'''SupportsService''' est une méthode qui renvoie la valeur "vrai" si le service spécifié est disponible. Dans l'exemple ci-dessus, on vérifie la présence d'un service afin de déterminer le type de document en cours d'activation.
 
'''SupportsService''' est une méthode qui renvoie la valeur "vrai" si le service spécifié est disponible. Dans l'exemple ci-dessus, on vérifie la présence d'un service afin de déterminer le type de document en cours d'activation.
  
==L'Outil X-Ray==
+
==L'Outil Xray==
L'utilisation de "HasUnoInterfaces" et de "supportsService" permet d'obtenir des informations sur un objet donné lors de son exécution, mais procéder ainsi pour apprendre le langage Basic deviendrait vite fastidieux. Heureusement, et grâce à Bernard Marcelly, nous disposons de l'outil X-Ray. Cet outil est disponible ici: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Téléchargez le fichier zip, dézippez l'archive, ouvrez le document dans OpenOffice.org, et suivez les instructions pour son installation et configuration.  
+
L'utilisation de "HasUnoInterfaces" et de "supportsService" permet d'obtenir des informations sur un objet donné lors de son exécution, mais procéder ainsi pour apprendre le langage Basic deviendrait vite fastidieux. Heureusement, et grâce à Bernard Marcelly, nous disposons de l'outil Xray. Cet outil est disponible ici en [[http://berma.pagesperso-orange.fr/Files_fr/XrayTool60_fr.odt version française]] et ici en [[http://berma.pagesperso-orange.fr/Files_en/XrayTool60_en.odt version anglaise]]. Téléchargez le fichier odt, ouvrez le document dans OpenOffice.org, et suivez les instructions pour son installation et configuration.  
  
Une partie de la configuration de l'outil X-Ray concerne la définition de l'endroit où est stockée une copie locale (sur le disque dur) du Kit de Développement OpenOffice.org (appélé SDK). Téléchargez le Kit de Développement OpenOffice.org depuis [[ftp://mirrors.dotsrc.org/openoffice/stable/2.0.4_sdk/]] et installez le sur votre disque dur.  
+
Une partie de la configuration de l'outil Xray concerne la définition de l'endroit où est stockée une copie locale (sur le disque dur) du Kit de Développement OpenOffice.org (appélé SDK). Téléchargez le Kit de Développement OpenOffice.org depuis [[http://www.openoffice.org/dev_docs/source/sdk/ le site du SDK]] et installez le sur votre disque dur.  
  
Dans l'exemple ci-dessus, au début du code, il y a deux lignes mises en commentaires (les lignes de commentaires commencent toujours avec des apostrophes):  
+
Dans l'exemple ci-dessus, au début du code, il y a deux lignes mises en commentaires (les lignes de commentaires commencent avec des apostrophes ou le mot réservé rem):  
  
<code>[oobas]
+
<source lang="oobas">
'basicLibraries.loadLibrary("Xray")
+
'BasicLibraries.loadLibrary("XrayTool")
'xray.xray thisComponent
+
'xray thisComponent
</code>
+
</source>
Une fois l'outil X-Ray installé, supprimez les apostrophes dans les lignes indiquées ci-dessus et relancez la macro. A partir de la version 5, la commande à utiliser dans votre code est tout simplement "xray".
+
Une fois l'outil Xray installé, supprimez les apostrophes dans les lignes indiquées ci-dessus et relancez la macro.
  
 
'''BasicLibraries''' est une commande OpenOffice.org Basic qui renvoie un objet permettant d'accéder aux bibliothèques OpenOffice.org. La méthode <tt>loadLibrary</tt> rend disponible aux utilisateurs les routines présentes dans cette bibliothèque.  
 
'''BasicLibraries''' est une commande OpenOffice.org Basic qui renvoie un objet permettant d'accéder aux bibliothèques OpenOffice.org. La méthode <tt>loadLibrary</tt> rend disponible aux utilisateurs les routines présentes dans cette bibliothèque.  
  
<tt>xray.xray</tt> indique la bibliothèque xray et la sous-routine xray contenue dans celle-ci, l'objet thisComponent étant l'objet transmis à xray pour l'introspection.  
+
<tt>xray</tt> indique la routine xray contenue dans la bibliothèque XrayTool, l'objet thisComponent étant l'objet transmis à xray pour l'introspection.  
  
 
Afin de trouver l'objet que vous cherchez, il est souvent nécessaire de le découvrir ou de le créer depuis StarDesktop ou thisComponent.
 
Afin de trouver l'objet que vous cherchez, il est souvent nécessaire de le découvrir ou de le créer depuis StarDesktop ou thisComponent.
Line 281: Line 281:
 
Pour créer un nouveau document Writer, on écrit le code suivant:  
 
Pour créer un nouveau document Writer, on écrit le code suivant:  
  
<code>[oobas]
+
<source lang="oobas">
 
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
 
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
+
</source>
  
 
De la même manière, pour un nouveau document Calc:  
 
De la même manière, pour un nouveau document Calc:  
  
<code>[oobas]
+
<source lang="oobas">
 
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
 
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
+
</source>
  
 
Il serait sans doute plus facile d'écrire une fonction simple:  
 
Il serait sans doute plus facile d'écrire une fonction simple:  
  
<code>[oobas]
+
<source lang="oobas">
 
function fnNewDoc(sDocType as string)
 
function fnNewDoc(sDocType as string)
 
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
 
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
 
end function
 
end function
</code>
+
</source>
  
 
Ensuite, on pourra créer de nouveaux documents ainsi:  
 
Ensuite, on pourra créer de nouveaux documents ainsi:  
  
<code>[oobas]
+
<source lang="oobas">
 
oDoc = fnNewDoc("swriter")
 
oDoc = fnNewDoc("swriter")
 
oDoc = fnNewDoc("scalc")
 
oDoc = fnNewDoc("scalc")
Line 307: Line 307:
 
oDoc = fnNewDoc("sdraw")
 
oDoc = fnNewDoc("sdraw")
 
oDoc = fnNewDoc("smath")
 
oDoc = fnNewDoc("smath")
</code>
+
</source>
  
 
Voir également http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .
 
Voir également http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .
Line 314: Line 314:
 
Le code suivant donne un exemple permettant d'ouvrir un fichier. Pour plus d'informations sur l'utilisation d'URL au sein de OpenOffice.org, voir [[ URL Basics]].  
 
Le code suivant donne un exemple permettant d'ouvrir un fichier. Pour plus d'informations sur l'utilisation d'URL au sein de OpenOffice.org, voir [[ URL Basics]].  
  
<code>[oobas]
+
<source lang="oobas">
 
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
 
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
 
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
 
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
 
sURL = ConvertToURL(sFile)
 
sURL = ConvertToURL(sFile)
 
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
 
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
+
</source>
  
 
Ici encore, il peut être plus rationnel de simplifier le code en écrivant une fonction:  
 
Ici encore, il peut être plus rationnel de simplifier le code en écrivant une fonction:  
  
<code>[oobas]
+
<source lang="oobas">
 
function fnOpenDoc(sFile)
 
function fnOpenDoc(sFile)
 
sURL = ConvertToURL(sFile)
 
sURL = ConvertToURL(sFile)
 
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
 
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
 
end function
 
end function
</code>
+
</source>
  
 
Exemples d'utilisation de la fonction:  
 
Exemples d'utilisation de la fonction:  
  
<code>[oobas]
+
<source lang="oobas">
 
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
 
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
 
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
 
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>
+
</source>
  
 
==La sélection en cours==
 
==La sélection en cours==
Line 342: Line 342:
 
Editons la routine principale du code ci-dessous et re-exécutons-la successivement sur un document texte comportant plusieurs sélections différentes (pour sélectionner plus d'un bloc de texte, nous maintenons la touche Control enfoncée).  
 
Editons la routine principale du code ci-dessous et re-exécutons-la successivement sur un document texte comportant plusieurs sélections différentes (pour sélectionner plus d'un bloc de texte, nous maintenons la touche Control enfoncée).  
  
<code>[oobas]
+
<source lang="oobas">
 
sub main
 
sub main
basicLibraries.loadLibrary("Xray")
+
BasicLibraries.loadLibrary("XrayTool")
 
if fnWhichComponent(thisComponent) = "Text" then
 
if fnWhichComponent(thisComponent) = "Text" then
 
         oCurSelection = thisComponent.getCurrentSelection()
 
         oCurSelection = thisComponent.getCurrentSelection()
         'xray.xray oCurSelection
+
         'xray oCurSelection
 
         if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
 
         if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
 
                 msgbox "Il y a " & oCurSelection.getCount() & _
 
                 msgbox "Il y a " & oCurSelection.getCount() & _
Line 354: Line 354:
 
end if
 
end if
 
end sub
 
end sub
</code>
+
</source>
 
Lorsqu'il n'y a aucune sélection, le nombre affiché est un - le point d'insertion -, avec un bloc de text sélectionné, il renvoie également un, mais avec deux blocs de texte, ce nombre devient égal à trois - le point d'insertion et les deux blocs de texte sélectionnés.  
 
Lorsqu'il n'y a aucune sélection, le nombre affiché est un - le point d'insertion -, avec un bloc de text sélectionné, il renvoie également un, mais avec deux blocs de texte, ce nombre devient égal à trois - le point d'insertion et les deux blocs de texte sélectionnés.  
  
Line 362: Line 362:
  
 
==Les propriétés==
 
==Les propriétés==
Retirons le commentaire de <tt>'xray.xray oCurSelection</tt> de manière à lancer xray, ce qui permet de constater que l'objet pointé par <tt>oCurSelection</tt> possède une "propriété" nommée <tt>Count</tt> dont la description est "pseudo-prop, read only". Nous pourrions écrire <tt>oCurSelection.count</tt> en OpenOffice.org Basic, mais comme ce n'est pas possible dans tous les autres langages qui accèdent à l'API OpenOffice.org, ce wiki essaiera de toujours utiliser l'approche par méthode (je signale çà car je n'ai pas pris l'habitude de le faire et il m'arrive d'oublier).  
+
Retirons le commentaire de <tt>'xray oCurSelection</tt> de manière à lancer xray, ce qui permet de constater que l'objet pointé par <tt>oCurSelection</tt> possède une "propriété" nommée <tt>Count</tt> dont la description est "pseudo-prop, read only". Nous pourrions écrire <tt>oCurSelection.count</tt> en OpenOffice.org Basic, mais comme ce n'est pas possible dans tous les autres langages qui accèdent à l'API OpenOffice.org, ce wiki essaiera de toujours utiliser l'approche par méthode (je signale çà car je n'ai pas pris l'habitude de le faire et il m'arrive d'oublier).  
  
 
L'exemple suivant montre comment changer une valeur de propriété pour les sélections courantes.  
 
L'exemple suivant montre comment changer une valeur de propriété pour les sélections courantes.  
  
<code>[oobas]
+
<source lang="oobas">
 
sub main
 
sub main
basicLibraries.loadLibrary("Xray")
+
BasicLibraries.loadLibrary("XrayTool")
 
if fnWhichComponent(thisComponent) = "Text" then
 
if fnWhichComponent(thisComponent) = "Text" then
 
   oCurSelection = thisComponent.getCurrentSelection()
 
   oCurSelection = thisComponent.getCurrentSelection()
 
   if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
 
   if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
 
       nCount = oCurSelection.Count
 
       nCount = oCurSelection.Count
       'xray.xray oCurSelection.getByIndex(0)
+
       'xray oCurSelection.getByIndex(0)
 
       'Attention : le point d'insertion va voir la même action appliquée deux fois
 
       'Attention : le point d'insertion va voir la même action appliquée deux fois
 
       'ici çà n'a pas d'importance mais il est des cas ou cela pourrait en avoir.
 
       'ici çà n'a pas d'importance mais il est des cas ou cela pourrait en avoir.
Line 382: Line 382:
 
end if
 
end if
 
end sub
 
end sub
</code>
+
</source>
 
En Basic OpenOffice.org nous pouvons raccourcir la ligne d'affectation ainsi :  
 
En Basic OpenOffice.org nous pouvons raccourcir la ligne d'affectation ainsi :  
  
<code>[oobas]
+
<source lang="oobas">
 
oCurSelection(i).CharStyleName = "Strong Emphasis"
 
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
+
</source>
 
Ce wiki essaiera toujours d'utiliser les noms complets des méthodes pour l'indexation et l'assignation des propriétés. La raison en est que non seulement cela aide les nouveaux venus à comprendre ce qui se passe mais également nous rendons ainsi la conversion du code vers d'autres langages plus aisée (encore une fois, je n'ai pas l'habitude de pratiquer systématiquement ainsi, c'est pourquoi des contre-exemples pourraient m'échapper).  
 
Ce wiki essaiera toujours d'utiliser les noms complets des méthodes pour l'indexation et l'assignation des propriétés. La raison en est que non seulement cela aide les nouveaux venus à comprendre ce qui se passe mais également nous rendons ainsi la conversion du code vers d'autres langages plus aisée (encore une fois, je n'ai pas l'habitude de pratiquer systématiquement ainsi, c'est pourquoi des contre-exemples pourraient m'échapper).  
  
Line 399: Line 399:
 
Lorsqu'un document Writer est actif et que du texte y est sélectionné, <tt>thisDocument.getText()</tt> et <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> possèdent toutes deux le service <tt>com.sun.star.text.TextRange</tt> qui lui-même possède l'interface <tt>com.sun.star.container.XContentEnumerationAccess</tt>. Il est possible de créer une énumération des paragraphes du document en cours ou d'un sélection donnée.  
 
Lorsqu'un document Writer est actif et que du texte y est sélectionné, <tt>thisDocument.getText()</tt> et <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> possèdent toutes deux le service <tt>com.sun.star.text.TextRange</tt> qui lui-même possède l'interface <tt>com.sun.star.container.XContentEnumerationAccess</tt>. Il est possible de créer une énumération des paragraphes du document en cours ou d'un sélection donnée.  
  
<code>[oobas]
+
<source lang="oobas">
 
' Creation de l'objet énumeration
 
' Creation de l'objet énumeration
 
oTextElementEnum = thisComponent.getText().createEnumeration()
 
oTextElementEnum = thisComponent.getText().createEnumeration()
Line 414: Line 414:
 
         end if
 
         end if
 
wend
 
wend
</code>
+
</source>
 
Exercise 3 : Etendre l'exemple ci-dessus pour lui faire afficher la liste de toutes les portions de textes mises en gras.
 
Exercise 3 : Etendre l'exemple ci-dessus pour lui faire afficher la liste de toutes les portions de textes mises en gras.
  
Line 422: Line 422:
 
Par exemple, si le document en cours dans OpenOffice.org est une classeur, alors l'accès à une feuille spécifique peut s'effectuer par accès indexé :  
 
Par exemple, si le document en cours dans OpenOffice.org est une classeur, alors l'accès à une feuille spécifique peut s'effectuer par accès indexé :  
  
<code>[oobas]
+
<source lang="oobas">
 
oSheet = thisComponent.getSheets.getByIndex(0)
 
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
+
</source>
 
ou bien par accès nommé :  
 
ou bien par accès nommé :  
  
<code>[oobas]
+
<source lang="oobas">
 
oSheet = thisComponent.getSheets.getByName("Feuille1")
 
oSheet = thisComponent.getSheets.getByName("Feuille1")
</code>
+
</source>
 
Pour vérifier qu'un objet doté d'un nom particulier existe déjà, utilisons <tt>hasByName</tt>. Par exemple :  
 
Pour vérifier qu'un objet doté d'un nom particulier existe déjà, utilisons <tt>hasByName</tt>. Par exemple :  
  
<code>[oobas]
+
<source lang="oobas">
 
if thisComponent.getSheets.hasByName("Feuille1") then
 
if thisComponent.getSheets.hasByName("Feuille1") then
</code>
+
</source>
 
Parcourir tous les noms d'objets disponibles peut se faire comme ceci :
 
Parcourir tous les noms d'objets disponibles peut se faire comme ceci :
  
<code>[oobas]
+
<source lang="oobas">
 
mNames = thisComponent.getSheets.getElementnames
 
mNames = thisComponent.getSheets.getElementnames
 
for i = lbound(mNames) to ubound(mNames)
 
for i = lbound(mNames) to ubound(mNames)
 
         msgbox mNames(i)
 
         msgbox mNames(i)
 
next
 
next
</code>
+
</source>
 
   
 
   
  
Line 449: Line 449:
 
Ex :  
 
Ex :  
  
<code>[oobas]
+
<source lang="oobas">
 
thisComponent.getSheets.insertByName("NouvelleFeuille")
 
thisComponent.getSheets.insertByName("NouvelleFeuille")
</code>
+
</source>
  
 
=Créer de nouveaux objets=
 
=Créer de nouveaux objets=
Line 458: Line 458:
 
Par exemple, si le document en cours est un document Writer, alors <tt>thisComponent.getText</tt> est un objet qui fournit le service <tt>com.sun.star.text.Text</tt> qui implémente l'interface <tt>com.sun.star.text.XSimpleText</tt> laquelle définit les méthodes <tt>createTextCursor</tt> et <tt>createTextCursorByRange</tt>. Ces deux méthodes permettent de créer un curseur texte afin d'accéder au corps du document. Ces curseurs sont indépendants du curseur de visualisation. Ce dernier est visible à l'écran et est manipulé par l'utilisateur (et également par programme), tandis qu'un curseur texte n'apparaît pas à l'écran et n'est employé que par des programmes. Le morceau de code qui suit montre la création d'un curseur texte qui démarre à l'emplacement du curseur de visualisation pour être ensuite déplacé indépendamment de ce dernier.  
 
Par exemple, si le document en cours est un document Writer, alors <tt>thisComponent.getText</tt> est un objet qui fournit le service <tt>com.sun.star.text.Text</tt> qui implémente l'interface <tt>com.sun.star.text.XSimpleText</tt> laquelle définit les méthodes <tt>createTextCursor</tt> et <tt>createTextCursorByRange</tt>. Ces deux méthodes permettent de créer un curseur texte afin d'accéder au corps du document. Ces curseurs sont indépendants du curseur de visualisation. Ce dernier est visible à l'écran et est manipulé par l'utilisateur (et également par programme), tandis qu'un curseur texte n'apparaît pas à l'écran et n'est employé que par des programmes. Le morceau de code qui suit montre la création d'un curseur texte qui démarre à l'emplacement du curseur de visualisation pour être ensuite déplacé indépendamment de ce dernier.  
  
<code>[oobas]
+
<source lang="oobas">
 
oVC = thisComponent.getCurrentController.getViewCursor
 
oVC = thisComponent.getCurrentController.getViewCursor
 
oCursor = oVC.getText.createTextCursorByRange(oVC)
 
oCursor = oVC.getText.createTextCursorByRange(oVC)
Line 464: Line 464:
 
oCursor.gotoEndOfSentence(true)
 
oCursor.gotoEndOfSentence(true)
 
msgbox oCursor.getString
 
msgbox oCursor.getString
</code>
+
</source>
  
 
Certains objets sont dépendants du contexte et peuvent être créés par appel de la méthode <tt>createInstance</tt> définie dans l'interface <tt>com.sun.star.lang.XMultiServiceFactory</tt>. Par exemple, pour ajouter un rectangle sur la première page d'un document Draw :  
 
Certains objets sont dépendants du contexte et peuvent être créés par appel de la méthode <tt>createInstance</tt> définie dans l'interface <tt>com.sun.star.lang.XMultiServiceFactory</tt>. Par exemple, pour ajouter un rectangle sur la première page d'un document Draw :  
  
<code>[oobas]
+
<source lang="oobas">
 
dim aPoint as new com.sun.star.awt.Point
 
dim aPoint as new com.sun.star.awt.Point
 
dim aSize as new com.sun.star.awt.Size
 
dim aSize as new com.sun.star.awt.Size
Line 483: Line 483:
 
   
 
   
 
thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
 
thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>
+
</source>
  
 
Cet exemple utilise également des structures UNO. Voir plus bas pour plus d'informations sur ce sujet.
 
Cet exemple utilise également des structures UNO. Voir plus bas pour plus d'informations sur ce sujet.
Line 489: Line 489:
 
Certains objets sont indépendants du contexte. Pour les créer, nous utilisons la commande Basic OpenOffice.org <tt>createUnoService</tt>. Par exemple, pour créer l'équivalent de StarDesktop :  
 
Certains objets sont indépendants du contexte. Pour les créer, nous utilisons la commande Basic OpenOffice.org <tt>createUnoService</tt>. Par exemple, pour créer l'équivalent de StarDesktop :  
  
<code>[oobas]
+
<source lang="oobas">
 
oDesktop = createUnoService("com.sun.star.frame.Desktop")
 
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>
+
</source>
  
 
Le procédé que j'emploie pour savoir comment accéder ou créer un objet est le suivant :
 
Le procédé que j'emploie pour savoir comment accéder ou créer un objet est le suivant :
Line 507: Line 507:
 
Les structures UNO se déclarent au moyen de la commande Basic OpenOffice.org <tt>dim</tt> :  
 
Les structures UNO se déclarent au moyen de la commande Basic OpenOffice.org <tt>dim</tt> :  
  
<code>[oobas]
+
<source lang="oobas">
 
dim aPoint as new com.sun.star.awt.Point
 
dim aPoint as new com.sun.star.awt.Point
</code>
+
</source>
 
Ou encore en employant la commande Basic OpenOffice.org <tt>createUnoStruct</tt>:  
 
Ou encore en employant la commande Basic OpenOffice.org <tt>createUnoStruct</tt>:  
  
<code>[oobas]
+
<source lang="oobas">
 
aPoint = createUnoStruct("com.sun.star.awt.Point")
 
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>
+
</source>
  
 
{| border="1"
 
{| border="1"
Line 532: Line 532:
 
L'exemple ci-dessous crée un gestionnaire de clavier :  
 
L'exemple ci-dessous crée un gestionnaire de clavier :  
  
<code>[oobas]
+
<source lang="oobas">
 
global IannzExampleKeyHandler
 
global IannzExampleKeyHandler
 
   
 
   
Line 565: Line 565:
 
end if
 
end if
 
end function
 
end function
</code>
+
</source>
 
Une variable globale conserve sa valeur après la sortie de la macro. Dans ce cas, nous voulons pouvoir utiliser cette variable plus tard pour supprimer le handler. Je fais débuter tous mes noms de variables globales du radical Iannz qui est le nom que j'ai enregistré pour le site web OpenOffice.org. Ceci permet d'éviter des conflits éventuels entre mes variables globales et d'autres bibliothèques qui pourraient utiliser les mêmes noms.  
 
Une variable globale conserve sa valeur après la sortie de la macro. Dans ce cas, nous voulons pouvoir utiliser cette variable plus tard pour supprimer le handler. Je fais débuter tous mes noms de variables globales du radical Iannz qui est le nom que j'ai enregistré pour le site web OpenOffice.org. Ceci permet d'éviter des conflits éventuels entre mes variables globales et d'autres bibliothèques qui pourraient utiliser les mêmes noms.  
  
Line 588: Line 588:
  
 
=Utilisation de l'enregistreur=
 
=Utilisation de l'enregistreur=
Voir la section [[ The OpenOffice.org recorder and UNO dispatch calls]] où sont comparés l'enregistrement des commandes UNO Dispatch et les appels API.
+
Voir la section [[ L'enregistreur de macro OpenOffice.org et les appels UNO (dispatch)]]
 +
où sont comparés l'enregistrement des commandes UNO Dispatch et les appels API.
 +
 
 +
Traduit de l'anglais : [[ The OpenOffice.org recorder and UNO dispatch calls]]
  
 
= Voir aussi=
 
= Voir aussi=
 
* [[Programming_OooWriter |Programming OOoWriter in C++]] où des record OOBasic sont utilisés en C++
 
* [[Programming_OooWriter |Programming OOoWriter in C++]] où des record OOBasic sont utilisés en C++
 
* Une brève description de l'[[XIntrospection_Interface|interface XIntrospection]].
 
* Une brève description de l'[[XIntrospection_Interface|interface XIntrospection]].
* Télécharger [http://www.ooomacros.org/dev.php#101416 XRay OOoBasic tool] de Bernard Marcelly.  
+
* Télécharger [http://www.openoffice.org/fr/Documentation/Basic/ L'outil XRay OOoBasic] de Bernard Marcelly.  
 +
* A voir aussi en anglais : [[Object Inspector|The New Object Inspector]] et [[BASIC/UNO_Object_Browser|The BASIC UNO Object Browser]]
  
 
[[Category:Basic:Tutorials]]
 
[[Category:Basic:Tutorials]]

Latest revision as of 06:34, 1 May 2016

Comment démarrer

Cette page est un guide de démarrage qui vous permettra d'écrire des macros en OpenOffice.org Basic. Une connaissance préalable de la programmation est indispensable. Merci d'éditer cette page pour la rendre plus lisible. J'espère que vous la trouverez utile.

Si vous maîtrisez les bases, alors vous pouvez consulter le CookBook qui donne des exemples et fournit des guides complémentaires.


Où le code est-il enregistré ?

Le code OpenOffice.org Basic est enregistré dans des modules eux-mêmes placés dans les bibliothèques. Une bibliothèque peut être :

  • Partagée (pour une installation en réseau - OOo Macros & Dialogues)
  • Uniquement pour l'utilisateur courant (Mes Macros & Dialogues)
  • Incorporée à un document ou à un modèle de manière que son code ne soit disponible que lorsque ce document est ouvert.

Lorsque des bibliothèques ne sont stockées ni dans un document ni dans un modèle, c'est-à-dire lorsque les bibliothèques sont partagées ou pour l'utilisateur courant, on les appelle Bibliothèques OpenOffice.org.

Pour connaître les dossiers qui contiennent les bibliothèques OpenOffice.org voir :
Outils > Options… > OpenOffice.org > Chemins > BASIC.

[NdT : depuis la version 2.0.3, ces chemins ne sont plus affichés dans l'interface de OOo]

Note Ne copiez pas ni ne déplacez les bibliothèques en utilisant les commandes du système d'exploitation. Préférez le gestionnaire de macros ou le gestionnaire de packages.


La taille autorisée pour les modules placés à l'intérieur des bibliothèques est limitée à 64 Ko. Une bilbiothèque peut contenir jusqu'à 16.000 modules.

Pour plus d'information, reportez-vous à l'aide en ligne, rubriques : "Bibliothèques;organisation" et "Modules;sous-routines et fonctions".

Accéder à l'IDE

Pour accéder à l'IDE (environnement de développement intégré) pour la première fois :

OpenOffice.org 1.1.x: Outils > Macros > Macro… >

OpenOffice.org 1.9.x et ultérieur : Outils > Macros > Gérer les macros > OpenOffice.org Basic… >

Pour commencer, nous allons utiliser le Module1 de la bibliothèque Standard, présente pour l'utilisateur courant uniquement.

Saisissons un nom pour notre nouvelle macro : HelloWorld

Dans la macro, sélectionnons Standard dans la zone de liste.

Cliquons sur Nouveau

Nous devons maintenant trouver quelque chose comme ça :

REM  *****  BASIC  *****
 
Sub Main
 
End Sub
 
Sub HelloWorld
 
End Sub

Le curseur est positionné au début de la ligne Sub HelloWorld.

Note Maintenant que l'IDE est actif, il peut être accédé depuis le menu Fenêtre d'OpenOffice.org ou par la barre des tâches du système d'exploitation.

Saisie de code

Sélectionnons et effaçons :

REM  *****  BASIC  *****
 
Sub Main
 
End Sub

Au-dessous de la ligne "Sub HelloWorld" entrons msgbox "Hello World!", de manière à ce que l'éditeur ressemble à ceci :

Sub HelloWorld
  msgbox "Hello World!"
End Sub
Notes: L'IDE ne fournit aucune fonctionnalité de complétion du code, ni d'aide sur la syntaxe des commandes lors de la frappe. Pour obtenir de l'aide sur une commande Basic, plaçons le curseur dans la commande et tapons F1.
Les commandes OpenOffice.org Basic ne sont pas sensibles à la casse. C'est pourquoi msgbox, MSGBOX et Msgbox sont équivalents.
Les chaînes sont entourées de guillemets doubles.

Exécution du code

Le code Basic peut être exécuté de plusieurs façons :

  • Directement dans l'IDE. La barre des macro comprte un bouton Exécuter (par défaut, le troisième de la seconde barre d'outils). Ce bouton lance la première macro du module en cours.
  • Depuis le menu Outils :

(Version 1.1.x) Outils > Macros > Macro…;

(Version 1.9.x et supérieures) Outils > Macros > Exécuter la macro…

  • Par assignation de la macro à une touche.
  • Par assignation de la macro à un bouton de barre d'outil.
  • Par assignation de la macro à un évènement.

Pour l'instant essayons de lancer la procédure "HelloWorld" en cliquant sur le bouton Exécuter. Un dialogue intitulé "soffice" et comportant le texte "Hello World!" ainsi qu'un bouton OK doit s'afficher.

Enregistrement du code

Le code est enregistré automatiquement chaque fois que son conteneur est lui-même enregistré. Par conséquent, si le code se trouve dans une bibliothèque OpenOffice.org (partagée ou de l'utilisateur), il est automatiquement enregistré lorsque OpenOffice.org est refermé. Si le code se trouve dans une bilbiothèque qui fait partie d'un document, alors il est enregistré lorsque le document l'est.

Un bouton Enregistrer figure dans la barre d'outils Standard (celle du haut par défaut). Si le code se trouve à l'intérieur d'un document ou modèle, alors la totalité du document est enregistrée. Si le code se trouve à l'intérieur d'une bibliothèque OpenOffice.org alors seule la bilbiothèque courante est enregistrée.

Les variables

Nous pouvons forcer la déclaration des variables en insérant Option Explicit au début du module. Pour consulter une discussion consacrée à la déclaration ou non des variables, voir : [cette discussion].

Dans cette discussion, on voit que l'auteur de cette page défendait initialement la déclaration systématique des variables. Depuis lors il a changé d'avis et ne les déclare plus du tout. Bref, c'est une question de préférence personnelle. Dans un cas comme dans l'autre, les préférences de l'auteur vont au nommage des variables selon la convention suivante, qui sera utilisée tout au long des exemples de ce wiki :

La première lettre du nom de la variable indique le type de valeur contenue, telle que présentée à la table ci-dessous (basée sur un tableau dans Tutorial.pdf de Sun)

Lettre Signification
a Structure
b Boolean (TRUE ou FALSE)
e Enumeration. Cette variable ne peut prendre qu'une valeur parmi un ensemble limité de valeurs.
f Float (de 3.402823 x 1038 à 1.401298 x 10-45. Une variable de type float [NdT : single] peut occuper jusqu'à quatre octets)
Double (de 1.79769313486232 x 10308 à 4.94065645841247 x 10-324. Une variable de ce type peut occuper jusqu'à huit octets)
Currency (de -922337203685477.5808 à +922337203685477.5807 et occupe jusqu'à huit octets en mémoire)
m Array (aka sequence aka matrice)
n Integer (de -32768 à 32767) ou
Long (de -2147483648 à 2147483647).
o Object, service ou interface
s String (Une variable string peut mémoriser jusqu'à 65535 caractères Unicode).
x Interface, montre que seules les opérations portant sur une interface particulière d'un objet sont utilisées
v Variant, n'importe quelle valeur


Utilisons des noms descriptifs suffisamment longs et employons le style "Camel case" [NdT : usage conjoint des majuscules et des minuscules pour faire ressortir les éléments du nom]

Note : Les variables définies par l'utilisateur en OpenOffice.org Basic ne sont pas sensibles à la casse. Les constantes UNO-API le sont.


Les variables indexant les boucles constituent une exception conventionnelle aux longs noms descriptifs. Des symboles tels que i, j et k sont en effet d'usage fréquent. De même, lorsqu'une chaîne est construite, on utilise fréquemment s comme variable temporaire.

Editons la routine sub HelloWorld de manière qu'elle ressemble à ceci et exécutons-la :

sub HelloWorld
dim i as integer 'ligne optionnelle
  for i = 0 to 2
    'Ces lignes sont indentées par souci de lisiblité uniquement
    'Notre code devrait toujours être structuré ainsi pour lui donner des chances de survie
    msgbox "Hello World " & i
  next i
end sub

Pour plus d'informations sur les variables, reportons-nous à l'aide en ligne, rubrique "variables;utilisation".

L'API OpenOffice.org

Cette section commence par un exemple. La suite donne des informations complémentaires qui nous permettront de comprendre l'exemple et de l'étendre.

Essayons d'exécuter le code ci-dessous lorsque différents types de documents sont ouverts.

sub main
'BasicLibraries.loadLibrary("XrayTool")
'xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub
 
 
function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then 
   if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
      fnWhichComponent = "Texte"
   elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
      fnWhichComponent = "Feuille de calcul"
   elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
      fnWhichComponent = "Presentation"
   elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
      fnWhichComponent = "Dessin"
   else
      fnWhichComponent = "Oops le document ouvert est autre chose"
   end if
else
   fnWhichComponent = "Ce n'est pas un document"
end if
End function

Convention de nommage des routines

Dans l'exemple ci-dessus, le nom de la fonction utilisateur commence par "fn". Il s'agit de la convention adoptée par l'auteur initial [NdT : version anglaise] qui permet au lecteur de savoir qu'il s'agit d'une fonction définie par l'utilisateur. Dans le même esprit, l'auteur initial utilise la convention de débuter les noms des procédures par "sub". Lorsque l'on apprend un nouveau langage et de nouvelles API, il peut s'avérer difficile de reconnaître ce qui ressortit du langage lui-même de ce qui a été défini ailleurs dans notre code. Ce document/wiki emploie ces conventions pour le nommage des fonctions et des procédures.

Présentation de l'API OpenOffice.org

Cette section introduit les termes :

  • Interface
  • Module
  • Service
  • Méthode
  • Propriété

S'il n'est pas essentiel de comprendre la différence entre une interface et un service ou ce qu'est un module pour pouvoir écrire des extensions à OpenOffice.org, la compréhension de ces termes aide à correctement interpréter la documentation ainsi qu'à l'introspection des éléments manipulés. Peut-être nous faudra-t-il relire cette section plusieurs fois.

Une interface est la définition d'un ensemble de méthodes (avec leurs arguments) qu'un service implémentant cette interface doit comporter.

Les interfaces sont regroupées en modules pour des besoins de nommage. Toutes les interfaces (et les services) commencent par le nom "com.sun.star" puis vient le nom du module puis celui de l'interface (ou du service).

Par exemple, la plupart des services fournissent l'interface com.sun.star.beans.XPropertySet. Cette interface est enregistrée dans le module "beans" et fournit l'accès aux propriétés d'un service. Une propriété est une valeur tandis qu'une méthode définit une action.

Un objet OpenOffice.org peut supporter de nombreux services.

Un objet OpenOffice.org peut supporter un service qui implémente une interface dans laquell une description de méthode déclare qu'un autre objet OpenOffice.org est retourné.

Introspection

HasUnoInterfaces est une fonction OpenOffice.org Basic utilisée pour l'introspection. Ce document [link] permettra d'apprendre ce que l'on entend par introspection dans d'autres langages de programmation.

HasUnoInterfaces renvoie une valeur "vrai" si toutes les interfaces spécifiées sont disponibles pour l'objet appelant.

La plupart des objets OpenOffice.org fournissent la méthode supportsService parce qu'ils disposent également de l'interface com.sun.star.lang.XServiceInfo.

Dans l'exemple ci-dessus, la commande OpenOffice.org Basic, HasUnoInterfaces vérifie si le document actif dispose de l'interface com.sun.star.lang.XServiceInfo, car si cette interface n'est pas présente, alors le document n'aura pas non plus la méthode supportsService, et une erreur d'exécution se produirait si un objet tentait d'accéder à une méthode inexistante.

SupportsService est une méthode qui renvoie la valeur "vrai" si le service spécifié est disponible. Dans l'exemple ci-dessus, on vérifie la présence d'un service afin de déterminer le type de document en cours d'activation.

L'Outil Xray

L'utilisation de "HasUnoInterfaces" et de "supportsService" permet d'obtenir des informations sur un objet donné lors de son exécution, mais procéder ainsi pour apprendre le langage Basic deviendrait vite fastidieux. Heureusement, et grâce à Bernard Marcelly, nous disposons de l'outil Xray. Cet outil est disponible ici en [version française] et ici en [version anglaise]. Téléchargez le fichier odt, ouvrez le document dans OpenOffice.org, et suivez les instructions pour son installation et configuration.

Une partie de la configuration de l'outil Xray concerne la définition de l'endroit où est stockée une copie locale (sur le disque dur) du Kit de Développement OpenOffice.org (appélé SDK). Téléchargez le Kit de Développement OpenOffice.org depuis [le site du SDK] et installez le sur votre disque dur.

Dans l'exemple ci-dessus, au début du code, il y a deux lignes mises en commentaires (les lignes de commentaires commencent avec des apostrophes ou le mot réservé rem):

'BasicLibraries.loadLibrary("XrayTool")
'xray thisComponent

Une fois l'outil Xray installé, supprimez les apostrophes dans les lignes indiquées ci-dessus et relancez la macro.

BasicLibraries est une commande OpenOffice.org Basic qui renvoie un objet permettant d'accéder aux bibliothèques OpenOffice.org. La méthode loadLibrary rend disponible aux utilisateurs les routines présentes dans cette bibliothèque.

xray indique la routine xray contenue dans la bibliothèque XrayTool, l'objet thisComponent étant l'objet transmis à xray pour l'introspection.

Afin de trouver l'objet que vous cherchez, il est souvent nécessaire de le découvrir ou de le créer depuis StarDesktop ou thisComponent.

Desktop, documents, et current selection

StarDesktop et ThisComponent sont des commandes OpenOffice.org Basic qui ont trait à l'application et le document actif (c'est-à-dire, celui qui a le focus actuellement sur le bureau) respectivement.

Contrairement à Microsoft Office, l'application OpenOffice.org est monolithique et comporte différents composants. Lorsqu'on exécute du code, il peut être utile de vérifier quel composant est actuellement en cours d'activation. Le code ci-dessus donne un exemple de la manière de procéder à cette vérification.

Quand il est fait référence au Desktop dans StarDesktop, celui-ci se réfère à une existence virtuelle (puisqu'auparavant il existait réellement dans OpenOffice.org et dans StarOffice). On peut ainsi le considérer comme étant l'application OpenOffice.org elle-même.

Création de Nouveaux Documents

Pour créer un nouveau document Writer, on écrit le code suivant:

oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())

De la même manière, pour un nouveau document Calc:

oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())

Il serait sans doute plus facile d'écrire une fonction simple:

function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function

Ensuite, on pourra créer de nouveaux documents ainsi:

oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")

Voir également http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

Ouverture d'un document

Le code suivant donne un exemple permettant d'ouvrir un fichier. Pour plus d'informations sur l'utilisation d'URL au sein de OpenOffice.org, voir URL Basics.

sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())

Ici encore, il peut être plus rationnel de simplifier le code en écrivant une fonction:

function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function

Exemples d'utilisation de la fonction:

oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux

La sélection en cours

Nous avons souvent besoin d'exécuter du code qui affecte la sélection courante. ThisComponent possède une méthode getCurrentSelection. Comme de nombreux types d'objets sont sélectionnables, il est habituel de vérifier que l'objet sélectionné possède le service qui contient la méthode que nous voulons appliquer à l'objet.

Editons la routine principale du code ci-dessous et re-exécutons-la successivement sur un document texte comportant plusieurs sélections différentes (pour sélectionner plus d'un bloc de texte, nous maintenons la touche Control enfoncée).

sub main
BasicLibraries.loadLibrary("XrayTool")
if fnWhichComponent(thisComponent) = "Text" then
        oCurSelection = thisComponent.getCurrentSelection()
        'xray oCurSelection
        if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
                msgbox "Il y a " & oCurSelection.getCount() & _
                 " sélections dans le document texte en cours."
        end if
end if
end sub

Lorsqu'il n'y a aucune sélection, le nombre affiché est un - le point d'insertion -, avec un bloc de text sélectionné, il renvoie également un, mais avec deux blocs de texte, ce nombre devient égal à trois - le point d'insertion et les deux blocs de texte sélectionnés.

Exercice 1 : Modifier le code ci-dessus afin qu'il fonctionne sur des plages de cellules sélectionnées dans une feuille de calcul.

Question 1 : Lorsque deux blocs de cellules sont sélectionnés, quelle est la valeur du nombre de sélections ?

Les propriétés

Retirons le commentaire de 'xray oCurSelection de manière à lancer xray, ce qui permet de constater que l'objet pointé par oCurSelection possède une "propriété" nommée Count dont la description est "pseudo-prop, read only". Nous pourrions écrire oCurSelection.count en OpenOffice.org Basic, mais comme ce n'est pas possible dans tous les autres langages qui accèdent à l'API OpenOffice.org, ce wiki essaiera de toujours utiliser l'approche par méthode (je signale çà car je n'ai pas pris l'habitude de le faire et il m'arrive d'oublier).

L'exemple suivant montre comment changer une valeur de propriété pour les sélections courantes.

sub main
BasicLibraries.loadLibrary("XrayTool")
if fnWhichComponent(thisComponent) = "Text" then
   oCurSelection = thisComponent.getCurrentSelection()
   if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
      nCount = oCurSelection.Count
      'xray oCurSelection.getByIndex(0)
      'Attention : le point d'insertion va voir la même action appliquée deux fois
      'ici çà n'a pas d'importance mais il est des cas ou cela pourrait en avoir.
      for i = 0 to nCount - 1
         oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
      next
   end if
end if
end sub

En Basic OpenOffice.org nous pouvons raccourcir la ligne d'affectation ainsi :

oCurSelection(i).CharStyleName = "Strong Emphasis"

Ce wiki essaiera toujours d'utiliser les noms complets des méthodes pour l'indexation et l'assignation des propriétés. La raison en est que non seulement cela aide les nouveaux venus à comprendre ce qui se passe mais également nous rendons ainsi la conversion du code vers d'autres langages plus aisée (encore une fois, je n'ai pas l'habitude de pratiquer systématiquement ainsi, c'est pourquoi des contre-exemples pourraient m'échapper).

Exercice 2 : Réécrire le code ci-dessus de manière que l'avertissement disparaisse.

Voir Current selection.

Accès répété à des objets subordonnés (accès aux énumérations)

Il arrive qu'une énumération soit nécessaire pour accéder à l'objet désiré. C'est le cas, par exemple, des paragraphes à l'intérieur d'un document ou dans une sélection.

Lorsqu'un document Writer est actif et que du texte y est sélectionné, thisDocument.getText() et thisComponent.getCurrentSelection().getByIndex(i) possèdent toutes deux le service com.sun.star.text.TextRange qui lui-même possède l'interface com.sun.star.container.XContentEnumerationAccess. Il est possible de créer une énumération des paragraphes du document en cours ou d'un sélection donnée.

' Creation de l'objet énumeration
oTextElementEnum = thisComponent.getText().createEnumeration()
'ou bien : thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()
 
' boucler sur tous les élément texte
while oTextElementEnum.hasMoreElements()
        oTextElement = oTextElementEnum.nextElement
        if oTextElement.supportsService("com.sun.star.text.TextTable") then
                MsgBox "Le bloc en cours contient un tableau."
        end if
        if oTextElement.supportsService("com.sun.star.text.Paragraph") then
                MsgBox "Le bloc en cours contient un paragraphe."
        end if
wend

Exercise 3 : Etendre l'exemple ci-dessus pour lui faire afficher la liste de toutes les portions de textes mises en gras.

Accès nommés

Certains objets fournissent l'accès nommé à un type particulier d'objet subordonné, d'autres fournissent l'accès indexé et certains fournissent les deux à la fois, accès nommé et indexé.

Par exemple, si le document en cours dans OpenOffice.org est une classeur, alors l'accès à une feuille spécifique peut s'effectuer par accès indexé :

oSheet = thisComponent.getSheets.getByIndex(0)

ou bien par accès nommé :

oSheet = thisComponent.getSheets.getByName("Feuille1")

Pour vérifier qu'un objet doté d'un nom particulier existe déjà, utilisons hasByName. Par exemple :

if thisComponent.getSheets.hasByName("Feuille1") then

Parcourir tous les noms d'objets disponibles peut se faire comme ceci :

mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
        msgbox mNames(i)
next


Quelques objets subordonnés nommés fournissent également l'interface : com.sun.star.container.XNameContainer. Cette interface définit que de tels objets doivent comporter les méthodes : insertByName, replaceByname and removeByName.

Ex :

thisComponent.getSheets.insertByName("NouvelleFeuille")

Créer de nouveaux objets

Certains objets proposent des services qui implémentent des interfaces fournissant des méthodes spécifiques pour créer un type particulier d'objet.

Par exemple, si le document en cours est un document Writer, alors thisComponent.getText est un objet qui fournit le service com.sun.star.text.Text qui implémente l'interface com.sun.star.text.XSimpleText laquelle définit les méthodes createTextCursor et createTextCursorByRange. Ces deux méthodes permettent de créer un curseur texte afin d'accéder au corps du document. Ces curseurs sont indépendants du curseur de visualisation. Ce dernier est visible à l'écran et est manipulé par l'utilisateur (et également par programme), tandis qu'un curseur texte n'apparaît pas à l'écran et n'est employé que par des programmes. Le morceau de code qui suit montre la création d'un curseur texte qui démarre à l'emplacement du curseur de visualisation pour être ensuite déplacé indépendamment de ce dernier.

oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString

Certains objets sont dépendants du contexte et peuvent être créés par appel de la méthode createInstance définie dans l'interface com.sun.star.lang.XMultiServiceFactory. Par exemple, pour ajouter un rectangle sur la première page d'un document Draw :

dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size
 
aPoint.x = 1000
aPoint.y = 1000
 
aSize.Width = 10000
aSize.Height = 10000
 
oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint
 
thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)

Cet exemple utilise également des structures UNO. Voir plus bas pour plus d'informations sur ce sujet.

Certains objets sont indépendants du contexte. Pour les créer, nous utilisons la commande Basic OpenOffice.org createUnoService. Par exemple, pour créer l'équivalent de StarDesktop :

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

Le procédé que j'emploie pour savoir comment accéder ou créer un objet est le suivant :

Est-ce que l'objet existe déjà ? Si oui, alors je dois pouvoir y accéder à partir de quelque chose comme thisComponent.

L'objet doit-il appartenir à un autre objet ? Si oui, alors le propriétaire comporte-t-il une méthode spécifique pour créer l'objet ? Si oui, j'appelle cette méthode.

Le nouvel objet doit-il appartenir à un autre objet qui ne fournit par de méthode de création mais fournit createInstance ? Si l'objet ne fournit pas createInstance suis-je certain que j'utilise le bon objet ou est-il dépendant du contexte ?

Il me semble que la création d'objets est mal documentée actuellement c'est pourquoi j'espère que ce document/wiki rendra les choses plus claires.


Structures UNO

Les structures UNO se déclarent au moyen de la commande Basic OpenOffice.org dim :

dim aPoint as new com.sun.star.awt.Point

Ou encore en employant la commande Basic OpenOffice.org createUnoStruct:

aPoint = createUnoStruct("com.sun.star.awt.Point")
Note : La casse est importante lors de la déclaration de structures UNO. Tout ce qui précède le nom de la structure est en minuscules, le nom lui-même marriant minuscules et majuscules.

Création de Listeners et de Handlers

L'interface utilisateur permet d'assigner des macros à certains événements :

OpenOffice.org versions 1.1.x: Outils > Adaptation > Evénements.

OpenOffice.org versions 1.9.x and above: Outils > Personnaliser > Evénements.

Nous pouvons également assigner des macros à une gamme plus large d'événements en utilisant la commande Basic OpenOffice.org CreateUnoListener. La même commande sert à créer à la fois des listeners aet des handlers. Un listener attend un événement et permet toujours à d'autres listeners de répondre à ce même événement. Un handler attend un événement et peut éventuellement le consommer afin que d'autres listeners ne puissent pas agir dessus.

L'exemple ci-dessous crée un gestionnaire de clavier :

global IannzExampleKeyHandler
 
sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Enregistre le listener
end sub
 
 
sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub
 
 
sub KeyHandler_disposing
end sub
 
 
function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
        KeyHandler_keyReleased = False    
end function
 
 
function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false   'Laisser d'autres listeners gérer l'événement
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
        if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
                msgbox "Alt + Q a été appuyé"
                KeyHandler_keyPressed = true    'Ne pas laisser d'autres listeners gérer l'événement
        end if
end if
end function

Une variable globale conserve sa valeur après la sortie de la macro. Dans ce cas, nous voulons pouvoir utiliser cette variable plus tard pour supprimer le handler. Je fais débuter tous mes noms de variables globales du radical Iannz qui est le nom que j'ai enregistré pour le site web OpenOffice.org. Ceci permet d'éviter des conflits éventuels entre mes variables globales et d'autres bibliothèques qui pourraient utiliser les mêmes noms.

sub SetupKeyHandler initialise le handler. Le premier paramètre de CreateUnoListener est le nom générique des méthodes qui sont appelées quand ce type d'événement se produit. Dans cet exemple ."KeyHandler_".

Le second parameter est le nom de l'interface du listener ou du handler, "com.sun.star.awt.XKeyHandler". Le nom est sensible à la casse, tout jusque et y compris le nom du module est toujours en minuscules, le nom de l'interface commence par un "X" et le reste est en TitleCase.

Utilsions le SDK pour trouver quelles méthodes l'interface doit fournir. Nous devrons fournir des routines pour toutes ces méthodes, même si nous n'avons pas l'intention de les utiliser. Nous devrons également fournir une méthode de nettoyage. Les noms de ces routines débutent par la chaîne passée comme premier paramètre à CreateUnoListener. Dans l'exemple c'est "KeyHandler_".

Il y a donc dans l'exemple KeyHandler_disposing et KeyHandler_keyReleased qui, en fait, ne font rien mais sont nécessaires, et KeyHandler_keyPressed qui accomplit la fonctionnalité effective.

sub RemoveKeyHandler montre comment supprimer le handler.

Les constantes OpenOffice.org

L'exemple ci-dessus utilise des constantes OpenOffice.org.

Par ex : com.sun.star.awt.KeyModifier.MOD2

Les constantes OpenOffice.org sont sensibles à la casse. Tout jusque et y compris le nom du module est toujours en minuscules. Le nom du groupe de constantes est en TitleCase. Le nom effectif de la constante est toujours en MAJUSCULES.

Les programmeurs qui n'utilisent pas le Basic OpenOffice.org peuvent ne pas avoir accès à ces constantes.

Utilisation de l'enregistreur

Voir la section L'enregistreur de macro OpenOffice.org et les appels UNO (dispatch) où sont comparés l'enregistrement des commandes UNO Dispatch et les appels API.

Traduit de l'anglais : The OpenOffice.org recorder and UNO dispatch calls

Voir aussi

Personal tools