SFDocuments.FormControl-service

De service FormControl biedt toegang tot de besturingselementen die horen bij een formulier, een subformulier of een tabelbesturingselement van een FormDocument. Elke instantie van de service FormControl verwijst naar een enkel besturingselement in het formulier. Met deze service kunnen gebruikers:

Eigenschappen van het besturingselement verkrijgen en instellen, dat wordt vertegenwoordigd door de instantie FormControl.
Toegang tot de huidige waarde weergegeven door het besturingselement.
De focus instellen op het gewenste besturingselement.

Om de service FormControl in een bepaald formulier, subformulier of tabelbesturingselement te gebruiken, moeten alle besturingselementen unieke namen hebben.

Keuzerondjes die dezelfde groepsnaam delen, moeten ook unieke besturingselementnamen hebben.

Het belangrijkste doel van de service FormControl is het instellen en verkrijgen van de eigenschappen en waarden die door de besturingselementen in een formulier worden weergegeven.

Alle besturingselementen hebben een eigenschap Value. De inhoud is echter afhankelijk van het type bedieningselement. Lees voor meer informatie de Value Property hieronder.

Het is ook mogelijk om de besturingselementen op te maken via de eigenschappen XControlModel en XControlView.

De service SFDocuments.FormControl is nauw verwant aan de service SFDocuments.Form.

Service aanroep

Voordat de service FormControl gebruikt kan worden, moet de bibliotheek ScriptForge eerst worden geladen of geïmporteerd:

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService

De service FormControl wordt aangeroepen via een bestaande instantie van de service Form via de methode 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()

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

Een uitleg over hoe u een FormDocument opent en toegang krijgt tot de formulieren ervan, staat hier: SFDocuments.Form.

Een instantie van FormControl kan ook worden aangemaakt via de service SFDocuments.FormEvent, die retourneert de SFDocuments.FormControl die de gebeurtenis heeft gestart.


      Sub OnEvent(ByRef poEvent As Object)
          Dim oControl As Object
          Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)
          ' oControl staat nu voor de instantie van de klasse FormControl die de huidige gebeurtenis heeft gestart
          ' ...
      End Sub

In Python


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

In de vorige voorbeelden mag het deel "SFDocuments." worden weggelaten.

De service FormEvent wordt exclusief gebruikt om instanties van de services SFDocuments.Form en SFDocuments.FormControl aan te maken wanneer er op een formulier of besturingselement een gebeurtenis plaatsvindt.

Besturingselementen

De service FormControl is beschikbaar voor de volgende besturingselementen:

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

Eigenschappen

