Contenu

# 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 :

commande : la commande à exécuter. Il peut s'agir d'un fichier exécutable ou d'un document enregistré auprès d'une application afin que le système sache quelle application lancer pour ce document. Cette méthode démarre indifféremment des scripts .bat ou shell. La commande doit être exprimée dans la notation SF_FileSystem.FileNaming actuelle.

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.

Rubriques connexes

Fonction Array

Utilisation des fonctions Cacl dans les macros

Appel de scripts Python à partir du Basic

ScriptForge.Service Basic

ScriptForge. Service FileSystem