Service ScriptForge.Session

Le service Session rassemble diverses méthodes à usage général concernant :

l'environnement d'installation ou d'exécution
introspection UNO
l'invocation de scripts ou de programmes externes

Invocation du service

Avant d'utiliser le service Session, la bibliothèque ScriptForge doit être chargée ou importée :

• Les macros Basic nécessitent de charger la bibliothèque ScriptForge à l'aide de l'instruction suivante :
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Les scripts Python nécessitent un import depuis le module scriptforge :
from scriptforge import CreateScriptService

En Basic :


    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Dim session As Variant
    session = CreateScriptService("Session")

En Python


    from scriptforge import CreateScriptService
    session = CreateScriptService("Session")

Constantes

Vous trouverez ci-dessous une liste de constantes disponibles pour faciliter la désignation de la bibliothèque contenant un script Basic ou Python à invoquer. Utilisez-les comme session.CONSTANT.

CONSTANT	Valeur	Où trouver la bibliothèque ?	Applicable
SCRIPTISEMBEDDED	"document"	dans le document	Basic + Python
SCRIPTISAPPLICATION	"application"	dans n'importe quelle bibliothèque partagée	Basic
SCRIPTISPERSONAL	"user"	dans Mes macros	Python
SCRIPTISPERSOXT	"user:uno_packages"	dans un extension installée pour l'utilisateur actif	Python
SCRIPTISSHARED	"share"	dans Macros d'application	Python
SCRIPTISSHAROXT	"share:uno_packages"	dans une extension installée pour tous les utilisateurs	Python
SCRIPTISOXT	"uno_packages"	dans une extensions dont les paramètres d'installation sont inconnus	Python

Liste des méthodes dans le service Session
ExecuteBasicScript ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod	HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions	UnoMethods UnoProperties UnoObjectType WebService

Les méthodes Execute... du service Session se comportent comme suit :
Les arguments sont passés par valeur. Les modifications apportées par la fonction appelée aux arguments ne mettent pas à jour leurs valeurs dans le script appelant.
Une valeur unique ou un tableau de valeurs est renvoyé au script appelant.

ExecuteBasicScript

Exécuter le script BASIC en fonction de son nom et de son emplacement, et récupérer son résultat, le cas échéant.

Si le script ne renvoie rien, ce qui est le cas des procédures définies avec Sub, la valeur retournée est Empty.

Syntaxe :

session.ExecuteBasicScript(scope: str, script: str, args: any[0..*]): any

Paramètres :

scope : chaîne spécifiant où le script est stocké. Il peut s'agir de "document" (constante session.SCRIPTISEMBEDDED) ou "application" (constante session.SCRIPTISAPPLICATION).

script : chaîne spécifiant le script à appeler au format "library.module.method" en tant que chaîne sensible à la casse.

Une bibliothèque est chargée en mémoire si nécessaire.
Le module ne doit pas être un module de classe.
La méthode peut être un Sub ou une Function.

arts : les arguments à passer au script appelé.

Exemple :

Considérez la fonction de base suivante nommée DummyFunction qui est stockée dans "Mes macros" dans la bibliothèque "Standard" à l'intérieur d'un module nommé "Module1".

La fonction prend simplement deux valeurs entières v1 et v2 et renvoie la somme de toutes les valeurs commençant par v1 et se terminant par v2.


    Function DummyFunction(v1 as Integer, v2 as Integer) As Long
        Dim result as Long, i as Integer
        For i = v1 To v2
            result = result + i
        Next i
        DummyFunction = result
    End Function

Les exemples ci-dessous montrent comment appeler DummyFunction à partir de scripts Basic et Python.

En Basic :


    Dim session : session = CreateScriptService("Session")
    Dim b_script as String, result as Long
    b_script = "Standard.Module1.DummyFunction"
    result = session.ExecuteBasicScript("application", b_script, 1, 10)
    MsgBox result ' 55

En Python


    session = CreateScriptService("Session")
    bas = CreateScriptService("Basic")
    b_script = 'Standard.Module1.DummyFunction'
    result = session.ExecuteBasicScript('application', b_script, 1, 10)
    bas.MsgBox(result) # 55

ExecuteCalcFunction

Exécute une fonction Calc en utilisant son nom anglais et en se basant sur les arguments donnés.
Si les arguments sont des matrices, la fonction est exécutée comme une formule de matrice.

Syntaxe :

