Inhoud

# SFDocuments.Form-service

De service Form biedt methodes en eigenschappen om formulieren in LibreOffice-documenten te beheren. Deze service ondersteunt formulieren in Base-, Calc- en Writer-documenten en maakt het volgende mogelijk:

- Formulieren openen en activeren.

- Door de records navigeren die op het formulier worden weergegeven.

- Toegang krijgen tot de bedieningselementen in het formulier.

- Toegang krijgen tot subformulieren van een bovenliggend formulier.

De service SFDocuments.Form is beschikbaar vanaf LibreOffice 7.2 en later.

Formulieren worden meestal gebruikt in LibreOffice-documenten om gebruikersinterfaces te maken die zijn verbonden met relationele databases. Daarom biedt de service Form snelle toegang tot de gekoppelde database via de SFDatabases .Database-service.

De service SFDocuments.Form is nauw verwant aan de SFDocuments.FormControl-service.

## Definities

### FormDocument

Formulieren worden meestal gemaakt in Base-documenten, maar ze kunnen ook worden toegevoegd aan Writer- en Calc-documenten.

In Base maakt elk formulier dat u maakt met de functie Invoegen - Formulier of via de Assistent Formulier is eigenlijk een FormDocument dat kan worden afgehandeld met de service Form. Basisdocumenten kunnen een onbeperkt aantal formulierdocumenten bevatten.

Hieronder ziet u een voorbeeld dat de hiërarchie toont van alle elementen die betrokken zijn bij het openen van formulieren en subformulieren in een basisdocument. Stel dat u een basisbestand hebt met de naam Employees.odb en daarin een formulierdocument hebt gemaakt om nieuwe werknemers aan de database toe te voegen. Het formulierdocument bevat een hoofdformulier met de naam EmployeeData dat toegang geeft tot een tabel. Er is ook een subformulier WorksAtPlant waarmee u de nieuwe werknemer kunt koppelen aan één van de vestigingen van het bedrijf.

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

Een FormDocument kan worden gezien als een set formulieren die toegang bieden tot datasets zoals databasetabellen en query's vanuit LibreOffice-documenten. De namen van formulieren en subformulieren in een FormDocument zijn toegankelijk via de Formuliernavigator.

### Formulieren en subformulieren

Een formulierdocument is samengesteld uit één of meer formulieren die op hun beurt weer een willekeurig aantal subformulieren kunnen bevatten. Een formulier is een abstracte set besturingselementen die zijn gekoppeld aan een opgegeven gegevensbron, wat een databasetabel, een query of een SQL-instructie SELECT kan zijn.

In Calc- en Writer-documenten kan elk formulier worden gekoppeld aan datasets die zich in verschillende databases bevinden. Aan de andere kant is in Base-documenten de database in het document gemeenschappelijk voor alle formulieren.

Om de service SFDocuments.Form aan te roepen, raadpleegt u de methodes Forms(), FormDocuments() en OpenFormDocument() van het SFDocuments.Document-service.

## Service aanroep

Voordat de service Form gebruikt kan worden, moet de bibliotheek ScriptForge eerst worden geladen of geïmporteerd:

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService

### In Writer-documenten

Het onderstaande codefragment laat zien hoe u toegang krijgt tot het formulier met de naam Form1 dat zich in een Writer-bestand bevindt:

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

##### In Python

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

Formulieren zijn toegankelijk via hun naam of index, zoals hieronder weergegeven:

         Set myForm = oDoc.Forms(0)

##### In Python

         my_form = doc.Forms(0)

Als u probeert toegang te krijgen tot een FormDocument dat momenteel is geopend in Ontwerpmodus, wordt er een uitzondering gemaakt.

### In Calc-documenten

Een formulier in een Calc-bestand moet een unieke naam hebben binnen het blad. Daarom vereist de methode Forms twee argumenten, waarbij de eerste de bladnaam aangeeft en de tweede de formuliernaam.

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

Dit wordt op dezelfde manier bereikt met Python:

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

### In Base-documenten

