Vsebina

# Storitev SFDocuments.FormControl

Storitev FormControl omogoča dostop do kontrolnikov, ki pripadajo obrazcu, podobrazcu ali kontrolniku tabele FormDocument. Vsaka instanca storitve FormControl se nanaša na posamezen kontrolnik v obrazcu. Ta storitev omogoča uporabnikom:

- pridobiti in določiti lastnosti kontrolnika, ki ga predstavlja instanca FormControl;

- dostopati do trenutne vrednosti, ki jo prikazuje kontrolnik;

- določiti pozornost na želeni kontrolnik.

Če želite uporabiti storitev FormControl v določenem obrazcu, podobrazcu ali kontrolniku tabele, morajo imeti vsi kontrolniki enkratna imena.

Izbirni gumbi z istim imenom skupine morajo prav tako imeti enkratna imena kontrolnikov.

Glavni namen storitve FormControl je določanje in pridobivanje lastnosti in prikazanih vrednosti kontrolnikov v obrazcu.

Vsi kontrolniki imajo lastnost Value, vendar je njena vsebina odvisna od vrste kontrolnika. Podrobnosti si oglejte spodaj v razdelku Lastnost Value.

Kontrolnike lahko oblikujete prek lastnosti XControlModel in XControlView.

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

## Priklic storitve

Pred uporabo storitve FormControl 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

Storitev FormControl je priklicana iz obstoječe instance storitve Form prek njene metode Controls.

          Dim oDoc as Object, myForm As Object, myControl As Object
          Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
          Set myForm = oDoc.Forms("formDocumentName", "formName") ' SFDocuments.Form
          Set myControl = myForm.Controls("myTextBox") ' SFDocuments.FormControl
          myControl.Value = "Current time = " & Now()

##### V Pythonu

          from scriptforge import CreateScriptService
          from time import localtime, strftime
          bas = CreateScriptService('ScriptForge.Basic')
          doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
          form = doc.Forms('formDocumentName', 'formName')  # SFDocuments.Form
          control = form.Controls('myTextBox')  # SFDocuments.FormControl
          control.Value = 'Trenutni čas: ' + strftime("%a, %d %b %Y %H:%M:%S", localtime())

Podrobnosti o odpiranju FormDocument in pridobivanju dostopa do njegovih obrazcev si preberite na strani pomoči storitve SFDocuments.Form.

Instanco FormControl lahko pridobite tudi prek storitve SFDocuments.FormEvent, ki vrne instanco razreda SFDocuments.FormControl, ki je sprožila dogodek.

          Sub OnEvent(ByRef poEvent As Object)
              Dim oControl As Object
              Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)
              ' oControl zdaj predstavlja instanco razreda FormControl, ki je sprožila trenutni dogodek
              ' ...
          End Sub

##### V Pythonu

          def onEvent(event: uno):
              control = CreateScriptService('SfDocuments.FormEvent', event)

V prejšnjih primerih ste morda opazili, da lahko predpono SFDocuments. izpustite.

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

## Vrste kontrolnikov

Storitev FormControl je na voljo za naslednje vrste kontrolnikov:

Button CheckBox ComboBox CurrencyField DateField FileControl FixedText FormattedField | GroupBox HiddenControl ImageButton ImageControl ListBox NavigationBar NumericField | PatternField RadioButton ScrollBar SpinButton TableControl TextField TimeField

## Lastnosti

