Indhold

# Tjenesten SFDocuments.FormControl

Tjenesten FormControl (formularkontrol) giver adgang til de kontroller, der tilhører en formular, en underformular eller en tabel-kontrol i et FormDocument (formulardokument). Hver instans af tjenesten FormControl henviser til et enkelt kontrolelement i formularen. Denne tjeneste lader brugerne:

- Find og sæt kontrolelementets egenskaber repræsenteret af instansen af FormControl (formularkontrol).

- Tilgå den aktuelle værdi, der vises af kontrollen.

- Sæt fokus på den ønskede kontrol.

For at bruge tjenesten FormControl i en bestemt formular, underformular eller tabelkontrol, må alle kontroller have entydige navne.

Alternativknapper, der deler det samme gruppenavn, skal også have entydige navne.

Hovedformålet med tjenesten FormControl (formularkontrol) er at sætte og hente egenskaber og værdier, der vises af kontrollerne på en formular.

Alle kontrolelementer har egenskaben Value (værdi). Dens indhold varierer efter kontroltypen. Læs mere information i afsnittet Egenskaben Value (værdi) nedenfor.

Det er også muligt at formatere kontrollerne gennem egenskaberne XControlModel (x_kontrolmodel) og XControlView (x_kontrolvisning).

Tjenesten SFDocuments.FormControl er nært beslægtet med tjenesten SFDocuments.Form.

## Kald af tjeneste

Før brug af tjenesten FormControl 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

Tjenesten FormControl kaldes fra en eksisterende tjenesteforkomst Form gennem dens 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()

##### I Python

          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 = 'Current Time = ' + strftime("%a, %d %b %Y %H:%M:%S", localtime())

Læs mere om, hvordan du åbner et FormDocument (formulardokument) og får adgang til dets formularer på tjenestenSFDocuments.Forms hjælpeside.

Alternativ kan en instans af FormControl (formularkontrol) hentes gennem tjenesten SFDocuments.FormEvent (…formularhændelse), som returnerer den instans af SFDocuments.FormControl-klassen, som udløste hændelsen.

          Sub OnEvent(ByRef poEvent As Object)
              Dim oControl As Object
              Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)
              ' oControl repræsenterer nu den instans af FormControl-klassen, som udløste den aktuelle hændelse
              ' ...
          End Sub

##### I Python

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

Bemærk i de foregående eksempler, at forstavelsen "SFDocuments." kan udelades.

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.

## Kontroltyper

Tjenesten FormControl (formularkontrol) er tilgængelig for følgende kontroltyper:

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

## Egenskaber

