Serviço ScriptForge.UI

O serviço UI (do inglês, User Interface - Interface de Usuário) simplifica a identificação e manipulação das diferentes janelas que compõem toda a aplicação do Collabora Office:

• Seleção de janelas

• Redimensionamento e movimentação de janelas

• Ajustes da barra de status

• Apresentação de uma barra de progresso flutuante

• Criação de novas janelas

• Acesso aos documentos

O serviço UI é o ponto de partida para abrir, criar ou acessar os conteúdos de documentos novos ou existentes usando um script de usuário.

Definições

WindowName

Uma janela pode ser designada usando vários métodos:

• um caminho completo e um nome de arquivo

• o último componente do nome completo do arquivo ou apenas o último componente sem o sufixo

• o título da janela

• para novos documentos, alguma coisa como "Sem título 1"

• uma das janelas especiais "BASICIDE" e "WELCOMESCREEN"

O nome das janelas é sensível ao caso.

Objeto Document

Os métodos CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument e OpenDocument, descritos abaixo, geram objetos de documento. Quando uma janela contém um documento, uma instância do serviço Document representa o documento. Como um contraexemplo, a janela da IDE do Basic não é um documento, mas é uma janela em nossa terminologia. Adicionalmente um documento possui um tipo: Calc, Impress, Writer, ...

As propriedades e métodos específicos aplicáveis aos documentos são implementadas em uma classe de documento.

A implementação dos objetos de documentos é feita na biblioteca associada SFDocuments. Veja seu serviço "Document".

Invocação do serviço

Antes de usar o serviço UI a biblioteca ScriptForge precisa 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

Dim ui As Variant
GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
Set ui = CreateScriptService("UI")

from scriptforge import CreateScriptService
ui = CreateScriptService("UI")

Propriedades

Constantes

Os exemplos abaixo mostram uma MsgBox com os nomes de todos os documentos atualmente abertos.

Dim openDocs as Object, strDocs as String
Set openDocs = ui.Documents()
strDocs = openDocs(0)
For i = 1 to UBound(openDocs)
    strDocs = strDocs & Chr(10) & openDocs(i)
Next i
MsgBox strDocs

ui = CreateScriptService("UI")
bas = CreateScriptService("Basic")
openDocs = ui.Documents()
strDocs = "\n".join(openDocs)
bas.MsgBox(strDocs)

Note que, como exceção, os métodos marcados com (*) não são aplicáveis aos documentos Base.

Activate

Torna ativa uma janela específica. O método retorna True se a janela é encontrada e pode ser ativada. Não há mudança no estado corrente da interface do usuário se nenhuma janela corresponde à seleção.

svc.Activate(windowname: str): bool

windowname: Veja as definições apresentadas acima.

ui.Activate("C:\Documents\My file.odt")

ui.Activate(r"C:\Documents\My file.odt")

CreateBaseDocument

Cria e armazena um novo documento Collabora Office Base com um banco de dados vazio de um tipo especificado. O método retorna uma instância do serviço Document.

svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc

filename: Identifica o arquivo a ser criado. Deve seguir a notação SF_FileSystem.FileNaming. Se o arquivo já existe, ele será sobrescrito sem aviso prévio.

embeddeddatabase: Pode ser "HSQLDB" (padrão), "FIREBIRD" ou "CALC".

registrationname: Nome usado para armazenar a nova base de dados no registro de bancos de dados. Quando for igual a "" nenhum registro será feito. Se o nome já existe, ele será sobrescrito sem aviso prévio.

calcfilename: Quando embeddeddatabase = "CALC", o argumento calcfilename representa o arquivo contendo as tabelas representadas por planilhas Calc. O arquivo deve existir, caso contrário um erro será lançado.

Dim myBase As Object, myCalcBase As Object
Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")
Set myCalcBase = ui.CreateBaseDocument("C:\Databases\MyCalcBaseFile.odb", _
    "CALC", , "C:\Databases\MyCalcFile.ods")

myBase = ui.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
myCalcBase = ui.CreateBaseDocument(r"C:\Databases\MyCalcBaseFile.odb", \
    "CALC", calcfilename = r"C:\Databases\MyCalcFile.ods")

CreateDocument (*)

Cria um novo documento Collabora Office de um determinado tipo ou baseado em algum template. O método retorna um objeto de documento.

svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc

documenttype : "Calc", "Writer", etc. Se ausente, o argumento templatefile deve estar presente.

templatefile: O nome completo do arquivo (FileName) do template a ser usado na construção do novo documento. Se o arquivo não existir, o argumento é ignorado. O serviço FileSystem fornece o caminho para a pasta de templates (TemplatesFolder e UserTemplatesFolder) que podem ajudar na preparação deste argumento.

