Conteúdo

# SFDocuments.Form serviço

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

- Abrir e ativar formulários.

- Navegue pelos registos apresentados no formulário.

- Obtenha acesso aos controlos dentro do formulário.

- Obter acesso aos subformulários de um formulário principal.

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

Os formulários são normalmente utilizados em documentos LibreOffice para criar interfaces de utilizador ligadas a bases de dados relacionais. Por conseguinte, o serviço Form proporciona 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

Os formulários são normalmente criados em documentos do Base, mas também podem ser adicionados a documentos do Writer e do Calc.

No Base, cada formulário que criar utilizando a funcionalidade Inserir - Formulário ou através do Assistente de Formulários é, na verdade, um FormDocument que pode ser gerido com o serviço Form. Os documentos Base podem conter um número ilimitado de documentos de formulário.

Segue-se um exemplo que ilustra a hierarquia de todos os elementos envolvidos no acesso a formulários e subformulários num documento Base. Suponha que tem um ficheiro Base denominado Employees.odb e que, no seu interior, criou um documento de formulário para adicionar novos funcionários à base de dados. O documento de formulário contém um formulário principal denominado EmployeeData que dá acesso a uma tabela. Existe também um subformulário WorksAtPlant que permite associar o novo colaborador a uma das fábricas da empresa.

        Employees.odb (Documento base)
         |
         |-- AddEmployee (FormDocument)
              |
              |-- Dados do Colaborador (Formulário Principal)
                   |
                   |-- WorksAtPlant (SubForm)

Um FormDocument pode ser considerado como um conjunto de formulários que permitem aceder a conjuntos de dados, tais como tabelas de bases de dados e consultas, a partir de documentos LibreOffice. É possível aceder aos nomes dos formulários e subformulários dentro de um FormDocument utilizando o Form Navigator.

### Formulários e subformulários

Um documento de formulário é composto por um ou mais formulários que, por sua vez, também podem conter um número variável de subformulários. Um formulário é um conjunto abstrato de controlos ligados a uma fonte de dados específica, que pode ser uma tabela de base de dados, uma consulta ou uma instrução SQL SELECT.

Nos documentos do Calc e do Writer, cada formulário pode ser associado a conjuntos de dados localizados em bases de dados diferentes. Por outro lado, nos documentos do Base, a base de dados contida no documento é comum a todos os formulários.

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

## Chamada de serviço

Antes de utilizar o serviço Form, é necessário carregar ou importar a biblioteca ScriptForge:

• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService

### Nos documentos do Writer

O trecho de código abaixo mostra como aceder ao formulário denominado Form1 que se encontra num ficheiro 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')

É possível aceder aos formulários pelos seus nomes ou pelos seus índices, conforme ilustrado abaixo:

         Set myForm = oDoc.Forms(0)

##### Em Python

         my_form = doc.Forms(0)

Se tentar aceder a um FormDocument que esteja atualmente aberto no Modo de Design, será lançada uma exceção.

### Nos documentos do Calc

Um formulário num ficheiro Calc deve ter um nome único dentro da respetiva folha de cálculo. Por conseguinte, o método Forms requer dois argumentos: o primeiro indica o nome da folha de cálculo e o segundo especifica 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")

Isto consegue-se exatamente da mesma forma utilizando Python:

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

### Nos documentos de base

Um FormDocument dentro de um documento Base é acedido pelo seu nome. O exemplo seguinte abre o documento de formulário denominado thisFormDocument e acede ao formulário MainForm:

          Dim oDb As Object, myForm As Object
          Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
          ' A mensagem abaixo só é necessária se o formulário ainda não tiver sido aberto
          oDb.OpenFormDocument("thisFormDocument")
          Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
          ' Ou, em alternativa, para aceder ao formulário através do seu índice...
          Set myForm = oDb.Forms("thisFormDocument", 0)

Para realizar qualquer ação num formulário utilizando o serviço Form, o FormDocument deve ter sido aberto manualmente pelo utilizador ou programaticamente num script do utilizador. Esta última opção pode ser realizada chamando o método OpenFormDocument do serviço Base.

Para aceder a um determinado subformulário de um formulário, utilize o método SubForms. Note-se 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 traduzem-se em Python da seguinte forma:

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

