Serviço ScriptForge.Session

O serviço Session reúne diversos métodos de propósito geral sobre:

Invocação do serviço

Antes de utilizar o serviço Session, a biblioteca ScriptForge deve ser carregada ou importada:

note

• Macros BASIC precisam carregar a biblioteca ScriptForge usando a seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Scripts Python exigem uma importação do módulo scriptforge:
from scriptforge import CreateScriptService


Em Basic

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

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

Constantes

Abaixo está uma lista de constantes disponíveis para facilitar a designação de uma biblioteca contendo um script Basic ou Python a ser invocado. Use-as no formato session.CONSTANT.

CONSTANT

Valor

Onde encontrar a biblioteca?

Aplicável

SCRIPTISEMBEDDED

"document"

No documento

Basic + Python

SCRIPTISAPPLICATION

"application"

Em qualquer biblioteca compartilhada

Basic

SCRIPTISPERSONAL

"user"

Em Minhas Macros

Python

SCRIPTISPERSOXT

"user:uno_packages"

Em uma extensão instalada para o usuário atual

Python

SCRIPTISSHARED

"share"

Em macros do LibreOffice

Python

SCRIPTISSHAROXT

"share:uno_packages"

Em uma extensão instalada para todos os usuários.

Python

SCRIPTISOXT

"uno_packages"

Em uma extensão mas os parâmetros de instalação são desconhecidos.

Python


Lista de Métodos do Serviço Session

ExecuteBasicScript
ExecuteCalcFunction
ExecutePythonScript
GetPDFExportOptions
HasUnoMethod

HasUnoProperty
OpenURLInBrowser
RunApplication
SendMail
SetPDFExportOptions

UnoMethods
UnoProperties
UnoObjectType
WebService


tip

Métodos Execute... no serviço Session se comportam da seguinte forma:
Argumentos são passados por valor. Mudanças nos argumentos feitas pela função chamada não alteram seus valores no script original.
Um valor único ou um array é retornado ao script que chamou o método.


ExecuteBasicScript

Executa o script Basic dado seu nome e localização e retorna seu resultado, se houver.

Se o script não retornar valor algum, que é o caso de procedimentos definidos como Sub, o valor retornado é Empty.

Sintaxe:

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

Parâmetros:

scope: Valor string especificando onde o script está armazenado. Pode ter o valor "document" (constante session.SCRIPTISEMBEDDED) or "application" (constante session.SCRIPTISAPPLICATION).

script: Valor string sensível à caixa especificando o script a ser chamado no formato "biblioteca.módulo.método".

args: Argumentos que serão passados ao script chamado.

Exemplo:

Considere a seguinte função Basic chamada DummyFunction que é armazenada em "Minhas macros" na biblioteca "Standard" dentro do módulo chamado "Module1".

A função simplesmente recebe dois valores inteiros v1 e v2 e retorna a soma de todos os valores iniciando em v1 e terminando em 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
  

Os exemplos abaixo mostram como chamar DummyFunction a partir de scripts escritos em Basic e Python.

Em 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
  
Em 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

Executa uma função Calc usando seu nome em inglês com base nos argumentos fornecidos.
Se os argumentos forem Arrays, a função é executada como uma Função de Matriz.

Sintaxe:

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

Parâmetros:

calcfunction: Nome da função Calc a ser chamada, em inglês.

args: Argumentos a serem passados à função Calc chamada. Cada argumento deve ser uma string, um valor numérico ou um array de arrays contendo esses tipos.

Exemplo:

Em 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)
    ' Gera um erro
  
Em 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

Executa um script Python dada sua localização e seu nome, retornando os resultados, quando houver. O resultado pode ser um valor único ou um Array de valores.

Se o script não for encontrado, ou se nada for retornado pelo script, o valor retornado é Empty.

A Interface de Programação de Aplicações (API) Scripting Framework do LibreOffice suporta a execução de scripts inter-linguagem entre Python e o Basic, ou demais linguagens suportadas. Os argumentos podem ser passados para frente ou de volta entre chamadas, desde que representem tipo de dados primitivos que ambas linguagens reconheçam, e assumindo que o Scripting Framework faça a conversão adequadamente.

Sintaxe:

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

Parâmetros:

scope: Uma das constantes aplicáveis listadas acima. O valor padrão é session.SCRIPTISSHARED.

script: String sensível à caixa em um dos formatos: "biblioteca/módulo.py$método" ou "módulo.py$método" ou "minhaExtensão.oxt|meuScript|módulo.py$método".

args: Argumentos que serão passados ao script chamado.

Exemplo:

Considere a função Python odd_integers definida abaixo que cria uma lista com os valores ímpares entre v1 e v2. Suponha que esta função esteja armazenada em um arquivo chamado my_macros.py em sua pasta de scripts de usuário.


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

Leia a página de ajuda Organização e localização de scripts Python para aprender mais sobre onde scripts Python são armazenados.


Os seguintes exemplos mostram como chamar a função odd_integers a partir de scripts escritos em Basic e Python.

Em 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)
  
Em Python

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

GetPDFExportOptions

Retorna as configurações atuais de exportação de PDF definidas na caixa de diálogo Opções de PDF, que pode ser acessada ao escolher Arquivo - Exportar como - Exportar como PDF .

