Innhald

# Tenesta SFDocuments. Form

Tenesta Form har metodar og eigenskapar for å administrera skjema i LibreOffice-dokument. Denne tenesta har støtte for skjema i Base-, Calc- og Writer-dokument og tillèt:

- Opna og aktiver skjema.

- Naviger gjennom postane som vert viste i skjemaet.

- Få tilgang til kontrollelementa i skjemaet.

- Få tilgang til underskjema til eit overordna skjema.

Tenesta SFDocuments.Form er tilgjengeleg frå LibreOffice 7.2 og seinare.

Skjema vert til vanleg brukte i LibreOffice-dokument for å laga brukargrensesnitt kopla til relasjonsdatabasar. Difor gjev tenesta Form rask tilgang til den tilkopla databasen gjennom tenesta SFDatabases .Database.

Tenesta SFDocuments.Form er nært knytt til tenesta SFDocuments.FormControl.

## Definisjonar

### FormDocument

Skjema vert til vanleg laga i Base-dokument, men de kan også leggjast til i Writer- og Calc-dokument.

I Base er kvart skjema som er laga med funksjonen Set inn → Skjema… eller med skjemavegvisaren eit FormDocument som kan handsamast ved hjelp av tenesta Form. Det er inga grense for kor mange skjemadokument grunndokumenta kan innehalda.

Nedanfor er eit eksempel som viser hierarkiet til alle elementa som er involverte i tilgang til skjema og underskjema i eit basisdokument. Gå ut frå at du har ei basisfil med namnet Employees.odb der du har laga eit skjemadokument for å leggja til nye tilsette i databasen. Skjemadokumentet inneheld eit hovudskjema kalla EmployeeData som gir tilgang til ein tabell. Det finst også eit underskjema WorksAtPlant som du kan bruka til å kopla den nye medarbeidaren til ei av avdelingane i selskapet.

        Employees.odb (Tilsette) (Base-dokument)
         |
         |-- AddEmployee (FormDocument)
              |
              |-- EmployeeData (TilsetteData) (Hovudskjema)
                   |
                   |-- WorksAtPlant (SubForm)

Eit FormDocument (skjemadokument) kan sjåast på som eit sett med skjema som gjev tilgang til datasett som for eksempel database-tabellar og -spørjinghar i LibreOffice- dokument. Du har tilgang til namna på skjema og underskjema i eit skjemadokument med Skjemanavigatoren.

### Skjema og underskjema

Eit skjemadokument er sett saman ev eitt eller fleire skjema, som igjen kan innehalda eit vilkårleg tal på underskjema. Eit skjema er eit abstrakt sett av kontrollelement som er knytte til ei bestemt datakjelde, som kan vera ei bestemt datakjelde, som igjen kan vera ein databasetabell, ei spørjing eller eit SQL SELECT-uttrykk.

I Calc- og Writer-dokument kan kvart skjema koplast til datasett plassert i ulike databasar. På den andre sida, kan databasar i Base-dokument vera felles for alle skjemaa.

For å kalla opp tenesta SFDocuments.Form referererd dutil metodane Forms(), FormDocuments() og OpenFormDocument() i tenesta SFDocuments.Document

## Oppkall av tenester

Før du brukar tenesta Form, må ScriptForge-biblioteket lastast inn eller importerast:

• Grunnleggjande makroar krev innlasting av biblioteket ScriptForge ved hjelp av denne setninga:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-skript krev import frå scriptforge-modulen:
from scriptforge import CreateScriptService

### I Writer-dokument

Kodesnutten nedanfor viser korleis du får tilgang til skjemaet med namnet Form1 i ei Writer-fil:

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

Du kan få tilgang til skjema etter namnet deira eller med indeksar slik som vist nedanfor:

         Set myForm = oDoc.Forms(0)

##### I Python

         my_form = doc.Forms(0)

Viss du prøver å få tilgang til eit FormDocument som er opna i Utformingsmodus, vert det sett opp eit unntak.

