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

Forms are usually created in Base documents, but they can be added to Writer and Calc documents as well.

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 %PRODUCTNAM- 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

I Writer-dokumenter

The code snippet below shows how to access the form named Form1 that is inside a Writer file:


      Dim oDoc As Object, myForm As Object, ui as Object
      Set ui = CreateScriptService("UI")
      Set oDoc = ui.OpenDocument("~/Documents/MyForm.odt")
      Set myForm = oDoc.Forms("Form1")
   
In Python

     from scriptforge import CreateScriptService
     svc = CreateScriptService('UI') 
     doc = svc.OpenDocument('~/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)
   
In 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

A form in a Calc file must have a unique name inside its sheet. Hence, the Forms method requires two arguments, the first indicating the sheet name and the second specifying the form name.


      Dim oDoc As Object, myForm As Object, ui as Object
      Set ui = CreateScriptService("UI")
      Set oDoc = ui.OpenDocument("~/Documents/MyForms.ods")
      Set myForm = oDoc.Forms("Sheet1", "Form1")
   

This is achieved identically using Python:


     svc = CreateScriptService('UI')
     doc = svc.OpenDocument('~/Documents/MyForms.ods')
     my_form = doc.Forms('Sheet1', 'Form1')
   

I Base-dokumenter

A FormDocument inside a Base document is accessed by its name. The following example opens the form document named thisFormDocument and accesses the form MainForm:


      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

To perform any action on a form using the Form service, the FormDocument must have been opened either manually by the user or programmatically in a user script. The latter can be done by calling the OpenFormDocument method of the Base service.


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

Previous examples translate in Python as:


     db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
     #  The statement below is necessary only if the form hasn't been opened yet
     form_doc = db.OpenFormDocument('thisFormDocument')
     form = form_doc.Forms('thisFormDocument', 'MainForm')
     #  Or, alternatively, to access the form by its index ...
     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
   
In 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.


It is recommended to free resources after use of the Form service.


     myForm.Dispose() ' Basic
   

     form.Dispose()  # Python
   

This operation is done implicitly when a form document is closed with the CloseFormDocument() method described below.

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

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

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

ThisComponent applies to Calc and Writer documents. For Base documents use ThisDataBaseDocument.


CloseFormDocument

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

Syntaks:

svc.CloseFormDocument(): bool

Eksempel:


      myForm.CloseFormDocument() ' Basic
   
In 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:

controlname : A valid control name as a case-sensitive string. If absent, the list of control names is returned as a zero-based array.

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

Each form has its own database connection, except in Base documents where they all share the same connection.

Syntaks:

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

Parametre:

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

Eksempel:


      Dim myDb As Object ' SFDatabases.Database
      Set myDb = oForm.GetDatabase()
   
In 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
   
In 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
   
In 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
   
In 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:

offset: The number of records to go forward (Default = 1).

Eksempel:


      myForm.MoveNext() ' Basic
   
In 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:

offset: The number of records to go backwards (Default = 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
   
In 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:

subform: A subform stored in the current Form class instance given by its name or index.

When this argument is absent, the method returns a list of available subforms as a zero-based array. If the form has a single subform, you can set subform = 0 to get access to it.

Eksempel:


      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-rutiner eller identifikatorer, som indledes med et understregningstegn "_" er reserveret til internt brug. De er ikke beregnet til brug i Basic-makroer.