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

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

     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)
   

     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
   

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

Hendingseigenskapar

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

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

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.

svc.Activate(): bool

Det følgjande eksempelet går ut frå at du ønskjer å aktiverer 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 aktiverer deretter 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()
   

     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

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

svc.CloseFormDocument(): bool

      myForm.CloseFormDocument() ' Basic
   

      form.CloseFormDocument()  # Python
   

Denne metoden lukkar berre skjemadokument i Base-dokument. Viss skjemaet er lagra i eit Writer- eller Calc-dokument, er oppkall av CloseFormDocument utan verknad.

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.

svc.Controls(opt controlname: str): any

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.

      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

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.

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

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

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

      db = form.GetDatabase()  # SFDatabases.Database
   

MoveFirst

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

svc.MoveFirst(): bool

      myForm.MoveFirst() ' Basic
   

      form.MoveFirst()  # Python
   

MoveLast

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

svc.MoveLast(): bool

      myForm.MoveLast() ' Basic
   

      form.MoveLast()  # Python
   

MoveNew

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

svc.MoveNew(): bool

      myForm.MoveNew() ' Basic
   

      form.MoveNew()  # Python
   

MoveNext

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

svc.MoveNext(opt offset: int): bool

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

      myForm.MoveNext() ' Basic
   

      form.MoveNext()  # Python
   

MovePrevious

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

svc.MovePrevious(opt offset: int): bool

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

      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.

svc.Requery(): bool

      myForm.Requery() ' Basic
   

      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.

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

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.

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