Nápověda LibreOfficeDev 7.6
Služba FormControl poskytuje přístup k ovládacím prvkům náležejícím k formuláři, podformuláři nebo prvku tabulky objektu FormDocument. Každá instance služby FormControl odkazuje na jeden ovládací prvek ve formuláři. Služba umožňuje uživatelům:
Získávat a nastavovat vlastnosti ovládacího prvku představovaného instancí služby FormControl.
Přistupovat k aktuální hodnotě zobrazené ovládacím prvkem.
Nastavovat zaměření požadovaného ovládacího prvku.
Aby bylo službu FormControl v určitém formuláři, podformuláři či prvku tabulky možné používat, musí mít všechny ovládací prvky jedinečné názvy.
Jedinečné názvy ovládacích prvků musí mít i přepínače, které jsou součástí skupiny téhož názvu.
Hlavním účelem služby FormControls je nastavovat a získávat vlastnosti a hodnoty zobrazené ovládacími prvky formuláře.
Každý ovládací prvek má vlastnost Value. Její obsah se však liší podle druhu ovládacího prvku. Další informace naleznete níže v části Vlastnost Value.
Ovládací prvky je také možné formátovat prostřednictvím vlastností XControlModel a XControlView.
Služba SFDocuments.FormControl úzce souvisí se službou SFDocuments.Form.
Před používáním služby FormControl je nutné načíst či naimportovat knihovnu ScriptForge pomocí:
Instance služby FormControl je vytvořena z existující instance služby Form pomocí její metody Controls.
      Dim oDoc as Object, myForm As Object, myControl As Object
      Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
      Set myForm = oDoc.Forms("formDocumentName", "formName") ' SFDocuments.Form
      Set myControl = myForm.Controls("myTextBox") ' SFDocuments.FormControl
      myControl.Value = "Current time = " & Now()
   
      from scriptforge import CreateScriptService
      from time import localtime, strftime
      bas = CreateScriptService('ScriptForge.Basic')
      doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
      form = doc.Forms('formDocumentName', 'formName')  # SFDocuments.Form
      control = form.Controls('myTextBox')  # SFDocuments.FormControl
      control.Value = 'Aktuální čas = ' + strftime("%a, %d %b %Y %H:%M:%S", localtime())
   Informace o tom, jak otevřít dokument formulářů FormDocument a získat přístup k jeho formulářům, naleznete na stránce o službě SFDocuments.Form.
