Pomoc LibreOffice 25.2
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.
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 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.
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
Przed użyciem usługi Form należy załadować lub zaimportować bibliotekę ScriptForge:
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")
   
     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)
   
     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.
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')
   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')
   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
   
     def OnEvent(event: uno):
         form = CreateScriptService('SFDocuments.FormEvent', event)
         pass
   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.
| 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 | Obiekt UNO reprezentujący interakcje z formularzem. Zobacz XForm oraz DataForm w dokumentacji API, aby uzyskać szczegółowe informacje. | 
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 | ||
|---|---|---|
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.
svc.Activate(): bool
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()
   
     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.
Ta metoda jest przestarzała. Zamiast jej użyj metody ScriptForge.FormDocument.CloseDocument.
Zamyka dokument formularza zawierający rzeczywistą instancję Form. Instancja Form została usunięta.
svc.CloseFormDocument(): bool
      myForm.CloseFormDocument() ' Basic
   
      form.CloseFormDocument()  # Python
   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.
svc.Controls(opt controlname: str): any
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.
      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
   
      form = doc.Forms('myForm')
      form_names = form.Controls()
      form_control = form.Controls('myTextBox')  # SFDocuments.FormControl
   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.
svc.GetDatabase(opt user: str, opt password: str): svc
user, password: opcjonalne parametry logowania (domyślnie = "").
      Dim myDb As Object ' SFDatabases.Database
      Set myDb = oForm.GetDatabase()
   
      db = form.GetDatabase()  # SFDatabases.Database
   Kursor formularza znajduje się na pierwszym rekordzie. Zwraca wartość True, jeśli operacja się powiedzie.
svc.MoveFirst(): bool
      myForm.MoveFirst() ' Basic
   
      form.MoveFirst()  # Python
   Kursor formularza znajduje się na ostatnim rekordzie. Zwraca wartość True, jeśli operacja się powiedzie.
svc.MoveLast(): bool
      myForm.MoveLast() ' Basic
   
      form.MoveLast()  # Python
   Kursor formularza zostanie ustawiony na obszarze nowego rekordu. Zwraca wartość True, jeśli operacja się powiedzie.
svc.MoveNew(): bool
      myForm.MoveNew() ' Basic
   
      form.MoveNew()  # Python
   Kursor formularza zostanie ustawiony na następnym rekordzie. Zwraca wartość True, jeśli operacja się powiedzie.
svc.MoveNext(opt offset: int): bool
offset: liczba rekordów do przeskoczenia do przodu (domyślnie = 1).
      myForm.MoveNext() ' Basic
   
      form.MoveNext()  # Python
   Kursor formularza znajduje się na poprzednim rekordzie. Zwraca wartość True, jeśli operacja się powiedzie.
svc.MovePrevious(opt offset: int): bool
offset: liczba rekordów do powrotu (domyślnie = 1).
      myForm.MovePrevious() ' Basic
   
      form.MovePrevious()  # Python
   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.
svc.Requery(): bool
      myForm.Requery() ' Basic
   
      form.Requery()  # Python
   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.
svc.Subforms(): str[0..*]
svc.Subforms(subform: str): svc
svc.Subforms(subform: int): svc
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.
      Dim myForm As Object, myList As Variant, mySubform As Object
      myList = myform.Subforms()
      Set mySubform = myForm.Subforms("mySubform") ' SFDocuments.Form
   
      subform_names = form.Subforms()
     subform = form.Subforms('mySubform')  # SFDocuments.Form