ScriptForge.Session serviço
O serviço Session reúne vários métodos de uso geral relacionados com:
-
o ambiente de instalação ou de execução
-
Introspecção da UNO
-
a execução de scripts ou programas externos
Chamada de serviço
Antes de utilizar o serviço Session, é necessário carregar ou importar a biblioteca ScriptForge:
• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService
GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
Dim session As Variant
session = CreateScriptService("Session")
from scriptforge import CreateScriptService
session = CreateScriptService("Session")
Constantes
Segue-se uma lista de constantes disponíveis para facilitar a indicação da biblioteca que contém um script em Basic ou Python a ser executado. Utilize-as na forma session.CONSTANT.
|
CONSTANT |
Valor |
Onde fica a biblioteca? |
Aplicável |
|---|---|---|---|
|
SCRIPTISEMBEDDED |
"document" |
no documento |
Basic + Python |
|
SCRIPTISAPPLICATION |
"application" |
em qualquer biblioteca partilhada |
Basic |
|
SCRIPTISPERSONAL |
"user" |
em As minhas macros |
Python |
|
SCRIPTISPERSOXT |
"user:uno_packages" |
numa extensão instalada para o utilizador atual |
Python |
|
SCRIPTISSHARED |
"share" |
em Macros da aplicação |
Python |
|
SCRIPTISSHAROXT |
"share:uno_packages" |
numa extensão instalada para todos os utilizadores |
Python |
|
SCRIPTISOXT |
"uno_packages" |
numa extensão, mas os parâmetros de instalação são desconhecidos |
Python |
|
Lista de métodos do serviço de sessão |
||
|---|---|---|
|
ExecuteBasicScript |
HasUnoProperty |
|
Os métodos Execute... no serviço Session comportam-se da seguinte forma:
Os argumentos são passados por valor. As alterações feitas pela função chamada aos argumentos não atualizam os seus valores no script de chamada.
É devolvido ao script de chamada um único valor ou um conjunto de valores.
ExecuteBasicScript
Executar o script BASIC, indicando o seu nome e localização, e obter o seu resultado, caso exista.
Se o script não devolver nada, o que acontece no caso de procedimentos definidos com Sub, o valor devolvido é Empty.
session.ExecuteBasicScript(scope: str, script: str, args: any[0..*]): any
scope: String que especifica onde o script está armazenado. Pode ser «document» (constante session.SCRIPTISEMBEDDED) ou «application» (constante session.SCRIPTISAPPLICATION).
script: Cadeia de caracteres que especifica o script a ser chamado no formato «biblioteca.módulo.método», sendo que se distingue entre maiúsculas e minúsculas.
-
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.
args: Os argumentos a passar ao script chamado.
Considere a seguinte função básica denominada DummyFunction, que se encontra armazenada em «As minhas macros», na biblioteca «Padrão», dentro de um módulo denominado «Módulo1».
A função recebe simplesmente dois valores inteiros, v1 e v2, e devolve a soma de todos os valores que começam em v1 e terminam 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 em Basic e Python.
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
session = CreateScriptService("Session")
bas = CreateScriptService("Basic")
b_script = 'Standard.Module1.DummyFunction'
result = session.ExecuteBasicScript('application', b_script, 1, 10)
bas.MsgBox(result) # 55
ExecuteCalcFunction
Execute uma função do Calc utilizando o seu nome em inglês e com base nos argumentos fornecidos.
Se os argumentos forem matrizes, a função é executada como uma fórmula de matriz.
O método devolve um escalar (cadeia de caracteres ou valor numérico) ou o conjunto de matrizes devolvido pela chamada à função.
session.ExecuteCalcFunction(calcfunction: str, args: any[0..*]): any
calcfunction: O nome da função do Calc a ser chamada, em inglês.
args: Os argumentos a passar à função Calc chamada.
Cada argumento pode ser
-
uma cadeia de caracteres, um valor numérico, uma data ou um valor booleano
-
um tabular de 1D, um tabular de 2D ou um tabular de tabulares que combine os tipos de dados acima referidos
-
um objeto UNO com.sun.star.table.XCellRange
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
' --------
table1 = Array("Símbolo", "H", "He", "Li")
table2 = Array("Número Atómico", 1,0, 2,0, 3,0)
table3 = Array("Massa", 1,008, 4,0026, 6,94)
table = Array(table1, table2, table3) ' matriz de matrizes
search = Array("Símbolo", "Número Atómico", "Massa")
result = session.ExecuteCalcFunction("XLOOKUP", "Mass", search, table)
MsgBox result(0)(3) ' 6,94
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
Executar o script Python com base na sua localização e nome e, caso haja, obter o seu resultado. O resultado pode ser um único valor ou um conjunto de valores.
Se o script não for encontrado, ou se não devolver qualquer resultado, o valor devolvido é Vazio.
session.ExecutePythonScript(scope: str, script: str, args: any[0..*]): any
âmbito: Uma das constantes aplicáveis enumeradas acima. O valor predefinido é session.SCRIPTISSHARED.
script: Pode ser «library/module.py$method», «module.py$method» ou «myExtension.oxt|myScript|module.py$method», como uma cadeia de caracteres que distingue maiúsculas de minúsculas.
biblioteca: O caminho da pasta para o módulo Python.
myScript: A pasta que contém o módulo Python.
module.py: O módulo Python.
método: A função em Python.
args: Os argumentos a passar ao script chamado.
Considere a função Python odd_integers definida abaixo, que cria uma lista com valores inteiros ímpares entre v1 e v2. Suponha que esta função esteja guardada num ficheiro chamado my_macros.py na pasta de scripts do utilizador.
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 dos scripts Python para saber mais sobre onde os scripts Python podem ser guardados.
Os exemplos seguintes mostram como chamar a função odd_integers a partir de scripts em Basic e Python.
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)
session = CreateScriptService("Session")
script = "my_macros.py$odd_integers"
result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)
bas.MsgBox(repr(result))
GetPDFExportOptions
Devolve as definições atuais de exportação para PDF definidas na caixa de diálogo , à qual se pode aceder selecionando .
As opções de exportação definidas na caixa de diálogo são guardadas para utilização futura. Por conseguinte, GetPDFExportOptions devolve as definições atualmente definidas. Além disso, utilize SetPDFExportOptions para alterar as opções atuais de exportação para PDF.
Este método devolve um objeto Dictionary, no qual cada chave representa opções de exportação e os valores correspondentes são as definições atuais de exportação para PDF.
Leia a página da wiki sobre exportação para PDF para saber mais sobre todas as opções disponíveis.
session.GetPDFExportOptions(): obj
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
' ...
HasUnoMethod
Devolve True se um objeto UNO contiver o método indicado. Devolve False quando o método não é encontrado ou quando um argumento é inválido.
session.HasUnoMethod(unoobject: uno, methodname: str): bool
unoobject: O objeto a inspecionar.
nome do método: o método como uma cadeia de caracteres que distingue maiúsculas de minúsculas
Dim a As Variant
a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
MsgBox session.HasUnoMethod(a, "callFunction") ' True
bas = CreateScriptService("Basic")
a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
result = session.HasUnoMethod(a, "callFunction")
bas.MsgBox(result) # True
HasUnoProperty
Devolve True se um objeto UNO tiver a propriedade indicada. Devolve False quando a propriedade não é encontrada ou quando um argumento é inválido.
session.HasUnoProperty(unoobject: uno, propertyname: str): bool
unoobject: O objeto a inspecionar.
propertyname: a propriedade como uma cadeia de caracteres que distingue maiúsculas de minúsculas
Dim svc As Variant
svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
MsgBox session.HasUnoProperty(svc, "Wildcards")
bas = CreateScriptService("Basic")
a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
result = session.HasUnoProperty(a, "Wildcards")
bas.MsgBox(result) # True
OpenURLInBrowser
Abra um Localizador Uniforme de Recursos (URL) no navegador predefinido.
session.OpenURLInBrowser(url: str)
url: O URL a abrir.
' Basic
session.OpenURLInBrowser("help.libreoffice.org/")
# Python
session.OpenURLInBrowser("help.libreoffice.org/")
RunApplication
Executa um comando de sistema arbitrário e devolve True se tiver sido executado com sucesso.
session.RunApplication(command: str, parameters: str): bool
comando: O comando a executar. Pode tratar-se de um ficheiro executável ou de um documento associado a uma aplicação, para que o sistema saiba qual a aplicação a iniciar para esse documento. Este método executa igualmente ficheiros .bat ou scripts de shell. O comando deve ser expresso na notação atual SF_FileSystem.FileNaming.
parâmetros: Uma lista de parâmetros separados por espaços, apresentada como uma única cadeia de caracteres. O método não valida os parâmetros fornecidos, limitando-se a transmiti-los ao comando especificado.
session.RunApplication("Notepad.exe")
session.RunApplication("C:\\myFolder\\myDocument.odt")
session.RunApplication("kate", "/home/user/install.txt") ' GNU/Linux
session.RunApplication("Notepad.exe")
session.RunApplication(r"C:\\myFolder\\myDocument.odt")
session.RunApplication("kate", "/home/user/install.txt") # GNU/Linux
SendMail
Enviar uma mensagem — com anexos opcionais — aos destinatários a partir do cliente de e-mail do utilizador. A mensagem pode ser editada pelo utilizador antes do envio ou, em alternativa, ser enviada imediatamente.
session.SendMail(recipient: str, cc: str = '', bcc: str = '', subject: str = '', body: str = '', filenames: str = '', editmessage: bool = True)
destinatário: Um endereço de e-mail (o destinatário do campo «Para»).
cc: Uma lista de endereços de e-mail separados por vírgulas (os destinatários em «cópia»).
bcc: Uma lista de endereços de e-mail separados por vírgulas (os destinatários da «cópia oculta»).
assunto: o cabeçalho da mensagem.
corpo: O conteúdo da mensagem como texto sem formatação.
nomes de ficheiros: uma lista de nomes de ficheiros separados por vírgulas. Cada nome de ficheiro deve respeitar a notação SF_FileSystem.FileNaming.
editmessage: Quando True (por predefinição), a mensagem é editada antes de ser enviada.
session.SendMail("someone@example.com" _
, Cc := "b@other.fr, c@other.be" _
, FileNames := "C:\myFile1.txt, C:\myFile2.txt")
session.SendMail("someone@example.com",
cc="john@other.fr, mary@other.be"
filenames=r"C:\myFile1.txt, C:\myFile2.txt")
SetPDFExportOptions
Modifies the PDF export settings defined in the dialog, which can be accessed by choosing .
Calling this method changes the actual values set in the dialog, which are used by the ExportAsPDF method from the Document service.
This method returns True when successful.
Read the PDF Export wiki page to learn more about all available options.
session.SetPDFExportOptions(pdfoptions: obj): bool
pdfoptions: Dictionary object that defines the PDF export settings to be changed. Each key-value pair represents an export option and the value that will be set in the dialog.
The following example changes the maximum image resolution to 150 dpi and exports the current document as a PDF file.
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)
UnoMethods
Returns a list of the methods callable from an UNO object. The list is a zero-based array of strings and may be empty.
session.UnoMethods(unoobject: uno): str[0..*]
unoobject: The object to inspect.
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
bas = CreateScriptService("Basic")
a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
methods = session.UnoMethods(a)
msg = "\n".join(methods)
bas.MsgBox(msg)
UnoProperties
Returns a list of the properties of an UNO object. The list is a zero-based array of strings and may be empty.
session.UnoProperties(unoobject: uno): str[0..*]
unoobject: The object to inspect.
Dim svc As Variant
svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
MsgBox SF_Array.Contains(session.UnoProperties(svc), "Wildcards") ' True
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
Identify the type of a UNO object as a string.
session.UnoObjectType(unoobject: uno): str
unoobject: The object to identify.
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"
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
Get some web content from a URI.
session.WebService(uri: str): str
uri: URI address of the web service.
session.WebService("wiki.documentfoundation.org/api.php?" _
& "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss")
session.WebService(("wiki.documentfoundation.org/api.php?"
"hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss"))
Todas as rotinas ou identificadores do ScriptForge Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.