Een FormDocument in een basisdocument is toegankelijk via zijn naam. Het volgende voorbeeld opent het formulierdocument met de naam thisFormDocument en opent het formulier MainForm:

          Dim oDb As Object, myForm As Object
          Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
          ' Onderstaande instructie is alleen nodig als het formulier nog niet is geopend
          oDb.OpenFormDocument("thisFormDocument")
          Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
          ' Of, als alternatief, om toegang te krijgen tot het formulier via de index ...
          Set myForm = oDb.Forms("thisFormDocument", 0)

Om een actie op een formulier uit te voeren met behulp van de service Form, moet het FormDocument handmatig door de gebruiker of programmatisch in een gebruikersscript zijn geopend. Dit laatste kan worden gedaan door de methode OpenFormDocument van de Base-service.

Gebruik de methode SubForms om toegang te krijgen tot een bepaald subformulier van een formulier. Merk op dat in het onderstaande voorbeeld mySubForm een nieuwe instantie is van de service Form.

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

Eerdere voorbeelden vertalen in Python als:

         db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
         #  De onderstaande instructie is alleen nodig als het formulier nog niet geopend is
         form_doc = db.OpenFormDocument('thisFormDocument')
         form = form_doc.Forms('thisFormDocument', 'MainForm')
         #  Of, benader het formulier via de index van het formulier
         form = form_doc.Forms('thisFormDocument', 0)
         sub_form = form.SubForms('mySubForm')

### In formuliergebeurtenissen

Om de service Form aan te roepen als er een gebeurtenis plaatsvindt:

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

##### In Python

         def OnEvent(event: uno):
             form = CreateScriptService('SFDocuments.FormEvent', event)
             pass

De service FormEvent wordt exclusief gebruikt om instanties van de services SFDocuments.Form en SFDocuments.FormControl aan te maken wanneer er op een formulier of besturingselement een gebeurtenis plaatsvindt.

Het wordt aanbevolen om bronnen vrij te geven na gebruik van de service Form.

         myForm.Dispose() ' Basic

         form.Dispose()  # Python

Dit wordt automatisch gedaan als het formulier wordt gesloten met de methode CloseFormDocument(), die hieronder is beschreven.

## Eigenschappen

Naam | AlleenLezen | Type | Beschrijving
--- | --- | --- | ---
AllowDeletes | Nee | Boolean | Geeft aan of er op het formulier records verwijderd kunnen worden.
AllowInserts | Nee | Boolean | Geeft aan of er op het formulier records toegevoegd kunnen worden.
AllowUpdates | Nee | Boolean | Geeft aan of er op het formulier records gewijzigd kunnen worden.
BaseForm | Ja | String | Specificeert de hiërarchische naam van de Base Form die het huidige form bevat.
Bookmark | Nee | Variant | Specificeert uniek het huidige record op het formulier van de onderliggende tabel, query of SQL-instructie.
CurrentRecord | Nee | Long | Identificeert het huidige record in de dataset die wordt bekeken op een formulier.Als het rijnummer positief is, gaat de cursor naar het gegeven rijnummer ten opzichte van het begin van de resultatenset. Het aantal rijen begint bij 1. Als het gegeven rijnummer negatief is, gaat de cursor naar een absolute rijpositie ten opzichte van het einde van de resultatenset. Rij -1 verwijst naar de laatste rij in de resultatenset.
Filter | Nee | String | Specificeert een subset van records die moet worden weergegeven als een SQL WHERE-clausule zonder het trefwoord WHERE.
LinkChildFields | Ja | String | Geeft aan hoe records in een onderliggend subformulier worden gekoppeld aan records in het bovenliggende formulier.
LinkParentFields | Ja | String | Geeft aan hoe records in een onderliggend subformulier worden gekoppeld aan records in het bovenliggende formulier.
Name | Ja | String | De naam van het huidige formulier.
OrderBy | Nee | String | Geeft aan in welke volgorde de records moeten worden weergegeven als een SQL ORDER BY-clausule zonder de trefwoorden ORDER BY.
Parent | Ja | Object | Het kan een SFDocuments.Form of een SFDocuments.Document-object zijn.
RecordSource | Nee | String | Specificeert de bron van de gegevens, zoals een tabelnaam, een querynaam of een SQL-instructie.
XForm | Ja | UNO -object | Raadpleeg XForm en DataForm in de API-documentatie voor gedetailleerde informatie.

