Aide LibreOffice 7.6
La bibliothèque ScriptForge est disponible pour Basic et Python. La plupart des services, méthodes et propriétés fonctionnent de manière identique dans les deux langages de programmation. Cependant, en raison des différences dans le fonctionnement de chaque langage, les utilisateurs de ScriptForge doivent être conscients de certaines caractéristiques de la bibliothèque lors de l'utilisation de Python :
Méthodes et noms de propriétés : en Python, toutes les méthodes et propriétés peuvent être utilisées dans les formats minuscules, ProperCased ou camelCased.
Arguments : tous les arguments de mot-clé transmis aux méthodes sont en minuscules.
Dates : tous les objets de date sont transmis et renvoyés sous la forme d'objets Python natifs datetime.datetime.
Matrices : les matrices unidimensionnelles sont passées et renvoyées sous forme de tuples (qui est un objet immuable). Les matrices à deux dimensions sont transmises et renvoyées sous forme de tuples de tuples.
Aucun : le mot-clé None de Python est équivalent à Null, Empty ou Nothing de Basic.
Objets UNO : toutes les structures UNO sont échangées entre Basic et Python sans aucun changement.
Débogage : chaque fois qu'une erreur se produit dans les scripts Python qui utilisent ScriptForge, le message d'erreur fourni par la pile d'exécution Python affiche la ligne de code qui a déclenché l'erreur. Dans Basic, les messages d'erreur n'affichent pas ces informations.
Consultez l'Aide sur les scripts Python de LibreOffice pour plus d'informations sur les scripts Python avec LibreOffice.
En fonction de vos objectifs, vous pouvez choisir l'une des approches suivantes pour exécuter des scripts Python dans LibreOffice :
Exécuter des scripts dans le processus LibreOffice actuel : les scripts Python sont exécutés depuis le processus LibreOffice en utilisant le menu ou l'extension APSO pour appeler des scripts utilisateurs stockés dans le dossier scripts Python. Vous pouvez également utiliser le shell APSO Python pour exécuter de manière interactive des scripts Python.
Exécuter les scripts séparément du processus LibreOffice : les scripts Python sont exécutés à partir d'un processus externe qui se connecte à un processus LibreOffice actif à l'aide d'un socket.
Si vous envisagez d'exécuter des scripts depuis le processus LibreOffice, il est recommandé d'installer l'extension APSO (Alternative Script Organizer for Python). Cependant, pour développer des scripts Python en dehors de LibreOffice, vous pouvez choisir votre EDI Python préféré.
Le moyen le plus simple de démarrer avec les scripts Python dans LibreOffice consiste à installer l'extension APSO. Après l'avoir installée, ouvrez n'importe quel composant LibreOffice et allez dans
.Dans la fenêtre principale d'APSO, allez dans
.Vous pouvez également ouvrir APSO en utilisant le raccourci par défaut Alt+Maj+F11.
Vous pouvez maintenant commencer à saisir des commandes Python et le shell imprimera la sortie correspondante après l'exécution de chaque ligne de code.
Pour commencer à utiliser la bibliothèque ScriptForge, vous devez importer la méthode CreateScriptService, avec laquelle vous pourrez accéder aux services fournis par la bibliothèque. L'exemple ci-dessous utilise le service Basic pour afficher une boîte de message.
from scriptforge import CreateScriptService
bas = CreateScriptService("Basic")
bas.MsgBox("Hello!")
Pour exécuter l'exemple ci-dessus, saisissez chaque ligne dans le shell Python, une par une, en appuyant sur la touche Entrée après avoir saisi chaque ligne de code.
Vous pouvez maintenant commencer à exécuter des commandes Python à l'aide de l'un des services ScriptForge. Par exemple, l'extrait de code ci-dessous utilise le service UI pour créer un document Writer vierge.
ui = CreateScriptService("UI")
doc = ui.CreateDocument("Writer")
Vous pouvez créer vos propres fichiers Python et les modifier avec votre éditeur de texte préféré. Vous pourrez ensuite les appeler à partir de n'importe quel composant LibreOffice.
La première étape consiste à localiser l'emplacement de stockage de vos scripts utilisateur. Pour cela, reportez-vous à la page d'aide Organisation et emplacement des scripts Python.
Vous pouvez maintenant créer un fichier texte dans votre dossier de scripts utilisateur Python, par exemple sf_test.py, et commencer à taper vos scripts.
Voici un exemple simple qui obtient la valeur numérique d'une cellule Calc et l'incrémente de 1. Tapez simplement le code suivant dans le fichier sf_test.py.
from scriptforge import CreateScriptService
doc = CreateScriptService("Calc")
def increment_cell(args=None):
value = doc.GetValue("A1")
value += 1
doc.SetValue("A1", value)
g_exportedScripts = (increment_cell, )
Cet exemple crée la fonction increment_cell. Notez que g_exportedScripts est un tuple qui indique quelles fonctions seront affichées dans LibreOffice en tant que scripts utilisateur.
Pour exécuter ce script depuis un document Calc :
Créez ou ouvrez un fichier Calc.
Saisissez une valeur numérique dans la cellule "A1" de la feuille active.
Allez dans
.Choisissez Mes macros - sf_test dans le sélecteur de bibliothèque. Choisissez ensuite la fonction increment_cell sous la liste .
Cliquez sur Exécuter. Notez que la valeur de la cellule "A1" a été incrémentée de 1.
Vous pouvez également utiliser APSO pour exécuter des scripts Python de la même manière :
Ouvrez d'abord APSO en allant dans
.Dans la liste des macros, accédez à
.Cliquez sur
.La première étape pour exécuter des scripts à partir d'un processus distinct consiste à rechercher le dossier dans lequel LibreOffice est installé. Il existe plusieurs façons de le faire, mais ScriptForge fournit un moyen rapide d'identifier votre chemin d'installation. Pour cela, ouvrez le shell Python d'APSO et saisissez :
from scriptforge import CreateScriptService
fs = CreateScriptService("FileSystem")
fs.FileNaming = "SYS"
inst_dir = fs.InstallFolder
print(inst_dir)
La sortie du code ci-dessus est le répertoire de base dans lequel LibreOffice est installé. Vous devez maintenant ajouter le sous-dossier "program" au chemin résultant. Il s'agit du dossier de base à partir duquel vous exécuterez les scripts Python à partir d'un processus distinct.
For example, suppose you get /usr/lib/libreoffice/ as the result from running the Python code above. Then you need to consider /usr/lib/libreoffice/program as the path to run your Python scripts.
To run Python scripts from a separate process, you need to start LibreOffice with a few additional options that specify the hostname and port through which the external process will communicate with the LibreOffice component process.
Open the your operating system's command prompt, navigate to the program folder of your LibreOffice installation directory and type:
./soffice --accept='socket,host=localhost,port=2021;urp;'
The command above will start LibreOffice with a communication channel open so that other processes can exchange messages with it.
Note that the previous example opens LibreOffice start center. If you want to open a specific component, for instance Writer, you can add the --writer flag to the command, as follows.
./soffice --writer --accept='socket,host=localhost,port=2021;urp;'
Take note of the host and port parameters, which in this example are localhost and 2021, respectively.
Start the Python shell from within the program folder inside your LibreOffice installation path. Follow the steps above to learn how to find your installation path.
On Linux / Mac OS:
$ cd /usr/lib/libreoffice/program
$ python
On Windows:
$ cd C:\Program Files\LibreOffice\program\
$ python.exe
This will open the Python shell and now you can start typing commands that will be executed by LibreOffice. But first you need to set up the socket connection.
from scriptforge import ScriptForge, CreateScriptService
ScriptForge(hostname='localhost', port=2021)
The second line of code above defines the host and port settings so that the Python shell can communicate with an ongoing LibreOffice process opened with the same socket settings.
Now you can run other Python commands and they will be able to communicate with the LibreOffice process. For example:
ui = CreateScriptService("UI")
bas = CreateScriptService("Basic")
doc = ui.OpenDocument("~/Documents/myFile.ods")
bas.MsgBox(doc.DocumentType)