Vsebina

# Storitev SFDocuments.Form

Storitev Form ponuja metode in lastnosti za upravljanje z obrazci v dokumentih LibreOffice. Storitev podpira obrazce v dokumentih programov Base, Calc in Writer ter omogoča, da:

- odprete in aktivirate obrazce;

- krmarite po zapisih, ki jih prikazuje obrazec;

- pridobite dostop do kontrolnikov v obrazcu;

- pridobite dostop do podobrazcev nadrejenega obrazca.

Storitev SFDocuments.Form je na voljo od LibreOffice 7.2 naprej.

Obrazce običajno uporabljamo v dokumentih LibreOffice za ustvarjanje uporabniških vmesnikov, povezanih z relacijskimi zbirkami podatkov. Zato ponuja storitev Form hiter dostop do povezane zbirke podatkov prek storitve SFDatabases.Database.

Storitev SFDocuments.Form je sorodna s storitvijo SFDocuments.FormControl.

## Definicije

### FormDocument

Obrazci so običajno ustvarjeni v dokumentih Base, lahko pa jih tudi dodamo dokumentom programov Writer in Calc.

V programu Base je vsak obrazec, ki ga ustvarite s funkcionalnostjo Vstavi – Obrazec ali s Čarovnikom za obrazce dejansko obrazec dokumenta FormDocument, s katerim lahko ravnate s storitvijo Form. Dokumenti Base lahko vsebujejo neomejeno število dokumentov obrazcev.

Sledi primer, ki prikazuje hierarhijo vseh elementov, ki so vpleteni v dostop do obrazcev in podobrazcev v dokumentu Base. Recimo, da imamo datoteko programa Base o zaposlenih Employees.odb, v njej pa smo ustvarili dokument obrazca, da v zbirko podatkov dodajamo nove zaposlene. Obrazec dokumenta vsebuje glavni obrazec EmployeeData, ki ponuja dostop do tabele. Na voljo je tudi podobrazec WorksAtPlant, ki omogoča, da povežete novega zaposlenega z eno od tovarn podjetja.

        Employees.odb (dokument Base)
         |
         |-- AddEmployee (FormDocument)
              |
              |-- EmployeeData (glavni obrazec)
                   |
                   |-- WorksAtPlant (SubForm)

FormDocument lahko razumemo kot množico obrazcev, ki ponujajo dostop do nabora podatkov, kot so tabele in poizvedbe zbirke podatkov v samih dokumentih LibreOffice. Do imen obrazcev in podobrazcev v dokumentu obrazca (FormDocument) lahko dostopate s Krmarjem po obrazcih.

### Obrazci in podobrazci

Dokument obrazca sestavlja en ali več obrazcev, ki lahko vsebujejo poljubno število podobrazcev. Obrazec je abstrakten nabor kontrolnikov, ki so povezani z določenim virom podatkov, ki je lahko tabela zbirke podatkov, poizvedba ali SQL-izjava SELECT.

V dokumentih programov Calc in Writer je lahko vsak obrazec povezan z nabori podatkov, ki se nahajajo v različnih zbirkah podatkov. Na drugi strani je v dokumentih programa Base vsebovana zbirka podatkov skupna vsem obrazcev.

Če želite priklicati storitev SFDocuments.Form, si oglejte metode Forms(), FormDocuments() in OpenFormDocument()storitve SFDocuments.Document

## Priklic storitve

Pred uporabo storitve Form je potrebno naložiti ali uvoziti knjižnico ScriptForge:

• Za makre Basic mora biti naložena knjižnica ScriptForge z naslednjim ukazom:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Za skripte Python mora biti opravljen uvoz iz modula scriptforge:
from scriptforge import CreateScriptService

### V dokumentih programa Writer

Spodnji odlomek kode prikazuje, kako dostopate do obrazca Form1, ki se nahaja v datoteki programa Writer:

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

##### V Pythonu

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

Do obrazcev lahko dostopate z njihovimi imeni ali z njihovimi indeksi, kar je prikazano spodaj:

         Set myForm = oDoc.Forms(0)

##### V Pythonu

         my_form = doc.Forms(0)