Ime | Samo za branje | Vrsta | Uporabno za | Opis
--- | --- | --- | --- | ---
Action | Ne | String | Button | Določa dejanje, sproženo s klikom gumba. Dovoljene vrednosti so: none (brez), submitForm (pošlji obrazec), resetForm (ponastavi obrazec), refreshForm (osveži obrazec), moveToFirst (pomakni na prvega), moveToLast (pomakni na zadnjega), moveToNext (pomakni na naslednjega), moveToPrev (pomakni na prejšnjega), saveRecord (shrani zapis), moveToNew (pomakni na novega), deleteRecord (izbriši zapis), undoRecord (razveljavi zapis).
Caption | Ne | String | Button, CheckBox, FixedText, GroupBox, RadioButton | Določa besedilo, prikazano s kontrolnikom.
ControlSource | Da | String | CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField | Določa polje nabora vrstic, preslikanih v trenutni kontrolnik.
ControlType | Da | String | Vse | Ena od zgoraj navedenih vrst kontrolnika.
Default | Ne | Boolean | Button | Določa, ali je gumb za ukaz privzeti gumb (V redu oz. OK).
DefaultValue | Ne | Variant | CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Določa privzeto vrednost za inicializacijo kontrolnika v novem zapisu.
Enabled | Ne | Boolean | Vse (razen skriti kontrolnik HiddenControl) | Določa, ali je kontrolnik dosegljiv s kazalko.
Format | Ne | String | DateField, TimeField, FormattedField (read-only) | Določa obliko za prikaz datumov in časov. Možni so le naslednji nizi: Za datume: "Standard (short)" (standardni kratki), "Standard (short YY)" (standardni kratki LL), "Standard (short YYYY)" (standardni kratki LLLL), "Standard (long)" (standardni dolgi), "DD/MM/YY" (DD/MM/LL), "MM/DD/YY" (MM/DD/LL), "YY/MM/DD" (LL/MM/DD), "DD/MM/YYYY" (DD/MM/LLLL), "MM/DD/YYYY" (MM/DD/LLLL), "YYYY/MM/DD" (LLLL/MM/DD), "YY-MM-DD" (LL-MM-DD), "YYYY-MM-DD" (LLLL-MM-DD). Za čase: "24h short" (kratek 24-urni), "24h long" (dolgi 24-urni), "12h short" (kratki 12-urni), "12h long" (dolgi 12-urni).
ListCount | Da | Long | ComboBox, ListBox | Vrne število vrstic v seznamskem polju ali kombiniranem polju.
ListIndex | Ne | Long | ComboBox, ListBox | Določa, kateri element je izbran v seznamskem polju ali kombiniranem polju. V primeru izbora več elementov hkrati vrne indeks prvega elementa ali pa je določen le en element.
ListSource | Ne | Variant | ComboBox, ListBox | Določa podatke, vsebovane v kombiniranem ali seznamskem polju kot ničelno polje z vrednostmi nizov. V kombinaciji z ListSourceType lahko vsebuje tudi ime tabele, poizvedbe ali celotno izjavo SQL.
ListSourceType | Ne | Integer | ComboBox, ListBox | Določa vrsto podatkov, vsebovanih v kombiniranem ali seznamskem polju. Biti mora ena od konstant com.sun.star.form.ListSourceType.*.
Locked | Ne | Boolean | ComboBox, CurrencyField, DateField, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField | Določa, ali je kontrolnik samo za branje.
MultiSelect | Ne | Boolean | ListBox | Določa, ali lahko uporabnik v seznamskem polju izbere več elementov.
Name | Da | String | Vse | Ime kontrolnika.
Parent | Da | Object | Vse | Glede na vrsto nadrejenega oz. stariša (obrazec, podobrazec ali kontrolnik tabele) vrne nadrejeno instanco predmeta razreda SFDocuments.Form ali SFDocuments.FormControl.
Picture | Ne | String | Button, ImageButton, ImageControl | Določa ime datoteke, ki vsebuje bitno sliko ali drugo vrsto grafike, ki bo prikazana v kontrolniku. Ime datoteke mora biti skladno z atributom FileNaming storitve ScriptForge.FileSystem.
Required | Ne | Boolean | CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Kontrolnik je zahtevan, ko osnovni podatki ne smejo vsebovati vrednosti null.
Text | Da | String | ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField | Omogoča dostop do besedila, ki ga prikaže kontrolnik.
TipText | Ne | String | Vse (razen skriti kontrolnik HiddenControl) | Določa besedilo, ki bo prikazano kot namig, ko s kazalcem miške postojite nad kontrolnikom.
TripleState | Ne | Boolean | CheckBox | Določa, ali se kontrolnik potrditvenega polja lahko izriše matirano (osivelo).
Value | Ne | Variant |  | Ta lastnost je odvisna od vrste trenutnega kontrolnika. Podrobnosti si oglejte v sestavku Lastnost Value.
Visible | Ne | Boolean | Vse (razen skriti kontrolnik HiddenControl) | Določa, ali je kontrolnik skrit ali viden.
XControlModel | Da | Predmet UNO | Vse | Predmet UNO, ki predstavlja model kontrolnika. Podrobnosti si oglejte v dokumentaciji API-ja za XControlModel in UnoControlModel.
XControlView | Da | Predmet UNO | Vse | Predmet UNO, ki predstavlja pogled kontrolnika. Podrobnosti si oglejte v dokumentaciji API-ja za XControl in UnoControl.

