Inhalte

# Dienst SFDocuments.Form

Der Dienst Form stellt Methoden und Eigenschaften bereit, um Formulare in LibreOffice-Dokumenten zu verwalten. Dieser Dienst unterstützt Formulare in Base-, Calc- und Writer-Dokumenten und ermöglicht Folgendes:

- Formulare öffnen und aktivieren.

- Durch die vom Formular angezeigten Datensätze navigieren.

- Zugriff auf die Steuerelemente im Formular erhalten.

- Zugriff auf Unterformulare eines übergeordneten Formulars erhalten.

Der Dienst SFDocuments.Form ist ab LibreOffice 7.2 verfügbar.

Formulare werden normalerweise in LibreOffice-Dokumenten verwendet, um Benutzerschnittstellen zu erstellen, die mit relationalen Datenbanken verbunden sind. Daher bietet der Dienst Form schnellen Zugriff auf die verknüpfte Datenbank über den Dienst SFDatabases.Database.

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

## Definitionen

### FormDocument

Formulare werden normalerweise in Base-Dokumenten erstellt, können aber auch zu Writer- und Calc-Dokumenten hinzugefügt werden.

In Base ist jedes Formular, das mit der Funktion Einfügen – Formular… oder mit dem Formularassistenten erstellt wird, eigentlich ein FormDocument, das mit dem Dienst Form verarbeitet werden kann. Base-Dokumente können eine unbegrenzte Anzahl von Formulardokumenten enthalten.

Unten ist ein Beispiel, das die Hierarchie aller Elemente zeigt, die am Zugriff auf Formulare und Unterformulare in einem Basisdokument beteiligt sind. Angenommen, Sie haben eine Base-Datei mit dem Namen Employees.odb und darin haben Sie ein Formulardokument erstellt, um neue Mitarbeiter zur Datenbank hinzuzufügen. Das Formulardokument enthält ein Hauptformular namens EmployeeData, das Zugriff auf eine Tabelle gewährt. Es gibt auch ein Unterformular WorksAtPlant, mit dem Sie den neuen Mitarbeiter einem der Werke des Unternehmens zuordnen können.

        Employees.odb (Base-Dokument)
         |
         |-- AddEmployee (FormDocument)
              |
              |-- EmployeeData (Hauptformular)
                   |
                   |-- WorksAtPlant (SubForm)

Ein FormDocument kann als eine Reihe von Formularen betrachtet werden, die Zugriff auf Datenbestände wie Datenbanktabellen und Abfragen aus LibreOffice-Dokumenten bieten. Auf die Namen von Formularen und Unterformularen in einem Formulardokument kann mit dem Formularnavigator zugegriffen werden.

### Formulare und Unterformulare

Ein Formulardokument besteht aus einem oder mehreren Formularen, die wiederum beliebig viele Unterformulare enthalten können. Ein Formular ist ein abstrakter Satz von Steuerelementen, die mit einer bestimmten Datenquelle verknüpft sind, die eine Datenbanktabelle, eine Abfrage oder eine SQL-Anweisung SELECT sein kann.

In Calc- und Writer-Dokumenten kann jedes Formular mit Datenbeständen verknüpft werden, die sich in verschiedenen Datenbanken befinden. Bei Base-Dokumenten hingegen ist die im Dokument enthaltene Datenbank allen Formularen gemeinsam.

Um den Dienst SFDocuments.Form aufzurufen, wird auf die Methoden Forms(), FormDocuments() und OpenFormDocument() des Dienstes SFDocuments.Document verwiesen

## Dienstaufruf

Vor der Verwendung des Dienstes Form 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

### In Writer-Dokumenten

Der folgende Code-Schnipsel zeigt, wie auf das Formular mit dem Namen Form1 zugegriffen wird, das sich in einer Writer-Datei befindet:

          Dim oDoc As Object, myForm As Object, ui as Object
          Set ui = CreateScriptService("UI")
          Set oDoc = ui.OpenDocument("/home/user/Documents/MyForm.odt")
          Set myForm = oDoc.Forms("Form1")

##### In Python

         from scriptforge import CreateScriptService
         ui = CreateScriptService('UI')
         doc = ui.OpenDocument('/home/user/Documents/MyForm.odt')
         my_form = doc.Forms('Form1')

Formulare können über ihre Namen oder ihre Indexe aufgerufen werden, wie unten gezeigt:

         Set myForm = oDoc.Forms(0)

##### In Python

         my_form = doc.Forms(0)

Wenn Sie versuchen, auf ein FormDocument zuzugreifen, das derzeit im Designmodus geöffnet ist, wird eine Ausnahme ausgelöst.

### In Calc-Dokumenten