hidden: Se True, abre o novo documento no plano de fundo (padrão = False). Use com cuidado, pois a ativação ou fechamento posterior só pode ser feita por meio de programação.

Em ambos os exemplos abaixo, a primeira chamada do método CreateDocument cria um documento Calc em branco, enquanto que a segunda chamada cria um documento usando um arquivo de modelo.

Dim myDoc1 As Object, myDoc2 As Object, FSO As Object
Set myDoc1 = ui.CreateDocument("Calc")
Set FSO = CreateScriptService("FileSystem")
Set myDoc2 = ui.CreateDocument(, FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))

myDoc1 = ui.CreateDocument("Calc")
fs = CreateScriptService("FileSystem")
myDoc2 = ui.CreateDocument(templatefile = fs.BuildPath(fs.TemplatesFolder, "personal/CV.ott"))

GetDocument

Retorna um objeto de um documento aberto, o qual se refere ou à janela ativa, um nome específico de janela ou ao documento ativo.

svc.GetDocument(windowname: str = ''): svc

svc.GetDocument(windowname: uno): svc

windowname: Veja as definições acima. Se este argumento não estiver presente, a janela ativa é usada. Objetos UNO dos tipos com.sun.star.lang.XComponent or com.sun.star.comp.dba.ODatabaseDocument também são aceitos. Portanto, passar ThisComponent ou ThisDatabaseDocument como argumentos resulta na criação de um novo serviço SFDocuments.Document, Base ou Calc.

Dim myDoc As Object
Set myDoc = ui.GetDocument("C:\Documents\My file.odt")
Set myBase = ui.GetDocument(ThisDatabaseDocument)

from scriptforge import CreateScriptService
bas = CreateScriptService("Basic")
myDoc = ui.GetDocument(r"C:\Documents\My file.odt")
myDoc = ui.GetDocument(bas.ThisComponent)

Para acessar o nome da janela atualmente ativa, consulte a propriedade ActiveWindow.

Maximize

Maximiza a janela ativa ou uma janela determinada.

svc.Maximize(windowname: str)

windowname: Veja as definições acima. Se este argumento estiver ausente a janela ativa é maximizada.

ui.Maximize("Untitled 1")

ui.Maximize("Untitled 1")

Minimize

Minimiza a janela ativa ou uma janela determinada.

svc.Minimize(windowname: str)

windowname: Veja as definições acima. Se este argumento estiver ausente a janela ativa é minimizada.

ui.Minimize()

ui.Minimize()

OpenBaseDocument

Abre um documento Collabora Office Base existente. O método retorna um objeto de documento.

svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc

filename: Identifica o arquivo a ser aberto. Deve seguir a notação SF_FileSystem.FileNaming.

RegistrationName : Nome a ser usado para encontrar o banco de dados no registro de bancos de dados. É ignorado se FileName for diferente de "".

macroexecution: Se igual a 0 então o comportamento é definido pelas configurações de usuário. Se for igual a 1, macros não são executáveis. Se for igual a 2, macros são executáveis.

Dim myBase As Object
Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)

ui.OpenBaseDocument(r"C:\Documents\myDB.odb", macroexecution = ui.MACROEXECALWAYS)

Para melhorar a legibilidade do código você pode usar constantes predefinidas para o argumento macroexecution, como nos exemplos acima.

OpenDocument (*)

Abre um documento Collabora Office com as opções dadas. Retorna um objeto de documento ou uma de suas subclasses. O método retorna Nothing (em BASIC) ou None (em Python) se a abertura falhar, mesmo quando a falha for causada por uma decisão do usuário.

svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc

filename: Identifica o nome do arquivo a ser aberto. Deve seguir a notação FileNaming do serviço FileSystem.

password: Senha a ser usada quando o documento for protegido. Se a senha for incorreta ou inexistente, o usuário será solicitado a informar a senha do documento.

readonly: Somente Leitura. Padrão = False.

hidden: Se True, abre o novo documento no plano de fundo (padrão = False). Use com cuidado, pois a ativação ou fechamento posterior só pode ser feita por meio de programação.

macroexecution: Se igual a 0 então o comportamento é definido pelas configurações de usuário. Se for igual a 1, macros não são executáveis. Se for igual a 2, macros são executáveis.

filtername: Nome do filtro que deve ser usado para carregar o documento. Se este argumento for passado, então o filtro deve existir.

filteroptions: String opcional com as opções associadas ao filtro.

Dim myDoc As Object, FSO As Object
Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)

ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)

Resize

Redimensiona ou move a janela ativa. Valores negativos ou não informados são ignorados. Se a janela estiver minimizada ou maximizada, a chamada do método Resize sem argumentos restaurará a janela.

svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)

left, top: Distâncias do canto superior esquerdo com relação às bordas superior e esquerda da tela, em pixels.

width, height: Novas dimensões da janela, em pixels.

Nos exemplos a seguir, os valores width e height da janela são modificados e os valores top e left são mantidos.

ui.Resize(, ,500, 500)

ui.Resize(width = 500, height = 500)

Para redimensionar uma janela que não está ativa, primeiro ative-a usando o método Activate.

RunCommand

Executa um comando UNO na janela atual. Alguns comandos típicos são: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.

Comandos podem ser executados com ou sem argumentos. Argumentos não são validados antes de executar o comando. Se o comando ou seus argumentos forem inválidos, então nada acontecerá.

Para uma lista completa de comandos UNO que podem ser executadas no Collabora Office, consulte a página Wiki Development/DispatchCommands.

svc.RunCommand(command: str, [args: any])

command: String sensível à caixa contendo o nome do comando UNO. A inclusão do prefixo ".uno" ao comando é opcional. O comando em si não é verificado. Se nada acontecer após a chamada do comando, então o comando está provavelmente errado.

args: Para cada argumento a ser passado ao comando, especifique um par contendo o nome do argumento e seu valor.

O seguinte exemplo executa o comando .uno:About na janela atual.

Set ui = CreateScriptService("UI")
ui.RunCommand("About")

Abaixo é dado um exemplo que executa o comando UNO .uno:BasicIDEAppear e passa os argumentos necessários para abrir a IDE do Basic em uma linha específica de um módulo.

' Argumentos passados ao comando:
' Document  = "LibreOffice Macros & Dialogs"
' LibName = "ScriptForge"
' Name = "SF_Session"
' Line = 600
ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", _
              "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)

Note que executar o comando BasicIDEAppear sem argumentos simplesmente abrirá a IDE do Basic.

ui = CreateScriptService("UI")
ui.RunCommand("About")

ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", \
              "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)

Em Python também é possível chamar RunCommand usando argumentos de palavra-chave:

ui.RunCommand(".uno:BasicIDEAppear", Document = "LibreOffice Macros & Dialogs", \
              LibName = "ScriptForge", Name = "SF_Session", Line = 600)

Cada módulo do Collabora Office tem seu próprio conjunto de comandos disponíveis. Uma forma fácil de aprender comandos é indo em Ferramentas - Personalizar - Teclado. Quando você posicionar o mouse sobre uma função na lista Função, uma caixa de dica será apresentada com o comando UNO correspondente.

SetStatusbar (*)

Mostra um texto e uma barra de progresso na barra de status da janela ativa. Quaisquer chamadas subsequentes na mesma macro referem-se à mesma barra de status na mesma janela, mesmo se a janela não estiver mais visível. Uma chamada sem argumentos restaura a barra de status ao seu estado normal.

svc.SetStatusbar(text: str = '', percentage: int = -1)

text: Um texto opcional a ser mostrado na frente da barra de progresso.

percentage: Um valor opcional referente ao progresso a ser mostrado, entre 0 e 100.

Dim i As Integer
For i = 0 To 100
    ui.SetStatusbar("Progress ...", i)
    Wait 50
Next i
' Redefine a barra de status
ui.SetStatusbar

from time import sleep
for i in range(101):
    ui.SetStatusbar("Test:", i)
    sleep(0.05)
ui.SetStatusbar()

ShowProgressBar

Mostra uma caixa de diálogo não modal. Especifica seu título, um texto explicativo e uma porcentagem de progresso a ser informada na barra de progresso. A caixa de diálogo permanece visível até uma chamada do método sem argumentos ou até que o usuário feche-a manualmente.

svc.ShowProgressBar(title: str = '', text: str = '', percentage: str = -1)

title: Título a ser apresentado no topo da caixa de diálogo. Padrão = "ScriptForge".

text: Texto opcional a ser apresentado acima da barra de progresso.

porcentagem: um grau opcional de progresso entre 0 e 100.

Dim i As Integer
For i = 0 To 100
    ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
    Wait 50
Next i
' Fecha a janela com a barra de progresso
ui.ShowProgressBar

from time import sleep
for i in range(101):
    ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
    sleep(0.05)
# Fecha a janela com a barra de progresso
ui.ShowProgressBar()

WindowExists

Retorna True se a janela especificada pode ser identificada.

svc.WindowExists(windowname: str): bool

windowname: Veja as definições apresentadas acima.

If ui.WindowExists("C:\Document\My file.odt") Then
    ' ...

if ui.WindowExists(r"C:\Document\My file.odt"):
    # ...