Naam	AlleenLezen	Type	Van toepassing op	Beschrijving
Action	Nee	String	Button	Specificeert de actie die uitgevoerd moet worden als er op de knop wordt gedrukt. Geaccepteerde waarden zijn: none, submitForm, resetForm, refreshForm, moveToFirst, moveToLast, moveToNext, moveToPrev, saveRecord, moveToNew, deleteRecord, undoRecord.
Caption	Nee	String	Button, CheckBox, FixedText, GroupBox, RadioButton	Specificeert de tekst die getoond wordt op het besturingselement.
ControlSource	Ja	String	CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField	Specificeert het veld dat nu gekoppeld is aan het huidige besturingselement.
ControlType	Ja	String	Alle	Een van de bovenstaande besturingselementen.
Default	Nee	Boolean	Button	Geeft aan of een knop de standaardknop OK is.
DefaultValue	Nee	Variant	CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField	Specificeert de standaardwaarde van een besturingselement om een nieuw record te initialiseren.
Enabled	Nee	Boolean	Alle (zonder HiddenControl)	Specificeert of het besturingselement toegankelijk is met de cursor.
Format	Nee	String	DateField, TimeField, FormattedField (read-only)	Specificeert het datumformaat dat gebruikt wordt voor het tonen. De mogelijke tekenreeksen zijn: Voor datums: "Standaard (kort)", "Standaard (kort YY)", "Standaard (kort YYYY)", "Standaard (lang)", "DD/MM/JJ", "MM/DD/JJ", "JJ/MM/DD", "DD/MM/JJJJ", "MM/DD/JJJJ" , "JJJJ/MM/DD", "JJ-MM-DD", "JJJJ-MM-DD". Voor tijden: "24u kort", "24u lang", "12u kort", "12u lang".
ListCount	Ja	Long	ComboBox, ListBox	Telt het aantal rijen in een ListBox / ComboBox.
ListIndex	Nee	Long	ComboBox, ListBox	Specificeert welk item is geselecteerd in een ListBox of ComboBox. Bij meervoudige selectie wordt de index van het eerste item geretourneerd of wordt er slechts één item ingesteld.
ListSource	Nee	Variant	ComboBox, ListBox	Specificeert de gegevens in een ComboBox of een ListBox als een op nul gebaseerde matrix van tekenreeksen. In combinatie met ListSourceType kan het ook de naam van een tabel, een query of een volledige SQL-instructie bevatten.
ListSourceType	Nee	Integer	ComboBox, ListBox	Specificeert het type gegevens in een keuzelijst met invoervak of een keuzelijst. Het moet een van de com.sun.star.form.ListSourceType zijn. * constanten.
Locked	Nee	Boolean	ComboBox, CurrencyField, DateField, FileControl, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField	Geeft aan of het besturingselement alleen-lezen is.
MultiSelect	Nee	Boolean	ListBox	Geeft aan of de gebruiker meerdere items in een keuzelijst kan selecteren.
Name	Ja	String	Alle	De naam van het besturingselement.
Parent	Ja	Object	Alle	Afhankelijk van het bovenliggende type, een formulier, een subformulier of een tabelbesturingselement, retourneert het bovenliggende SFDocuments.Form of SFDocuments.FormControl klasse-object-instantie.
Picture	Nee	String	Button, ImageButton, ImageControl	Specificeert de bestandsnaam die een bitmap of ander type afbeelding bevat die op het besturingselement moet worden weergegeven. De bestandsnaam moet voldoen aan het kenmerk FileNaming van de service ScriptForge.FileSystem.
Required	Nee	Boolean	CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField	Er is sprake van een controle wanneer de onderliggende gegevens geen null-waarde mogen bevatten.
Text	Ja	String	ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField	Geeft toegang tot de tekst die door het besturingselement wordt weergegeven.
TipText	Nee	String	Alle (behalve HiddenControl)	Hiermee geeft u de tekst op die wordt weergegeven als knopinfo wanneer u de muisaanwijzer over het besturingselement beweegt.
TripleState	Nee	Boolean	CheckBox	Geeft aan of het selectievakje gedimd (grijs) kan worden weergegeven of niet.
Value	Nee	Variant		Deze eigenschap is afhankelijk van het huidige besturingstype. Raadpleeg De eigenschap Value voor meer informatie.
Visible	Nee	Boolean	Alle (behalve HiddenControl)	Geeft aan of het besturingselement verborgen of zichtbaar is.
XControlModel	Ja	UNO -object	Alle	Het UNO-object dat het besturingselementmodel vertegenwoordigt. Raadpleeg XControlModel en UnoControlModel in de API-documentatie voor meer informatie.
XControlView	Ja	UNO -object	Alle	Het UNO-object dat de besturingselementweergave vertegenwoordigt. Raadpleeg XControl en UnoControl in de API-documentatie voor meer informatie.

De eigenschap Value

Type besturingselement	Type	Beschrijving
Button	Boolean	Alleen van toepassing op aan/uit knoppen.
CheckBox	Booleaans of geheel getal	0, False: niet aangevinkt 1, True: aangevinkt 2: grijs weergegeven, weet niet (van toepassing als TripleState True is)
ComboBox	String	De geselecteerde waarde, als een tekenreeks. De eigenschap ListIndex is een alternatieve optie om toegang te krijgen tot de index van de geselecteerde waarde.
CurrencyField	Numeriek
DateField	Date
FileControl	String	Een bestandsnaam die is opgemaakt in overeenstemming met de eigenschap FileNaming van de service ScriptForge.FileSystem
FormattedField	Tekenreeks of numeriek
HiddenControl	String
ListBox	Tekenreeks of matrix met tekenreeksen	De geselecteerde rij(en) als een enkele tekenreeks of een reeks tekenreeksen. Er kan slechts één waarde worden ingesteld. Als het vak is gekoppeld aan een database, haalt of stelt deze eigenschap de onderliggende gegevens in. Anders krijgt of stelt het de gegevens in die worden weergegeven.
NumericField	Numeriek
PatternField	String
RadioButton	Boolean	Elke knop heeft zijn eigen naam. Meerdere keuzerondjes zijn gekoppeld als ze dezelfde groepsnaam hebben. Wanneer een optieveld is ingesteld op True, worden de andere bijbehorende velden automatisch ingesteld op False
ScrollBar	Numeriek	Moet binnen de vooraf gedefinieerde grenzen vallen
SpinButton	Numeriek	Moet binnen de vooraf gedefinieerde grenzen vallen
TextField	String	De tekst die in het veld verschijnt
TimeField	Date

