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:

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.

warning

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.

tip

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

note

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

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.

note

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


tip

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
   
warning

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.


Podpořte nás!