Tjenesten SFDocuments.Form

Tjenesten Form giver metoder og egenskaber til administration af formularer i LibreOffice-dokumenter. Denne tjeneste understøtter formularer i Base-, Calc- og Writer-dokumenter og tillader:

tip

Tjenesten SFDocuments.Form er tilgængeligt fra LibreOffice 7.2 og derefter.


Formularer bruges sædvanligvis i LibreOffice-dokcumenter til at oprette brugerflader forbundet med relationsdatabaser. Derfor giver tjenesten Form hurtig adgang til den linkede database gennem tjenesten SFDatabases.Database.

tip

Tjenesten SFDocuments.Form er tæt beslægtet med tjenesten SFDocuments.FormControl.


Definitioner

FormDocument

Formularer oprettes sædvanligvis i Base-dokumenter, men kan også tilføjes tilføjes til Writer- og Calc-dokumenter.

I Base er hver formular, du opretter med funktionaliteten Indsæt ▸ Formular eller med Formularguiden faktisk et FormDocument (formulardokument), der kan håndteres med tjenesten Form. Base-dokumenter kan indeholde et ubegrænset antal formulardokumenter.

Herunder viser et eksempel hierarkiet i alle elementer, der er involveret i at tilgå formularer og underformularer i et Base-dokument. Antag, at du har et Base-dokument kaldetEmployees.odb (Ansatte) og at du i det har oprettet en formular til tilføjelse af nye ansatte i databasen. Formulardokumentet indeholde en hovedformular ved navn EmployeeData (Ansattes data), der giver adgang til en tabel. Der er også en underformular WorksAtPlant (arbejder_i_afdeling), der lader dig tilknytte den nyansatte til en afdelingerne i din virksomhed.


    Employees.odb (Ansatte) (Base-dokument)
     |
     |-- AddEmployee (FormDocument)
          |
          |-- EmployeeData (AnsatteData) (Hovedformular)
               |
               |-- WorksAtPlant (SubForm)
  
note

Et FormDocument (formulardokument) kan være et sæt af formularer, der giver adgang til datasæt, som fx database-tabeller og -forespørgsler i LibreOffice- dokumenter. Navne på formularer og underformularer i et formulardokument kan tilgås med Formularnavigator.


Formularer og underformularer

Et formulardokument er sammensat af en eller flere formularer, som igen også kan indeholde et vilkårligt antal underformularer. En formular er et abstrakt sæt af kontroller, der er knyttet til en bestemt datakilde, som kan være en database-tabel, en forespørgsel eller et SQL SELECT-udtryk.

I Calc- og Writer-dokumenter kan hver formular være knyttet til datasæt, der er placeret i forskellige databaser. På den anden side kan databaser, der er placeret i Base-dokumenter, være fælles for alle formularer.

tip

For at kalde tjenesten SFDocuments.Form henviser du til metoderne Forms() (formularer()), FormDocuments() (formulardokumenter()) og OpenFormDocument() (Åbne_formulardokumenter ()) i tjenesten SFDocuments.Document


Kald af tjeneste

Før brug af tjenesten Form skal biblioteket ScriptForge være indlæst eller importeret:

note

• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-scripts kræver import af scriptforge-modulet:
from scriptforge import CreateScriptService


I Writer-dokumenter

Kodestumpen herunder viser, hvordan man tilgår formularen ved navnForm1 (formular_1), som findes i en 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")
   
I Python

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

Formularer kan tilgås med deres navne eller med deres indekser, som vist herunder:


     Set myForm = oDoc.Forms(0)
   
I Python

     my_form = doc.Forms(0)
   
warning

Hvis du prøver at tilgå et FormDocument (formulardokument), der aktuelt er åbnet i Designtilstand sættes der et undtagelsesflag.


I Calc-dokumenter

En formular i en Calc-fil skal have et unikt navn på sit ark. Derfor kræver metoden Forms (formularer) to argumenter, hvoraf den første viser arknavnet og den anden angiver formularnavnet.


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

Dette opnås på samme måde med Python:


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

I Base-dokumenter

Et FormDocument (formulardokument) inde i et Base-dokument tilgås med dets navn. Det følgende eksempel åbner formulardokumentet ved navn thisFormDocument (dette_formulardokument) og tilgår formularen MainForm (hovedformular):


      Dim oDb As Object, myForm As Object
      Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
      ' Udtrykket herunder er kun nødvendigt, hvis formularen endnu ikke er åbnet
      oDb.OpenFormDocument("thisFormDocument")
      Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
      ' Eller alternativt at tilgå formularen med dens indeks…
      Set myForm = oDb.Forms("thisFormDocument", 0)
   
note

For at udføre enhver handling på en formular med tjenesten Form (formular), skal FormDocument (formulardokument) være åbnet enten manuelt af grugeren eller af programmet i et bruger-script. Det sidste kan gøres ved at kalde metoden OpenFormDocument (åbent_formulardokument) i tjenesten Base.