Ein Formular in einer Calc-Datei muss in seiner Tabelle einen eindeutigen Namen haben. Daher erfordert die Methode Forms zwei Argumente, wobei das erste den Tabellennamen und das zweite den Formularnamen festlegt.

          Dim oDoc As Object, myForm As Object, ui as Object
          Set ui = CreateScriptService("UI")
          Set oDoc = ui.OpenDocument("/home/user/Documents/MyForms.ods")
          Set myForm = oDoc.Forms("Sheet1", "Form1")

Dies wird auf identische Weise mit Python erreicht:

         ui = CreateScriptService('UI')
         doc = ui.OpenDocument('/home/user/Documents/MyForms.ods')
         my_form = doc.Forms('Sheet1', 'Form1')

### In Base-Dokumenten

Auf ein FormDocument innerhalb eines Base-Dokuments wird über seinen Namen zugegriffen. Das folgende Beispiel öffnet das Formulardokument namens thisFormDocument und greift auf das Formular MainForm zu:

          Dim oDb As Object, myForm As Object
          Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
          ' Die folgende Anweisung ist nur erforderlich, wenn das Formular noch nicht geöffnet wurde
          oDb.OpenFormDocument("thisFormDocument")
          Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
          ' Oder alternativ, um auf das Formular über seinen Index zuzugreifen …
          Set myForm = oDb.Forms("thisFormDocument", 0)

Um eine Aktion auf einem Formular mit dem Dienst Form auszuführen, muss FormDocument entweder manuell vom Benutzer oder programmgesteuert in einem Benutzerskript geöffnet worden sein. Letzteres kann durch Aufrufen der Methode OpenFormDocument des Dienstes Base erfolgen.

Um auf ein bestimmtes Unterformular eines Formulars zuzugreifen, verwenden Sie die Methode SubForms. Beachten Sie, dass im folgenden Beispiel mySubForm eine neue Instanz des Dienstes Form ist.

         Dim mySubForm As Object
         Set mySubForm = myForm.SubForms("mySubForm")

Vorherige Beispiele wie folgt übersetzt in Python:

         db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
         # Die folgende Anweisung ist nur erforderlich, wenn das Formular noch nicht geöffnet wurde
         form_doc = db.OpenFormDocument('thisFormDocument')
         form = form_doc.Forms('thisFormDocument', 'MainForm')
         # Oder alternativ, um auf das Formular über seinen Index zuzugreifen …
         form = form_doc.Forms('thisFormDocument', 0)
         sub_form = form.SubForms('mySubForm')

### In Formularereignisse

So rufen Sie den Dienst Form auf, wenn ein Formularereignis stattfindet:

          Sub OnEvent(ByRef poEvent As Object)
              Dim myForm As Object
              Set myForm = CreateScriptService("SFDocuments.FormEvent", poEvent)
              '(...)
          End sub

##### In Python

         def OnEvent(event: uno):
             form = CreateScriptService('SFDocuments.FormEvent', event)
             pass

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

Es wird empfohlen, Ressourcen nach der Verwendung des Formulardienstes freizugeben.

         myForm.Dispose() ' Basic

         form.Dispose()  # Python

Diese Operation wird implizit ausgeführt, wenn ein Formulardokument mit der unten beschriebenen Methode CloseFormDocument() geschlossen wird.

## Eigenschaften

Name | Schreibgeschützt | Typ | Beschreibung
--- | --- | --- | ---
AllowDeletes | Nein | Boolean | Legt fest, ob das Formular das Löschen von Datensätzen zulässt.
AllowInserts | Nein | Boolean | Legt fest, ob das Formular das Hinzufügen von Datensätzen zulässt.
AllowUpdates | Nein | Boolean | Legt fest, ob das Formular das Aktualisieren von Datensätzen zulässt.
BaseForm | Ja | String | Legt den hierarchischen Namen des Basisformulars fest, welches das eigentliche Formular enthält.
Bookmark | Nein | Variant | Legt eindeutig den aktuellen Datensatz der zugrunde liegenden Tabelle, Abfrage oder SQL-Anweisung des Formulars fest.
CurrentRecord | Nein | Long | Identifiziert den aktuellen Datensatz im Datenbestand, der in einem Formular angezeigt wird. Wenn die Zeilennummer positiv ist, bewegt sich der Cursor auf die angegebene Zeilennummer in Bezug auf den Beginn der Ergebnismenge. Die Zeilenzählung beginnt bei 1. Wenn die angegebene Zeilennummer negativ ist, bewegt sich der Cursor an eine absolute Zeilenposition in Bezug auf das Ende der Ergebnismenge. Zeile -1 bezieht sich auf die letzte Zeile in der Ergebnismenge.
Filter | Nein | String | Legt eine Teilmenge von Datensätzen fest, die als SQL-Klausel WHERE ohne das Schlüsselwort WHERE angezeigt werden sollen.
LinkChildFields | Ja | String | Legt fest, wie Datensätze in einem untergeordneten Unterformular mit Datensätzen in seinem übergeordneten Formular verknüpft werden.
LinkParentFields | Ja | String | Legt fest, wie Datensätze in einem untergeordneten Unterformular mit Datensätzen in seinem übergeordneten Formular verknüpft werden.
Name | Ja | String | Der Name des aktuellen Formulars.
OrderBy | Nein | String | Legt fest, in welcher Reihenfolge die Datensätze als SQL-Klausel ORDER BY ohne die Schlüsselwörter ORDER BY angezeigt werden sollen.
Parent | Ja | Object | Das übergeordnete Element des aktuellen Formulars. Es kann entweder ein Objekt SFDocuments.Form oder ein Objekt SFDocuments.Document sein.
RecordSource | Nein | String | Legt die Datenquelle als Tabellenname, Abfragename oder SQL-Anweisung fest.
XForm | Ja | UNO Objekt | Das UNO-Objekt, das Interaktionen mit dem Formular darstellt. Siehe XForm und DataForm in der API-Dokumentation für detaillierte Informationen.

