Dienst SFDocuments.FormControl

Der Dienst FormControl bietet Zugriff auf die Steuerelemente, die zu einem Formular, einem Unterformular oder einem Tabellensteuerelement eines FormDocument gehören. Jede Instanz des Dienstes FormControl verweist auf ein einzelnes Steuerelement im Formular. Dieser Dienst ermöglicht Benutzern:

Das Abrufen und Festlegen der Eigenschaften des Steuerelements, das durch die Instanz FormControl dargestellt wird.
Den Zugriff auf den aktuellen Wert, der vom Steuerelement angezeigt wird.
Das Setzen des Fokus auf das gewünschte Steuerelement.

Um den Dienst FormControl in einem bestimmten Formular, Unterformular oder Tabellensteuerelement zu verwenden, müssen alle Steuerelemente eindeutige Namen haben.

Optionsfelder, die denselben Gruppennamen haben, müssen auch eindeutige Steuerelementnamen haben.

Der Hauptzweck des Dienstes FormControl ist das Festlegen und Abrufen der Eigenschaften und Werte, die von den Steuerelementen in einem Formular angezeigt werden.

Alle Steuerelemente haben eine Eigenschaft Value. Der Inhalt variiert jedoch je nach Steuerelementtyp. Weitere Informationen finden Sie unten unter Die Eigenschaft von Value.

Es ist auch möglich, die Steuerelemente über die Eigenschaften XControlModel und XControlView zu formatieren.

Der Dienst SFDocuments.FormControl ist eng verwandt mit dem Dienst SFDocuments.Form.

Dienstaufruf

Vor der Verwendung des Dienstes FormControl muss die Bibliothek ScriptForge geladen oder importiert werden:

• Grundlegende Makros erfordern das Laden der Bibliothek ScriptForge mit der folgenden Anweisung:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-Skripte erfordern einen Import aus dem Modul scriptforge:
from scriptforge import CreateScriptService

Der Dienst FormControl wird von einer bestehenden Dienstinstanz Form über seine Methode Controls aufgerufen.


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

Um mehr darüber zu erfahren, wie Sie ein FormDocument öffnen und auf seine Formulare zugreifen können, sei auf die Hilfeseite des Dienstes SFDocuments.Form verwiesen.

Alternativ kann eine Instanz FormControl über den Dienst SFDocuments.FormEvent abgerufen werden, der die Klasseninstanz SFDocuments.FormControl zurückgibt, die das Ereignis ausgelöst hat.


      Sub OnEvent(ByRef poEvent As Object)
          Dim oControl As Object
          Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)
          ' oControl stellt nun die Instanz der Klasse "FormControl" dar, die das aktuelle Ereignis ausgelöst hat
          ' ...
      End Sub

In Python


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

Beachten Sie, dass in den vorherigen Beispielen das Präfix "SFDocuments." weggelassen werden kann.

Der Dienst FormEvent wird ausschließlich zum Erstellen von Instanzen der Dienste SFDocuments.Form und SFDocuments.FormControl verwendet, wenn ein Formular- oder Steuerelementereignis stattfindet.

Steuerelementtypen

Der Dienst FormControl ist für die folgenden Steuerelementtypen verfügbar:

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

Eigenschaften

