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

tip

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:

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.

tip

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:

note

• 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

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

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

Propriedades

Nome

Somente leitura

Tipo

Descrição

ActiveWindow

Sim

String

Um nome de janela "WindowName" único e válido para a janela atualmente ativa. Quando a janela não puder ser identificada, uma string de comprimento zero é retornada.

Height

Sim

Integer

Retorna a altura da janela ativa, em pixels.

Width

Sim

Integer

Retorna a largura da janela ativa, em pixels.

X

Sim

Integer

Retorna a coordenada X da janela ativa, que é a distância para a borda esquerda da tela, em pixels.

Y

Sim

Integer

Retorna a coordenada Y da janela ativa, que é a distância para a borda superior da tela, em pixels. Este valor não considera decorações de janela adicionadas por seu sistema operacional, então mesmo que a janela esteja maximizada este valor pode não ser zero.


Constantes

Nome

Valor

Descrição

MACROEXECALWAYS

2

Macros são sempre executadas

MACROEXECNEVER

1

Macros nunca são executadas

MACROEXECNORMAL

0

A execução de macros depende das configurações do usuário


Exemplo:

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

Em Basic

     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
   
Em Python

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

Lista de Métodos no Serviço UI

Activate
CreateBaseDocument
CreateDocument (*)
Documents
GetDocument

Maximize
Minimize
OpenBaseDocument
OpenDocument (*)
Resize

RunCommand
SetStatusBar (*)
ShowProgressBar
WindowExists


warning

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.

Sintaxe:

svc.Activate(windowname: str): bool

Parâmetros:

windowname: Veja as definições apresentadas acima.

Exemplo:

Em Basic

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

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

CreateBaseDocument

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

Sintaxe:

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

Parâmetros:

Filename : Identifica o arquivo a ser criado. Ele deve seguir a notação SF_FileSystem.FileNaming. Se o arquivo já existir, ele será sobrescrito sem aviso.

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.

Exemplo:

Em Basic

      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")
   
Em Python

     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 LibreOffice de um determinado tipo ou com base em um determinado modelo. O método retorna uma instância da classe documento ou de uma de suas subclasses (Calc, Writer).

Sintaxe:

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

Parâmetros:

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.

Exemplo:

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.

Em Basic

      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"))
   
Em Python

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

Documents

A lista dos documentos abertos no momento. As janelas especiais são ignoradas. Essa lista consiste em uma matriz unidimensional baseada em zero de nomes de arquivos - usando a notação ScriptForge.FileSystem.FileNaming - ou de títulos de janelas para documentos não salvos.

Sintaxe:

svc.Documents(): str[1..*]

Exemplo:

Nos dois exemplos abaixo, o método pode retornar uma matriz vazia se não houver documentos abertos.

Em Basic

      Dim docList As Variant
      docList = ui.Documents
   
Em Python

     docList = ui.Documents()
   

GetDocument

Retorna uma instância da classe Document ou de uma de suas subclasses (Calc, Writer, Base, FormDocument) referente a uma determinada janela ou ao documento ativo.

Sintaxe:

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

svc.GetDocument(windowname: uno): svc

Parâmetros:

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.

Exemplo:

Em Basic

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

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

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


Maximize

Maximiza a janela ativa ou uma janela determinada.

Sintaxe:

svc.Maximize(windowname: str)

Parâmetros:

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

Exemplo:

Em Basic

      ui.Maximize("Untitled 1")
   
Em Python

     ui.Maximize("Untitled 1")
   

Minimize

Minimiza a janela ativa ou uma janela determinada.

Sintaxe:

svc.Minimize(windowname: str)

Parâmetros:

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

Exemplo:

Em Basic

     ui.Minimize()
   
Em Python

     ui.Minimize()
   

OpenBaseDocument

Abre um documento base LibreOffice existente. O método retorna um objeto Base.

Sintaxe:

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

Parâmetros:

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: 0 = comportamento é definido pela configuração do usuário, 1 = macros não são executáveis, 2 = macros são executáveis. O padrão é 0.

Exemplo:

Em Basic

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

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

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


OpenDocument (*)

Abre um documento LibreOffice 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.

Sintaxe:

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

Parâmetros:

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: 0 = comportamento é definido pela configuração do usuário, 1 = macros não são executáveis, 2 = macros são executáveis. O padrão é 0.

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.

Exemplo:

Em Basic

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

     myDoc = 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.

Sintaxe:

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

Parâmetros:

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.

Exemplo:

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

Em Basic

      ui.Resize(Width := 500, Height := 500)
   
Em Python

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

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

tip

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


Sintaxe:

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

Parâmetros:

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.

Exemplo:

Em Basic

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.

Em Python

    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)
  
tip

Cada módulo do LibreOffice 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.

Sintaxe:

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

Parâmetros:

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.

Exemplo:

Em Basic

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

     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.

Sintaxe:

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

Parâmetros:

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.

Exemplo:

Em Basic

      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
   
Em Python

     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.

Sintaxe:

svc.WindowExists(windowname: str): bool

Parâmetros:

windowname: Veja as definições apresentadas acima.

Exemplo:

Em Basic

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

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

♥ Doe para nosso projeto! ♥