For at tilgå en given underformular bruger du metoden SubForms (underformular). Bemærk, at o eksemplet herunder er mySubForm (min_underformular) en ny forekomst af tjenesten Form (formular).


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

De foregående eksempler oversættes i Python som:


     db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
     #  Udtrykket herunder er kun nødvendigt, hvis fornularen endnu ikke er åbnet
     form_doc = db.OpenFormDocument('thisFormDocument')
     form = form_doc.Forms('thisFormDocument', 'MainForm')
     #  Eller alternativt for at tilgå formularen med dens indeks…
     form = form_doc.Forms('thisFormDocument', 0)
     sub_form = form.SubForms('mySubForm')
   

I Formularhændelser

For at kalde tjenesten Form (formular), når en hændelse finder sted:


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

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

Tjenesten FormEvent (formularhændelse) bruges udelukkende til at oprette forekomster af tjenesterne SFDocuments.Form og SFDocuments.FormControl, når der finder en formular- eller kontrol-hændelse sted.


Det anbefales at frigøre ressourcer efter brug af tjenesten Formular.


     myForm.Dispose() ' Basic
   

     form.Dispose()  # Python
   

Denne handling udføres underforstået, når et formulardokument er lukket med metoden CloseFormDocument() (luk_formulardokument) beskrevet herunder.

Egenskaber

Navn

Skrivebeskyttet

Type

Beskrivelse

AllowDeletes

Nej

Boolean

Angiver, om formularen tillader at poster slettes.

AllowInserts

Nej

Boolean

Angiver, om formularen tillader tilføjelse af poster.

AllowUpdates

Nej

Boolean

Angiver, om formularen tillader at poster opdateres

BaseForm

Ja

String

Angiver det hierarkiske navn på Baseformularen, der indeholder den aktuelle formular.

Bookmark

Nej

Variant

Angiver entydigt den aktuelle post i formularens underliggende tabel, forespørgsel eller SQL-udtryk.

CurrentRecord

Nej

Long

Identificerer den den aktuelle post i datasættet set i en formular. Hvis rækkenummeret er positivt, flytter markøren til det givne rækkenummer med i forhold til begyndelsen af resultatsættet. Rækketællinger starter med 1. Hvis det givne rækkenummer er negativt, flytter markøren til en-1absolut rækkeposition i for til slutningen af resultatsættet. Række -1 henviser til den sidste række i resultatsættet.

Filter

Nej

String

Angiver en delmængde af poster, der vises som en SQL WHEREsætning uden nøgleordet WHERE.

LinkChildFields

Ja

String

Angiver, hvordan poster i en afkoms-underformaler tilknyttes til poster i dens ophavsformular.

LinkParentFields

Ja

String

Angiver, hvordan poster i en afkoms-underformaler tilknyttes til poster i dens ophavsformular.

Name

Ja

String

Den aktuelle formulars navn.

OrderBy

Nej

String

Angiver, i hvilken rækkefølge poster skal vises som en SQL ORDER BY-sætning uden nøgleordene ORDER BY (sorter efter).

Parent

Ja

Object

Ophavet til den aktuelle formular. Det kan være et af objekterne SFDocuments.Form (formular) eller SFDocuments.Document (dokument) .

RecordSource

Nej

String

Angiver datakilden som et tabelnavn, et forspørgselsnavn eller et SQL-udtryk.

XForm

Ja

UNO
objekt

UNO- objekt repræsenterende interaktioner med formularen. Se detaljeret information i API-dokumentationen: XForm og DataForm.


Hændelsesegenskaber

Egenskaberne herunder returnerer eller sætter URI-strenge, der definerer det script, der udløses af hændelsen.

Navn

Skrivebeskyttet

Basic IDE Beskrivelse

OnApproveCursorMove

Nej

Før posthandling

OnApproveParameter

Nej

Fyld parametre

OnApproveReset

Nej

Før nulstilling

OnApproveRowChange

Nej

Før posthandling

OnApproveSubmit

Nej

Før indsendelse

OnConfirmDelete

Nej

Bekræft sletning

OnCursorMoved

Nej

Efter postændring

OnErrorOccurred

Nej

Der skete en fejl

OnLoaded

Nej

Under indlæsning

OnReloaded

Nej

Under genindlæsning

OnReloading

Nej

Før genindlæsning

OnResetted

Nej

Efter nulstilling

OnRowChanged

Nej

Efter posthandling

OnUnloaded

Nej

Under rensning (af hukommelsen)

OnUnloading

Nej

Før fjernelse


tip

To learn more about URI strings, refer to the Scripting Framework URI Specification.


Liste over metoderne i tjenesten Form

Activate
CloseFormDocument
Controls
GetDatabase

MoveFirst
MoveLast
MoveNext
MoveNew

MovePrevious
Requery
SubForms


Activate

Sætter fokus på den aktuelle forekomst af Form (formular). Returnerer True (sand), hvis fokuseringen lykkedes.

