Sumário

# Serviço SFDocuments.Form

O serviço Form fornece métodos e propriedades para gerenciar formulários em documentos do LibreOffice. Este serviço suporta formulários de documentos Base, Calc e Writer e permite:

- Abrir e ativar formulários.

- Navegar pelos registros mostrados no formulário.

- Acessar os controles do formulário.

- Acessar os subformulários de um formulário pai.

O serviço SFDocuments.Form está disponível a partir do LibreOffice 7.2.

Formulários são geralmente usados em documentos do LibreOffice para criar interfaces de usuário conectadas a bancos de dados relacionais. Assim, o serviço Form fornece acesso rápido à base de dados associada através do serviço SFDatabases.Database.

O serviço SFDocuments.Form está intimamente relacionado com o serviço SFDocuments.FormControl.

## Definições

### FormDocument

Formulários são geralmente criados em documentos Base, mas também podem ser adicionados a documentos Writer e Calc.

No Base, cada formulário criado com a funcionalidade Inserir - Formulário ou através do Assistente de Formulários é na verdade um FormDocument (documento de formulário) que pode ser manuseado com o serviço Form. Documentos Base podem conter uma quantidade ilimitada de documentos de formulário.

Abaixo é dado um exemplo ilustrando a hierarquia de todos os elementos envolvidos ao acessar formulários e subformulários em um documento Base. Imagine que você tem um arquivo Base com o nome Employees.odb e dentro dele você criou um documento de formulário para adicionar novos funcionários ao banco de dados. O documento de formulário contém um formulário principal com o nome EmployeeData que dá acesso à tabela. Há também um subformulário WorksAtPlant que permite associar o novo empregado a uma das instalações da empresa.

        Employees.odb (documento Base)
         |
         |-- AddEmployee (FormDocument)
              |
              |-- EmployeeData (Formulário principal)
                   |
                   |-- WorksAtPlant (SubForm)

Um FormDocument pode ser visto como um conjunto de formulários que dão acesso a conjuntos de dados (datasets) como as tabelas do banco de dados ou consultas a partir de um documento LibreOffice. Os nomes dos formulários e subformulários em um FormDocument pode ser acessados usando o Navegador de formulários.

### Formulários e subformulários

Um documento de formulário é composto por um ou mais formulários que, por sua vez, podem também conter um número qualquer de subformulários. Um formulário é um conjunto abstrato de controles que estão ligados a uma fonte de dados, a qual pode ser uma tabela de um banco de dados, uma consulta ou uma instrução SELECT do SQL.

Em documentos Calc e Writer, cada formulário pode estar ligado a conjuntos de dados localizados em diferentes bancos de dados. Por outro lado, em documentos Base o banco de dados contudo no documento é comum a todos os formulários.

Para invocar o serviço SFDocuments.Form utilize os métodos Forms(), FormDocuments() e OpenFormDocument() do serviço SFDocuments.Document.

## Invocação do serviço

Antes de usar o serviço Form 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 documentos do Writer

O trecho de código abaixo mostra como acessar o formulário chamado Form1 que está em um arquivo do Writer.

          Dim oDoc As Object, myForm As Object, ui as Object
          Set ui = CreateScriptService("UI")
          Set oDoc = ui.OpenDocument("/home/user/Documents/MyForm.odt")
          Set myForm = oDoc.Forms("Form1")

##### Em Python

         from scriptforge import CreateScriptService
         ui = CreateScriptService('UI')
         doc = ui.OpenDocument('/home/user/Documents/MyForm.odt')
         my_form = doc.Forms('Form1')

Formulários podem ser acessado por seus nomes ou por seus índices, conforme mostrado abaixo:

         Set myForm = oDoc.Forms(0)

##### Em Python

         my_form = doc.Forms(0)

Se você tentar acessar um FormDocument que estiver atualmente aberto no Modo de Edição uma exceção será lançada.

### Em documentos do Calc

Um formulário em um arquivo Calc deve ter um nome único dentro de uma mesma planilha. Assim, o método Forms necessita de dois argumentos, o primeiro indicando o nome da planilha e o segundo especificando o nome do formulário.

          Dim oDoc As Object, myForm As Object, ui as Object
          Set ui = CreateScriptService("UI")
          Set oDoc = ui.OpenDocument("/home/user/Documents/MyForms.ods")
          Set myForm = oDoc.Forms("Sheet1", "Form1")

