Service ScriptForge.Session

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

Invocation du service

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

note

‚ÄĘ 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


tip

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.

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.

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
  
tip

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.

tip

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
    ' ...
  
note

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.

tip

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)
  
note

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"))
  
warning

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.


Aidez-nous !