Spis treści

# Usługa SFDocuments.Form

Usługa Form udostępnia metody i właściwości umożliwiające zarządzanie formularzami w dokumentach LibreOffice. Usługa obsługuje formularze w dokumentach Base, Calc i Writer oraz pozwala na:

- Otwieranie i aktywowanie formularzy.

- Nawigowanie pomiędzy rekordami wyświetlanymi w formularzu.

- Uzyskiwanie dostępu do formantów znajdujących się w formularzu.

- Uzyskiwanie dostępu do podformularzy formularza nadrzędnego.

Usługa SFDocuments.Form jest dostępna od wersji 7.2 LibreOffice i nowszych.

Formularze są zwykle używane w dokumentach LibreOffice do tworzenia interfejsów użytkownika połączonych z relacyjnymi bazami danych. Dlatego usługa Form zapewnia szybki dostęp do połączonej bazy danych poprzez usługę SFDatabases.Database.

Usługa SFDocuments.Form jest ściśle powiązana z usługą SFDocuments.FormControl.

## Definicje

### FormDocument

Formularze są zwykle tworzone w dokumentach Base, ale można je również dodawać do dokumentów Writer i Calc.

W Base każdy formularz utworzony za pomocą funkcji Wstaw - Formularz lub za pomocą Kreatora formularzy jest w rzeczywistości FormDocument, który można obsłużyć za pomocą usługi Form. Dokumenty Base mogą zawierać nieograniczoną liczbę dokumentów formularzy.

Poniżej znajduje się przykład pokazujący hierarchię wszystkich elementów związanych z dostępem do formularzy i podformularzy w dokumencie Base. Załóżmy, że masz plik Base o nazwie Employees.odb i w nim utworzono dokument formularza umożliwiający dodanie nowych pracowników do bazy danych. Dokument formularza zawiera formularz główny o nazwie EmployeeData, który umożliwia dostęp do tabeli. Dostępny jest także podformularz WorksAtPlant, który pozwala na powiązanie nowego pracownika z jednym z zakładów firmy.

        Employees.odb (dokument Base)
         |
         |-- AddEmployee (FormDocument)
              |
              |-- EmployeeData (formularz główny)
                   |
                   |-- WorksAtPlant (SubForm)

FormDocument można postrzegać jako zestaw formularzy zapewniających dostęp do zbiorów danych, takich jak tabele bazy danych i kwerendy z dokumentów LibreOffice. Dostęp do nazw formularzy i podformularzy w dokumencie FormDocument można uzyskać za pomocą Nawigatora formularza.

### Formularze i podformularze

Dokument formularza składa się z jednego lub większej liczby formularzy, które z kolei mogą zawierać dowolną liczbę podformularzy. Formularz to abstrakcyjny zestaw formantów połączony z określonym źródłem danych, którym może być tabela bazy danych, kwerenda lub instrukcja SQL SELECT.

W dokumentach programów Calc i Writer każdy formularz można powiązać ze zbiorami danych znajdującymi się w różnych bazach danych. Natomiast w dokumentach bazowych baza danych zawarta w dokumencie jest wspólna dla wszystkich formularzy.

Aby wywołać usługę SFDocuments.Form, skorzystaj z metod Forms(), FormDocuments() i OpenFormDocument() usługi SFDocuments.Document

## Wywoływanie usługi

Przed użyciem usługi Form należy załadować lub zaimportować bibliotekę ScriptForge:

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService

### W dokumentach programu Writer

Poniższy fragment kodu pokazuje, jak uzyskać dostęp do formularza o nazwie Form1, który znajduje się w pliku programu Writer:

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

##### W języku Python

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

Dostęp do formularzy można uzyskać po ich nazwach lub indeksach, na przykład:

         Set myForm = oDoc.Forms(0)

##### W języku Python

         my_form = doc.Forms(0)

Jeśli spróbujesz uzyskać dostęp do FormDocument, który jest aktualnie otwarty w Trybie projektu, zostanie zgłoszony wyjątek.

### W dokumentach programu Calc

Formularz w pliku Calc musi mieć unikalną nazwę w swoim arkuszu. Dlatego metoda Forms wymaga dwóch argumentów, pierwszy wskazujący nazwę arkusza, drugi określający nazwę formularza.

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