### I Calc-dokument

Eit skjema i ei Calc-fil må ha eit unikt namn i tabellen. Difor krev metoden Forms to argument, det første som viser tabellnamnet og det andre som viser skjemanamnet.

          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 oppnår du på same måte med Python:

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

### I Base-dokument

Eit FormDocument i eit Base-dokument vert opna med namnet. Eksempelet nedanfor opnar skjemadokumentet kalla thisFormDocument og får tilgang til skjemaet MainForm

          Dim oDb As Object, myForm As Object
          Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
          ' Uttrykket nedanfor er nødvendig berre viss skjemaet ikkje er opna.
          oDb.OpenFormDocument("thisFormDocument")
          Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
          ' Eller alternativt for å få tilgang til skjemaet med indeksen for det …
          Set myForm = oDb.Forms("thisFormDocument", 0)

For å utføra ei handling på eit skjema ved å bruka tenesta Form, må FormDocument vera opna anten manuelt av brukaren eller av programmet i eit brukarskript. Det siste kan ein gjera ved å kalla opp metoden OpenFormDocument i tenesta Base.

For å få tilgang til eit gjeve underskjema brukar du metoden SubForms. Merk at i eksempelet nedanfor er mySubForm ein ny førekomst av tenesta Form.

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

Dei tidlegare eksempla vert omsette i Python som:

         db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
         # Uttrykket nedanfor er nødvendig berre viss skjemaet ikkje er opna.
         form_doc = db.OpenFormDocument('thisFormDocument')
         form = form_doc.Forms('thisFormDocument', 'MainForm')
         #  eller alternativt for å få tilgang til skjemaet med indeksen for det …
         form = form_doc.Forms('thisFormDocument', 0)
         sub_form = form.SubForms('mySubForm')

### I skjemahendingar

For å kalla opp tenesta Form når ei hending finn stad:

          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

Tenesta FormEvent vert brukt berre til å laga førekomstar av tenestene SFDocuments.Form og SFDocuments.FormControl når når det dukkar opp ei skjema- eller kontrollhending.

Det vert tilrådd å frigjera ressursar etter å ha brukt tenesta «Form».

         myForm.Dispose() ' Basic

         form.Dispose()  # Python

Denne handlinga vert utført utan vilkår når eit skjemadokument vert lukka med metoden CloseFormDocument() forklart nedanfor.

## Eigenskapar

Namn | Skriveverna | Type | Beskriving
--- | --- | --- | ---
AllowDeletes | Nei | Boolean | Spesifiserer om skjemaet tillèt at postar vert sletta.
AllowInserts | Nei | Boolean | Spesifiserer om skjemaet tillèt at det vert lagt til postar.
AllowUpdates | Nei | Boolean | Spesifiserer om skjemaet tillèt at postar vert oppdaterte.
BaseForm | Ja | String | Spesifiserer det hierarkiske namnet på Base-formularet som inneheld det aktuelle skjemaet.
Bookmark | Nei | Variant | Spesifiserer eintydig den aktuelle posten i skjemaet sin underliggjande tabell, spørjing eller SQL-uttrykk.
CurrentRecord | Nei | Long | Identifiserer den gjeldande posten i datasettet som vert vist i eit skjema. Viss radnummeret er positivt,vert markøren flytt til det gjevne radnummeret i forhold til byrjinga av resultatsettet. Talet på rader byrjar på 1. Viss det gjevne radnummeret er negativt, vert markøren flytt til ei absolutt radplassering i forhold til slutten av resultatsettet. Rad -1 refererer til den siste rada i resultatsettet.
Filter | Nei | String | Spesifiserer ei delmengd av postar som skal visast som ein SQL WHERE-setning utan nøkkelordet WHERE.
LinkChildFields | Ja | String | Set korleis postar i eit underliggjande skjema er lenkja til eit overliggjande skjema.
LinkParentFields | Ja | String | Set korleis postar i eit underliggjande skjema er lenkja til eit overliggjande skjema.
Name | Ja | String | Namnet på det gjeldande skjemaet.
OrderBy | Nei | String | Spesifiserer kva rekkjefølgje postar skal visast som ein SQL ORDER BY-setning utan nøkkelordet ORDER BY.
Parent | Ja | Object | Opphavet til det gjeldande skjemaet. Det kan vera eit av objekta SFDocuments.Form eller SFDocuments.Document
RecordSource | Nei | String | Gjev datakjelda som eit tabellnamn, eit spørjingsnamn eller eit SQL-yttrykk.
XForm | Ja | UNO objekt | UNO-objektet som representerer samhandlingar med skjemaet. Du finn detaljert informasjon i API-dokumentasjonen XForm og DataFoirm.