Instanci FormControl je také možné získat prostřednictvím služby SFDocuments.FormEvent, která vrátí instanci třídy SFDocuments.FormControl, která událost spustila.
      Sub OnEvent(ByRef poEvent As Object)
          Dim oControl As Object
          Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)
          ' oControl nyní představuje instanci třídy FormControl, která spustila aktuální událost
          ' ...
      End Sub
   
      def onEvent(event: uno):
          control = CreateScriptService('SfDocuments.FormEvent', event)
   V předchozích příkladech může být předpona "SFDocuments." vynechána.
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.
Služba FormControl je k dispozici pro tyto druhy ovládacích prvků:
Button
CheckBox
ComboBox
CurrencyField
DateField
FileControl
FixedText
FormattedField
GroupBox
HiddenControl
ImageButton
ImageControl
ListBox
NavigationBar
NumericField
PatternField
RadioButton
ScrollBar
SpinButton
TableControl
TextField
TimeField
| Název | Pouze pro čtení | Druh | Použitelné na | Popis | 
|---|---|---|---|---|
| Action | ne | String | Button | Určuje akci spuštěnou při klepnutí na tlačítko. Možnými hodnotami jsou: none, submitForm, resetForm, refreshForm, moveToFirst, moveToLast, moveToNext, moveToPrev, saveRecord, moveToNew, deleteRecord, undoRecord. | 
| Caption | ne | String | Button, CheckBox, FixedText, GroupBox, RadioButton | Určuje text zobrazený ovládacím prvkem. | 
| ControlSource | ano | String | CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField | Určuje pole řádku se záznamem namapované na aktuální ovládací prvek. | 
| ControlType | ano | String | všechny | Některý z výše uvedených druhů ovládacích prvků. | 
| Default | ne | Boolean | Button | Určuje, zda je tlačítko s příkazem výchozím tlačítkem (OK). | 
| DefaultValue | ne | Variant | CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Určuje výchozí hodnotu pro inicializaci ovládacího prvku v novém záznamu. | 
| Enabled | ne | Boolean | všechny (kromě prvku HiddenControl) | Určuje, zda je možné k ovládacímu prvku přistupovat pomocí kurzoru. | 
| Format | ne | String | DateField, TimeField, FormattedField (read-only) | Určuje formát použitý pro zobrazení data a času. Musí se jednat o některý z následujících řetězců: Pro datum: "Standard (short)", "Standard (short YY)", "Standard (short YYYY)", "Standard (long)", "DD/MM/YY", "MM/DD/YY", "YY/MM/DD", "DD/MM/YYYY", "MM/DD/YYYY" , "YYYY/MM/DD", "YY-MM-DD", "YYYY-MM-DD". Pro čas: "24h short", "24h long", "12h short", "12h long". | 
| ListCount | ano | Long | ComboBox, ListBox | Vrátí počet řádků v ovládacím prvku ListBox nebo ComboBox. | 
| ListIndex | ne | Long | ComboBox, ListBox | Určuje, která položka je v ovládacím prvku ListBox nebo ComboBox vybrána. U vícenásobného výběru se vrátí index první položky nebo se pouze první položka nastaví. | 
| ListSource | ne | Variant | ComboBox, ListBox | Určuje data obsažená v ovládacích prvku ComboBox nebo ListBox jako pole řetězců začínající od 0. V kombinaci s vlastností ListSourceType může obsahovat také název tabulky, dotazu či úplného SQL příkazu. | 
| ListSourceType | ne | Integer | ComboBox, ListBox | Určuje typ dat obsažených v poli se seznamem nebo v seznamu. Musí se jednat o některou z konstant com.sun.star.form.ListSourceType.*. | 
| Locked | ne | Boolean | ComboBox, CurrencyField, DateField, FileControl, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField | Určuje, zda je ovládací prvek pouze pro čtení. | 
| MultiSelect | ne | Boolean | ListBox | Určuje, zda může uživatel v seznamu vybrat více položek. | 
| Name | ano | String | všechny | Název ovládacího prvku. | 
| Parent | ano | Object | všechny | Podle typu rodičovského prvku (formulář, podformulář nebo prvek tabulky) vrátí rodičovskou instanci třídy SFDocuments.Form nebo SFDocuments.FormControl. | 
| Picture | ne | String | Button, ImageButton, ImageControl | Určuje název souboru obsahujícího rastr nebo jiný typ grafiky, která se má na zadaném ovládacím prvku zobrazit. Název souboru musí odpovídat atributu FileNaming ze služby ScriptForge.FileSystem. | 
| Required | ne | Boolean | CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Ovládací prvek je povinný v případě, že s ním propojená data nemohou obsahovat hodnotu null. | 
| Text | ano | String | ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField | Poskytuje přístup k textu zobrazenému ovládacím prvkem. | 
| TipText | ne | String | všechny (kromě prvku HiddenControl) | Určuje text, který se zobrazí jako tip po najetí ukazatelem myši nad ovládací prvek. | 
| TripleState | ne | Boolean | CheckBox | Určuje, zda může být zaškrtávací pole zobrazeno jako neaktivní (zašedlé). | 
| Value | ne | Variant | Tato vlastnost závisí na druhu ovládacího prvku. Další informace naleznete v části Vlastnost Value. | |
| Visible | ne | Boolean | všechny (kromě prvku HiddenControl) | Určuje, zda ovládací prvek skrytý, nebo viditelný. | 
| XControlModel | ano | objekt | všechny | Objekt UNO představující model ovládacího prvku. Podrobné informace naleznete v dokumentaci API na stránkách XControlModel a UnoControlModel. | 
| XControlView | ano | objekt | všechny | Objekt UNO představující pohled (view) ovládacího prvku. Podrobné informace naleznete v dokumentaci API na stránkách XControl a UnoControl. | 
| Druh ovládacího prvku | Typ | Popis | 
|---|---|---|
| Button | Boolean | Použitelné pouze na přepínací tlačítka. | 
| CheckBox | Boolean nebo Integer | 0, False: nezaškrtnuto | 
| ComboBox | String | Vybraná hodnota jako typ String. Jinou možností je vlastnost ListIndex pro přístup k indexu vybrané hodnoty. | 
| CurrencyField | číselný | |
| DateField | Date | |
| FileControl | String | Název souboru formátovaný v souladu s vlastností FileNaming ze služby SF_FileSystem. | 
| FormattedField | String nebo číselný | |
| HiddenControl | String | |
| ListBox | String nebo pole řetězců | Vybraný řádek (či řádky) jako jediný řetězec nebo jako pole řetězců. Nastavit lze pouze jedinou hodnotu. Jestliže je pole propojeno s databází, tato vlastnost získává nebo nastavuje v ní uložená data. V opačném případě získává nebo nastavuje zobrazená data. | 
| NumericField | číselný | |
| PatternField | String | |
| RadioButton | Boolean | Každé tlačítko má vlastní název. Více ovládacích prvků typu RadioButton je spolu propojeno v případě, že sdílejí stejný název skupiny. Je-li tlačítko RadioButton nastaveno na True, ostatní související tlačítka se automaticky nastaví na False. | 
| ScrollBar | číselný | Musí se nacházet v předem definovaných mezích. | 
| SpinButton | číselný | Musí se nacházet v předem definovaných mezích. | 
| TextField | String | Text zobrazený v poli. | 
| TimeField | Date | 
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 zobrazený v IDE jazyka Basic | 
|---|---|---|
| OnActionPerformed | ne | Provést akci | 
| OnAdjustmentValueChanged | ne | Při úpravě | 
| OnApproveAction | ne | Schválit akci | 
| OnApproveReset | ne | Před přenastavením | 
| OnApproveUpdate | ne | Před aktualizací | 
| OnChanged | ne | Změněno | 
| OnErrorOccurred | ne | Došlo k chybě | 
| OnFocusGained | ne | Při zaměření | 
| OnFocusLost | ne | Při ztrátě zaměření | 
| OnItemStateChanged | ne | Změna stavu položky | 
| OnKeyPressed | ne | Klávesa stisknuta | 
| OnKeyReleased | ne | Klávesa uvolněna | 
| OnMouseDragged | ne | Myš se pohnula spolu se stisknutou klávesou | 
| OnMouseEntered | ne | Myš uvnitř | 
| OnMouseExited | ne | Myš vně | 
| OnMouseMoved | ne | Posuv myši | 
| OnMousePressed | ne | Stisknuto tlačítko myši | 
| OnMouseReleased | ne | Uvolněno tlačítko myši | 
| OnResetted | ne | Po přenastavení | 
| OnTextChanged | ne | Text změněn | 
| OnUpdated | ne | Po aktualizaci | 
Podrobnosti o řetězcích URI naleznete na stránce Scripting Framework URI Specification.
| Seznam metod služby FormControl | |
|---|---|
Tuto metodu lze použít pouze na ovládací prvky druhu TableControl. Návratová hodnota závisí na zadaných argumentech.
Je-li nepovinný argument controlname vynechán, vrátí se pole začínající od 0 s názvy všech ovládacích prvků.
Je-li však argument controlname zadán, metoda vrátí instanci třídy FormControl odpovídající požadovanému ovládacímu prvku.
svc.Controls(): str[0..*]
svc.Controls(controlname: str): svc
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 myGrid As Object, myList As Variant, myControl As Object
      Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
      ' Vrátí pole s názvy všech ovládacích prvků pro prvek "myTableControl"
      myList = myGrid.Controls()
      ' Vrátí instanci třídy FormControl odpovídající prvku "myCheckBox"
      Set myControl = myGrid.Controls("myCheckBox")
   Pomocí Pythonu:
      grid = form.Controls('myTableControl')  # SFDocuments.FormControl
      control_names = form.Controls()
      control = grid.Controls('myCheckBox')  # SFDocuments.FormControl
   Nastaví ovládacímu prvku zaměření. V případě úspěšného nastavení vrátí True.