Osiąga się to identycznie za pomocą Pythona:

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

### W dokumentach programu Base

Dostęp do FormDocument wewnątrz dokumentu Base można uzyskać po jego nazwie. Poniższy przykład otwiera dokument formularza o nazwie thisFormDocument i uzyskuje dostęp do formularza MainForm:

          Dim oDb As Object, myForm As Object
          Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
          ' Poniższa instrukcja jest konieczna tylko w przypadku, gdy formularz nie został jeszcze otwarty
          oDb.OpenFormDocument("thisFormDocument")
          Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
          ' Lub, ewentualnie, aby uzyskać dostęp do formularza po jego indeksie...
          Set myForm = oDb.Forms("thisFormDocument", 0)

Aby wykonać jakąkolwiek akcję na formularzu za pomocą usługi Form, FormDocument musi zostać otwarty ręcznie przez użytkownika lub programowo w skrypcie użytkownika. To drugie można wykonać wywołując metodę OpenFormDocument usługi Base.

Aby uzyskać dostęp do danego podformularza należy skorzystać z metody SubForms. Zauważ, że w poniższym przykładzie mySubForm jest nową instancją usługi Form.

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

Poprzednie przykłady są tłumaczone w Pythonie jako:

         db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
         #  Poniższa instrukcja jest konieczna tylko w przypadku, gdy formularz nie został jeszcze otwarty
         form_doc = db.OpenFormDocument('thisFormDocument')
         form = form_doc.Forms('thisFormDocument', 'MainForm')
         #  Lub, ewentualnie, aby uzyskać dostęp do formularza po jego indeksie...
         form = form_doc.Forms('thisFormDocument', 0)
         sub_form = form.SubForms('mySubForm')

### W zdarzeniach Form

Aby wywołać usługę Form po wystąpieniu zdarzenia formularza:

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

##### W języku Python

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

Usługa FormEvent służy wyłącznie do tworzenia instancji usług SFDocuments.Form i SFDocuments.FormControl w przypadku wystąpienia formularza lub zdarzenia formantu.

Zalecane jest zwolnienie zasobów po skorzystaniu z usługi Form.

         myForm.Dispose() ' Basic

         form.Dispose()  # Python

Ta operacja jest wykonywana niejawnie, gdy dokument formularza jest zamykany za pomocą metody CloseFormDocument() opisanej poniżej.

## Właściwości

Nazwa | Tylko do odczytu | Typ | Opis
--- | --- | --- | ---
AllowDeletes | Nie | Boolean | Określa, czy formularz umożliwia usuwanie rekordów.
AllowInserts | Nie | Boolean | Określa, czy formularz umożliwia dodawanie rekordów.
AllowUpdates | Nie | Boolean | Określa, czy formularz umożliwia aktualizację rekordów.
BaseForm | Tak | String | Określa hierarchiczną nazwę formularza Base zawierającego rzeczywisty formularz.
Bookmark | Nie | Variant | Określa jednoznacznie bieżący rekord podstawowej tabeli, kwerendy lub instrukcji SQL formularza.
CurrentRecord | Nie | Long | Identyfikuje bieżący rekord w zestawie danych wyświetlanym w formularzu. Jeżeli numer wiersza jest dodatni, kursor przesuwa się do podanego numeru wiersza względem początku zbioru wyników. Liczenie wierszy rozpoczyna się od 1. Jeśli podany numer wiersza jest ujemny, kursor przesuwa się do bezwzględnej pozycji wiersza względem końca zestawu wyników. Wiersz -1 odnosi się do ostatniego wiersza w zestawie wyników.
Filter | Nie | String | Określa podzbiór rekordów, które mają być wyświetlane jako klauzula SQL WHERE bez słowa kluczowego WHERE.
LinkChildFields | Tak | String | Określa sposób łączenia rekordów w podformularzu podrzędnym z rekordami w formularzu nadrzędnym.
LinkParentFields | Tak | String | Określa sposób łączenia rekordów w podformularzu podrzędnym z rekordami w formularzu nadrzędnym.
Name | Tak | String | Nazwa bieżącego formularza.
OrderBy | Nie | String | Określa, w jakiej kolejności rekordy powinny być wyświetlane jako instrukcja SQL ORDER BY bez słów kluczowych ORDER BY.
Parent | Tak | Object | Element nadrzędny bieżącego formularza. Może to być obiekt SFDocuments.Form lub obiekt SFDocuments.Document.
RecordSource | Nie | String | Określa źródło danych jako nazwę tabeli, nazwę kwerendy lub instrukcję SQL.
XForm | Tak | Obiekt UNO | Obiekt UNO reprezentujący interakcje z formularzem. Zobacz XForm oraz DataForm w dokumentacji API, aby uzyskać szczegółowe informacje.

