SFDocuments.Form service

The Form service provides methods and properties to manage forms in LibreOffice documents. This service supports forms in Base, Calc and Writer documents and allows to:

• Open and activate forms.

• Navigate through records shown by the form.

• Get access to the controls inside the form.

• Get access to subforms of a parent form.

The SFDocuments.Form service is available from LibreOffice 7.2 onwards.

Forms are usually used in LibreOffice documents to create user interfaces connected to relational databases. Hence, the Form service provides quick access to the linked database through the SFDatabases.Database service.

The SFDocuments.Form service is closely related to the SFDocuments.FormControl service.

Definiciones

FormDocument

Los formularios se suelen crear dentro de documentos de Base, pero es posible añadirlos también a documentos de Writer y de Calc.

In Base, each form you create using the Insert - Form functionality or through the Form Wizard is actually a FormDocument that can be handled with the Form service. Base documents can contain an unlimited number of form documents.

Below is an example showing the hierarchy of all the elements involved in accessing forms and subforms in a Base document. Suppose you have a Base file named Employees.odb and inside it you created a form document to add new employees to the database. The form document contains a main form named EmployeeData that gives access to a table. There is also a subform WorksAtPlant that allows you to associate the new employee to one of the plants of the company.

    Employees.odb (Base document)
     |
     |-- AddEmployee (FormDocument)
          |
          |-- EmployeeData (Main Form)
               |
               |-- WorksAtPlant (SubForm)
  

A FormDocument can be seen as a set of forms that provide access to datasets such as database tables and queries from within LibreOffice documents. The names of forms and subforms inside a FormDocument can be accessed using the Form Navigator.

Formularios y subformularios

A form document is composed of one or more forms which, in turn, may also contain any number of subforms. A Form is an abstract set of controls that are linked to a specified data source, which can be a database table, a query or a SQL SELECT statement.

In Calc and Writer documents, each form can be linked to datasets located in different databases. On the other hand, in Base documents the database contained in the document is common to all forms.

To invoke the SFDocuments.Form service refer to the methods Forms(), FormDocuments() and OpenFormDocument() of the SFDocuments.Document service

Invocación del servicio

Antes de utilizar el servicio Form, es necesario cargar o importar la biblioteca ScriptForge:

• Para cargar la biblioteca ScriptForge que necesitan las macros de Basic se debe usar la siguiente declaración:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Los scripts de Python necesitan importar el módulo scriptforge:
from scriptforge import CreateScriptService

En documentos de Writer

The code snippet below shows how to access the form named Form1 that is inside a Writer file:

      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")
   

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

Forms can be accessed by their names or by their indices, as shown below:

     Set myForm = oDoc.Forms(0)
   

     my_form = doc.Forms(0)
   

If you try to access a FormDocument that is currently opened in Design Mode an exception will be raised.

En documentos de Calc

A form in a Calc file must have a unique name inside its sheet. Hence, the Forms method requires two arguments, the first indicating the sheet name and the second specifying the form name.

      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")
   

Esto se logra de idéntica manera utilizando Python:

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

En documentos de Base

A FormDocument inside a Base document is accessed by its name. The following example opens the form document named thisFormDocument and accesses the form MainForm:

      Dim oDb As Object, myForm As Object
      Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
      ' The statement below is necessary only if the form hasn't been opened yet
      oDb.OpenFormDocument("thisFormDocument")
      Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
      ' Or, alternatively, to access the form by its index ...
      Set myForm = oDb.Forms("thisFormDocument", 0)
   

To perform any action on a form using the Form service, the FormDocument must have been opened either manually by the user or programmatically in a user script. The latter can be done by calling the OpenFormDocument method of the Base service.

To access a given subform of a form use the SubForms method. Note that in the example below mySubForm is a new instance of the Form service.

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

Los ejemplos anteriores se traducen en Python como:

     db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
     #  The statement below is necessary only if the form hasn't been opened yet
     form_doc = db.OpenFormDocument('thisFormDocument')
     form = form_doc.Forms('thisFormDocument', 'MainForm')
     # O, alternativamente, para acceder al formulario por su índice ...
     form = form_doc.Forms('thisFormDocument', 0)
     sub_form = form.SubForms('mySubForm')
   

En eventos de formulario

Para invocar el servicio Form cuando acaece un evento de formulario:

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

     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.

Es recomendable liberar recursos después de utilizar el servicio Form.

     myForm.Dispose() ' Basic
   

     form.Dispose()  # Python
   

This operation is done implicitly when a form document is closed with the CloseFormDocument() method described below.

Propiedades