### Eventos no formulário

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

          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 é utilizado exclusivamente para criar instâncias dos serviços SFDocuments.Form e SFDocuments.FormControl quando ocorre um evento de formulário ou de controlo.

Recomenda-se libertar os recursos após a utilização do serviço Form.

         myForm.Dispose() ' Basic

         form.Dispose()  # Python

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

## Características

Nome | Apenas leitura | Tipo | Descrição
--- | --- | --- | ---
AllowDeletes | Não | Boolean | Especifica se o formulário permite eliminar registos.
AllowInserts | Não | Boolean | Especifica se o formulário permite adicionar registos.
AllowUpdates | Não | Boolean | Especifica se o formulário permite atualizar registos.
BaseForm | Sim | String | Especifica o nome hierárquico do formulário base que contém o formulário propriamente dito.
Bookmark | Não | Variant | Especifica de forma única o registo atual da tabela, consulta ou instrução SQL subjacente ao formulário.
CurrentRecord | Não | Long | Identifica o registo atual no conjunto de dados que está a ser visualizado num formulário. Se o número da linha for positivo, o cursor desloca-se para o número de linha indicado, a partir do início do conjunto de resultados. A contagem de linhas começa em 1. Se o número de linha indicado for negativo, o cursor desloca-se para uma posição absoluta da linha, a partir do fim do conjunto de resultados. A linha -1 refere-se à última linha do conjunto de resultados.
Filter | Não | String | Especifica um subconjunto de registos a apresentar como uma cláusula WHERE de SQL, sem a palavra-chave WHERE.
LinkChildFields | Sim | String | Especifica a forma como os registos num subformulário filho estão ligados aos registos do seu formulário pai.
LinkParentFields | Sim | String | Especifica a forma como os registos num subformulário filho estão ligados aos registos do seu formulário pai.
Name | Sim | String | O nome do formulário atual.
OrderBy | Não | String | Especifica a ordem em que os registos devem ser apresentados, como uma cláusula SQL ORDER BY, sem as palavras-chave ORDER BY.
Parent | Sim | Object | O objeto pai do formulário atual. Pode ser um objeto SFDocuments.Form ou um objeto SFDocuments.Document.
RecordSource | Não | String | Especifica a origem dos dados, seja um nome de tabela, um nome de consulta ou uma instrução SQL.
XForm | Sim | UNO objeto | O objeto UNO que representa as interações com o formulário. Consulte XForm e DataForm na documentação da API para obter informações detalhadas.

## Propriedades do evento

As propriedades abaixo devolvem ou definem cadeias de caracteres URI que definem o script acionado pelo evento.

Nome | ReadOnly | Descrição básica do IDE
--- | --- | ---
OnApproveCursorMove | Não | Antes da alteração do registo
OnApproveParameter | Não | Preencher os parâmetros
OnApproveReset | Não | Antes da reinicialização
OnApproveRowChange | Não | Antes da ação recorde
OnApproveSubmit | Não | Antes de enviar
OnConfirmDelete | Não | Confirmar eliminação
OnCursorMoved | Não | Após a alteração do registo
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 a reinicialização
OnRowChanged | Não | Após uma sessão de negociação recorde
OnUnloaded | Não | Ao descarregar
OnUnloading | Não | Antes da descarga

Para saber mais sobre cadeias de caracteres URI, consulte a Especificação de URI do Scripting Framework.

Lista de métodos do serviço Form
Activate Controls GetDatabase MoveFirst | MoveLast MoveNext MoveNew | MovePrevious Requery SubForms

## Activate

Coloca o foco na instância atual de Form. Devolve True se o foco tiver sido estabelecido com sucesso.

O comportamento do método Activate depende do tipo de documento em que o formulário se encontra:

- Nos documentos do Writer: Coloca o foco nesse documento.

- Nos documentos Calc: Coloca o foco na folha à qual o formulário pertence.

- No documentos Base: Coloca o foco no FormDocument a que o Form se refere.

### Sintaxe:

svc.Activate(): bool

### Exemplo:

