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.

Serviço SFDatabases.Database

SFDocuments.Document serviço

ScriptForge.UI service