Nápověda LibreOffice 25.2
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.
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í 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.
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.
Před používáním služby Form je nutné načíst či naimportovat knihovnu ScriptForge pomocí:
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.
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')
   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')
   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
   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().
| Název | Pouze pro čtení | Typ | Popis | 
|---|---|---|---|
| AllowDeletes | ne | Boolean | Určuje, zda formulář umožňuje mazat záznamy. | 
| AllowInserts | ne | Boolean | Určuje, zda formulář umožňuje přidávat záznamy. | 
| AllowUpdates | ne | Boolean | Určuje, zda formulář umožňuje aktualizovat záznamy. | 
| BaseForm | ano | String | Určuje v hierarchii název formuláře Base obsahujícího aktuální formulář. | 
| Bookmark | ne | Variant | Určuje unikátně aktuální záznam z tabulky, dotazu nebo SQL příkazu propojeného s formulářem. | 
| CurrentRecord | ne | Long | Identifikuje aktuální záznam v datové sadě, která se ve formuláři zobrazuje. Je-li číslo řádku kladné, kurzor se na daný řádek přesune od začátku výsledné sady. Čísla řádků začínají od 1. Je-li číslo řádku záporné, kurzor se přesune na pozici řádku od konce výsledné sady. Řádek -1 tak odkazuje na poslední řádek výsledků. | 
| Filter | ne | String | Určuje podmnožinu záznamů, které se mají zobrazit jako klauzule SQL WHERE bez klíčového slova WHERE. | 
| LinkChildFields | ano | String | Určuje, jak jsou záznamy v podformuláři propojeny se záznamy v rodičovském formuláři. | 
| LinkParentFields | ano | String | Určuje, jak jsou záznamy v podformuláři propojeny se záznamy v rodičovském formuláři. | 
| Name | ano | String | Název aktuálního formuláře. | 
| OrderBy | ne | String | Určuje, v jakém pořadí se mají záznamy zobrazit jako klauzule SQL ORDER BY bez klíčových slov ORDER BY. | 
| Parent | ano | Object | Rodičovský objekt aktuálního formuláře. Jedná se buď o objekt SFDocuments.Form, nebo SFDocuments.Document. | 
| RecordSource | ne | String | Určuje zdroj dat, například název tabulky, název dotazu nebo SQL příkaz. | 
| XForm | ano | objekt | Objekt UNO představující interakce s formulářem. Podrobné informace naleznete v dokumentaci API pro rozhraní XForm a službu DataForm. | 
Následující vlastnosti vrátí nebo nastaví řetězce URI, které určují skript, který byl událostí spuštěn.
| Název | Pouze pro čtení | Popis v IDE jazyka BASIC | 
|---|---|---|
| OnApproveCursorMove | ne | Před změnou záznamu | 
| OnApproveParameter | ne | Vyplnit parametry | 
| OnApproveReset | ne | Před přenastavením | 
| OnApproveRowChange | ne | Před záznamem | 
| OnApproveSubmit | ne | Před odesláním | 
| OnConfirmDelete | ne | Potvrdit odstranění | 
| OnCursorMoved | ne | Po změně záznamu | 
| OnErrorOccurred | ne | Došlo k chybě | 
| OnLoaded | ne | Při načítání | 
| OnReloaded | ne | Při opětovném načtení | 
| OnReloading | ne | Před opětovným načtením | 
| OnResetted | ne | Po přenastavení | 
| OnRowChanged | ne | Po záznamu | 
| OnUnloaded | ne | Při uvolnění | 
| OnUnloading | ne | Před uvolněním | 
Podrobnosti o řetězcích URI naleznete na stránce Scripting Framework URI Specification.
| Seznam metod služby Form | ||
|---|---|---|
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.
Tato metoda je označena jako zastaralá, použijte místo ní metodu ScriptForge.FormDocument.CloseDocument.
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
   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
   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
   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
   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
   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
   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
   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
   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
   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