As opções de exportação definidas na caixa de diálogo Opções de PDF são mantidas para uso futuro. Portanto, GetPDFExportOptions retorna as configurações definidas atualmente. Além disso, use SetPDFExportOptions para alterar as opções atuais de exportação de PDF.

Este método retorna um objeto Dictionary em que cada chave representa as opções de exportação e os valores correspondentes são as configurações atuais de exportação de PDF.

tip

Acesse página wiki de exportação PDF para saber mais sobre todas as opções disponíveis.


Sintaxe:

session.GetPDFExportOptions(): obj

Exemplo:

Em 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 só está disponível em scripts Basic.


HasUnoMethod

Retorna True se um objeto UNO contém o método especificado. Retorna False se o método não for encontrado o quando um argumento for inválido.

Sintaxe:

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

Parâmetros:

unoobject: Objeto UNO a ser inspecionado.

methodname: Nome do método como uma string sensível à caixa.

Exemplo:

Em Basic

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

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

HasUnoProperty

Retorna True se um objeto UNO contém a propriedade especificada. Retorna False se a propriedade não for encontrada o quando um argumento for inválido.

Sintaxe:

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

Parâmetros:

unoobject: Objeto UNO a ser inspecionado.

propertyname: Nome da propriedade como uma string sensível à caixa.

Exemplo:

Em Basic

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

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

OpenURLInBrowser

Abre um endereço URL (Uniform Resource Locator) no navegador padrão.

Sintaxe:

session.OpenURLInBrowser(url: str)

Parâmetros:

url: Endereço URL a ser aberto.

Exemplo:


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

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

RunApplication

Executa um comando de sistema arbitrário e retorna True se a execução foi bem-sucedida.

Sintaxe:

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

Parâmetros:

command: Comando a ser executado. Pode ser um arquivo executável ou um documento que esteja associado a uma aplicação de maneira que o sistema saiba qual aplicação deve ser lançada para abrir o documento. O comando deve ser expresso usando a notação SF_FileSystem.FileNaming atual.

parameters: Lista de parâmetros separados por espaços como uma string única. O método não valida os parâmetros, apenas os passa para o comando especificado.

Exemplo:

Em Basic

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

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

SendMail

Envia uma mensagem - com anexos opcionais - aos destinatários a partir da aplicação de e-mail padrão do usuário. A mensagem pode ser editada pelo usuário antes de ser enviada ou, alternativamente, pode ser enviada imediatamente.

Sintaxe:

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

Parâmetros:

recipient: Um endereço de e-mail (campo "Destinatário" do e-mail).

cc: Lista de endereços de e-mail separados por vírgula (campo CC do e-mail).

bcc: Lista de endereços de e-mail separados por vírgula (campo BCC do e-mail).

subject: Assunto da mensagem.

body: Texto não formatado com o conteúdo da mensagem.

filenames: Lista de nomes de arquivos separados por vírgula. Cada nome de arquivo deve obedecer a notação SF_FileSystem.FileNaming corrente.

editmessage: Quando True (padrão), a mensagem é editada antes de ser enviada.

Exemplo:

Em Basic

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

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

SetPDFExportOptions

Modifica as configurações de exportação de PDF definidas na caixa de diálogo Opções de PDF, que pode ser acessada ao escolher Arquivo - Exportar como - Exportar como PDF.

Chamar este método muda os valores reais definidos na caixa de diálogo Opções de PDF, que são usados pelo método ExportAsPDF do serviço Document.

Este método retorna True quando for bem-sucedido.

tip

Acesse página wiki de exportação PDF para saber mais sobre todas as opções disponíveis.


Sintaxe:

session.SetPDFExportOptions(pdfoptions: obj): bool

Parâmetros:

pdfoptions: objeto tipo Dicionary que define as configurações de exportação de PDF a serem alteradas. Cada par de valores-chave representa uma opção de exportação e o valor que será definido na caixa de diálogo.

Exemplo:

Em Basic

O exemplo a seguir altera a resolução máxima da imagem para 150 dpi e exporta o documento atual como um arquivo 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

Este método só está disponível em scripts Basic.


UnoMethods

Retorna uma lista de métodos que podem ser chamados a partir de um objeto UNO. A lista é um Array indexado em zero com Strings.

Sintaxe:

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

Parâmetros:

unoobject: Objeto UNO a ser inspecionado.

Exemplo:

Em 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
  
Em Python

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

UnoProperties

Retorna uma lista com as propriedades de um objeto UNO. A lista é um Array indexado em zero com Strings.

Sintaxe:

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

Parâmetros:

unoobject: Objeto UNO a ser inspecionado.

Exemplo:

Em Basic

    Dim svc As Variant
    svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    MsgBox SF_Array.Contains(session.UnoProperties(svc), "Wildcards") ' True
  
Em 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

Identifica o tipo de um objeto UNO como uma String.

Sintaxe:

session.UnoObjectType(unoobject: uno): str

Parâmetros:

unoobject: Objeto UNO a ser identificado.

Exemplo:

Em 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"
  
Em 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

Obtém conteúdo web a partir de um endereço URI.

Sintaxe:

session.WebService(uri: str): str

Parâmetros:

uri Endereço URI do serviço web (web service).

Exemplo:

Em Basic

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

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

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.


♥ Doe para nosso projeto! ♥