Metoda je často volána z události formuláře nebo ovládacího prvku.
svc.SetFocus(): bool
      Dim oDoc As Object, oForm As Object, oControl As Object
      Set oDoc = CreateScriptService("SFDocuments.Document", ThisComponent)
      Set oForm = oDoc.Forms(0)
      Set oControl = oForm.Controls("thisControl") ' SFDocuments.FormControl
      oControl.SetFocus()
   
     bas = CreateScriptService('ScriptForge.Basic')
     doc = CreateScriptService('SFDocuments.Document', bas.ThisComponent)
     form = doc.Forms(0)
     control = form.Controls('thisControl')  # SFDocuments.FormControl
     control.SetFocus()
   Použití služby FormControl ukazují dva následující příklady:
V prvních z nich se v načte z prvku ComboBox aktuální hodnota obsahující názvy měst a zapíše se do formuláře do prvku FixedTest:
     Dim oDoc as Object, myForm as Object, myControl as Object
     Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
     myForm = oDoc.Forms("formDocumentName", "formName")
     Dim lbCity : lbCity = myForm.Controls("labelCity")
     Dim cbCity : cbCity = myForm.Controls("comboboxCity")
     lbCity.Caption = "Selected City: " & cbCity.Value
   
     bas = CreateScriptService('ScriptForge.Basic')  # metody jako v Basicu
     doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
     form = doc.Forms('formDocumentName', 'formName')
     lbl_city = form.Controls('labelCity')
     combo_city = form.Controls('comboboxCity')
     lbl_city.Caption = "Vybrané město: " + combo_city.Value
   Následující část kódu lze použít ke zpracování ovládacích prvků typu RadioButton, které sdílí stejný název skupiny. Předpokládá se, že jsou k dispozici tři přepínače pojmenované optA, optB a optC a že je záměrem zobrazit popisek vybraného.
     Dim oDoc as Object, myForm as Object
     Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
     myForm = oDoc.Forms("formDocumentName", "formName")
     Dim optNames As Object : optNames = Array("optA", "optB", "optC")
     Dim optControl as Object, opt as Variant
     For Each opt In optNames
         optControl = myForm.Controls(opt)
         If optControl.Value = True Then
             MsgBox "Vybraná možnost: " & optControl.Caption
             Exit For
         End If
     Next opt
   
     bas = CreateScriptService('ScriptForge.Basic')  # metody jako v Basicu
     doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
     form = doc.Forms('formDocumentName', 'formName')
     radio_buttons = ['optA', 'optB', 'optC']
     for name in radio_buttons:
        control = form.controls(name)
        if control.Value == True:
           bas.MsgBox('Vybraná možnost: ' + control.Caption)
           break