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

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

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
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.


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 LibreOfficeDev 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 LibreOfficeDev 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 LibreOfficeDev 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 LibreOfficeDev 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 LibreOfficeDev, 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 LibreOfficeDev 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"):
         # ...