Name	Schreibgeschützt	Typ	Anwendbar auf	Beschreibung
Action	Nein	String	Button	Legt die Aktion fest, die ausgelöst wird, wenn auf die Schaltfläche geklickt wird. Akzeptierte Werte sind: none, submitForm, resetForm, refreshForm, moveToFirst, moveToLast, moveToNext, moveToPrev, saveRecord, moveToNew, deleteRecord, undoRecord.
Caption	Nein	String	Button, CheckBox, FixedText, GroupBox, RadioButton	Legt den vom Steuerelement angezeigten Text fest.
ControlSource	Ja	String	CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField	Legt das Feld "Rowset" fest, das dem aktuellen Steuerelement zugeordnet ist.
ControlType	Ja	String	Alle	Einer der oben aufgeführten Steuerelementtypen.
Default	Nein	Boolean	Button	Legt fest, ob eine Befehlsschaltfläche die Standardschaltfläche "OK" ist.
DefaultValue	Nein	Variant	CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField	Legt den Standardwert fest, der verwendet wird, um ein Steuerelement in einem neuen Datensatz zu initialisieren.
Enabled	Nein	Boolean	Alle (außer "HiddenControl")	Legt fest, ob mit dem Cursor auf das Steuerelement zugegriffen werden kann.
Format	Nein	String	DateField, TimeField, FormattedField (read-only)	Legt das Format fest, das zum Anzeigen von Datum und Uhrzeit verwendet wird. Es muss eine der folgenden Zeichenfolgen sein: Für Datumsangaben: „Standard (short)“, „Standard (short JJ)“, „Standard (short JJJJ)“, „Standard (long)“, „TT/MM/JJ“, „MM/TT/JJ“, „ JJ/MM/TT“, „TT/MM/JJJJ“, „MM/TT/JJJJ“, „JJJJ/MM/TT“, „JJ-MM-TT“, „JJJJ-MM-TT“. Für Zeiten: „24h short“, „24h long“, „12h short“, „12h long“.
ListCount	Ja	Long	ComboBox, ListBox	Gibt die Anzahl der Zeilen in einem Listenfeld oder einem Kombinationsfeld zurück.
ListIndex	Nein	Long	ComboBox, ListBox	Legt fest, welches Element in einem Listenfeld oder Kombinationsfeld ausgewählt ist. Bei Mehrfachauswahl wird der Index des ersten Eintrags zurückgegeben oder nur ein Eintrag gesetzt.
ListSource	Nein	Variant	ComboBox, ListBox	Legt die in einem Kombinationsfeld oder einem Listenfeld enthaltenen Daten als nullbasierte Matrix von Zeichenfolgen fest. Kann in Kombination mit ListSourceType auch den Namen einer Tabelle, einer Abfrage oder einer kompletten SQL-Anweisung enthalten.
ListSourceType	Nein	Integer	ComboBox, ListBox	Legt den Datentyp fest, der in einem Kombinationsfeld oder einem Listenfeld enthalten ist. Es muss eine der Konstanten com.sun.star.form.ListSourceType.* sein.
Locked	Nein	Boolean	ComboBox, CurrencyField, DateField, FileControl, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField	Legt fest, ob das Steuerelement schreibgeschützt ist.
MultiSelect	Nein	Boolean	ListBox	Legt fest, ob der Benutzer mehrere Elemente in einem Listenfeld auswählen kann.
Name	Ja	String	Alle	Der Name des Steuerelements.
Parent	Ja	Object	Alle	Je nach übergeordnetem Typ gibt ein Formular, ein Unterformular oder ein Tabellensteuerelement die übergeordnete Klassenobjektinstanz SFDocuments.Form oder SFDocuments.FormControl zurück.
Picture	Nein	String	Button, ImageButton, ImageControl	Legt den Dateinamen fest, der eine Bitmap oder einen anderen Grafiktyp enthält, die auf dem Steuerelement angezeigt werden soll. Der Dateiname muss dem Attribut FileNaming des Dienstes ScriptForge.FileSystem entsprechen.
Required	Nein	Boolean	CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField	Ein Steuerelement wird als erforderlich bezeichnet, wenn die zugrunde liegenden Daten keine Werte vom Typ null enthalten dürfen.
Text	Ja	String	ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField	Ermöglicht den Zugriff auf den Text, der vom Steuerelement angezeigt wird.
TipText	Nein	String	Alle (außer HiddenControl)	Legt den Text fest, der als Info angezeigt wird, wenn Sie den Mauszeiger über das Steuerelement bewegen.
TripleState	Nein	Boolean	CheckBox	Legt fest, ob das Kontrollkästchen abgeblendet (grau) angezeigt werden soll oder nicht.
Value	Nein	Variant		Diese Eigenschaft hängt vom aktuellen Steuerelementtyp ab. Weitere Informationen finden Sie unter Die Eigenschaft Value.
Visible	Nein	Boolean	Alle (außer HiddenControl)	Legt fest, ob das Steuerelement ausgeblendet oder sichtbar ist.
XControlModel	Ja	UNO Objekt	Alle	Das UNO-Objekt, welches das Steuerelementmodell darstellt. Siehe XControlModel und UnoControlModel in der API-Dokumentation für weitere Informationen.
XControlView	Ja	UNO Objekt	Alle	Das UNO-Objekt, das die Steuerelementansicht darstellt. Siehe XControl und UnoControl in der API-Dokumentation für weitere Informationen.

Die Eigenschaft Value

Steuerelementtyp	Typ	Beschreibung
Button	Boolean	Gilt nur für Wechselschaltflächen.
CheckBox	Boolean oder Integer	0, False: nicht angekreuzt 1, True: angekreuzt 2: ausgegraut, unbekannt (anwendbar, wenn TripleState True ist)
ComboBox	String	Der ausgewählte Wert als Zeichenfolge. Die Eigenschaft ListIndex ist eine alternative Option, um auf den Index des ausgewählten Werts zuzugreifen.
CurrencyField	Numeric
DateField	Date
FileControl	String	Ein Dateiname, der gemäß der Eigenschaft FileNaming des Dienstes ScriptForge.FileSystem formatiert ist
FormattedField	String oder Numeric
HiddenControl	String
ListBox	String oder Matrix mit Strings	Die ausgewählte(n) Zeile(n) als einzelne Zeichenfolge oder als Matrix von Zeichenfolgen. Es kann nur ein einzelner Wert gesetzt werden. Wenn das Feld mit einer Datenbank verknüpft ist, ruft diese Eigenschaft die zugrunde liegenden Daten ab oder setzt sie. Andernfalls erhält oder setzt es die angezeigten Daten.
NumericField	Numeric
PatternField	String
RadioButton	Boolean	Jede Schaltfläche hat einen eigenen Namen. Mehrere Optionsfelder sind miteinander verknüpft, wenn sie denselben Gruppennamen haben. Wenn ein Optionsfeld auf True gesetzt ist, werden die anderen zugehörigen Felder automatisch auf False gesetzt
ScrollBar	Numeric	Muss innerhalb der vordefinierten Grenzen liegen
SpinButton	Numeric	Muss innerhalb der vordefinierten Grenzen liegen
TextField	String	Der Text, der im Feld erscheint
TimeField	Date