Navn | Skrivebeskyttet | Type | Gælder for | Beskrivelse
--- | --- | --- | --- | ---
Action | Nej | String | Button | Angiver den handling, der udløses, når der klikkes på knappen. Accepterede værdier er: none (ingen), submitForm (indsend_formular), resetForm (nulstil_formular), refreshForm (genopfrisk_formular), moveToFirst (flyt_til_første), moveToLast (flyt_til_sidste), moveToNext (flyt_til_næste), moveToPrev (flyt_til_forrige), saveRecord (gem_post), moveToNew (flyt_til_ny), deleteRecord (slet_post), undoRecord (fortryd_post).
Caption | Nej | String | Button, CheckBox, FixedText, GroupBox, RadioButton | Angiver den tekst, der vises af kontrollen.
ControlSource | Ja | String | CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField | Angiver feltet rækkesæt (rowset) mappet til det aktuelle kontrolelement.
ControlType | Ja | String | Alle | En af kontroltyperne, der er oplistet herover.
Default | Nej | Boolean | Button | Angiver, om en af kommandoknapperne er standardknappen OK.
DefaultValue | Nej | Variant | CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Angiver standardværdien, der bruges til at initialisere en kontrol i en ny post.
Enabled | Nej | Boolean | Alle (undtagen HiddenControl (skjult_kontrol)) | Angiver om kontrollen er tilgængelig med markøren.
Format | Nej | String | DateField, TimeField, FormattedField (read-only) | Angiver formatet til visning af datoer og klokkeslæt. Det skal være en af følgende strenge: Til datoer: "Standard (kort)", "Standard (kort YY)", "Standard (kort YYYY)", "Standard (lang)", "DD/MM/YY", "MM/DD/YY", "YY/MM/DD", "DD/MM/YYYY", "MM/DD/YYYY" , "YYYY/MM/DD", "YY-MM-DD", "YYYY-MM-DD". Til klokkeslæt: "24t kort", "24t lang", "12t kort", "12t lang".
ListCount | Ja | Long | ComboBox, ListBox | Returnerer antallet af rækker i en rulleliste eller et kombinationsfelt.
ListIndex | Nej | Long | ComboBox, ListBox | Angiver, hvilket element, der er valgt i en rulleliste eller et kombinationsfelt. I tilfælde af markering af flere elementer, returneres det første elements indeks eller der sættes kun et element.
ListSource | Nej | Variant | ComboBox, ListBox | Angiver data, der er indeholdt i et kombinationsfelt eller en rulleliste som en nul-baseret matrix af strengværdier. Kombineret med ListSourceType (oplist_kildetype), kan den også indeholde navnet på en tabel, en forespørgsel eller et helt SQL-udtryk.
ListSourceType | Nej | Integer | ComboBox, ListBox | Angiver datatypen, der er indeholdt i et kombinationsfelt eller en rulleliste. Det skal være en af konstanterne i com.sun.star.form.ListSourceType.*.
Locked | Nej | Boolean | ComboBox, CurrencyField, DateField, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField | Angiver, om kontrollen er skrivebeskyttet.
MultiSelect | Nej | Boolean | ListBox | Angiver, om brugeren kan vælge flere elementer i en rulleliste.
Name | Ja | String | Alle | Kontrollens navn.
Parent | Ja | Object | Alle | Afhængigt af ophavstypen (en formular, en underformular eller et tabelkontrolelement) returneres ophavets instans af klassen SFDocuments.Form (…formular) eller SFDocuments.FormControl (formularkontrol).
Picture | Nej | String | Button, ImageButton, ImageControl | Angiver filnavnet, der indeholder et bitmap eller en anden type grafik, der skal vises på kontrollen. Filnavnet stemme overens med attributten FileNaming (filnavngivelse) i tjenesten ScriptForge.FileSystem (…filsystem).
Required | Nej | Boolean | CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | En kontrol kaldes nødvendig, når de underliggende data ikke må indeholde værdien null.
Text | Ja | String | ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField | Giver adgang til teksten, der vises af kontrollen.
TipText | Nej | String | Alle (undtagen HiddenControl (skjult.kontrol)) | Angiver teksten, der ses som et værktøjstip, når du holder markøren over kontrollen.
TripleState | Nej | Boolean | CheckBox | Angiver, om kontrollens afkrydsningsfelt må vises nedtonet (gråt) eller ej.
Value | Nej | Variant |  | Denne egenskab afhænger af den aktuelle kontroltype. Se mere information i Egenskaben Value (værdi).
Visible | Nej | Boolean | Alle (undtagen HiddenControl(skjult_kontrol)) | Angiver, om kontrollen er skjult eller synlig.
XControlModel | Ja | UNO- objekt | Alle | UNO objektet, der repræsentererthe kontrolmodellen. Se mere information XControlModel og UnoControlModel i the API-dokumentationen.
XControlView | Ja | UNO- objekt | Alle | UNO objektet, der repræsenterer kontrolvisningen. Se mere information om XControl og UnoControl i API-dokumentationen.

## Egenskaben Value (værdi)

Kontroltype | Type | Beskrivelse
--- | --- | ---
Button | Boolean | Kun til at slå knapper til/fra
CheckBox | Boolsk eller heltal | 0, False (falsk): ikke tjekket 1, True (sand): tjekket 2: nedtonet, ved ikke (gælder, hvis TripleState er True (sand))
ComboBox | String | Den valgte værdi som en streng. Egenskaben ListIndex (listeindeks) er en alternativ indstilling til at tilgå den valgte værdis indeks.
CurrencyField | Numerisk |
DateField | Date |
FileControl | String | Et filnavn formateret i overensstemmelse med egenskaben FileNaming i tjenesten ScriptForge.FileSystem
FormattedField | Streng eller numerisk |
HiddenControl | String |
ListBox | Streng eller en matrix af strenge | De valgte rækker som en enkelt streng eller en matrix af strenge. Kun en enkelt værdi kan sættes. Hvis felter er knyttet til databasen, henter eller sætter denne egenskab de underliggende data. Ellers henter eller sætter den de viste data.
NumericField | Numerisk |
PatternField | String |
RadioButton | Boolean | Hver knap har sit eget navn. Flere Alternativ-kontroller er knyttet sammen, når de har fælles gruppenavn. Hvis en alternativknap er sat til True (sand), sættes de andre beslægtede knapper automatisk til False (falsk)
ScrollBar | Numerisk | Skal være inden for de foruddefinerede grænser
SpinButton | Numerisk | Skal være inden for de foruddefinerede grænser
TextField | String | Teksten, der vises i feltet
TimeField | Date |