## Lastnost Value

Vrsta kontrolnika | Vrsta | Opis
--- | --- | ---
Button | Boolean | Samo za preklopne gumbe.
CheckBox | Logična vrednost ali celo število | 0, False: ni preverjeno 1, True: preverjeno 2: osivelo, ni znano (deluje le, če ima TripleState vrednost True)
ComboBox | String | Izbrana vrednost kot niz. Lastnost ListIndex je alternativna možnost dostopa do indeksa izbrane vrednosti.
CurrencyField | Številska |
DateField | Date |
FileControl | String | Ime datoteke, oblikovano v skladu z lastnostjo FileNaming storitve ScriptForge.FileSystem.
FormattedField | Niz ali številska |
HiddenControl | String |
ListBox | Niz ali polje nizov | Izbrane vrstice kot en sam niz ali polje nizov. Nastavite lahko samo posamezno vrednost. Če je polje povezano z zbirko podatkov, ta lastnost pridobi ali določi osnovne podatke. Sicer pridobi ali določi podatke, ki bodo prikazani.
NumericField | Številska |
PatternField | String |
RadioButton | Boolean | Vsak gumb ima svoje ime. Več izbirnih kontrolnikov RadioButton je medsebojno povezanih, če imajo isto ime skupine. Če je izbirni gumb RadioButton nastavljen na True, se drugi povezani izbirni gumbi samodejno nastavijo na False
ScrollBar | Številska | Mora biti v okviru vnaprej določenih meja
SpinButton | Številska | Mora biti v okviru vnaprej določenih meja
TextField | String | Besedilo, ki se pojavi v polju
TimeField | Date |

## Lastnosti dogodka

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

Ime | Samo za branje | Opis, kot je označen v Basic IDE
--- | --- | ---
OnActionPerformed | Ne | Izvrši dejanje
OnAdjustmentValueChanged | Ne | Med prilagajanjem
OnApproveAction | Ne | Odobri dejanje
OnApproveReset | Ne | Pred ponastavljanjem
OnApproveUpdate | Ne | Pred posodobitvijo
OnChanged | Ne | Spremenjeno
OnErrorOccurred | Ne | Nastala je napaka
OnFocusGained | Ne | Ob pridobljeni pozornosti
OnFocusLost | Ne | Ob izgubljeni pozornosti
OnItemStateChanged | Ne | Stanje elementa spremenjeno
OnKeyPressed | Ne | Tipka pritisnjena
OnKeyReleased | Ne | Tipka sproščena
OnMouseDragged | Ne | Miška premaknjena ob pritisnjeni tipki
OnMouseEntered | Ne | Kazalec miške znotraj
OnMouseExited | Ne | Kazalec miške zunaj
OnMouseMoved | Ne | Miška premaknjena
OnMousePressed | Ne | Gumb miške pritisnjen
OnMouseReleased | Ne | Gumb miške sproščen
OnResetted | Ne | Po ponastavitvi
OnTextChanged | Ne | Besedilo spremenjeno
OnUpdated | Ne | Po posodobitvi

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

Seznam metod storitve FormControl
Controls | SetFocus

## Controls

Ta metoda deluje le za kontrolnike vrste TableControl. Vrnjena vrednost je odvisna od podanih argumentov.