Isso é realizado de forma idêntica em Python:

         ui = CreateScriptService('UI')
         doc = ui.OpenDocument('/home/user/Documents/MyForms.ods')
         my_form = doc.Forms('Sheet1', 'Form1')

### Em documentos do Base

Um FormDocument dentro de um documento Base é acessado por seu nome. O exemplo a seguir abre o documento de formulário thisFormDocument e acessa o formulário MainForm:

          Dim oDb As Object, myForm As Object
          Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
          ' A instrução abaixo é necessária somente se o formulário ainda não tiver sido aberto
          oDb.OpenFormDocument("thisFormDocument")
          Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
          ' Alternativamente é possível acessar o formulário por seu índice
          Set myForm = oDb.Forms("thisFormDocument", 0)

Para realizar qualquer ação em um formulário usando o serviço Form, o FormDocument deve ter sido aberto manualmente pelo usuário ou usando linguagem de programação em um script. A segunda opção pode ser usada ao chamar o método OpenFormDocument do serviço Base.

Para acessar um dado subformulário de um formulário, use o método SubForms. Note que no exemplo abaixo mySubForm é uma nova instância do serviço Form.

         Dim mySubForm As Object
         Set mySubForm = myForm.SubForms("mySubForm")

Os exemplos anteriores pode ser traduzidos para Python da seguinte forma:

         db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
         # A instrução abaixo é necessária somente se o formulário não tiver sido aberto ainda
         form_doc = db.OpenFormDocument('thisFormDocument')
         form = form_doc.Forms('thisFormDocument', 'MainForm')
         # Ou alternativamente, para acessar o formulário usando seu índice...
         form = form_doc.Forms('thisFormDocument', 0)
         sub_form = form.SubForms('mySubForm')

### Em eventos de formulário

Para invocar o serviço Form quando um evento de formulário ocorrer:

          Sub OnEvent(ByRef poEvent As Object)
              Dim myForm As Object
              Set myForm = CreateScriptService("SFDocuments.FormEvent", poEvent)
              '(...)
          End sub

##### Em Python

         def OnEvent(event: uno):
             form = CreateScriptService('SFDocuments.FormEvent', event)
             pass

O serviço FormEvent é usado exclusivamente para criar instâncias dos serviços SFDocuments.Form e SFDocuments.FormControl quando um evento de formulário ou controle ocorrer.

É recomendável liberar os recursos após o uso do serviço Form.

         myForm.Dispose() ' Basic

         form.Dispose()  # Python

Esta operação é feita implicitamente quando um documento de formulário é fechado com o método CloseFormDocument() descrito abaixo.

## Propriedades

Nome | Somente leitura | Tipo | Descrição
--- | --- | --- | ---
AllowDeletes | Não | Boolean | Especifica se o formulário permite que registros sejam apagados.
AllowInserts | Não | Boolean | Especifica se o formulário permite que registros sejam adicionados.
AllowUpdates | Não | Boolean | Especifica se o formulário permite que registros sejam atualizados.
BaseForm | Sim | String | Especifica o nome hierárquico do formulário Base contido no documento atual.
Bookmark | Não | Variant | Especifica de forma única o registro atual da tabela associada ao formulário, consulta ou instrução SQL.
CurrentRecord | Não | Long | Identifica o registro atual no banco de dados sendo apresentado no formulário. Se o número da linha for positivo, o cursor se move para a linha especificada com relação ao início do conjunto de resultado. A contagem de linhas se inicia em 1. Se o número de linha for negativo, o cursor se move para uma posição de linha absoluta com relação ao final do conjunto de resultado. O valor -1 para a linha refere-se à ultima linha no conjunto de resultado.
Filter | Não | String | Especifica um subconjunto de registros a serem apresentados como uma cláusula SQL WHERE sem a palavra chave WHERE.
LinkChildFields | Sim | String | Especifica como os registros em um subformulário filho serão ligados aos registros de seu formulário pai.
LinkParentFields | Sim | String | Especifica como os registros em um subformulário filho serão ligados aos registros de seu formulário pai.
Name | Sim | String | O nome do formulário atual.
OrderBy | Não | String | Especifica em que ordem os registros devem ser mostrados como uma cláusula SQL ORDER BY sem a palavra chave ORDER BY.
Parent | Sim | Object | Pai do formulário atual. Pode ser um objeto SFDocuments.Form ou um SFDocuments.Document.
RecordSource | Não | String | Especifica a fonte dos dados, como um nome de tabela, um nome de consulta ou uma instrução SQL.
XForm | Sim | Objeto UNO | Objeto UNO representando interações com o formulário. Consulte a documentação API de XForm e DataForm para maiores detalhes.