Če poskusite dostopati do dokumenta obrazca FormDocument, ki je trenutno odprt v oblikovalnem načinu, bo priklicana izjema.

### V dokumentih programa Calc

Vsak obrazec v datoteki programa Calc mora imeti enkratno ime v okviru istega delovnega lista. Zato metoda Forms zahteva dva argumenta, prvi določa ime delovnega lista, drugi pa ime obrazca.

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

Isto dosežete v Pythonu na sledeč način:

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

### V dokumentih programa Base

Do dokumenta FormDocument v dokumentu programa Base dostopate z njegovim imenom. Naslednji primer odpre dokument obrazca z imenom thisFormDocument in dostopa do obrazca MainForm:

          Dim oDb As Object, myForm As Object
          Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
          ' Spodnji ukaz je potreben le, če obrazec še ni odprt
          oDb.OpenFormDocument("thisFormDocument")
          Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
          ' Ali če želite do obrazca dostopati z njegovim indeksom ...
          Set myForm = oDb.Forms("thisFormDocument", 0)

Če želite z obrazcem izvesti dejanje z uporabo storitve Form, morate odpreti FormDocument ročno kot uporabnik ali programsko z uporabniškim skriptom. Slednje lahko storite s klicem metode OpenFormDocument storitve Base.

Za dostop do danega podobrazca obrazca uporabite metodo SubForms. Upoštevajte, da je v spodnjem primeru mySubForm nova instanca storitve Form.

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

Zgornje primere lahko prevedemo v Python na sledeč način:

         db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
         #  Spodnji ukaz je potreben le, če obrazec še ni odprt
         form_doc = db.OpenFormDocument('thisFormDocument')
         form = form_doc.Forms('thisFormDocument', 'MainForm')
         #  Ali če želite do obrazca dostopati z njegovim indeksom ...
         form = form_doc.Forms('thisFormDocument', 0)
         sub_form = form.SubForms('mySubForm')

### Dogodki v obrazcu

Za priklic storitve Form ob dogodku obrazca:

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

##### V Pythonu

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

Storitev FormEvent se uporablja izključno za ustvarjanje instanc storitev SFDocument.Form in SFDocuments.FormControl, ko se zgodi dogodek obrazca ali kontrolnika.

Priporočamo, da po uporabi storitve Form sprostite vire.

         myForm.Dispose() ' Basic

         form.Dispose()  # Python

Ta operacija se izvrši implicitno, ko zaprete dokument obrazca z metodo CloseFormDocument(), ki je opisana v nadaljevanju.

## Lastnosti

Ime | Samo za branje | Vrsta | Opis
--- | --- | --- | ---
AllowDeletes | Ne | Boolean | Določa, ali obrazec dovoljuje brisanje zapisov.
AllowInserts | Ne | Boolean | Določa, ali obrazec dovoljuje dodajanje zapisov.
AllowUpdates | Ne | Boolean | Določa, ali obrazec dovoljuje posodabljanje zapisov.
BaseForm | Da | String | Določa hierarhično ime obrazca Base, ki vsebuje dejanski obrazec.
Bookmark | Ne | Variant | Enkratno določa trenutni zapis obrazca v tabeli, poizvedbi ali izjavi SQL.
CurrentRecord | Ne | Long | V naboru podatkov identificira trenutni zapis, prikazan v obrazcu. Če je podano število vrstic pozitivno, se kazalka premakne na podano številko vrstice glede na začetek množice rezultatov. Štetje vrstic se začne z 1. Če je podano število vrstic negativno, se kazalka premakne na absolutni položaj vrstic glede na konec množice rezultatov. Vrstica -1 se sklicuje na zadnjo vrstico v množici rezultatov.
Filter | Ne | String | Določa podmnožico zapisov, ki bodo prikazani kot stavek SQL WHERE, vendar brez ključne besede WHERE.
LinkChildFields | Da | String | Določa, koliko zapisov v podrejenem podobrazcu je povezanih z zapisi v njegovem nadrejenem obrazcu.
LinkParentFields | Da | String | Določa, koliko zapisov v podrejenem podobrazcu je povezanih z zapisi v njegovem nadrejenem obrazcu.
Name | Da | String | Ime trenutnega obrazca.
OrderBy | Ne | String | Določa, v kakšnem zaporedju naj bodo prikazani zapisi kot stavek SQL ORDER BY, vendar brez ključnih besed ORDER BY.
Parent | Da | Object | Nadrejeni oz. stariš trenutnega obrazca. Lahko je predmet SFDocuments.Form ali SFDocuments.Document.
RecordSource | Ne | String | Določa vir podatkov kot ime tabele, ime poizvedbe ali izjavo SQL.
XForm | Da | Predmet UNO | Predmet UNO, ki predstavlja interakcije z obrazcem. Podrobnosti si oglejte v dokumentaciji API-ja za vmesnik XForm in storitev DataForm.

