Inhalte

# 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.

Verwandte Themen

Dienst ScriptForge.Basic

Dienst SFDocuments.Form

Dienst SFDocuments.Document