## Ereigniseigenschaften

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

Name | Schreibgeschützt | Basic-IDE-Beschreibung
--- | --- | ---
OnApproveCursorMove | Nein | Vor der Datensatzänderung
OnApproveParameter | Nein | Beim Parameter füllen
OnApproveReset | Nein | Vor dem Zurücksetzen
OnApproveRowChange | Nein | Vor der Datensatzaktion
OnApproveSubmit | Nein | Vor dem Absenden
OnConfirmDelete | Nein | Beim Löschung bestätigen
OnCursorMoved | Nein | Nach der Datensatzänderung
OnErrorOccurred | Nein | Wenn Fehler aufgetreten
OnLoaded | Nein | Beim Laden
OnReloaded | Nein | Beim Neuladen
OnReloading | Nein | Vorm Neuladen
OnResetted | Nein | Nach dem Zurücksetzen
OnRowChanged | Nein | Nach der Datensatzaktion
OnUnloaded | Nein | Beim Entladen
OnUnloading | Nein | Vorm Entladen

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

Liste der Methoden im Dienst "Form"
Activate Controls GetDatabase MoveFirst | MoveLast MoveNext MoveNew | MovePrevious Requery SubForms

## Activate

Setzt den Fokus auf die aktuelle Instanz von Form. Gibt True zurück, wenn die Fokussierung erfolgreich war.

Das Verhalten der Methode Activate hängt von der Art des Dokuments ab, in dem sich das Formular befindet:

- In Writer-Dokumenten: Setzt den Fokus auf dieses Dokument.

- In Calc-Dokumenten: Setzt den Fokus auf die Tabelle, zu der das Formular gehört.

- In Base-Dokumenten: Setzt den Fokus auf das FormDocument, auf das sich Form bezieht.

### Syntax:

svc.Activate(): bool

### Beispiel:

Das folgende Beispiel geht davon aus, dass Sie das Formular mit dem Namen FormA aktivieren möchten, das sich in Sheet1 der aktuell geöffneten Calc-Datei befindet. Es erhält zunächst Zugriff auf das Dokument über den Dienst Document und ThisComponent und aktiviert dann das Formular.

         ' Erhält das Formular, das aktiviert wird
         Dim oDoc as Object, myForm as Object
         Set oDoc = CreateScriptService("Document", ThisComponent)
         Set myForm = oDoc.Forms("Sheet1", "FormA")
         ' Aktiviert das Formular
         myForm.Activate()

##### In Python

         doc = CreateScriptService('Document', XSCRIPTCONTEXT.getDocument())
         form = doc.Forms('Sheet1', 'FormA')
         form.Activate()

ThisComponent gilt für Calc- und Writer-Dokumente. Für Base-Dokumente müssen Sie ThisDataBaseDocument verwenden.

## CloseFormDocument

Diese Methode ist veraltet. Verwenden Sie stattdessen die Methode ScriptForge.FormDocument.CloseDocument.

Schließt das Formulardokument, das die eigentliche Instanz Form enthält. Die Instanz Form wird verworfen.

### Syntax:

svc.CloseFormDocument(): bool

### Beispiel:

          myForm.CloseFormDocument() ' Basic

##### In Python

          form.CloseFormDocument()  # Python

## Controls

Der von der Methode Controls zurückgegebene Wert hängt von den bereitgestellten Argumenten ab:

- Wird die Methode ohne Argumente aufgerufen, dann gibt sie die Liste der im Formular enthaltenen Steuerelemente zurück. Beachten Sie, dass die zurückgegebene Liste keine Steuerelemente von Unterformularen enthält.

- Wenn das optionale Argument ControlName verwendet wird, gibt die Methode eine Klasseninstanz FormControl zurück, die auf das angegebene Steuerelement verweist.