## Propriedades de evento

As propriedades abaixo retornam ou definem strings URI que definem os scripts a serem acionados pelo evento.

Nome | Somente leitura | Descrição na IDE do Basic
--- | --- | ---
OnApproveCursorMove | Não | Antes da alteração do registro
OnApproveParameter | Não | Parâmetros de preenchimento
OnApproveReset | Não | Antes de redefinir
OnApproveRowChange | Não | Antes de gravar ação
OnApproveSubmit | Não | Antes de enviar
OnConfirmDelete | Não | Confirmar exclusão
OnCursorMoved | Não | Após alteração do registro
OnErrorOccurred | Não | Ocorreu um erro
OnLoaded | Não | Ao carregar
OnReloaded | Não | Ao recarregar
OnReloading | Não | Antes de recarregar
OnResetted | Não | Após redefinir
OnRowChanged | Não | Após gravar ação
OnUnloaded | Não | Ao descarregar
OnUnloading | Não | Antes de descarregar

Para aprender mais sobre Strings URI leia a página Scripting Framework URI Specification.

Lista de Métodos no Serviço Form
Activate Controls GetDatabase MoveFirst | MoveLast MoveNext MoveNew | MovePrevious Requery SubForms

## Activate

Coloca o foco na instância Form atual. Retorna True se a focalização foi bem-sucedida.

O comportamento do método Activate depende do tipo de documento onde o formulário está localizado:

- Em documentos Writer: Coloca o foco no documento.

- Em documentos Calc: Coloca o foco na planilha à qual o formulário pertence.

- Em documentos Base: Coloca o foco no FormDocument ao qual a instância do serviço Form se refere.

### Sintaxe:

svc.Activate(): bool

### Exemplo:

Os exemplos a seguir assume que você deseja ativar o formulário com nome FormA localizado na planilha Sheet1 do documento Calc atualmente aberto. Primeiramente é obtido acesso ao documento usando o serviço Document e ThisComponent e após isso o formulário é ativado.

         'Obtém acesso ao formulário que se deseja ativar
         Dim oDoc as Object, myForm as Object
         Set oDoc = CreateScriptService("Document", ThisComponent)
         Set myForm = oDoc.Forms("Sheet1", "FormA")
         'Ativa o formulário
         myForm.Activate()

##### Em Python

         doc = CreateScriptService('Document', XSCRIPTCONTEXT.getDocument())
         form = doc.Forms('Sheet1', 'FormA')
         form.Activate()

ThisComponent se aplica a documentos Calc e Writer. Em documentos Base use ThisDataBaseDocument.

## CloseFormDocument

Esse método está obsoleto; em vez disso, use o método ScriptForge.FormDocument.CloseDocument.

Fecha o documento de formulário contendo a instância Form atual. A instância Form é descartada.

### Sintaxe:

svc.CloseFormDocument(): bool

### Exemplo:

          myForm.CloseFormDocument() ' Basic

##### Em Python

          form.CloseFormDocument()  # Python

## Controls

O valor retornado pelo método Controls depende dos argumentos fornecidos:

- Se o método for chamado sem argumentos, ele retornará a lista dos controles contidos no formulário. Esteja ciente de que a lista retornada não contém nenhum controle de subformulário.

- Se o argumento opcional ControlName for fornecido, o método retornará uma instância da classe FormControl representando o controle especificado.

### Sintaxe:

svc.Controls(opt controlname: str): any

### Parâmetros:

controlname: String sensível à caixa com o nome válido de um controle. Se não for especificado, a lista de nomes de controles é retornada em um Array indexado em zero.

