SFDocuments.FormDocument service

The FormDocument service allows to access form documents stored in LibreOffice Base documents.

In a Base document, existing form documents can be viewed by selecting View - Forms in the user interface. Each form document may be composed of one or more forms, including the main form and other sub-forms.

This service inherits methods and properties from the Document service and is often used alongside the Base and Database services.

tip

Refer to the Document service to learn more about methods and properties that can be used to manage LibreOffice documents.


Service invocation

Before using the FormDocument service the ScriptForge library needs to be loaded or imported:

note

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService


In Basic

A FormDocument service instance can be created by calling the method OpenFormDocument that exists both in the Base and Database services.

The example below uses the UI service to open a Base document and then retrieve a form document. Note that in this example both the Base document and the form document will be opened and displayed on the screen.


    Dim ui As Object, oBase As Object, oFormDoc As Object
    ui = CreateScriptService("UI")
    oBase = ui.OpenBaseDocument("C:\Documents\MyDatabase.odb")
    oFormDoc = oBase.OpenFormDocument("MyFormDocument")
    ' ...
    oFormDoc.CloseDocument()
  

The following example uses the Database service to open the form document. In this case, the Base file will not be opened and only the form document will be shown.


    Dim oDatabase As Object, oFormDoc As Object
    oDatabase = CreateScriptService("Database", "C:\Documents\MyDatabase.odb")
    oFormDoc = oDatabase.OpenFormDocument("MyFormDocument")
  
note

Calling OpenFormDocument for a form document that is already open will activate the document window and bring it to focus.


In Python

The examples above can be translated to Python as follows:


    ui = CreateScriptService("UI")
    baseDoc = ui.OpenBaseDocument("C:\Documents\MyDatabase.odb")
    formDoc = baseDoc.OpenFormDocument("MyFormDocument")
    # ...
    formDoc.CloseDocument()
  

    database = CreateScriptService("Database", "C:\Documents\MyDatabase.odb")
    formDoc = database.OpenFormDocument("MyFormDocument")
  

List of Methods in the FormDocument Service

CloseDocument
Forms

GetDatabase

PrintOut


CloseDocument

Closes the form document referred to by the FormDocument instance. Returns True if the form document was successfully closed.

Syntax:

svc.CloseDocument(): bool

Example:

In Basic

    oFormDoc.CloseDocument()
  
In Python

    formDoc.CloseDocument()
  

Forms

Returns either an array with the names of the main forms contained in the form document or a Form service instance referring to a specific form.

Call this method without arguments to obtain a zero-based string array with the names of all forms contained in the form document.

Provide a form name or index as argument to obtain a Form service instance corresponding to the specified form.

note

A form document has at least one main form. More complex form documents may be composed of more than one form and sub-forms.


Syntax:

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

svc.Forms(form: str): svc

svc.Forms(form: int): svc

Parameters:

form: This argument can be either a string with the name of a form that exists in the form document or the zero-based index of the form that shall be returned. If this argument is not specific, then an array with the name of all available forms is returned.

Example:

In Basic

The following example checks if the form document contains a form named "MainForm":


    arrForms = oFormDoc.Forms()
    If SF_Array.Contains(arrForms, "MainForm") Then
        ' ...
    End If
  

The example below retrieves the form named "MainForm" and moves it to the last record:


    Dim oForm As Object
    oForm = oFormDoc.Forms("MainForm")
    oForm.MoveLast()
  
In Python

    arrForms = formDoc.Forms()
    if "MainForm" in arrForms:
        # ...
  

    form = formDoc.Forms("MainForm")
    form.MoveLast()
  
tip

To learn more about form methods and properties, refer to the Form service help page.


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.

Syntax:

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

Parameters:

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

Example:


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

      db = form.GetDatabase()  # SFDatabases.Database
   

PrintOut

This method sends the contents form document to the default printer or to the printer defined by the SetPrinter() method.

Returns True if the document was successfully sent to the printer.

Syntax:

svc.PrintOut(pages: str = "", copies: int = 1, printbackground: bool = true, printblankpages: bool = false, printevenpages: bool = true, printoddpages: bool = true, printimages: bool = true): bool

Parameters:

pages: The pages to print as a string. This argument should be specified in the same manner as in the user interface (see File - Print dialog). Example: "1-4;10;15-18". The default value is an empty string "" which will cause all pages to be printed.

copies: The number of copies to be printed (Default = 1).

printbackground: specifies whether the background image should be printed (Default = True).

printblankpages: specifies whether blank pages should be printed (Default = False).

printevenpages: specifies whether even pages should be printed (Default = True).

printoddpages: specifies whether odd pages should be printed (Default = True).

printimages: specifies whether images should be printed (Default = True).

Example:

In Basic

    oFormDoc.PrintOut("1-4", Copies := 2, PrintBackground := False)
  
In Python

    formDoc.PrintOut("1-4", copies = 2, printbackground = False)
  
warning

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.


Please support us!