## Hendingseigenskapar

Eigenskapane nedanfor returnerer eller set URI-strengar som definerer eit skript som vert opna av hendinga.

Namn | Skriveverna | Basic IDE-beskriving
--- | --- | ---
OnApproveCursorMove | Nei | Før endring av post
OnApproveParameter | Nei | Fyllparametrar
OnApproveReset | Nei | Før nullstilling
OnApproveRowChange | Nei | Før posthandlinga
OnApproveSubmit | Nei | Før sendinga
OnConfirmDelete | Nei | Stadfest sletting
OnCursorMoved | Nei | Etter endring av post
OnErrorOccurred | Nei | Det oppstod ein feil
OnLoaded | Nei | Ved lasting
OnReloaded | Nei | Ved lasting på nytt
OnReloading | Nei | Før lasting på nytt
OnResetted | Nei | Etter tilbakestilling
OnRowChanged | Nei | Etter posthandling
OnUnloaded | Nei | Ved utlasting
OnUnloading | Nei | Før utlasting

Du kan læra meir om URI-strengar i Scripting Framework URI Specification.

Liste over metodar i tenesta Form
Activate Controls GetDatabase MoveFirst | MoveLast MoveNext MoveNew | MovePrevious Requery SubForms

## Activate

Set fokus på det gjeldande førekomsten av Form. Returner Sann viss fokuseringa lukkast.

Verkemåten til metoden Activate er avhengig av kva type dokument skjemaet er i:

- I Writer-dokument: Set fokus på dokumentet.

- I Calc-dokument: Set fokus på det arket som skjemaet er i.

- I Base-dokument: Set fokus på det FormDocument Form visar til.

### Syntaks:

svc.Activate(): bool

### Eksempel:

Det følgjande eksempelet går ut frå at du ønskjer å bruka skjemaet FormA (skjemaA) på Ark1 i den gjeldande opne Calc-fila. Det får først tilgang til dokumentet med tenesta Document og ThisComponent og slår deretter på skjemaet.

         ' Mottek skjemaet som vert aktivert
         Dim oDoc as Object, myForm as Object
         Set oDoc = CreateScriptService("Document", ThisComponent)
         Set myForm = oDoc.Forms("Sheet1", "FormA")
         ' Aktivere skjemaet
         myForm.Activate()

##### I Python

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

ThisComponent gjeld for Calc- og Writer-dokument. For Base-dokument, bruk ThisDataBaseDocument.

## CloseFormDocument

Denne metoden er utdatert, bruk metoden ScriptForge.FormDocument.CloseDocument i staden.

Lukker det skjemadokumentet som inneheld den aktuelle førekomsten av Form. Førekomsten av Form vert sletta.

### Syntaks:

svc.CloseFormDocument(): bool

### Eksempel:

          myForm.CloseFormDocument() ' Basic

##### I Python

          form.CloseFormDocument()  # Python

## Controls

Verdien som vert returnert av metoden Controls er avhengig av dei gjevne argumenta:

- Viss metoden vert kalla opp utan argument, vert lista over kontrollelementa som finst i skjemaet returnert. Merk at lista ikkje inneheld kontrollelement for underskjema.

