Služba SFDocuments.Form

Služba Form nabízí metody a vlastnosti pro správu formulářů v dokumentech LibreOffice. Podporuje formuláře v aplikacích Base, Calc a Writer a umožňuje:

• Otevírat a aktivovat formuláře.

• Navigovat mezi záznamy zobrazenými ve formuláři.

• Přistupovat k ovládacím prvkům formuláře.

• Přistupovat k podformulářům rodičovského formuláře.

Služba SFDocuments.Form je k dispozici od verze LibreOffice 7.2.

Formuláře se v dokumentech LibreOffice často využívají pro vytvoření uživatelského rozhraní propojeného s relační databází. Služba Form tak umožňuje rychlý přístup k odkazované databázi prostřednictvím služby SFDatabases.Database.

Služba SFDocuments.Form úzce souvisí se službou SFDocuments.FormControl.

Definice

FormDocument

Formuláře jsou zpravidla vytvářeny v dokumentech aplikace Base, je ale možné je přidat rovněž do dokumentů Writeru nebo Calcu.

V aplikaci Base je každý formulář vytvořený funkcí Vložit - Formulář nebo Průvodcem formulářem vlastně objektem FormDocument, se kterým lze zacházet pomocí služby Form. Dokumenty v Base mohou obsahovat neomezený počet takových dokumentů formulářů.

Níže je uveden příklad zobrazující hierarchii všech prvků, kterých se týká přístup k formulářům a podformulářům v dokumentu Base. Předpokládejme, že máte v Base soubor pojmenovaný Employees.odb a v něm jste vytvořili dokument formulářů, kterým se do databáze přidávají noví zaměstnanci. Tento dokument formulářů obsahuje hlavní formulář pojmenovaný EmployeeData umožňující přistupovat do tabulky databáze. Existuje také podformulář WorksAtPlant, pomocí něhož přiřadíte nového zaměstnance do jedné z provozoven společnosti.

    Employees.odb (dokument Base)
     |
     |-- AddEmployee (FormDocument)
          |
          |-- EmployeeData (hlavní formulář)
               |
               |-- WorksAtPlant (SubForm)
  

Na objekt FormDocument lze nahlížet jako na sadu formulářů, které poskytují z dokumentů LibreOffice přístup k datovým sadám, jako jsou databázové tabulky nebo dotazy. Názvy formulářů a podformulářů v objektu FormDocument je možné zjistit v Navigátoru formulářem.

Formuláře a podformuláře

Dokument formulářů se skládá z jednoho či více formulářů, které mohou obsahovat libovolný počet podformulářů. Objekt Form je abstraktní sada ovládacích prvků, které jsou propojeny s určitým zdrojem dat, kterým může být databázová tabulka, dotaz nebo SQL příkaz SELECT.

V dokumentech Calcu a Writeru je možné propojit každý formulář s datovou sadou v jiné databázi. Naproti tomu databáze obsažená v dokumentu Base je společná pro všechny formuláře.

Při volání služby SFDocuments.Form využijete metody Forms(), FormDocuments() a OpenFormDocument() ze služby SFDocuments.Document.

Volání služby

Před používáním služby Form je nutné načíst či naimportovat knihovnu ScriptForge pomocí:

• V makrech Basicu je nutné načíst knihovnu ScriptForge následujícím příkazem:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Ve skriptech Pythonu je nezbytné import z modulu scriptforge:
from scriptforge import CreateScriptService

V dokumentech Writeru

Následující část kódu ukazuje, jak přistupovat k formuláři pojmenovanému Form1, který je uložen v souboru Writeru:

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

K formulářům lze přistupovat buď pomocí názvu, nebo indexu, například:

     Set myForm = oDoc.Forms(0)
   

     my_form = doc.Forms(0)
   

Pokud se pokusíte přistoupit k objektu FormDocument, který je aktuálně otevřen v režimu návrhu, bude vyvolána výjimka.

V dokumentech Calcu

