SFDocuments.Form-service

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

tip

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.

tip

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 een van de vestigingen van het bedrijf.


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

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 een 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.

tip

Om de service SFDocuments.Form aan te roepen, raadpleegt u de methoden 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:

note

ā€¢ 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)
   
warning

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

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
   
note

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


tip

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


Lijst met methoden in de formulierservice

Activate
CloseFormDocument
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:

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()
   
note

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


CloseFormDocument

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
   
note

Deze methode sluit alleen formulierdocumenten die zich in Basisdocumenten bevinden. Als het formulier is opgeslagen in een Writer- of Calc-document, heeft het aanroepen van CloseFormDocument geen effect.


Controls

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

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:

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
   
warning

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


Help ons, alstublieft!