Sumário

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

The method returns a (string or numeric) scalar or the array of arrays returned by the call to the function.

### Sintaxe:

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

### Parâmetros:

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

args: The arguments to be passed to the called Calc function.
Each argument may be either

- a string, a numeric value, a date or a boolean

- a 1D array, a 2D array or an array of arrays combining above datatypes

- a com.sun.star.table.XCellRange UNO object

### 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)  ' Generates an error
        ' --------
        table1 = Array(\"Symbol\", \"H\", \"He\", \"Li\")
        table2 = Array(\"AtomicNumber\", 1.0, 2.0, 3.0)
        table3 = Array(\"Mass\", 1.008, 4.0026, 6.94)
        table = Array(table1, table2, table3)  ' array of arrays
        search = Array(\"Symbol\", \"AtomicNumber\", \"Mass\")
        result = session.ExecuteCalcFunction(\"XLOOKUP\", \"Mass\", search, table)
        MsgBox result(0)(3)  ' 6.94

##### 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) # Error
        # --------
        table = ( ("Symbol", "H", "He", "Li"),
                  ("AtomicNumber", 1.0, 2.0, 3.0),
                  ("Mass", 1.008, 4.0026, 6.94) )
        search = ("Symbol", "AtomicNumber", "Mass")
        result = session.ExecuteCalcFunction("XLOOKUP", "Mass", search, table)
        basic = CreateScriptService('Basic')
        basic.MsgBox(result[0][3]) # 6.94

## 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: O comando a ser executado. Pode ser um arquivo executável ou um documento registrado com um aplicativo para que o sistema saiba qual aplicativo iniciar para esse documento. Este método inicia igualmente scripts .bat ou shell. O comando deve ser expresso na 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.

Tópicos relacionados

Função Array

Chamar funções do Calc em Macros

Chamar scripts Python desde o Basic

Serviço ScriptForge.Basic

Serviço ScriptForge.FileSystem

♥ Doe para nosso projeto! ♥