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

     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.

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
   

     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

Właściwości zdarzenia

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

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

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.

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.

CloseFormDocument

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

svc.CloseFormDocument(): bool

      myForm.CloseFormDocument() ' Basic
   

      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.

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
   

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.

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
   

MoveFirst

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

svc.MoveFirst(): bool

      myForm.MoveFirst() ' Basic
   

      form.MoveFirst()  # Python
   

MoveLast

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

svc.MoveLast(): bool

      myForm.MoveLast() ' Basic
   

      form.MoveLast()  # Python
   

MoveNew

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
   

MoveNext

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
   

MovePrevious

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
   

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.

svc.Requery(): bool

      myForm.Requery() ' Basic
   

      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.

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
   

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.