Servicio ScriptForge.Session

El servicio Session re煤ne varios m茅todos de uso general relativos a:

Invocaci贸n del servicio

Antes de utilizar el servicio Session, es necesario cargar o importar la biblioteca ScriptForge:

note

鈥 Para cargar la biblioteca ScriptForge que necesitan las macros de Basic se debe usar la siguiente declaraci贸n:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

鈥 Los scripts de Python necesitan importar el m贸dulo 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

Below is a list of constants available to ease the designation of the library containing a Basic or Python script to invoke. Use them as session.CONSTANT.

CONSTANT

Valor

驴D贸nde se encuentra la biblioteca?

Se aplica

SCRIPTISEMBEDDED

"document"

en el documento

Basic + Python

SCRIPTISAPPLICATION

"application"

en cualquier biblioteca compartida

Basic

SCRIPTISPERSONAL

"user"

en Mis macros

Python

SCRIPTISPERSOXT

"user:uno_packages"

en una extensi贸n instalada para la cuenta de usuario actual

Python

SCRIPTISSHARED

"share"

en Macros de la aplicaci贸n

Python

SCRIPTISSHAROXT

"share:uno_packages"

en una extensi贸n instalada para todos los usuarios

Python

SCRIPTISOXT

"uno_packages"

en una extensi贸n cuyos par谩metros de instalaci贸n, empero, se desconocen

Python


Lista de m茅todos en el servicio Session

ExecuteBasicScript
ExecuteCalcFunction
ExecutePythonScript
GetPDFExportOptions
HasUnoMethod

HasUnoProperty
OpenURLInBrowser
RunApplication
SendMail
SetPDFExportOptions

UnoMethods
UnoProperties
UnoObjectType
WebService


tip

Execute... methods in Session service behave as follows:
Arguments are passed by value. Changes made by the called function to the arguments do not update their values in the calling script.
A single value or an array of values is returned to the calling script.


ExecuteBasicScript

Execute the BASIC script given its name and location, and fetch its result, if any.

If the script returns nothing, which is the case of procedures defined with Sub, the returned value is Empty.

Sintaxis:

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

Par谩metros:

scope: String specifying where the script is stored. It can be either "document" (constant session.SCRIPTISEMBEDDED) or "application" (constant session.SCRIPTISAPPLICATION).

script: String specifying the script to be called in the format "library.module.method" as a case-sensitive string.

args: The arguments to be passed to the called script.

Ejemplo:

Consider the following Basic function named DummyFunction that is stored in "My Macros" in the "Standard" library inside a module named "Module1".

La funci贸n simplemente recibe dos valores enteros, v1 y v2, y devuelve la suma de todos los valores a partir de v1 y que terminan en 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
  

The examples below show how to call DummyFunction from within Basic and Python scripts.

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

Execute a Calc function using its English name and based on the given arguments.
If the arguments are arrays, the function is executed as an array formula.

Sintaxis:

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

Par谩metros:

calcfunction: The name of the Calc function to be called, in English.

args: The arguments to be passed to the called Calc function. Each argument must be either a string, a numeric value or an array of arrays combining those types.

Ejemplo:

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)
    ' Genera un error.
  
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

Execute the Python script given its location and name, fetch its result if any. Result can be a single value or an array of values.

Si la secuencia de 贸rdenes no se encuentra o no devuelve nada, el valor devuelto ser谩 Empty.

El marco de programaci贸n de macros de la API (interfaz de programaci贸n de aplicaciones) de LibreOffice admite la ejecuci贸n de secuencias de 贸rdenes entre Python y Basic u otros lenguajes de programaci贸n admitidos. Los argumentos se pueden pasar de un lado a otro entre llamadas, siempre que representen tipos de datos primitivos que ambos lenguajes reconozcan y suponiendo que el marco de programaci贸n de macros los convierta de forma adecuada.

Sintaxis:

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

Par谩metros:

scope: One of the applicable constants listed above. The default value is session.SCRIPTISSHARED.

script: Either "library/module.py$method" or "module.py$method" or "myExtension.oxt|myScript|module.py$method" as a case-sensitive string.

args: The arguments to be passed to the called script.

Ejemplo:

Consider the Python function odd_integers defined below that creates a list with odd integer values between v1 and v2. Suppose this function is stored in a file named my_macros.py in your user scripts folder.


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

Read the help page Python Scripts Organization and Location to learn more about where Python scripts can be stored.


The following examples show how to call the function odd_integers from within Basic and Python scripts.

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