### Exemplo:

          Dim myForm As Object, myList As Variant, myControl As Object
          Set myForm = myDoc.Forms("myForm")
          myList = myform.Controls()
          Set myControl = myform.Controls("myTextBox") ' SFDocuments.FormControl

##### Em Python

          form = doc.Forms('myForm')
          form_names = form.Controls()
          form_control = form.Controls('myTextBox')  # SFDocuments.FormControl

## GetDatabase

Retorna uma instância do serviço SFDatabases.Database permitindo a execução de comandos SQL no banco de dados que o formulário atual está conectado e/ou está armazenado no documento Base atual.

Cada formulário tem sua própria conexão de banco de dados, exceto documentos Base onde todos compartilham a mesma conexão.

### Sintaxe:

svc.GetDatabase(opt user: str, opt password: str): svc

### Parâmetros:

user, password: Parâmetros opcionais de login (Padrão = "").

### Exemplo:

          Dim myDb As Object ' SFDatabases.Database
          Set myDb = oForm.GetDatabase()

##### Em Python

          db = form.GetDatabase()  # SFDatabases.Database

## MoveFirst

O cursor do formulário é posicionado no primeiro registro. Retorna True se for bem-sucedido.

### Sintaxe:

svc.MoveFirst(): bool

### Exemplo:

          myForm.MoveFirst() ' Basic

##### Em Python

          form.MoveFirst()  # Python

## MoveLast

Posiciona o cursor do formulário no último registro. RetornaTrue se for bem-sucedido.

### Sintaxe:

svc.MoveLast(): bool

### Exemplo:

          myForm.MoveLast() ' Basic

##### Em Python

          form.MoveLast()  # Python

## MoveNew

Posiciona o cursor do formulário na área do novo registro. RetornaTrue se for bem sucedido.

### Sintaxe:

svc.MoveNew(): bool

### Exemplo:

          myForm.MoveNew() ' Basic

##### Em Python

          form.MoveNew()  # Python

## MoveNext

Posiciona o cursor do formulário no próximo registro. RetornaTrue se for bem-sucedido.

### Sintaxe:

svc.MoveNext(opt offset: int): bool

### Parâmetros:

offset: Quantidade de registros para avançar (Padrão = 1).

### Exemplo:

          myForm.MoveNext() ' Basic

##### Em Python

          form.MoveNext()  # Python

## MovePrevious

Posiciona o cursor do formulário no registro anterior. Retorna True se for bem-sucedido.

### Sintaxe:

svc.MovePrevious(opt offset: int): bool

### Parâmetros:

offset: Quantidade de registros a retroceder (Padrão = 1).

### Exemplo:

          myForm.MovePrevious() ' Basic

          form.MovePrevious()  # Python

## Requery

Recarrega os dados atuais do banco de dados e atualiza o formulário. O cursor é posicionado no primeiro registro. Retorna True se for bem sucedido.

### Sintaxe:

svc.Requery(): bool

### Exemplo:

          myForm.Requery() ' Basic

##### Em Python

          form.Requery()  # Python

## Subforms

O valor retornado pelo método Subforms depende dos argumentos fornecidos:

- Se o método for chamado sem argumentos, então será retornada a lista de subformulários contidos na instância de formulário ou subformulário atual.

- Se o argumento opcional subform for fornecido, o método retornará uma nova instância do serviço SFDocuments.Form baseado no nome de formulário/subformulário ou índice especificado.

### Sintaxe:

svc.Subforms(): str[0..*]

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

### Parâmetros:

subform : Um subformulário armazenado na instância da classe atual Form fornecida por seu nome ou índice.

Quando esse argumento está ausente, o método retorna uma lista de subformulários disponíveis como uma matriz baseada em zero. Se o formulário tiver um único subformulário, você pode definir subform = 0 para obter acesso a ele.

### Exemplo:

          Dim myForm As Object, myList As Variant, mySubform As Object
          myList = myform.Subforms()
          Set mySubform = myForm.Subforms("mySubform") ' SFDocuments.Form

##### Em Python

          subform_names = form.Subforms()
         subform = form.Subforms('mySubform')  # SFDocuments.Form

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.

Tópicos relacionados

Serviço SFDatabases.Database

Serviço SFDocuments.Document

Serviço ScriptForge.UI

♥ Doe para nosso projeto! ♥