Serviço ScriptForge.Session

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

A instalação ou ambiente de execução
Introspecção UNO
A invocação de scripts externos ou programas

Invocação do serviço

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

• 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 da aplicação	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

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

A biblioteca é carregada na memória se necessário.
O módulo não pode ser um módulo de classe (class module).
O método pode ser um Sub ou uma Function.

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

"biblioteca": Caminho para a pasta do módulo Python.
"meuScript": Pasta contendo o módulo Python.
"módulo.py": O módulo Python.
"método": A função Python.

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

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.

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

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.

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)

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

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.

Função Array

Chamar funções do Calc em Macros

Chamar scripts Python desde o Basic

Serviço ScriptForge.Basic

Serviço ScriptForge.FileSystem