- Viss det valfrie argumentet ControlName er gjeve, returnerer metoden ein klasse-førekomst av FormControl som visar til det gjevne kontrollelementet.

### Syntaks:

svc.Controls(opt controlname: str): any

### Parametrar:

controlname: Eit gyldig kontrollnamn som ein streng (som skil mellom små og store bokstavar). Viss denne manglar vert lista over kontrollnamn returnert som ei nullbasert matrise.

### 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 ein førekomst av SFDatabases.Database som gjev tilgang til å utføra SQL-kommandoar på den databasen det gjeldande skjemaet er knytt til og/eller lagra i.

Kvart skjema har si eiga databasetilkopling, bortsett frå i Base-dokument der alle deler same tilkoplinga.

### Syntaks:

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

### Parametrar:

user, password: Dei valfrie parameterane for pålogging (Standard = "").

### Eksempel:

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

##### I Python

          db = form.GetDatabase()  # SFDatabases.Database

## MoveFirst

Skjemamarkøren er plassert på den første posten. Returnerer Sann viss det lukkast.

### Syntaks:

svc.MoveFirst(): bool

### Eksempel:

          myForm.MoveFirst() ' Basic

##### I Python

          form.MoveFirst()  # Python

## MoveLast

Skjemamarkøren er plassert på den siste posten. Returnerer Sann viss det lukkast.

### Syntaks:

svc.MoveLast(): bool

### Eksempel:

          myForm.MoveLast() ' Basic

##### I Python

          form.MoveLast()  # Python

## MoveNew

Skjemamarkøren er plassert på området for ny post. Returnerer Sann viss det lukkast.

### Syntaks:

svc.MoveNew(): bool

### Eksempel:

          myForm.MoveNew() ' Basic

##### I Python

          form.MoveNew()  # Python

## MoveNext

Skjemamarkøren er plassert på den neste posten. Returnerer Sann viss det lukkast.

### Syntaks:

svc.MoveNext(opt offset: int): bool

### Parametrar:

offset: Talet på postar som du skal gå framover (standard = 1).

### Eksempel:

          myForm.MoveNext() ' Basic

##### I Python

          form.MoveNext()  # Python

## MovePrevious

Skjemamarkøren er plassert på den førre posten. Returnerer Sann viss det lukkast.

### Syntaks:

svc.MovePrevious(opt offset: int): bool

### Parametrar:

offset: Talet på postar som du skal gå bakover (standard = 1).

### Eksempel:

          myForm.MovePrevious() ' Basic

          form.MovePrevious()  # Python

## Requery

Lastar inn gjeldande data frå databasen på nytt og oppdaterer skjemaet. Markøren er plassert på den første posten. Returnerer Sann viss det lukkast.

### Syntaks:

svc.Requery(): bool

### Eksempel:

          myForm.Requery() ' Basic

##### I Python

          form.Requery()  # Python

## Subforms

Verdien som vert returnert av metoden Subforms avhenger av dei gjevne argumenta:

- Viss metoden som er kalla utan argument vert kalla opp, returnerer han lista over underskjema i det gjeldande skjemaet eller i eit underskjema.

- Viss det valfrie argumentet subform er oppgjeve, returnerer metoden eit nyt eksemplar av SFDocuments.Form basert på namnet på eller indeksen til det spesifiserte skjemaet/underskjemaet.

### Syntaks:

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

### Parametrar:

subform: Eit underskjema lagra i den gjeldande klasseførekomsten Form gjeve ved namnet eller indeksen.

Når dette argumentet manglar, returnerer metoden ei liste over tilgjengelege underskjema som ei null-basert matrise. Viss skjemaet har eitt enkelt underskjema, kan du setja subform = 0 for å få tilgang til det.

### 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-rutinane og -identifikatorane som vert innleidde med understrek «_» er reserverte for internt bruk. Dei er ikkje meint brukte i Basic-makroar.

Liknande emne

Tenesta SFDatabases.Database

Tenesta SFDocuments.Document

Tenesta ScriptForge.UI

Støtt oss!