## Właściwości zdarzenia

Poniższe właściwości zwracają lub ustawiają ciągi URI, które definiują skrypt wyzwalany przez zdarzenie.

Nazwa | Tylko do odczytu | Opis IDE Basic
--- | --- | ---
OnApproveCursorMove | Nie | Przed zmianą rekordu
OnApproveParameter | Nie | Wypełnij parametry
OnApproveReset | Nie | Przed zresetowaniem
OnApproveRowChange | Nie | Przed operacją na rekordzie
OnApproveSubmit | Nie | Przed przesłaniem
OnConfirmDelete | Nie | Potwierdź usunięcie
OnCursorMoved | Nie | Po zmianie rekordu
OnErrorOccurred | Nie | Wystąpił błąd
OnLoaded | Nie | Podczas ładowania
OnReloaded | Nie | Podczas ponownego ładowania
OnReloading | Nie | Przed ponownym załadowaniem
OnResetted | Nie | Po resetowaniu
OnRowChanged | Nie | Po operacji na rekordzie
OnUnloaded | Nie | Podczas rozładowania
OnUnloading | Nie | Przed rozładowaniem

Aby dowiedzieć się więcej o ciągach URI, zapoznaj się z Specyfikacją URI platformy skryptowej.

Lista metod w usłudze Form
Activate CloseFormDocument Controls GetDatabase | MoveFirst MoveLast MoveNext MoveNew | MovePrevious Requery SubForms

## Activate

Ustawia fokus na bieżącą instancję Form. Zwraca True, jeśli fokus się powiódł.

Zachowanie metody Activate zależy od typu dokumentu, w którym znajduje się formularz:

- W dokumentach programu Writer: ustawia fokus na tym dokumencie.

- W dokumentach programu Calc: ustawia fokus na arkuszu, do którego należy formularz.

- W dokumentach programu Base: ustawia fokus na FormDocument, do którego odnosi się Form.

### Składnia:

svc.Activate(): bool

### Przykład:

Poniższy przykład zakłada, że chcesz aktywować formularz o nazwie FormA znajdujący się w Sheet1 aktualnie otwartego pliku Calc. Najpierw uzyskuje dostęp do dokumentu za pomocą usługi Document i ThisComponent, a następnie aktywuje formularz.

         ' Uzyskuje formularz, który zostanie aktywowany
         Dim oDoc as Object, myForm as Object
         Set oDoc = CreateScriptService("Document", ThisComponent)
         Set myForm = oDoc.Forms("Sheet1", "FormA")
         ' Aktywuje formularz
         myForm.Activate()

##### W języku Python

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

ThisComponent dotyczy dokumentów programów Calc i Writer. W przypadku dokumentów Base użyj ThisDataBaseDocument.

## CloseFormDocument

Zamyka dokument formularza zawierający rzeczywistą instancję Form. Instancja Form została usunięta.

### Składnia:

svc.CloseFormDocument(): bool

### Przykład:

          myForm.CloseFormDocument() ' Basic

##### W języku Python

          form.CloseFormDocument()  # Python

Ta metoda zamyka tylko dokumenty formularzy znajdujące się w dokumentach Base. Jeśli formularz jest przechowywany w dokumencie programu Writer lub Calc, wywołanie CloseFormDocument nie przyniesie żadnego efektu.

## Controls

Wartość zwrócona przez metodę Controls zależy od podanych argumentów:

- Jeżeli metoda zostanie wywołana bez argumentów, to zwróci listę formantów zawartych w formularzu. Należy pamiętać, że zwrócona lista nie zawiera żadnych formantów podformularza.