Devuelve la configuraci贸n actual de exportaci贸n a PDF que se ha definido en el cuadro de di谩logo Opciones de PDF, al cual se puede acceder al elegir Archivo聽鈻 Exportar a聽鈻 Exportar a PDF.

Export options set with the PDF Options dialog are kept for future use. Hence GetPDFExportOptions returns the settings currently defined. In addition, use SetPDFExportOptions to change current PDF export options.

This method returns a Dictionary object wherein each key represent export options and the corresponding values are the current PDF export settings.

tip

Read the PDF Export wiki page to learn more about all available options.


Sintaxis:

session.GetPDFExportOptions(): obj

Ejemplo:

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

Este m茅todo est谩 disponible 煤nicamente para secuencias BASIC.


HasUnoMethod

Returns True if an UNO object contains the given method. Returns False when the method is not found or when an argument is invalid.

Sintaxis:

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

Par谩metros:

unoobject: el objeto que se inspeccionar谩.

methodname: the method as a case-sensitive string

Ejemplo:

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

Returns True if a UNO object has the given property. Returns False when the property is not found or when an argument is invalid.

Sintaxis:

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

Par谩metros:

unoobject: el objeto que se inspeccionar谩.

propertyname: the property as a case-sensitive string

Ejemplo:

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

Abre un localizador uniforme de recursos (un URL, por sus siglas en ingl茅s) en el navegador predeterminado.

Sintaxis:

session.OpenURLInBrowser(url: str)

Par谩metros:

url: el URL para abrir.

Ejemplo:


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

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

RunApplication

Ejecuta una orden arbitraria del sistema y devuelve Verdadero si se inici贸 con 茅xito.

Sintaxis:

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

Par谩metros:

command: The command to execute. This may be an executable file or a document which is registered with an application so that the system knows what application to launch for that document. The command must be expressed in the current SF_FileSystem.FileNaming notation.

parameters: A list of space separated parameters as a single string. The method does not validate the given parameters, but only passes them to the specified command.

Ejemplo:

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

Send a message - with optional attachments - to recipients from the user's mail client. The message may be edited by the user before sending or, alternatively, be sent immediately.

Sintaxis:

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

Par谩metros:

recipient: una direcci贸n electr贸nica (el destinatario del campo 芦A禄).

cc: una lista de direcciones de correo electr贸nico separadas por comas (los destinatarios 芦con copia禄).

bcc: una lista de direcciones de correo electr贸nico separadas por comas (los destinatarios 芦con copia oculta禄).

subject: la cabecera del mensaje.

body: el contenido del mensaje como un texto sin formato.

filenames: una lista de nombres de archivo separados por comas. Cada uno de los nombres de archivo debe respetar la notaci贸n de SF_FileSystem.FileNaming.

editmessage: When True (default), the message is edited before being sent.

Ejemplo:

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

Modifies the PDF export settings defined in the PDF Options dialog, which can be accessed by choosing File - Export as - Export as PDF.

Calling this method changes the actual values set in the PDF Options dialog, which are used by the ExportAsPDF method from the Document service.

This method returns True when successful.

tip

Read the PDF Export wiki page to learn more about all available options.


Sintaxis:

session.SetPDFExportOptions(pdfoptions: obj): bool

Par谩metros:

pdfoptions: Dictionary object that defines the PDF export settings to be changed. Each key-value pair represents an export option and the value that will be set in the dialog.

Ejemplo:

En BASIC

The following example changes the maximum image resolution to 150 dpi and exports the current document as a PDF file.


    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

Este m茅todo est谩 disponible 煤nicamente para secuencias BASIC.


UnoMethods

Returns a list of the methods callable from an UNO object. The list is a zero-based array of strings and may be empty.

Sintaxis:

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

Par谩metros:

unoobject: el objeto que se inspeccionar谩.

Ejemplo:

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

Returns a list of the properties of an UNO object. The list is a zero-based array of strings and may be empty.

Sintaxis:

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

Par谩metros:

unoobject: el objeto que se inspeccionar谩.

Ejemplo:

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

Identify the type of a UNO object as a string.

Sintaxis:

session.UnoObjectType(unoobject: uno): str

Par谩metros:

unoobject: The object to identify.

Ejemplo:

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

Get some web content from a URI.

Sintaxis:

session.WebService(uri: str): str

Par谩metros:

uri: URI address of the web service.

Ejemplo:

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

Todas las rutinas o identificadores BASIC de ScriptForge precedidas por guion bajo 芦_禄 est谩n reservadas para uso interno. No deben utilizarse en macros BASIC o secuencias Python.


隆Necesitamos su ayuda!