Obsah

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

Související témata

Služba ScriptForge.Basic

Služba SFDocuments.Form

Služba SFDocuments.Document