Sumário

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

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

## Definições

### WindowName

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.

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

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:

• 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

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)

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)

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)

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

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)

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

Exibe uma caixa de diálogo não modal. Especifique seu título, um balão de diálogo 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"):
             # ...

Tópicos relacionados

Serviço ScriptForge.Basic

Serviço SFDocuments.Calc

Serviço SFDocuments.Document

♥ Doe para nosso projeto! ♥