### Syntax:

svc.Controls(opt controlname: str): any

### Parameter:

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

### Beispiel:

          Dim myForm As Object, myList As Variant, myControl As Object
          Set myForm = myDoc.Forms("myForm")
          myList = myform.Controls()
          Set myControl = myform.Controls("myTextBox") ' SFDocuments.FormControl

##### In Python

          form = doc.Forms('myForm')
          form_names = form.Controls()
          form_control = form.Controls('myTextBox')  # SFDocuments.FormControl

## GetDatabase

Gibt eine Instanz SFDatabases.Database zurück, die Zugriff auf die Ausführung von SQL-Befehlen auf der Datenbank gewährt, mit der das aktuelle Formular verbunden ist und/oder die im aktuellen Base-Dokument gespeichert ist.

Jedes Formular hat seine eigene Datenbankverbindung, außer in Base-Ddokumenten, wo alle dieselbe Verbindung teilen.

### Syntax:

svc.GetDatabase(opt user: str, opt password: str): svc

### Parameter:

user, password: Die optionalen Login-Parameter (Standard = "").

### Beispiel:

          Dim myDb As Object ' SFDatabases.Database
          Set myDb = oForm.GetDatabase()

##### In Python

          db = form.GetDatabase()  # SFDatabases.Database

## MoveFirst

Der Formularcursor wird auf den ersten Datensatz positioniert. Gibt bei Erfolg True zurück.

### Syntax:

svc.MoveFirst(): bool

### Beispiel:

          myForm.MoveFirst() ' Basic

##### In Python

          form.MoveFirst()  # Python

## MoveLast

Der Formularcursor wird auf den letzten Datensatz positioniert. Gibt bei Erfolg True zurück.

### Syntax:

svc.MoveLast(): bool

### Beispiel:

          myForm.MoveLast() ' Basic

##### In Python

          form.MoveLast()  # Python

## MoveNew

Der Formularcursor wird auf den neuen Datensatzbereich positioniert. Gibt bei Erfolg True zurück.

### Syntax:

svc.MoveNew(): bool

### Beispiel:

          myForm.MoveNew() ' Basic

##### In Python

          form.MoveNew()  # Python

## MoveNext

Der Formularcursor wird auf den nächsten Datensatz positioniert. Gibt bei Erfolg True zurück.

### Syntax:

svc.MoveNext(opt offset: int): bool

### Parameter:

offset: Die Anzahl der Datensätze, die vorwärts gegangen werden soll (Standard = 1).

### Beispiel:

          myForm.MoveNext() ' Basic

##### In Python

          form.MoveNext()  # Python

## MovePrevious

Der Formularcursor wird auf den vorherigen Datensatz positioniert. Gibt bei Erfolg True zurück.

### Syntax:

svc.MovePrevious(opt offset: int): bool

### Parameter:

offset: Die Anzahl der Datensätze, die rückwärts gegangen werden soll (Standard = 1).

### Beispiel:

          myForm.MovePrevious() ' Basic

          form.MovePrevious()  # Python

## Requery

Lädt die aktuellen Daten aus der Datenbank neu und aktualisiert das Formular. Der Cursor wird auf den ersten Datensatz positioniert. Gibt bei Erfolg True zurück.

### Syntax:

svc.Requery(): bool

### Beispiel:

          myForm.Requery() ' Basic

##### In Python

          form.Requery()  # Python

## Subforms

Der von der Methode Subforms zurückgegebene Wert hängt von den bereitgestellten Argumenten ab:

- Wenn die Methode ohne Argumente aufgerufen wird, gibt sie die Liste der Unterformulare zurück, die im aktuellen Formular oder der aktuellen Unterformularinstanz enthalten sind.

- Wenn das optionale Argument subform verwendet wird, gibt die Methode eine neue Instanz SFDocuments.Form basierend auf dem angegebenen Formular-/Unterformularnamen oder -index zurück.

### Syntax:

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

### Parameter:

subform: Ein Unterformular, das in der aktuellen Klasseninstanz Form gespeichert ist, angegeben durch seinen Namen oder Index.

Wenn dieses Argument fehlt, gibt die Methode eine Liste der verfügbaren Unterformulare als nullbasierte Matrix zurück. Wenn das Formular ein einzelnes Unterformular hat, können Sie subform = 0 setzen, um Zugriff darauf zu erhalten.

### Beispiel:

          Dim myForm As Object, myList As Variant, mySubform As Object
          myList = myform.Subforms()
          Set mySubform = myForm.Subforms("mySubform") ' SFDocuments.Form

##### In Python

          subform_names = form.Subforms()
         subform = form.Subforms('mySubform')  # SFDocuments.Form

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 SFDatabases.Database

Dienst SFDocuments.Document

Dienst ScriptForge.UI