Če neobvezni argument controlname ni podan, vrne ničelno polje z imeni vseh kontrolnikov.

Če pa je neobvezni argument controlname podan, metoda vrne instanco razreda FormControl, ki ustreza navedenemu kontrolniku.

### Skladnja:

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

svc.Controls(controlname: str): svc

### Parametri:

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

### Primer:

          Dim myGrid As Object, myList As Variant, myControl As Object
          Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
          ' Vrne polje z imeni vseh kontrolnikov v "myTableControl"
          myList = myGrid.Controls()
          ' Vrne instanco razreda FormControl, ki ustreza "myCheckBox"
          Set myControl = myGrid.Controls("myCheckBox")

Z uporabo Pythona:

          grid = form.Controls('myTableControl')  # SFDocuments.FormControl
          control_names = form.Controls()
          control = grid.Controls('myCheckBox')  # SFDocuments.FormControl

## SetFocus

Določi pozornost na kontrolnik. Vrne True, če je bilo določanje pozornosti uspešno.

To metodo pogosto kličejo obrazci ali dogodki kontrolnika.

### Skladnja:

svc.SetFocus(): bool

### Primer:

          Dim oDoc As Object, oForm As Object, oControl As Object
          Set oDoc = CreateScriptService("SFDocuments.Document", ThisComponent)
          Set oForm = oDoc.Forms(0)
          Set oControl = oForm.Controls("thisControl") ' SFDocuments.FormControl
          oControl.SetFocus()

##### V Pythonu

         bas = CreateScriptService('ScriptForge.Basic')
         doc = CreateScriptService('SFDocuments.Document', bas.ThisComponent)
         form = doc.Forms(0)
         control = form.Controls('thisControl')  # SFDocuments.FormControl
         control.SetFocus()

## Dodatni primeri

Spodaj sta primera, ki nakazujeta uporabo storitve FormControl.

Prvi primer prebere trenutno vrednost v kombiniranem polju, ki vsebuje imena mest, in ga zapiše v kontrolnik FixedTest v obrazcu Form:

         Dim oDoc as Object, myForm as Object, myControl as Object
         Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
         myForm = oDoc.Forms("formDocumentName", "formName")
         Dim lbCity : lbCity = myForm.Controls("labelCity")
         Dim cbCity : cbCity = myForm.Controls("comboboxCity")
         lbCity.Caption = "Selected City: " & cbCity.Value

##### V Pythonu

         bas = CreateScriptService('ScriptForge.Basic')  # Metode kot v Basicu
         doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
         form = doc.Forms('formDocumentName', 'formName')
         lbl_city = form.Controls('labelCity')
         combo_city = form.Controls('comboboxCity')
         lbl_city.Caption = "Izbrano mesto: " + combo_city.Value

Naslednji odlomek kode lahko uporabite za obdelavo izbirnih gumbov (kontrolnikov RadioButton), ki imajo isto ime skupine. V tem primeru predvidevamo, da so trije izbirni gumbi z imeni optA, optB in optC ter da želimo prikazati napis izbranega kontrolnika.

         Dim oDoc as Object, myForm as Object
         Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
         myForm = oDoc.Forms("formDocumentName", "formName")
         Dim optNames As Object : optNames = Array("optA", "optB", "optC")
         Dim optControl as Object, opt as Variant
         For Each opt In optNames
             optControl = myForm.Controls(opt)
             If optControl.Value = True Then
                 MsgBox "Izbrana možnost: " & optControl.Caption
                 Exit For
             End If
         Next opt

##### V Pythonu

         bas = CreateScriptService('ScriptForge.Basic')  # Metode kot v Basicu
         doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
         form = doc.Forms('formDocumentName', 'formName')
         radio_buttons = ['optA', 'optB', 'optC']
         for name in radio_buttons:
            control = form.controls(name)
            if control.Value == True:
               bas.MsgBox('Izbrana možnost: ' + control.Caption)
               break

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 ScriptForge.Basic

Storitev SFDocuments.Form

Storitev SFDocuments.Document