Eigenschappen gebeurtenis

De volgende eigenschappen retourneren of stellen URI-tekenreeksen in die het script definiëren dat door de gebeurtenis wordt geactiveerd.

Name	AlleenLezen	Beschrijving zoals aangegeven in de Basic IDE
OnActionPerformed	Nee	Bij het uitvoeren van een actie
OnAdjustmentValueChanged	Nee	Tijdens aanpassen
OnApproveAction	Nee	Bij het goedkeuren van actie
OnApproveReset	Nee	Voor het herstellen:
OnApproveUpdate	Nee	Voor het bijwerken
OnChanged	Nee	Gewijzigd
OnErrorOccurred	Nee	Als er een fout is opgetreden
OnFocusGained	Nee	Bij het verkrijgen van focus
OnFocusLost	Nee	Bij het verliezen van focus
OnItemStateChanged	Nee	Wanneer de itemstatus is gewijzigd
OnKeyPressed	Nee	Bij het indrukken van een toets
OnKeyReleased	Nee	Bij het loslaten van een toets
OnMouseDragged	Nee	Bij het bewegen van de muis tijdens toetsaanslagen
OnMouseEntered	Nee	Muis binnen
OnMouseExited	Nee	Muis buiten
OnMouseMoved	Nee	Muisbeweging
OnMousePressed	Nee	Muisknop ingedrukt
OnMouseReleased	Nee	Muisknop losgelaten
OnResetted	Nee	Na het herstellen
OnTextChanged	Nee	Als tekst is aangepast
OnUpdated	Nee	Na het bijwerken

Raadpleeg de Scripting Framework URI-specificatie voor meer informatie over URI-tekenreeksen.

Lijst met methoden in de service FormControl
Controls	SetFocus

Controls

Deze methode is alleen van toepassing op besturingselementen van het type TableControl. De geretourneerde waarde is afhankelijk van de opgegeven argumenten.

Als het optionele argument controlname ontbreekt, wordt een op nul gebaseerde matrix geretourneerd die de namen van alle besturingselementen bevat.

Aan de andere kant, als een controlname is opgegeven, retourneert de methode een FormControl klasse-instantie die overeenkomt met het opgegeven besturingselement.

Syntaxis:

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

svc.Controls(controlname: str): svc

Parameters:

controlname: Een geldige besturingselementnaam als hoofdlettergevoelige tekenreeks. Indien afwezig, wordt de lijst met namen van besturingselementen geretourneerd als een op nul gebaseerde matrix.

Voorbeeld:


      Dim myGrid As Object, myList As Variant, myControl As Object
      Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
      ' Retourneert een matrix met de namen van alle besturingselementen in "myTableControl"
      myList = myGrid.Controls()
      ' Retourneert een FormControl-klasse-instantie die overeenkomt met "myCheckBox
      Set myControl = myGrid.Controls("myCheckBox")

Bij het gebruik van Python:


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

SetFocus

Stelt de focus op het besturingselement in. Retourneert True als het focussen gelukt is.

Deze methode wordt vaak aangeroepen vanuit een formulier of besturingselementgebeurtenis.

Syntaxis:

svc.SetFocus(): bool

Voorbeeld:


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

In Python


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

Verdere voorbeelden

Hieronder staan twee voorbeelden die het gebruik van de service FormControl illustreren.

Het eerste voorbeeld leest de huidige waarde in een combobox met plaatsnamen en schrijft deze naar een besturingselement FixedTest op een formulier:


     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

In Python


     bas = CreateScriptService('ScriptForge.Basic')  # Basic-achtige methoden
     doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
     form = doc.Forms('formDocumentName', 'formName')
     lbl_city = form.Controls('labelCity')
     combo_city = form.Controls('comboboxCity')
     lbl_city.Caption = "Geselecteerde stad: " + combo_city.Value

Het volgende codefragment kan worden gebruikt om besturingselementen Keuzerondje te verwerken die dezelfde groepsnaam delen. Stel dat er in dit voorbeeld drie keuzerondjes zijn met de namen optA, optB en optC en dat we het bijschrift van het geselecteerde besturingselement willen weergeven.


     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 "Geselecteerde optie: " & optControl.Caption
             Exit For
         End If
     Next opt

In Python


     bas = CreateScriptService('ScriptForge.Basic')  # Basic-achtige methoden
     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('Geselecteerde optie: ' + control.Caption)
           break

Alle ScriptForge Basic-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

ScriptForge.Basic service

SFDocuments.Form-service

SFDocuments.Document-service