session.ExecuteCalcFunction(calcfunction: str, args: any[0..*]): any

Paramètres :

calcfunction : le nom de la fonction Calc à appeler, en anglais.

args : les arguments à passer à la fonction Calc appelée. Chaque argument doit être une chaîne, une valeur numérique ou un tableau de tableaux combinant ces types.

Exemple :

En Basic :


    session.ExecuteCalcFunction("AVERAGE", 1, 5, 3, 7) ' 4
    session.ExecuteCalcFunction("ABS", Array(Array(-1, 2, 3), Array(4, -5, 6), Array(7, 8, -9)))(2)(2) ' 9
    session.ExecuteCalcFunction("LN", -3)
    ' Génère une erreur.

En Python


    session.ExecuteCalcFunction("AVERAGE", 1, 5, 3, 7) # 4
    session.ExecuteCalcFunction("ABS", ((-1, 2, 3), (4, -5, 6), (7, 8, -9)))[2][2] # 9
    session.ExecuteCalcFunction("LN", -3)

ExecutePythonScript

Exécuter le script Python en fonction de son emplacement et de son nom, récupérer son résultat le cas échéant. Le résultat peut être une valeur unique ou une matrice de valeurs.

Si le script est introuvable, ou s'il ne renvoie rien, la valeur renvoyée est Empty.

L'environnement de script de l'interface de programmation d'application (API) LibreOffice prend en charge l'exécution de scripts inter-langages entre Python et Basic, ou d'autres langages de programmation pris en charge d'ailleurs. Les arguments peuvent être passés dans les deux sens entre les appels, à condition qu'ils représentent des types de données primitifs que les deux langages reconnaissent et en supposant que la structure de script les convertit de manière appropriée.

Syntaxe :

session.ExecutePythonScript(scope: str, script: str, args: any[0..*]): any

Paramètres :

scope : l'une des constantes applicables répertoriées ci-dessus. La valeur par défaut est session.SCRIPTISSHARED.

script : Soit "library/module.py$method" ou "module.py$method" ou "myExtension.oxt|myScript|module.py$method" comme chaîne sensible à la casse.

library : le chemin de dossier du module Python.
myScript : le dossier contenant le module Python.
module.py : le module Python.
method : la fonction Python.

arts : les arguments à passer au script appelé.

Exemple :

Considérez la fonction Python odd_integers définie ci-dessous qui crée une liste avec des valeurs entières impaires entre v1 et v2. Supposons que cette fonction soit stockée dans un fichier nommé my_macros.py dans le dossier de scripts utilisateur.


    def odd_integers(v1, v2):
        odd_list = [v for v in range(v1, v2 + 1) if v % 2 != 0]
        return odd_list

Lisez la page d'aide Organisation et emplacement des scripts Python pour en savoir plus sur l'emplacement de stockage des scripts Python.

Les exemples suivants montrent comment appeler la fonction odd_integers à partir de scripts Basic et Python.

En Basic :


    Dim script as String, session as Object
    script = "my_macros.py$odd_integers"
    session = CreateScriptService("Session")
    Dim result as Variant
    result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)
    MsgBox SF_String.Represent(result)

En Python


    session = CreateScriptService("Session")
    script = "my_macros.py$odd_integers"
    result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)
    bas.MsgBox(repr(result))

GetPDFExportOptions

Renvoie les paramètres d'export PDF actuels définis dans la boîte de dialogue Options PDF, accessible en choisissant Fichier - Exporter vers - Exporter au format PDF.

Les options d'export définies avec la boîte de dialogue Options PDF sont conservées pour une utilisation future. Par conséquent, GetPDFExportOptions renvoie les paramètres actuellement définis. En outre, utilisez SetPDFExportOptions pour modifier les options d'export PDF actuelles.

Cette méthode renvoie un objet Dictionary dans lequel chaque clé représente les options d'export et les valeurs correspondantes sont les paramètres d'export PDF actuels.

Lisez la page wiki d'exportation PDF pour en savoir plus sur toutes les options disponibles.

Syntaxe :

session.GetPDFExportOptions(): obj

Exemple :

En Basic :


    Dim expSettings As Object, msg As String, key As String, optLabels As Variant
    expSettings = session.GetPDFExportOptions()
    optLabels = expSettings.Keys
    For Each key in optLabels
        msg = msg + key & ": " & expSettings.Item(key) & Chr(10)
    Next key
    MsgBox msg
    ' Zoom: 100
    ' Changes: 4
    ' Quality: 90
    ' ...