## Eigenschappen gebeurtenis

De onderstaande eigenschappen retourneren of stellen URI-tekenreeksen in die het script definiëren dat door de gebeurtenis wordt geactiveerd.

Name | AlleenLezen | Basic IDE-beschrijving
--- | --- | ---
OnApproveCursorMove | Nee | Vóór recordwijziging
OnApproveParameter | Nee | Parameters vullen
OnApproveReset | Nee | Voorafgaand aan het herstellen
OnApproveRowChange | Nee | Voor recordactie
OnApproveSubmit | Nee | Voor het versturen
OnConfirmDelete | Nee | Verwijderen bevestigen
OnCursorMoved | Nee | Na recordwijziging
OnErrorOccurred | Nee | Fout opgetreden
OnLoaded | Nee | Bij het laden
OnReloaded | Nee | Bij het opnieuw laden
OnReloading | Nee | Voor het opnieuw laden
OnResetted | Nee | Na het herstellen
OnRowChanged | Nee | Na de recordactie
OnUnloaded | Nee | Bij het lossen
OnUnloading | Nee | Voor het lossen

Raadpleeg de Scripting Framework URI-specificatie voor meer informatie over URI-tekenreeksen.

Lijst met methodes in de formulierservice
Activate Controls GetDatabase MoveFirst | MoveLast MoveNext MoveNew | MovePrevious Requery SubForms

## Activate

Stelt de focus in op de huidige Form-instantie. Retourneert True als het scherpstellen gelukt is.

Het gedrag van de methode Activate hangt af van het type document waarin het formulier zich bevindt:

- In Writer-documenten: Stelt de focus op dat document in.

- In Calc-documenten: Stelt de focus in op het blad waartoe het formulier behoort.

- In Base-documenten: Stelt de focus in op het FormDocument waarnaar het Form verwijst.

### Syntaxis:

svc.Activate(): bool

### Voorbeeld:

In het volgende voorbeeld wordt ervan uitgegaan dat u het formulier met de naam FormA in Blad1 van het momenteel geopende Calc-bestand wilt activeren. Het krijgt eerst toegang tot het document met behulp van de service Document en ThisComponent en activeert vervolgens het formulier.

         ' Ontvangt het formulier dat wordt geactiveerd
         Dim oDoc as Object, myForm as Object
         Set oDoc = CreateScriptService("Document", ThisComponent)
         Set myForm = oDoc.Forms("Sheet1", "FormA")
         'Activeert het formulier
         myForm.Activate()

##### In Python

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

ThisComponent is van toepassing op Calc- en Writer-documenten. Gebruik voor basisdocumenten ThisDataBaseDocument.

## CloseFormDocument

Deze methode is verouderd. Gebruik in plaats daarvan de ScriptForge.FormDocument.CloseDocument-methode.

Sluit het formulierdocument dat de daadwerkelijke Form instantie bevat. De instantie Form is verwijderd.

### Syntaxis:

svc.CloseFormDocument(): bool

### Voorbeeld:

          myForm.CloseFormDocument() ' Basic

##### In Python

          form.CloseFormDocument()  # Python

## Controls

De waarde die wordt geretourneerd door de methode Controls hangt af van de opgegeven argumenten:

- Als de methode zonder argumenten wordt genoemd, retourneert het de lijst met besturingselementen in het formulier. Houd er rekening mee dat de geretourneerde lijst geen besturingselementen voor subformulieren bevat.

- Als het optionele argument ControlName is opgegeven, retourneert de methode een klasse-instantie FormControl die verwijst naar het opgegeven besturingselement.

### Syntaxis:

svc.Controls(opt controlname: str): any

### Parameters:

controlname : Een geldige besturingselementnaam als hoofdlettergevoelige tekenreeks. Indien afwezig, wordt de lijst met besturingselementnamen geretourneerd als een op nul gebaseerde matrix.

