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

The methods CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument and OpenDocument, described below, generate document objects. When a window contains a document, an instance of the Document class represents that document. A counterexample the Basic IDE is not a document but is a window in our terminology. Additionally a document has a type: 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

Before using the UI service the ScriptForge library needs to be loaded or imported:

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.

Documents

Sim

String array

Lista de documentos abertos no momento. Janelas especiais são ignoradas. A lista consiste de um array indexado em zero de uma dimensão contendo nomes de arquivos (em notação SF_FileSystem.FileNaming) ou os títulos das janelas no caso de documentos não salvos.

Height

Yes

Integer

Returns the height of the active window in pixels.

Width

Yes

Integer

Returns the width of the active window in pixels.

X

Yes

Integer

Returns the X coordinate of the active window, which is the distance to the left edge of the screen in pixels.

Y

Yes

Integer

Returns the Y coordinate of the active window, which is the distance to the top edge of the screen in pixels. This value does not consider window decorations added by your operating system, so even when the window is maximized this value may not be 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 (*)
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. 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.

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 baseado em algum template. O método retorna um objeto de documento.

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

GetDocument

Returns an open document object referring to either the active window, a given window or the active document.

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 LibreOffice Base existente. O método retorna um objeto de documento.

Sintaxe:

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

Parâmetros:

filename: Identifies the file to open. It must follow the SF_FileSystem.FileNaming notation.

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.

Exemplo:

Em Basic

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

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

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


OpenDocument (*)

Abre um documento LibreOffice existente com as opções especificadas. Retorna um objeto de documento ou uma de suas subclasses. O método retornará Nothing (em Basic) / 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: 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.

Exemplo:

Em Basic

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

     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(, ,500, 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

Runs a UNO command on the current window. A few typical commands are: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.

Commands can be run with or without arguments. Arguments are not validated before running the command. If the command or its arguments are invalid, then nothing will happen.

tip

For a complete list of UNO commands that can be run in LibreOffice, refer to the Wiki page Development/DispatchCommands.


Sintaxe:

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

Parâmetros:

command: Case-sensitive string containing the UNO command name. The inclusion of the prefix ".uno:" in the command is optional. The command itself is not checked for correctness. If nothing happens after the command call, then the command is probably wrong.

args: For each argument to be passed to the command, specify a pair containing the argument name and value.

Exemplo:

Em Basic

The following example runs the .uno:About command in the current window.


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

Below is an example that runs the UNO command .uno:BasicIDEAppear and passes the arguments required to open the Basic IDE at a specific line of a module.


    ' Arguments passed to the command:
    ' 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 that calling the command BasicIDEAppear without arguments will simply open the Basic IDE.

Em Python

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

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

In Python it is also possible to call RunCommand using keyword arguments:


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

Each LibreOffice component has its own set of commands available. One easy way to learn commands is going to Tools - Customize - Keyboard. When you position your mouse over a function in the Function list, a tooltip will appear with the corresponding UNO command.


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: str = -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"):
         # ...