Conteúdo
Índice 🔎︎

# 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

         GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
         Dim session As Variant
         session = CreateScriptService("Session")

Este serviço é totalmente compatível com as linguagens Basic e Python. Todos os exemplos são descritos usando a linguagem de programação Basic e podem ser facilmente convertidos para Python.

## 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-os como 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 HasUnoMethod | HasUnoProperty OpenURLInBrowser RunApplication SendMail | UnoMethods UnoProperties UnoObjectType WebService

Os métodos do serviço Session se comportam da seguinte forma:
Argumentos são passados por valor. Atualizações realizadas pela função chamada não são enviadas de volta para o script que a chamou.
Um valor único ou Array de valores é retornado pelo script que a chamou.

## ExecuteBasicScript

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

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

### Sintaxe:

          session.ExecuteBasicScript([Scope As String], Script As String[, arg0 As Variant, ...]) As Variant

### Parâmetros:

Scope: "document" ou "application" ou uma das constantes aplicáveis session.CONSTANTS.

Script: "biblioteca.módulo.método" como uma String sensível à caixa.
A biblioteca é carregada na memória se necessário.
O módulo não pode ser um módulo de classe.
O método pode ser um Sub ou uma Function.

arg0, ...: Argumentos a serem passados ao script chamado.

### Exemplo:

          session.ExecuteBasicScript(, "XrayTool._Main.Xray", CreateUnoService("com.sun.star.util.TextSearch"))
          ' Xray não retorna valor algum

## 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 As String, arg0, ...) As Variant

### Parâmetros:

CalcFunction: Nome em inglês da função a ser executada.

arg0, ...: Argumentos a serem fornecidos à função Calc. Cada argumento deve ser ou uma String, um valor numérico ou um Array combinando valores desses tipos.

### Exemplo:

          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

## 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] As String, Script As String[, arg0 As Variant, ...]) As Variant

### Parâmetros:

Scope: Uma das constantes aplicáveis session.CONSTANTS. 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.

arg0, ...: Argumentos a serem passados ao script chamado.

### Exemplo:

          session.ExecutePythonScript(session.SCRIPTISSHARED, "Capitalise.py$getNewString", "Abc") ' "abc"

## 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 As Object, MethodName As String) As Boolean

### Parâmetros:

UnoObject: Objeto UNO a ser inspecionado.

MethodName: Nome do método como uma String sensível à caixa.

### Exemplo:

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

## 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 As Object, PropertyName As String) As Boolean

### Parâmetros:

UnoObject: Objeto UNO a ser inspecionado.

PropertyName: Nome da propriedade como uma String sensível à caixa.

### Exemplo:

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

## OpenURLInBrowser

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

### Sintaxe:

          session.OpenURLInBrowser(URL As String)

### Parâmetros:

URL: Endereço URL a ser aberto.

### Exemplo:

          session.OpenURLInBrowser("https://docs.python.org/3/library/webbrowser.html")

## RunApplication

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

### Sintaxe:

          session.RunApplication(Command As String, Parameters As String) As Boolean

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

          session.RunApplication("Notepad.exe")
          session.RunApplication("C:\myFolder\myDocument.odt")
          session.RunApplication("kate", "/home/me/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 As String, [Cc As String], [Bcc As String], [Subject As String], [Body As String], [FileNames As String], [EditMessage As Boolean])

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

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

## 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 As Object) As Variant

### Parâmetros:

UnoObject: Objeto UNO a ser inspecionado.

### Exemplo:

          Dim a As Variant
          a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
          MsgBox SF_Array.Contains(session.UnoMethods(a), "callFunction")

## UnoProperties

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

### Sintaxe:

          session.UnoProperties(UnoObject As Object) As Variant

### Parâmetros:

UnoObject: Objeto UNO a ser inspecionado.

### Exemplo:

          Dim svc As Variant
          svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
          MsgBox SF_Array.Contains(session.UnoProperties(svc), "Wildcards")

## UnoObjectType

Identifica o tipo de um objeto UNO como uma String.

### Sintaxe:

          session.UnoObjectType(UnoObject As Object) As String

### Parâmetros:

UnoObject: Objeto UNO a ser identificado.

### Exemplo:

          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"

## WebService

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

### Sintaxe:

          session.WebService(URI As String) As String

### Parâmetros:

URI: expressão textual da URI do serviço web.

### Exemplo:

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

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.

Tópicos relacionados

Função Array

Chamar funções do Calc

Chamar scripts Python desde o Basic

Serviço ScriptForge.FileSystem