Formulář v souboru Calcu musí mít v rámci listu jedinečný název. Metoda Forms proto vyžaduje dva argumenty, první označující název listu a druhý určující název formuláře.

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

Totéž lze provést v Pythonu:

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

V dokumentech Base

K objektu FormDocument se v dokumentu Base přistupuje pomocí jeho názvu. V následujícím příkladu je otevřen dokument formulářů pojmenovaný thisFormDocument a přistoupí se k formuláři MainForm:

      Dim oDb As Object, myForm As Object
      Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
      ' Níže uvedený příkaz je nutný pouze tehdy, nebyl-li formulář dosud otevřen
      oDb.OpenFormDocument("thisFormDocument")
      Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
      ' K formuláři lze také přistupovat prostřednictvím jeho indexu
      Set myForm = oDb.Forms("thisFormDocument", 0)
   

Aby bylo možné ve formuláři provést jakoukoliv akci pomocí služby Form, je nutné, aby bylo objekt FormDocument otevřen, ať už ručně, nebo v uživatelském skriptu. Druhou možnost lze provést volání metody OpenFormDocument ze služby Base.

Pro přístup k podformuláři použijte metodu SubForms. V níže uvedeném příkladu je mySubForm novou instancí služby Form.

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

Předchozí příklady lze zapsat v Pythonu jako:

     db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
     # Níže uvedený příkaz je nutný pouze tehdy, nebyl-li formulář dosud otevřen
     form_doc = db.OpenFormDocument('thisFormDocument')
     form = form_doc.Forms('thisFormDocument', 'MainForm')
     # K formuláři lze také přistupovat prostřednictvím jeho indexu
     form = form_doc.Forms('thisFormDocument', 0)
     sub_form = form.SubForms('mySubForm')
   

V událostech formuláře

Vytvoření instance služby Form, když nastane událost:

      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
   

Služba FormEvent se používá pro vytvoření instancí služeb SFDocuments.Form a SFDocuments.FormControl výhradně v případě, že nastane událost formuláře nebo ovládacího prvku.

Po použití služby Form je doporučeno uvolnit zdroje.

     myForm.Dispose() ' Basic
   

     form.Dispose()  # Python
   

Tato operace se automaticky provede při uzavření dokumentu formulářů pomocí níže popsané metody CloseFormDocument().

Vlastnosti

Vlastnosti události

Následující vlastnosti vrátí nebo nastaví řetězce URI, které určují skript, který byl událostí spuštěn.

Podrobnosti o řetězcích URI naleznete na stránce Scripting Framework URI Specification.

Activate

Nastaví aktuální instanci služby Form zaměření. V případě úspěšného nastavení vrátí True.

Chování metody Activate závisí na typu dokumentu, v němž se formulář nachází:

• V dokumentech Writeru: Nastaví zaměření tomuto dokumentu.

• V dokumentech Calcu: Nastaví zaměření listu, k němuž formulář patří.

• V dokumentech Base: Nastaví zaměření na objekt FormDocument, na který formulář Form odkazuje.

svc.Activate(): bool

V následujícím příkladu se předpokládá, že chcete aktivovat formulář pojmenovaný FormA, umístěný na listu Sheet1 aktuálně otevřeného souboru Calcu. Nejprve se získá pomocí služby Document a komponenty ThisComponent přístup k dokumentu, poté se formulář aktivuje.

     ' Získá přístup k formuláři, který se má aktivovat
     Dim oDoc as Object, myForm as Object
     Set oDoc = CreateScriptService("Document", ThisComponent)
     
Set myForm = oDoc.Forms("Sheet1", "FormA")
     ' Aktivuje formulář
     myForm.Activate()
   

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

ThisComponent je relevantní pro dokumenty Calcu a Writeru. V dokumentech Base se používá ThisDataBaseDocument.

CloseFormDocument

Zavře dokument formulářů obsahující aktuální instanci služby Form. Tato instance je uvolněna.