## Lastnosti dogodka

Spodnje lastnosti vrnejo ali nastavijo nize URI, ki določajo skript, ki ga sproži dogodek.

Ime | Samo za branje | Opis Basic IDE
--- | --- | ---
OnApproveCursorMove | Ne | Pred spremembo zapisa
OnApproveParameter | Ne | Izpolni parametre
OnApproveReset | Ne | Pred ponastavljanjem
OnApproveRowChange | Ne | Pred zapisovanjem
OnApproveSubmit | Ne | Pred pošiljanjem
OnConfirmDelete | Ne | Potrditev brisanja
OnCursorMoved | Ne | Po spremembi zapisa
OnErrorOccurred | Ne | Nastala je napaka
OnLoaded | Ne | Ob nalaganju
OnReloaded | Ne | Ob ponovnem nalaganju
OnReloading | Ne | Pred ponovnim nalaganjem
OnResetted | Ne | Po ponastavitvi
OnRowChanged | Ne | Po zapisovanju
OnUnloaded | Ne | Ob zapiranju
OnUnloading | Ne | Pred zapiranjem

Če želite izvedeti več o nizih URI, si oglejte specifikacijo URI na spletni strani specifikacije URI ogrodja za skriptanje (v angl.).

Seznam metod storitve Form
Activate CloseFormDocument Controls GetDatabase | MoveFirst MoveLast MoveNext MoveNew | MovePrevious Requery SubForms

## Activate

Pozornost nastavi na trenutno instanco Form. Vrne True, če je bilo določanje pozornosti uspešno.

Vedenje metode Activate je odvisno od vrste dokumenta, v katerem se nahaja obrazec:

- V dokumentih Writer: nastavi pozornost na ta dokument.

- V dokumentih Calc: nastavi pozornost na delovni list, kateremu pripada obrazec.

- V dokumentih Base: nastavi pozornost na FormDocument, na katerega se sklicuje obrazec Form.

### Skladnja:

svc.Activate(): bool

### Primer:

Naslednji primer predvideva, da želite aktivirati obrazec z imenom FormA, ki se nahaja na delovnem listu Sheet1 trenutno odprte datoteke programa Calc. Najprej dobi dostop do dokumenta s storitvijo Document in ThisComponent, nato aktivira obrazec.

         'Dokoplje se do obrazca, ki bo aktiviran
         Dim oDoc as Object, myForm as Object
         Set oDoc = CreateScriptService("Document", ThisComponent)
         Set myForm = oDoc.Forms("Sheet1", "FormA")
         'Aktivira obrazec
         myForm.Activate()

##### V Pythonu

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

ThisComponent se uporablja za dokumente Calc in Writer. Za dokumente Base uporabite ThisDataBaseDocument.

## CloseFormDocument

Zapre dokument obrazca, ki vsebuje dejansko instanco Form. Instanca Form je odvržena.

### Skladnja:

svc.CloseFormDocument(): bool

### Primer:

          myForm.CloseFormDocument() ' Basic

##### V Pythonu

          form.CloseFormDocument()  # Python

Ta metoda le zapre dokumente obrazca, ki se nahajajo v dokumentih Base. Če je obrazec shranjen v dokumentu Writer ali Calc, klicanje CloseFormDocument nima učinka.

## Controls

Vrednost, ki jo vrne metoda Controls, je odvisna od podanih argumentov:

- Če metodo pokličete brez argumentov, vrne seznam kontrolnikov, vsebovanih v obrazcu. Upoštevajte, da vrnjeni seznam ne vsebuje kontrolnikov podobrazca.