### Voorbeeld:

          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

##### In Python

          form = doc.Forms('myForm')
          form_names = form.Controls()
          form_control = form.Controls('myTextBox')  # SFDocuments.FormControl

## GetDatabase

Retourneer een SFDatabases.Database-instantie die toegang geeft tot het uitvoeren van SQL-opdrachten op de database waaraan het huidige formulier is gekoppeld en/of dat is opgeslagen in het huidige basisdocument.

Elk formulier heeft zijn eigen databaseverbinding, behalve in Base-documenten waar ze allemaal dezelfde verbinding delen.

### Syntaxis:

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

### Parameters:

user, password: De optionele login-parameters (Standaard = "").

### Voorbeeld:

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

##### In Python

          db = form.GetDatabase()  # SFDatabases.Database

## MoveFirst

De formuliercursor wordt op het eerste record geplaatst. Retourneert True indien succesvol.

### Syntaxis:

svc.MoveFirst(): bool

### Voorbeeld:

          myForm.MoveFirst() ' Basic

##### In Python

          form.MoveFirst()  # Python

## MoveLast

De formuliercursor wordt op het laatste record geplaatst. Retourneert True indien succesvol.

### Syntaxis:

svc.MoveLast(): bool

### Voorbeeld:

          myForm.MoveLast() ' Basic

##### In Python

          form.MoveLast()  # Python

## MoveNew

De formuliercursor wordt op het nieuwe recordgebied geplaatst. Retourneert True indien succesvol.

### Syntaxis:

svc.MoveNew(): bool

### Voorbeeld:

          myForm.MoveNew() ' Basic

##### In Python

          form.MoveNew()  # Python

## MoveNext

De formuliercursor wordt op het volgende record geplaatst. Retourneert True indien succesvol.

### Syntaxis:

svc.MoveNext(opt offset: int): bool

### Parameters:

offset: Het aantal records dat vooruit moet (standaard = 1).

### Voorbeeld:

          myForm.MoveNext() ' Basic

##### In Python

          form.MoveNext()  # Python

## MovePrevious

De formuliercursor wordt op het vorige record geplaatst. Retourneert True indien succesvol.

### Syntaxis:

svc.MovePrevious(opt offset: int): bool

### Parameters:

offset: Het aantal records om achteruit te gaan (standaard = 1).

### Voorbeeld:

          myForm.MovePrevious() ' Basic

          form.MovePrevious()  # Python

## Requery

Opnieuw laden van de huidige gegevens uit de database en ververst het formulier De cursor staat op het eerste record. Retourneert True indien succesvol.

### Syntaxis:

svc.Requery(): bool

### Voorbeeld:

          myForm.Requery() ' Basic

##### In Python

          form.Requery()  # Python

## Subforms

De waarde die wordt geretourneerd door de methode Subforms hangt af van de opgegeven argumenten:

- Als de methode zonder argumenten wordt genoemd, dan retourneert deze de lijst met subformulieren die in het huidige formulier of subformulier voorkomen.

- Als het optionele argument subform is opgegeven, retourneert de methode een nieuwe instantie SFDocuments.Form op basis van de opgegeven naam of index van het formulier/subformulier.

### Syntaxis:

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

### Parameters:

subform: Een subformulier dat is opgeslagen in de huidige klasse-instantie Form, gegeven door zijn naam of index.

Als dit argument afwezig is, retourneert de methode een lijst met beschikbare subformulieren als een op nul gebaseerde matrix. Als het formulier een enkel subformulier heeft, kunt u subform = 0 instellen om er toegang toe te krijgen.

### Voorbeeld:

          Dim myForm As Object, myList As Variant, mySubform As Object
          myList = myform.Subforms()
          Set mySubform = myForm.Subforms("mySubform") ' SFDocuments.Form

##### In Python

          subform_names = form.Subforms()
         subform = form.Subforms('mySubform')  # SFDocuments.Form

Alle ScriptForge Basic-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

Verwante onderwerpen

SFDatabases.Database-service

SFDocuments.Document-service

Service ScriptForge.UI