O exemplo seguinte parte do princípio de que pretende ativar o formulário denominado FormA, localizado na Sheet1 do ficheiro do Calc atualmente aberto. Primeiro, obtém acesso ao documento utilizando o serviço Document e ThisComponent e, em seguida, ativa o formulário.

         'Recupera o formulário que será ativado'
         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 aplica-se a documentos do Calc e do Writer. Para documentos do Base, utilize ThisDataBaseDocument.

## CloseFormDocument

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

Fecha o documento do formulário que contém a instância Form propriamente dita. A instância Form é eliminada.

### Sintaxe:

svc.CloseFormDocument(): bool

### Exemplo:

          myForm.CloseFormDocument() ' Basic

##### Em Python

          form.CloseFormDocument()  # Python

## Controls

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

- Se o método for chamado sem argumentos, devolve a lista dos controlos contidos no formulário. Tenha em atenção que a lista devolvida não contém quaisquer controlos de subformulários.

- Se for fornecido o argumento opcional ControlName, o método devolve uma instância da classe FormControl que se refere ao controlo especificado.

### Sintaxe:

svc.Controls(opt controlname: str): any

### Parâmetros:

controlname : Um nome de controlo válido, expresso como uma cadeia de caracteres que distingue maiúsculas de minúsculas. Se não for especificado, a lista de nomes de controlos é devolvida como um array com índice a partir de 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

Devolve uma instância SFDatabases.Database que permite a execução de comandos SQL na base de dados à qual o formulário atual está ligado e/ou que está armazenada no documento Base atual.

Cada formulário tem a sua própria ligação à base de dados, exceto nos documentos Base, em que todos partilham a mesma ligação.

### Sintaxe:

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

### Parâmetros:

utilizador, palavra-passe: Os parâmetros opcionais de início de sessão (predefiniçã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 está posicionado no primeiro registo. Devolve True se a operação for bem-sucedida.

### Sintaxe:

svc.MoveFirst(): bool

### Exemplo:

          myForm.MoveFirst() ' Basic

##### Em Python

          form.MoveFirst()  # Python

## MoveLast

O cursor do formulário está posicionado no último registo. Devolve True se a operação for bem-sucedida.

### Sintaxe:

svc.MoveLast(): bool

### Exemplo:

          myForm.MoveLast() ' Basic

##### Em Python

          form.MoveLast()  # Python

## MoveNew

O cursor do formulário é posicionado na área do novo registo. Devolve True se a operação for bem-sucedida.

### Sintaxe:

svc.MoveNew(): bool

### Exemplo:

          myForm.MoveNew() ' Basic

##### Em Python

          form.MoveNew()  # Python

## MoveNext

O cursor do formulário é posicionado no registo seguinte. Devolve True se a operação for bem-sucedida.

### Sintaxe:

svc.MoveNext(opt offset: int): bool

### Parâmetros:

offset: O número de registos a avançar (Predefinição = 1).

### Exemplo:

          myForm.MoveNext() ' Basic

##### Em Python

          form.MoveNext()  # Python

## MovePrevious

O cursor do formulário é posicionado no registo anterior. Devolve True se a operação for bem-sucedida.

### Sintaxe:

svc.MovePrevious(opt offset: int): bool

### Parâmetros:

offset: O número de registos a recuar (Predefinição = 1).

### Exemplo:

          myForm.MovePrevious() ' Basic

          form.MovePrevious()  # Python

## Requery

Recarrega os dados atuais da base de dados e atualiza o formulário. O cursor é posicionado no primeiro registo. Devolve True se a operação for bem-sucedida.

### Sintaxe:

svc.Requery(): bool

### Exemplo:

          myForm.Requery() ' Basic

##### Em Python

          form.Requery()  # Python

## Subforms

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

- Se o método for chamado sem quaisquer argumentos, devolve a lista de subformulários contidos no formulário atual ou na instância do subformulário.

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

### Sintaxe:

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

### Parâmetros:

subformulário: Um subformulário armazenado na instância atual da classe Form, identificado pelo seu nome ou índice.

Quando este argumento não é fornecido, o método devolve uma lista de subformulários disponíveis sob a forma de uma matriz com índice a partir de zero. Se o formulário tiver um único subformulário, pode definir subform = 0 para aceder ao mesmo.

### 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 Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.

Tópicos relacionados

Serviço SFDatabases.Database

SFDocuments.Document serviço

ScriptForge.UI service

Necessitamos da sua ajuda!