- Jeżeli podany zostanie opcjonalny argument ControlName, metoda zwróci instancję klasy FormControl odwołującą się do określonego formantu.

### Składnia:

svc.Controls(opt controlname: str): any

### Parametry:

controlname: prawidłowa nazwa formantu jako ciąg uwzględniający wielkość liter. W przypadku braku lista nazw formantów jest zwracana jako tablica liczona od zera.

### Przykład:

          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

##### W języku Python

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

## GetDatabase

Zwróć instancję SFDatabases.Database zapewnia dostęp do wykonywania poleceń SQL w bazie danych, z którą bieżący formularz jest połączony i/lub który jest przechowywany w bieżącym dokumencie Base.

Każdy formularz ma własne połączenie z bazą danych, z wyjątkiem dokumentów Base, gdzie wszystkie mają to samo połączenie.

### Składnia:

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

### Parametry:

user, password: opcjonalne parametry logowania (domyślnie = "").

### Przykład:

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

##### W języku Python

          db = form.GetDatabase()  # SFDatabases.Database

## MoveFirst

Kursor formularza znajduje się na pierwszym rekordzie. Zwraca wartość True, jeśli operacja się powiedzie.

### Składnia:

svc.MoveFirst(): bool

### Przykład:

          myForm.MoveFirst() ' Basic

##### W języku Python

          form.MoveFirst()  # Python

## MoveLast

Kursor formularza znajduje się na ostatnim rekordzie. Zwraca wartość True, jeśli operacja się powiedzie.

### Składnia:

svc.MoveLast(): bool

### Przykład:

          myForm.MoveLast() ' Basic

##### W języku Python

          form.MoveLast()  # Python

## MoveNew

Kursor formularza zostanie ustawiony na obszarze nowego rekordu. Zwraca wartość True, jeśli operacja się powiedzie.

### Składnia:

svc.MoveNew(): bool

### Przykład:

          myForm.MoveNew() ' Basic

##### W języku Python

          form.MoveNew()  # Python

## MoveNext

Kursor formularza zostanie ustawiony na następnym rekordzie. Zwraca wartość True, jeśli operacja się powiedzie.

### Składnia:

svc.MoveNext(opt offset: int): bool

### Parametry:

offset: liczba rekordów do przeskoczenia do przodu (domyślnie = 1).

### Przykład:

          myForm.MoveNext() ' Basic

##### W języku Python

          form.MoveNext()  # Python

## MovePrevious

Kursor formularza znajduje się na poprzednim rekordzie. Zwraca wartość True, jeśli operacja się powiedzie.

### Składnia:

svc.MovePrevious(opt offset: int): bool

### Parametry:

offset: liczba rekordów do powrotu (domyślnie = 1).

### Przykład:

          myForm.MovePrevious() ' Basic

          form.MovePrevious()  # Python

## Requery

Przeładowuje aktualne dane z bazy danych i odświeża formularz. Kursor znajduje się na pierwszym rekordzie. Zwraca wartość True, jeśli operacja się powiedzie.

### Składnia:

svc.Requery(): bool

### Przykład:

          myForm.Requery() ' Basic

##### W języku Python

          form.Requery()  # Python

## Subforms

Wartość zwracana przez metodę Subforms zależy od podanych argumentów:

- Jeżeli metoda zostanie wywołana bez żadnych argumentów, to zwraca listę podformularzy zawartych w bieżącym formularzu lub instancji podformularza.

- Jeśli podany zostanie opcjonalny argument subform, metoda zwróci nową instancję SFDocuments.Form na podstawie określonej nazwy lub indeksu formularza/podformularza.

### Składnia:

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

### Parametry:

subform: podformularz przechowywany w bieżącej instancji klasy Form podany poprzez jego nazwę lub indeks.

W przypadku braku tego argumentu metoda zwraca listę dostępnych podformularzy w postaci tablicy liczonej od zera. Jeśli formularz ma pojedynczy podformularz, możesz ustawić subform = 0, aby uzyskać do niego dostęp.

### Przykład:

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

##### W języku Python

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

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.

Tematy pokrewne

Usługa SFDatabases.Database

Usługa SFDocuments.Document

Usługa ScriptForge.UI