Indhold

# 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:

- Åbn og aktiver formularer.

- Naviger gennem posterne, der vises i formularen.

- Få adgang til kontrollerne i formularen.

- Få adgang til til en ophavsformulars afkomsformularer.

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.

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)

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.

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:

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

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)

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 i eksemplet herunder er mySubForm (min_underformular) en ny instans 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

Tjenesten FormEvent (formularhændelse) bruges udelukkende til at oprette instanser 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-delsætning uden nøgleordene ORDER BY (sortér 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

For at lære mere om URI-strenge, se Scripting Framework URI Specification.

Liste over metoderne i tjenesten Form (formular)
Activate Controls GetDatabase MoveFirst | MoveLast MoveNext MoveNew | MovePrevious Requery SubForms

## Activate

Sætter fokus på den aktuelle instans 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:

- I Writer-dokumenter: Sætter fokus på dokumentet.

- I Calc-dokumenter: Sætter fokus på det ark, som formularen tilhører.

- I Base-dokumenter: Fokuserer på det FormDocument (formulardokument), Form (formularen) henviser til.

### Syntaks:

svc.Activate(): bool

### Eksempel:

Det følgende eksempel antager, at du vil aktivere formularen ved navn FormA (formularA) placeret på Ark1 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()

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

## CloseFormDocument

Denne metode er udfaset, brug metoden ScriptForge.FormDocument.CloseDocument i stedet.

Lukker det formulardokument, der indeholder den aktuelle instans af Form. Instansen af Form (formular) kasseres.

### Syntaks:

svc.CloseFormDocument(): bool

### Eksempel:

          myForm.CloseFormDocument() ' Basic

##### I Python

          form.CloseFormDocument()  # Python

## Controls

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

- Hvis metoden kaldes uden argumenter, så returnerer den listen over kontrolelementer, som formularen indeholder. Vær opmærksom på, at den returnerede liste ikke indeholder kontrolelementer fra underformularer.

- Hvis det valgfrie argument ControlName (kontrolnavn) er opgivet, returnerer metoden en instans af klassen FormControl (Formularkontrol), der henviser til den angivne kontrol.

### Syntaks:

svc.Controls(opt controlname: str): any

### Parametre:

controlname (kontrolelement_navn): Et gyldigt navn på et kontrolelement som en streng med forskel på store og små bogstaver. Hvis det mangler, returneres listen over kontrolnavne som et array med 0 som første indeks.

### 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 instans 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:

- Hvis metoden kaldes uden nogen argumenter, returnerer den listen over underformularer i den aktuelle instans af formularen eller underformularen.

- Hvis det frivillige argument subform (underformular) er opgivet, returnerer metoden et nyt eksemplar af SFDocuments.Form (SFdokumenter.formular) baseret på det angivne formular/underformular-navn eller indeks.

### 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

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

Relaterede emner

Tjenesten SFDatabases.Database

Tjenesten SFDocuments.Document

Tjenesten ScriptForge.UI (brugerflade)