Cette méthode n'est disponible que pour les scripts Basic.

HasUnoMethod

Renvoie True si un objet UNO contient la méthode donnée. Renvoie False lorsque la méthode est introuvable ou lorsqu'un argument est invalide.

Syntaxe :

session.HasUnoMethod(unoobject: uno, methodname: str): bool

Paramètres :

unoobject: l'objet à examiner.

methodname : la méthode sous forme de chaîne sensible à la casse

Exemple :

En Basic :


    Dim a As Variant
    a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    MsgBox session.HasUnoMethod(a, "callFunction") ' True

En Python


    bas = CreateScriptService("Basic")
    a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    result = session.HasUnoMethod(a, "callFunction")
    bas.MsgBox(result) # True

HasUnoProperty

Renvoie True si un objet UNO a la propriété donnée. Renvoie False lorsque la propriété est introuvable ou lorsqu'un argument n'est pas valide.

Syntaxe :

session.HasUnoProperty(unoobject: uno, propertyname: str): bool

Paramètres :

unoobject: l'objet à examiner.

propertyname : la propriété sous forme de chaîne sensible à la casse

Exemple :

En Basic :


    Dim svc As Variant
    svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    MsgBox session.HasUnoProperty(svc, "Wildcards")

En Python


    bas = CreateScriptService("Basic")
    a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    result = session.HasUnoProperty(a, "Wildcards")
    bas.MsgBox(result) # True

OpenURLInBrowser

Ouvrir un Localisateur de ressource universelle (URL) dans le navigateur par défaut.

Syntaxe :

session.OpenURLInBrowser(url: str)

Paramètres :

url: l'URL à ouvrir.

Exemple :


    ' Basic
    session.OpenURLInBrowser("help.libreoffice.org/")


    # Python
    session.OpenURLInBrowser("help.libreoffice.org/")

RunApplication

Exécute une commande système arbitraire et renvoie True si elle a été lancée avec succès.

Syntaxe :

session.RunApplication(command: str, parameters: str): bool

Paramètres :

command : la commande à exécuter. Il peut s'agir d'un fichier exécutable ou d'un document enregistré avec une application afin que le système sache quelle application lancer pour ce document. La commande doit être exprimée dans la notation actuelle SF_FileSystem.FileNaming.

parameters : une liste de paramètres séparés par des espaces sous la forme d'une chaîne unique. La méthode ne valide pas les paramètres donnés, mais les transmet uniquement à la commande spécifiée.

Exemple :

En Basic :


    session.RunApplication("Notepad.exe")
    session.RunApplication("C:\myFolder\myDocument.odt")
    session.RunApplication("kate", "/home/user/install.txt") ' GNU/Linux

En Python


    session.RunApplication("Notepad.exe")
    session.RunApplication(r"C:\myFolder\myDocument.odt")
    session.RunApplication("kate", "/home/user/install.txt") # GNU/Linux

SendMail

Envoyer un message - avec des pièces jointes facultatives - aux destinataires à partir du client de messagerie de l'utilisateur. Le message peut être modifié par l'utilisateur avant l'envoi ou, alternativement, être envoyé immédiatement.

Syntaxe :

session.SendMail(recipient: str, cc: str = '', bcc: str = '', subject: str = '', body: str = '', filenames: str = '', editmessage: bool = True)

Paramètres :

recipient : une adresse e-mail (le destinataire "À").

cc : une liste d'adresses e-mail séparées par des virgules (les destinataires en "copie carbone").

bcc : une liste d'adresses e-mail séparées par des virgules (les destinataires de la "copie carbone invisible").

subject: l'entête du message.

body : le contenu du message sous forme de texte non formaté.

filenames : une liste de noms de fichiers séparés par des virgules. Chaque nom de fichier doit respecter la notation SF_FileSystem.FileNaming.

editmessage : lorsque True (par défaut), le message est modifié avant d'être envoyé.

Exemple :

En Basic :


    session.SendMail("someone@example.com" _
        , Cc := "b@other.fr, c@other.be" _
        , FileNames := "C:\myFile1.txt, C:\myFile2.txt")

En Python


    session.SendMail("someone@example.com",
                     cc="john@other.fr, mary@other.be"
                     filenames=r"C:\myFile1.txt, C:\myFile2.txt")

SetPDFExportOptions