- Če je podan neobvezni argument ControlName, metoda vrne instanco razreda FormControl, ki se sklicuje na navedeni kontrolnik.

### Skladnja:

svc.Controls(opt controlname: str): any

### Parametri:

controlname: ime veljavnega kontrolnika kot niz, razlikuje med velikimi in malimi črkami. Če ni podano, vrne seznam imen kontrolnikov kot ničelno polje.

### Primer:

          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

##### V Pythonu

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

## GetDatabase

Vrne instanco SFDatabases.Database, ki ponuja dostop do izvajanja ukazov SQL z zbirko podatkov, s katero je povezan trenutni obrazec in/ali ki je shranjena v trenutnem dokumentu programa Base.

Vsak obrazec ima svojo povezavo z zbirko podatkov, razen dokumentov programa Base, kjer si vsi delijo isto povezavo.

### Skladnja:

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

### Parametri:

user, password: parametra prijave (uporabniško ime in geslo; privzeto = "").

### Primer:

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

##### V Pythonu

          db = form.GetDatabase()  # SFDatabases.Database

## MoveFirst

Kazalec obrazca je postavljen v prvi zapis. Vrne True, če uspe.

### Skladnja:

svc.MoveFirst(): bool

### Primer:

          myForm.MoveFirst() ' Basic

##### V Pythonu

          form.MoveFirst()  # Python

## MoveLast

Kazalec obrazca je postavljen v zadnji zapis. Vrne True, če uspe.

### Skladnja:

svc.MoveLast(): bool

### Primer:

          myForm.MoveLast() ' Basic

##### V Pythonu

          form.MoveLast()  # Python

## MoveNew

Kazalec obrazca je postavljen v področje novega zapisa. Vrne True, če uspe.

### Skladnja:

svc.MoveNew(): bool

### Primer:

          myForm.MoveNew() ' Basic

##### V Pythonu

          form.MoveNew()  # Python

## MoveNext

Kazalec obrazca je postavljen v naslednji zapis. Vrne True, če uspe.

### Skladnja:

svc.MoveNext(opt offset: int): bool

### Parametri:

offset: število zapisov, za kolikor se želite pomakniti naprej (privzeto = 1).

### Primer:

          myForm.MoveNext() ' Basic

##### V Pythonu

          form.MoveNext()  # Python

## MovePrevious

Kazalec obrazca je postavljen v prejšnji zapis. Vrne True, če uspe.

### Skladnja:

svc.MovePrevious(opt offset: int): bool

### Parametri:

offset: število zapisov, za kolikor se želite pomakniti nazaj (privzeto = 1).

### Primer:

          myForm.MovePrevious() ' Basic

          form.MovePrevious()  # Python

## Requery

Ponovno naloži trenutne podatke iz zbirke podatkov in osveži obrazec. Kazalka je postavljena v prvi zapis. Vrne True, če uspe.

### Skladnja:

svc.Requery(): bool

### Primer:

          myForm.Requery() ' Basic

##### V Pythonu

          form.Requery()  # Python

## Subforms

Vrednost, ki jo vrne metoda Subforms, je odvisna od podanih argumentov:

- Če metodo pokličete brez argumentov, vrne seznam podobrazcev vsebovanih v trenutni instanci obrazca ali podobrazca.

- Če je podan neobvezni argument subform, metoda vrne novo instanco SFDocuments.Form, ki temelji na navedenem imenu ali indeksu obrazca/podobrazca.

### Skladnja:

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

### Parametri:

subform: podobrazec, shranjen v trenutni instanci razreda Form, podan z imenom ali indeksom.

Če ta argument ni prisoten, metoda vrne seznam prisotnih podobrazcev kot ničelno polje. Če ima obrazec en sam podobrazec, lahko za dostop do njega določite subform = 0.

### Primer:

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

##### V Pythonu

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

Vsi podprogrami ali identifikatorji ScriptForge Basic s predpono podčrtaja (»_«) so rezervirani za interno uporabo. Uporabi v makrih Basic ali skriptih Python niso namenjeni.

Podobne teme

Storitev SFDatabases.Database

Storitev SFDocuments.Document

Storitev ScriptForge.UI