Ereigniseigenschaften

Die folgenden Eigenschaften geben URI-Zeichenfolgen zurück oder legen sie fest, die das durch das Ereignis ausgelöste Skript definieren.

Name	Schreibgeschützt	Beschreibung wie in der Basic-IDE angegeben
OnActionPerformed	Nein	Beim Aktion ausführen
OnAdjustmentValueChanged	Nein	Beim Einstellen
OnApproveAction	Nein	Beim Aktion genehmigen
OnApproveReset	Nein	Vor dem Zurücksetzen
OnApproveUpdate	Nein	Vor dem Aktualisieren
OnChanged	Nein	Wenn geändert
OnErrorOccurred	Nein	Wenn ein Fehler aufgetreten ist
OnFocusGained	Nein	Beim Erhalten des Fokus
OnFocusLost	Nein	Beim Verlust des Fokus
OnItemStateChanged	Nein	Wenn Artikelstatus geändert
OnKeyPressed	Nein	Wenn Taste gedrückt
OnKeyReleased	Nein	Beim Taste Loslassen
OnMouseDragged	Nein	Wenn die Maus bewegte wird, während eine Taste gedrückt ist
OnMouseEntered	Nein	Wenn Maus innerhalb
OnMouseExited	Nein	Wenn Maus außerhalb
OnMouseMoved	Nein	Bei Mausbewegung
OnMousePressed	Nein	Wenn Maustaste gedrückt
OnMouseReleased	Nein	Wenn Maustaste losgelassen
OnResetted	Nein	Nach dem Zurücksetzen
OnTextChanged	Nein	Wenn Texte geändert
OnUpdated	Nein	Nach dem Aktualisieren

Weitere Informationen zu URI-Zeichenfolgen finden Sie unter Scripting Framework URI Specification.

Liste der Methoden im Dienst FormControl
Controls	SetFocus

Controls

Diese Methode ist nur auf Steuerelemente vom Typ TableControl anwendbar. Der zurückgegebene Wert hängt von den bereitgestellten Argumenten ab.

Wenn das optionale Argument controlname fehlt, wird eine nullbasierte Matrix zurückgegeben, welche die Namen aller Steuerelemente enthält.

Wenn andererseits controlname vorhanden ist, gibt die Methode eine Klasseninstanz FormControl zurück, die dem angegebenen Steuerelement entspricht.

Syntax:

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

svc.Controls(controlname: str): svc

Parameter:

controlname: Ein gültiger Steuerelementname als Zeichenfolge mit Beachtung der Groß- und Kleinschreibung. Wenn nicht vorhanden, wird die Liste der Steuerelementnamen als nullbasierte Matrix zurückgegeben.

Beispiel:


      Dim myGrid As Object, myList As Variant, myControl As Object
      Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
      ' Gibt eine Matrix mit den Namen aller Steuerelemente in "myTableControl" zurück
      myList = myGrid.Controls()
      ' Gibt eine Klasseninstanz "FormControl" zurück, die "myCheckBox" entspricht
      Set myControl = myGrid.Controls("myCheckBox")

Bei der Verwendung von Python:


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

SetFocus

Setzt den Fokus auf das Steuerelement. Gibt True zurück, wenn die Fokussierung erfolgreich war.

Diese Methode wird häufig von einem Formular- oder Steuerelementereignis aufgerufen.

Syntax:

svc.SetFocus(): bool

Beispiel:


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

Weitere Beispiele

Unten sind zwei Beispiele, welche die Verwendung des Dienstes FormControl veranschaulichen.

Das erste Beispiel liest den aktuellen Wert in einem Kombinationsfeld, die Städtenamen enthält, und schreibt ihn in ein Steuerelement FixedTest in einem 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

In Python


     bas = CreateScriptService('ScriptForge.Basic') # Basic-ähnliche 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 = "Ausgewählte Stadt: " + combo_city.Value

Der folgende Codeschnipsel kann verwendet werden, um Optionsfelder zu verarbeiten, die denselben Gruppennamen haben. Angenommen, es gibt drei Optionsfelder mit den Namen optA, optB und optC und es soll die Beschriftung des ausgewählten Steuerelements angezeigt werden.


     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 "Ausgewählte Option: " & opt Control.Caption
             Exit For
         End If
     Next opt

In Python


     bas = CreateScriptService('ScriptForge.Basic') # Basic-ähnliche 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('Ausgewählte Option: ' + control.Caption)
           break

Alle ScriptForge Basic-Routinen oder Bezeichner, denen ein Unterstrich "_" vorangestellt ist, sind für den internen Gebrauch reserviert. Sie sind nicht für die Verwendung in Basic-Makros oder Python-Skripten vorgesehen.

Dienst ScriptForge.Basic

Dienst SFDocuments.Form

Dienst SFDocuments.Document