## Hændelsesegenskaber

Egenskaberne herunder returnerer eller sætter URI-strenge, der definerer det script, der udløses af hændelsen.

Navn | Skrivebeskyttet | Beskrivelse ifølge etiketten i Basic IDE
--- | --- | ---
OnActionPerformed | Nej | Udfør handling
OnAdjustmentValueChanged | Nej | Under justering
OnApproveAction | Nej | Godkend handling
OnApproveReset | Nej | Før nulstilling
OnApproveUpdate | Nej | Før opdatering
OnChanged | Nej | Ændret
OnErrorOccurred | Nej | Fejl opstod
OnFocusGained | Nej | Når fokus modtages
OnFocusLost | Nej | Når fokus mistes
OnItemStateChanged | Nej | Elementstatus ændret
OnKeyPressed | Nej | Tast trykket
OnKeyReleased | Nej | Tast sluppet
OnMouseDragged | Nej | Mus flyttet mens tast trykkes
OnMouseEntered | Nej | Mus indenfor
OnMouseExited | Nej | Mus udenfor
OnMouseMoved | Nej | Mus flyttet
OnMousePressed | Nej | Museknap trykket
OnMouseReleased | Nej | Museknap sluppet
OnResetted | Nej | Efter nulstilling
OnTextChanged | Nej | Tekst ændret
OnUpdated | Nej | Efter opdatering

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

Liste over metoder i tjenesten FormControl (formularkontrol)
Controls | SetFocus

## Controls

Denne metode gælder kun for kontroller af typen TableControl (tabelkontrol). Den returnerede værdi afhænger af de angivne parametre.

Hvis det frivillige argument controlname (kontrolnavn) mangler, returneres en nul-baseret matrix, der indeholder navnene på alle kontrolelementer.

På den anden side returnerer metoden, hvis der er anført et controlname (kontrolnavn), et klasseeksemplar FormControl, der svarer til det angivne kontrolelement.

### Syntaks:

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

svc.Controls(controlname: str): svc

### Parametre:

kontrolnavn: Et gyldigt kontrolnavn som en streng med forskel på store og små bogstaver. Hvis det mangler, returneres listen over kontrolnavnene som en nul-baseret matrix.

### Eksempel:

          Dim myGrid As Object, myList As Variant, myControl As Object
          Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
          ' Returnerer en matrix med navnene på alle kontrolller i "myTableControl" (min_tabelkontrol)
          myList = myGrid.Controls()
          ' Returnerer en instans af klassen FormControl (formularkontrol), som svarer til "myCheckBox" (mit_tjekfelt)
          Set myControl = myGrid.Controls("myCheckBox")

Med Python:

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

## SetFocus

Sætter fokus på kontrollen. Returnerer True (sand), hvis fokuseringen lykkedes.

Denne metode kaldes ofte fra en formular eller kontrolhændelse

### Syntaks:

svc.SetFocus(): bool

### Eksempel:

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

##### I Python

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

## Yderligere eksempler

Herunder er der to eksempler, der illustrerer brugen af tjenesten FormControl (formularkontrol).

Det første eksempel læser den aktuelle værdi i et kombinationsfelt, der indeholder bynavne og skriver den til kontrollen FixedTest (fast_test) i en formular

         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

##### I Python

         bas = CreateScriptService('ScriptForge.Basic')  # Basic-lignende metoder
         doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
         form = doc.Forms('formDocumentName', 'formName')
         lbl_city = form.Controls('labelCity')
         combo_city = form.Controls('comboboxCity')
         lbl_city.Caption = "Valgt by: " + combo_city.Value

Den følgende kodestump kan bruges til at behandle alternativkontrollerne, der har fælles gruppenavn. I dette eksempel antages det, at der er tre alternativknapper med navnene optA, optB og optC og vi vil vise den valgte kontrols feltpåskrift

         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 (beskedfelt) "Valgt indstilling: " & optControl.Caption
                 Exit For
             End If
         Next opt

##### I Python

         bas = CreateScriptService('ScriptForge.Basic')  # Basic-lignende metoder
         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('Valgt indstilling: ' + control.Caption)
               break

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

Tjenesten SFDocuments.Form

Tjenesten SFDocuments.Document