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:

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

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:

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

     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)
   

     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
   

     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

Eigenschappen gebeurtenis

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

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

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.

svc.Activate(): bool

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

     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

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

svc.CloseFormDocument(): bool

      myForm.CloseFormDocument() ' Basic
   

      form.CloseFormDocument()  # Python
   

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:

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

svc.Controls(opt controlname: str): any

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

      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
   

      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.

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

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

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

      db = form.GetDatabase()  # SFDatabases.Database
   

MoveFirst

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

svc.MoveFirst(): bool

      myForm.MoveFirst() ' Basic
   

      form.MoveFirst()  # Python
   

MoveLast

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

svc.MoveLast(): bool

      myForm.MoveLast() ' Basic
   

      form.MoveLast()  # Python
   

MoveNew

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

svc.MoveNew(): bool

      myForm.MoveNew() ' Basic
   

      form.MoveNew()  # Python
   

MoveNext

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

svc.MoveNext(opt offset: int): bool

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

      myForm.MoveNext() ' Basic
   

      form.MoveNext()  # Python
   

MovePrevious

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

svc.MovePrevious(opt offset: int): bool

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

      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.

svc.Requery(): bool

      myForm.Requery() ' Basic
   

      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.

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

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.

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

      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.