Ajuda do LibreOffice 24.8
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:
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.
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.
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".
Antes de usar o serviço UI a biblioteca ScriptForge precisa ser carregada ou importada:
    Dim ui As Variant
    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Set ui = CreateScriptService("UI")
  
    from scriptforge import CreateScriptService
    ui = CreateScriptService("UI")
  | 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. | 
| 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 | 
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)
   | Lista de Métodos no Serviço UI | ||
|---|---|---|
| 
           Activate | ||
Note que, como exceção, os métodos marcados com (*) não são aplicáveis aos documentos Base.
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")
    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.
svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc
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.
      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")
   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).
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"))
   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.
svc.Documents(): str[1..*]
Nos dois exemplos abaixo, o método pode retornar uma matriz vazia se não houver documentos abertos.
      Dim docList As Variant
      docList = ui.Documents
   
     docList = ui.Documents()
   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.
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.
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")
   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()
   Abre um documento base LibreOffice existente. O método retorna um objeto Base.
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: 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.
      Dim myBase As Object
      Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)
   
     myBase = 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.
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.
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: 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.
      Dim myDoc As Object, FSO As Object
      Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)
   
     myDoc = ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)
   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(Width := 500, Height := 500)
   
     ui.Resize(width = 500, height = 500)
   Para redimensionar uma janela que não está ativa, primeiro ative-a usando o método Activate.
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 LibreOffice, 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 .
    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 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.
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()
   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: int = -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()
   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"):
         # ...