svc.CloseFormDocument(): bool

      myForm.CloseFormDocument() ' Basic
   

      form.CloseFormDocument()  # Python
   

Tato metoda zavře pouze dokumenty formulářů umístěné v dokumentech Base. Jestliže je formulář uložen v dokumentu Writeru či Calcu, volání metody CloseFormDocument nic neprovede.

Controls

Hodnota vrácená metodou Controls závisí na zadaných argumentech:

• Je-li metoda zavolána bez argumentů, vrátí seznam ovládacích prvků, které formulář obsahuje. Mějte na paměti, že vrácený seznam nezahrnuje ovládací prvky z podformulářů.

• Je-li zadán nepovinný argument ControlName, metoda vrátí instanci třídy FormControl odkazující na požadovaný ovládací prvek.

svc.Controls(opt controlname: str): any

controlname: Platný název ovládacího prvku jako řetězec, u něhož záleží na velikost písmen. Není-li zadán, vrátí se seznam názvů ovládacích prvků jako pole začínající od 0.

      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

Vrátí instanci objektu SFDatabases.Database, která poskytuje přístup ke spouštění SQL příkazů na databázi, ke které je aktuální formulář připojen nebo která je uložena v aktuálním dokumentu Base.

Každý formulář má své spojení s databází, výjimkou jsou dokumenty Base, kde všechny formuláře sdílí stejné spojení.

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

user, password: Nepovinné přihlašovací parametry (výchozí = "").

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

      db = form.GetDatabase()  # SFDatabases.Database
   

MoveFirst

Umístí kurzor formuláře na první záznam. V případě úspěšného umístění vrátí True.

svc.MoveFirst(): bool

      myForm.MoveFirst() ' Basic
   

      form.MoveFirst()  # Python
   

MoveLast

Umístí kurzor formuláře na poslední záznam. V případě úspěšného umístění vrátí True.

svc.MoveLast(): bool

      myForm.MoveLast() ' Basic
   

      form.MoveLast()  # Python
   

MoveNew

Umístí kurzor formuláře na oblast s novým záznamem. V případě úspěšného umístění vrátí True.

svc.MoveNew(): bool

      myForm.MoveNew() ' Basic
   

      form.MoveNew()  # Python
   

MoveNext

Umístí kurzor formuláře na následující záznam. V případě úspěšného umístění vrátí True.

svc.MoveNext(opt offset: int): bool

offset: Počet záznamů, o který se má přejít vpřed (výchozí = 1).

      myForm.MoveNext() ' Basic
   

      form.MoveNext()  # Python
   

MovePrevious

Umístí kurzor formuláře na předchozí záznam. V případě úspěšného umístění vrátí True.

svc.MovePrevious(opt offset: int): bool

offset: Počet záznamů, o který se má přejít zpět (výchozí = 1).

      myForm.MovePrevious() ' Basic
   

      form.MovePrevious()  # Python
   

Requery

Znovu načte z databáze aktuální data a obnoví formulář. Kurzor je umístěn na první záznam. V případě úspěšného provedení vrátí True.

svc.Requery(): bool

      myForm.Requery() ' Basic
   

      form.Requery()  # Python
   

Subforms

Hodnota vrácená metodou Subforms závisí na zadaných argumentech:

• Pokud je metoda volána bez argumentů, vrátí seznam podformulářů, které obsahuje aktuální instance formuláře či podformuláře.

• Je-li zadán nepovinný argument subform, metoda vrátí novou instanci SFDocuments.Form podle uvedeného názvu nebo indexu formuláře či podformuláře.

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

subform: Podformulář uložený v aktuální instanci třídy Form zadaný názvem nebo indexem.

Pokud tento argument chybí, metoda vrátí seznam dostupných podformulářů, a to jako pole začínající od 0. Obsahuje-li formulář jediný podformulář a chcete-li k němu získat přístup, nastavte argument subform = 0.

      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
   

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.