Serviço ScriptForge.Session

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

Invocação do serviço


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

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


tip

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

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

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.


♥ Doe para nosso projeto! ♥