Obsah

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

##### V Pythonu

         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)

##### V Pythonu

         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

##### V Pythonu

         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

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 UNO | Objekt UNO představující interakce s formulářem. Podrobné informace naleznete v dokumentaci API pro rozhraní XForm a službu DataForm.

## 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.

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
Activate CloseFormDocument Controls GetDatabase | MoveFirst MoveLast MoveNext MoveNew | MovePrevious Requery SubForms

## 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.

### Syntaxe:

svc.Activate(): bool

### Příklad:

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

##### V Pythonu

         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.

### Syntaxe:

svc.CloseFormDocument(): bool

### Příklad:

          myForm.CloseFormDocument() ' Basic

##### V Pythonu

          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.

### Syntaxe:

svc.Controls(opt controlname: str): any

### Parametry:

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.

### Příklad:

          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

##### V Pythonu

          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í.

### Syntaxe:

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

### Parametry:

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

### Příklad:

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

##### V Pythonu

          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.

### Syntaxe:

svc.MoveFirst(): bool

### Příklad:

          myForm.MoveFirst() ' Basic

##### V Pythonu

          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.

### Syntaxe:

svc.MoveLast(): bool

### Příklad:

          myForm.MoveLast() ' Basic

##### V Pythonu

          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.

### Syntaxe:

svc.MoveNew(): bool

### Příklad:

          myForm.MoveNew() ' Basic

##### V Pythonu

          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.

### Syntaxe:

svc.MoveNext(opt offset: int): bool

### Parametry:

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

### Příklad:

          myForm.MoveNext() ' Basic

##### V Pythonu

          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.

### Syntaxe:

svc.MovePrevious(opt offset: int): bool

### Parametry:

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

### Příklad:

          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.

### Syntaxe:

svc.Requery(): bool

### Příklad:

          myForm.Requery() ' Basic

##### V Pythonu

          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.

### Syntaxe:

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

### Parametry:

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.

### Příklad:

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

##### V Pythonu

          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.

Související témata

Služba SFDatabases.Database

Služba SFDocuments.Document

Služba ScriptForge.UI