Metoden Activate (aktivér)s adfærd afhænger af den dokumenttype, hvor formularen er placeret:

Syntaks:

svc.Activate(): bool

Eksempel:

Det følgende eksempel antager, at du vil aktivere formularen ved navn FormA (formularA) placeret på Sheet1 (ark 1) i den aktuelt åbne Calc-fil. Det får først adgang til dokumentet med tjenesten Document og ThisComponent (denne komponent) og aktiverer derefter formularen.


     ' Får fat på den formular, der bliver aktiveret
     Dim oDoc as Object, myForm as Object
     Set oDoc = CreateScriptService("Document", ThisComponent)
     

Set myForm = oDoc.Forms("Sheet1", "FormA")

' Aktiverer formularen myForm.Activate()
I Python

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

ThisComponent (denne_komponent) anvendes på Calc- og Writer-dokumenter. Ved Base-dokumenter bruger duThisDataBaseDocument (dette_database-dokument).


CloseFormDocument

Lukker det formulardokument, der indeholder den aktuelle forekomst af Form. Forekomsten af Form (formular) bortskaffes.

Syntaks:

svc.CloseFormDocument(): bool

Eksempel:


      myForm.CloseFormDocument() ' Basic
   
I Python

      form.CloseFormDocument()  # Python
   
note

Denne metoder lukker kun formular-dokumenter i Base-dokumenter. Hvis formularen er gemt i et Writer- eller Calc-dokument, har kald af CloseFormDocument (luk_formular-dokument) ingen virkning.


Controls

Værdien, der returneres af metoden Controls, afhænger af de opgivne argumenter:

Syntaks:

svc.Controls(opt controlname: str): any

Parametre:

kontrolnavn: Et gyldigt kontrolnavn er en streng med Stort-og-småt. Hvis det mangler, returneres listen over kontrolnavne som en nul-baseret matrix.

Eksempel:


      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
   
I Python

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

GetDatabase

Returnerer en forekomst af SFDatabases.Database, der giver adgang til udførelse af SQL-kommandoer på den database, den aktuelle formular er knyttet til og/eller gemt i det aktuelle dokument.

Hver formular har sin engen database-forbindelse, undtagen i Base-dokumenter, hvor de alle deler den samme forbindelse.

Syntaks:

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

Parametre:

bruger, adgangskode: De frivillige parametre i log-in'et (Default = "").

Eksempel:


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

      db = form.GetDatabase()  # SFDatabases.Database
   

MoveFirst

Formularmarkøren er placeret på den første post, Returnerer True, hvis det lykkes.

Syntaks:

svc.MoveFirst(): bool

Eksempel:


      myForm.MoveFirst() ' Basic
   
I Python

      form.MoveFirst()  # Python
   

MoveLast

Formularmarkøren er placeret på den sidste post. Returnerer True, hvis det lykkes.

Syntaks:

svc.MoveLast(): bool

Eksempel:


      myForm.MoveLast() ' Basic
   
I Python

      form.MoveLast()  # Python
   

MoveNew

Formularmarkøren er placeret på området Ny post. Returnerer True, hvis det lykkes.

Syntaks:

svc.MoveNew(): bool

Eksempel:


      myForm.MoveNew() ' Basic
   
I Python

      form.MoveNew()  # Python
   

MoveNext

Formularmarkøren er placeret på den næste post. Returnerer True, hvis det lykkes.

Syntaks:

svc.MoveNext(opt offset: int): bool

Parametre:

forskydning: Antallet af poster, du skal gå frem (Standard = 1).

Eksempel:


      myForm.MoveNext() ' Basic
   
I Python

      form.MoveNext()  # Python
   

MovePrevious

Formelmarkøren er placeret på den forrige post. Returnerer True, hvis det lykkes.

Syntaks:

svc.MovePrevious(opt offset: int): bool

Parametre:

forskydning: Antallet af poster, der skal gås baglæns (Standard = 1).

Eksempel:


      myForm.MovePrevious() ' Basic
   

      form.MovePrevious()  # Python
   

Requery

Genindlæser de aktuelle data fra databasen og gentegner formularen. Markøren er placeret på den første post. Returnerer True, hvis det lykkes.

Syntaks:

svc.Requery(): bool

Eksempel:


      myForm.Requery() ' Basic
   
I Python

      form.Requery()  # Python
   

Subforms

Værdien, der returneres af metoden Subforms (underformularer), afhænger af de opgivne argumenter:

Syntaks:

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

Parametre:

underformular: En underformular, der er glemt i det aktuelle klasseekemplar Form (formular) angivet ved sit navn eller indeks.

Når dette argument mangler, returnerer metoden en liste over tilgængelige underformularer som en nul-baseret matrix. Hvis formularen har en enkelt underformular, kan du sætte subform = 0 (underformular = 0) for at tilgå den.

Eksempel:


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

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

Alle ScriptForge Basic-rutiner eller identifikatorer, der er indledet med et understreget tegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.


Støt os venligst!