Služba SFDocuments.FormControl

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.

Volání služby

Před používáním služby FormControl 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

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

V Pythonu


      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

V Pythonu


      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.

Druhy ovládacích prvků

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

Vlastnosti

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

Vlastnost Value

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 1, True: zaškrtnuto 2: zašedlé, neznámo (použitelné, pokud je vlastnost TripleStateTrue)
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

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 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
Controls	SetFocus

Controls

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.

Syntaxe:

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

svc.Controls(controlname: str): svc

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

SetFocus

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.

Syntaxe:

svc.SetFocus(): bool

Příklad:


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

V Pythonu


     bas = CreateScriptService('ScriptForge.Basic')
     doc = CreateScriptService('SFDocuments.Document', bas.ThisComponent)
     form = doc.Forms(0)
     control = form.Controls('thisControl')  # SFDocuments.FormControl
     control.SetFocus()

Další příklady

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

V Pythonu


     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

V Pythonu


     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

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.

Služba ScriptForge.Basic

Služba SFDocuments.Form

Služba SFDocuments.Document