Hilfe für LibreOffice 24.8
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.
Vor der Verwendung des Dienstes FormControl muss die Bibliothek ScriptForge geladen oder importiert werden:
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()
   
      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
   
      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.
Der Dienst FormControl ist für die folgenden Steuerelementtypen verfügbar:
| Button | GroupBox | PatternField | 
| 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, 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 | Alle | Das UNO-Objekt, welches das Steuerelementmodell darstellt. Siehe XControlModel und UnoControlModel in der API-Dokumentation für weitere Informationen. | 
| XControlView | Ja | UNO | Alle | Das UNO-Objekt, das die Steuerelementansicht darstellt. Siehe XControl und UnoControl in der API-Dokumentation für weitere Informationen. | 
| Steuerelementtyp | Typ | Beschreibung | 
|---|---|---|
| Button | Boolean | Gilt nur für Wechselschaltflächen. | 
| CheckBox | Boolean oder Integer | 0, False: nicht angekreuzt | 
| 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 | 
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 | |
|---|---|
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.
svc.Controls(): str[0..*]
svc.Controls(controlname: str): svc
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.
      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
   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.
svc.SetFocus(): bool
      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()
   
     bas = CreateScriptService('ScriptForge.Basic')
     doc = CreateScriptService('SFDocuments.Document', bas.ThisComponent)
     form = doc.Forms(0)
     control = form.Controls('thisControl')  # SFDocuments.FormControl
     control.SetFocus()
   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
   
     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
   
     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