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

The FormEvent service is used exclusively to create instances of the SFDocuments.Form and SFDocuments.FormControl services when a form or control event takes place.

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	No	Before record change
OnApproveParameter	No	Fill parameters
OnApproveReset	No	Prior to reset
OnApproveRowChange	No	Before record action
OnApproveSubmit	No	Before submitting
OnConfirmDelete	No	Confirm deletion
OnCursorMoved	No	After record change
OnErrorOccurred	No	Error occurred
OnLoaded	No	When loading
OnReloaded	No	When reloading
OnReloading	No	Before reloading
OnResetted	No	After resetting
OnRowChanged	No	After record action
OnUnloaded	No	When unloading
OnUnloading	No	Before unloading

To learn more about URI strings, refer to the Scripting Framework URI Specification.

List of methods in the Form service
Activate Controls GetDatabase MoveFirst	MoveLast MoveNext MoveNew	MovePrevious Requery SubForms

Activate

Sets the focus on the current Form instance. Returns True if focusing was successful.

The behavior of the Activate method depends on the type of document where the form is located:

In Writer documents: Sets the focus on that document.
In Calc documents: Sets the focus on the sheet to which the form belongs.
In Base documents: Sets the focus on the FormDocument the Form refers to.

Sintaxe:

svc.Activate(): bool

Exemplo:

The following example assumes you want to activate the form named FormA located in Sheet1 of the currently open Calc file. It first gets access to the document using the Document service and ThisComponent and then activates the form.


     'Gets hold of the form that will be activated
     Dim oDoc as Object, myForm as Object
     Set oDoc = CreateScriptService("Document", ThisComponent)
     Set myForm = oDoc.Forms("Sheet1", "FormA")
     'Activates the form
     myForm.Activate()

Em Python


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

ThisComponent applies to Calc and Writer documents. For Base documents use ThisDataBaseDocument.

CloseFormDocument

This method is deprecated, use ScriptForge.FormDocument.CloseDocument method instead.

Closes the form document containing the actual Form instance. The Form instance is disposed.

Sintaxe:

svc.CloseFormDocument(): bool

Exemplo:


      myForm.CloseFormDocument() ' Basic

Em Python


      form.CloseFormDocument()  # Python

Controls

The value returned by the Controls method depends on the arguments provided:

If the method is called without arguments, then it returns the list of the controls contained in the form. Be aware that the returned list does not contain any subform controls.
If the optional ControlName argument is provided, the method returns a FormControl class instance referring to the specified control.

Sintaxe:

svc.Controls(opt controlname: str): any

Parâmetros:

controlname : A valid control name as a case-sensitive string. If absent, the list of control names is returned as a zero-based array.

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

Return a SFDatabases.Database instance giving access to the execution of SQL commands on the database the current form is connected to and/or that is stored in the current Base document.

Each form has its own database connection, except in Base documents where they all share the same connection.

Sintaxe:

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

Parâmetros:

user, password: The login optional parameters (Default = "").

Exemplo:


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

Em Python


      db = form.GetDatabase()  # SFDatabases.Database

MoveFirst

The form cursor is positioned on the first record. Returns True if successful.

Sintaxe:

svc.MoveFirst(): bool

Exemplo:


      myForm.MoveFirst() ' Basic

Em Python


      form.MoveFirst()  # Python

MoveLast

The form cursor is positioned on the last record. Returns True if successful.

Sintaxe:

svc.MoveLast(): bool

Exemplo:


      myForm.MoveLast() ' Basic

Em Python


      form.MoveLast()  # Python

MoveNew

The form cursor is positioned on the new record area. Returns True if successful.

Sintaxe:

svc.MoveNew(): bool

Exemplo:


      myForm.MoveNew() ' Basic

Em Python


      form.MoveNew()  # Python

MoveNext

The form cursor is positioned on the next record. Returns True if successful.

Sintaxe:

svc.MoveNext(opt offset: int): bool

Parâmetros:

offset: The number of records to go forward (Default = 1).

Exemplo:


      myForm.MoveNext() ' Basic

Em Python


      form.MoveNext()  # Python

MovePrevious

The form cursor is positioned on the previous record. Returns True if successful.

Sintaxe:

svc.MovePrevious(opt offset: int): bool

Parâmetros:

offset: The number of records to go backwards (Default = 1).

Exemplo:


      myForm.MovePrevious() ' Basic


      form.MovePrevious()  # Python

Requery

Reloads the current data from the database and refreshes the form. The cursor is positioned on the first record. Returns True if successful.

Sintaxe:

svc.Requery(): bool

Exemplo:


      myForm.Requery() ' Basic

Em Python


      form.Requery()  # Python

Subforms

The value returned by the Subforms method depends on the arguments provided:

If the method is called without any arguments, then it returns the list of subforms contained in the current form or subform instance.
If the optional subform argument is provided, the method returns a new SFDocuments.Form instance based on the specified form/subform name or index.

Sintaxe:

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

Parâmetros:

subform: A subform stored in the current Form class instance given by its name or index.

When this argument is absent, the method returns a list of available subforms as a zero-based array. If the form has a single subform, you can set subform = 0 to get access to it.

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