Modifie les paramètres d'export PDF définis dans la boîte de dialogue Options PDF, accessible en choisissant Fichier - Exporter vers - Exporter au format PDF.

L'appel de cette méthode modifie les valeurs réelles définies dans la boîte de dialogue Options PDF, qui sont utilisées par la méthode ExportAsPDF du service Document.

Cette méthode renvoie True en cas de succès.

Lisez la page wiki d'exportation PDF pour en savoir plus sur toutes les options disponibles.

Syntaxe :

session.SetPDFExportOptions(pdfoptions: obj): bool

Paramètres :

pdfoptions : objet Dictionary qui définit les paramètres d'export PDF à modifier. Chaque paire clé-valeur représente une option d'export et la valeur qui sera définie dans la boîte de dialogue.

Exemple :

En Basic :

L'exemple suivant modifie la résolution d'image maximale à 150 ppp et exporte le document actuel sous forme de fichier PDF.


    Dim newSettings As Object, oDoc As Object
    Set oDoc = CreateScriptService("Document")
    Set newSettings = CreateScriptService("Dictionary")
    newSettings.Add("ReduceImageResolution", True)
    newSettings.Add("MaxImageResolution", 150)
    session.SetPDFExportOptions(newSettings)
    oDoc.ExportAsPDF("C:\Documents\myFile.pdf", Overwrite := True)

Cette méthode n'est disponible que pour les scripts Basic.

UnoMethods

Renvoie une liste des méthodes appelables depuis un objet UNO. La liste est une matrice de chaînes de base zéro et peut être vide.

Syntaxe :

session.UnoMethods(unoobject: uno): str[0..*]

Paramètres :

unoobject: l'objet à examiner.

Exemple :

En Basic :


    Dim svc : svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    Dim methods : methods = session.UnoMethods(svc)
    Dim msg as String
    For Each m in methods
        msg = msg & m & Chr(13)
    Next m
    MsgBox msg

En Python


    bas = CreateScriptService("Basic")
    a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    methods = session.UnoMethods(a)
    msg = "\n".join(methods)
    bas.MsgBox(msg)

UnoProperties

Renvoie une liste des propriétés d'un objet UNO. La liste est une matrice de chaînes de base zéro et peut être vide.

Syntaxe :

session.UnoProperties(unoobject: uno): str[0..*]

Paramètres :

unoobject: l'objet à examiner.

Exemple :

En Basic :


    Dim svc As Variant
    svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    MsgBox SF_Array.Contains(session.UnoProperties(svc), "Wildcards") ' True

En Python


    bas = CreateScriptService("Basic")
    svc = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    properties = session.UnoProperties(a)
    b = "Wildcards" in properties
    bas.MsgBox(str(b)) # True

UnoObjectType

Identifiez le type d'un objet UNO sous forme de chaîne.

Syntaxe :

session.UnoObjectType(unoobject: uno): str

Paramètres :

unoobject: l'objet à examiner.

Exemple :

En Basic :


    Dim svc As Variant, txt As String
    svc = CreateUnoService("com.sun.star.system.SystemShellExecute")
    txt = session.UnoObjectType(svc) ' "com.sun.star.comp.system.SystemShellExecute"
    svc = CreateUnoStruct("com.sun.star.beans.Property")
    txt = session.UnoObjectType(svc) ' "com.sun.star.beans.Property"

En Python


    bas = CreateScriptService("Basic")
    svc = bas.CreateUnoService("com.sun.star.system.SystemShellExecute")
    txt = session.UnoObjectType(svc) # "com.sun.star.comp.system.SystemShellExecute"
    svc = bas.CreateUnoService("com.sun.star.beans.Property")
    txt = session.UnoObjectType(svc) # "com.sun.star.beans.Property"

WebService

Récupérez du contenu web à partir d'une URI.

Syntaxe :

session.WebService(uri: str): str

Paramètres :

uri : le texte URI d'un service web.

Exemple :

En Basic :


    session.WebService("wiki.documentfoundation.org/api.php?" _
        & "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss")

En Python


    session.WebService(("wiki.documentfoundation.org/api.php?" 
                       "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss"))

Toutes les routines ou identifiants de base ScriptForge qui sont préfixés par un caractère de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans des macros de base ou des scripts Python.

Fonction Array

Utilisation des fonctions Cacl dans les macros

Appel de scripts Python à partir du Basic

ScriptForge.Service Basic

ScriptForge. Service FileSystem