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 e OpenDocument, descritos abaixo, geram objetos do tipo Document. Quando uma janela contém um documento, uma instância da classe Document é utilizada para representar o documento. Como um contra-exemplo, a janela IDE do Basic não é um documento, mas é uma janela nessa terminologia. Além disso, 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 blblioteca associada SFDocuments. Veja seu serviço "Document".


Invocação do serviço

Em Basic

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

    from scriptforge import CreateScriptService
    svcUI = 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

     svcUI = CreateScriptService("UI")
     sBasic = CreateScriptService("Basic")
     openDocs = svcUI.Documents()
     strDocs = "\n".join(openDocs)
     sBasic.MsgBox(strDocs)
   

Lista de Métodos no Serviço UI

Activate
CreateBaseDocument
CreateDocument (*)
GetDocument

Maximize
Minimize
OpenBaseDocument
OpenDocument (*)

Resize
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

      svcUI.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 = ''): 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) ou "FIREBIRD".

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.

Exemplo:

Em Basic

      Dim myBase As Object
      Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")
   
Em Python

     myBase = svcUI.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
   

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 = svcUI.CreateDocument("Calc")
     FSO = CreateScriptService("FileSystem")
     myDoc2 = svcUI.CreateDocument(templatefile = FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))
   

GetDocument

Retorna um objeto de documento que refere-se à janela ativa ou a uma janela determinada.

Sintaxe:

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

Parâmetros:

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

Exemplo:

Em Basic

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

     myDoc = svcUI.GetDocument(r"C:\Documents\My file.odt")
   
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

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

     svcUI.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 : Identifica o arquivo a ser aberto. Deve seguir a notação SF_FileSystem.FileNaming. Se o arquivo já existe, ele será sobrescrito sem um aviso.

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

     svcUI.OpenBaseDocument(r"C:\Documents\myDB.odb", macroexecution = svcUI.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

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

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

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


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):
         svcUI.SetStatusbar("Test:", i)
         sleep(0.05)
     svcUI.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):
         svcUI.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
         sleep(0.05)
     # Fecha a janela com a barra de progresso
     svcUI.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 svcUI.WindowExists(r"C:\Document\My file.odt"):
         # ...
   

♥ Doe para nosso projeto! ♥