SFDocuments.FormControl service

A FormControl szolgáltatás hozzáférést biztosít egy űrlaphoz, alűrlaphoz vagy a FormDocument táblázatvezérlőhöz tartozó vezérlőkhöz. A FormControl szolgáltatás minden egyes példánya az űrlap egyetlen vezérlőelemére utal. Ez a szolgáltatás lehetővé teszi a felhasználók számára, hogy:

Get and set the properties of the control represented by the FormControl instance.
Access the current value displayed by the control.
Set the focus on the desired control.

To use the FormControl service in a particular form, subform or table control, all controls must have unique names.

Radio buttons that share the same group name must also have unique control names.

The main purpose of the FormControl service is setting and getting the properties and values displayed by the controls in a form.

All controls have a Value property. However, its contents will vary according to the control type. For more information, read The Value Property below.

It is also possible to format the controls via the XControlModel and XControlView properties.

The SFDocuments.FormControl service is closely related to the SFDocuments.Form service.

A szolgáltatás igénybevétele

Before using the FormControl service the ScriptForge library needs to be loaded or imported:

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService

The FormControl service is invoked from an existing Form service instance through its Controls method.


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

A Python nyelvben


      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 = 'Current Time = ' + strftime("%a, %d %b %Y %H:%M:%S", localtime())

To learn more about how to open a FormDocument and get access to its forms, refer to the SFDocuments.Form service help page.

Alternatively a FormControl instance can be retrieved via the SFDocuments.FormEvent service, which returns the SFDocuments.FormControl class instance that triggered the event.


      Sub OnEvent(ByRef poEvent As Object)
          Dim oControl As Object
          Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)
          ' oControl now represents the instance of the FormControl class that triggered the current event
          ' ...
      End Sub

A Python nyelvben


      def onEvent(event: uno):
          control = CreateScriptService('SfDocuments.FormEvent', event)

Note that in previous examples, the prefix "SFDocuments." may be omitted.

The FormEvent service is used exclusively to create instances of the SFDocuments.Form and SFDocuments.FormControl services when a form or control event takes place.

Vezérlőelem-típusok

The FormControl service is available for the following control types:

Button
CheckBox
ComboBox
CurrencyField
DateField
FileControl
FixedText
FormattedField
GroupBox
HiddenControl
ImageButton
ImageControl
ListBox
NavigationBar
NumericField
PatternField
RadioButton
ScrollBar
SpinButton
TableControl
TextField
TimeField

Tulajdonságok

Név	Írásvédett	Típus	Alkalmazható a	Leírás
Action	Nem	String	Button	Specifies the action triggered when the button is clicked. Accepted values are: none, submitForm, resetForm, refreshForm, moveToFirst, moveToLast, moveToNext, moveToPrev, saveRecord, moveToNew, deleteRecord, undoRecord.
Caption	Nem	String	Button, CheckBox, FixedText, GroupBox, RadioButton	Specifies the text displayed by the control.
ControlSource	Igen	String	CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField	Specifies the rowset field mapped onto the current control.
ControlType	Igen	String	Minden	One of the control types listed above.
Default	Nem	Boolean	Button	Specifies whether a command button is the default OK button.
DefaultValue	Nem	Variant	CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField	Specifies the default value used to initialize a control in a new record.
Enabled	Nem	Boolean	Minden (kivéve rejtett vezérlőelemek)	Specifies if the control is accessible with the cursor.
Format	Nem	String	DateField, TimeField, FormattedField (read-only)	Specifies the format used to display dates and times. It must be one of following strings: For dates: "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". For times: "24h short", "24h long", "12h short", "12h long".
ListCount	Igen	Long	ComboBox, ListBox	Returns the number of rows in a ListBox or a ComboBox.
ListIndex	Nem	Long	ComboBox, ListBox	Specifies which item is selected in a ListBox or ComboBox. In case of multiple selection, the index of the first item is returned or only one item is set.
ListSource	Nem	Variant	ComboBox, ListBox	Specifies the data contained in a ComboBox or a ListBox as a zero-based array of string values. Combined with ListSourceType, may also contain the name of a table, a query or a complete SQL statement.
ListSourceType	Nem	Integer	ComboBox, ListBox	Specifies the type of data contained in a combobox or a listbox. It must be one of the com.sun.star.form.ListSourceType.* constants.
Locked	Nem	Boolean	ComboBox, CurrencyField, DateField, FileControl, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField	Specifies if the control is read-only.
MultiSelect	Nem	Boolean	ListBox	Specifies whether the user can select multiple items in a listbox.
Name	Igen	String	Minden	The name of the control.
Parent	Igen	Object	Minden	Depending on the parent type, a form, a subform or a tablecontrol, returns the parent SFDocuments.Form or SFDocuments.FormControl class object instance.
Picture	Nem	String	Button, ImageButton, ImageControl	Specifies the file name containing a bitmap or other type of graphic to be displayed on the control. The filename must comply with the FileNaming attribute of the ScriptForge.FileSystem service.
Required	Nem	Boolean	CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField	A control is said required when the underlying data must not contain a null value.
Text	Igen	String	ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField	Gives access to the text being displayed by the control.
TipText	Nem	String	Minden (kivéve rejtett vezérlőelemek)	Specifies the text that appears as a tooltip when you hover the mouse pointer over the control.
TripleState	Nem	Boolean	CheckBox	Specifies if the checkbox control may appear dimmed (grayed) or not.
Value	Nem	Variant		This property depends on the current control type. Refer to The Value property for more information.
Visible	Nem	Boolean	Minden (kivéve rejtett vezérlőelemek)	Specifies if the control is hidden or visible.
XControlModel	Igen	UNO objektum	Minden	The UNO object representing the control model. Refer to XControlModel and UnoControlModel in the API documentation for more information.
XControlView	Igen	UNO objektum	Minden	The UNO object representing the control view. Refer to XControl and UnoControl in the API documentation for more information.

The Value property

Vezérlőelem-típus	Típus	Leírás
Button	Boolean	Applicable to toggle buttons only.
CheckBox	Logikai vagy egész	0, False: not checked 1, True: checked 2: grayed out, don't know (applicable if TripleState is True)
ComboBox	String	The selected value, as a String. The ListIndex property is an alternate option to access the index of the selected value.
CurrencyField	Szám
DateField	Date
FileControl	String	A file name formatted in accordance with the FileNaming property of the ScriptForge.FileSystem service
FormattedField	Karakterlánc vagy szám
HiddenControl	String
ListBox	String or array of strings	A kiválasztott sor(ok) egyetlen karakterláncként vagy karakterláncok tömbjeként. Csak egyetlen értéket lehet beállítani. Ha a mező egy adatbázishoz kapcsolódik, ez a tulajdonság megkapja vagy beállítja az alapul szolgáló adatokat. Ellenkező esetben a megjelenített adatokat kapja meg vagy állítja be.
NumericField	Szám
PatternField	String
RadioButton	Boolean	Minden gombnak saját neve van. Több Rádiógomb vezérlőelem akkor kapcsolódik össze, ha ugyanaz a csoportnév van rajtuk. Ha egy Rádiógomb True értékre van állítva, a többi kapcsolódó gomb automatikusan False értékre lesz állítva.
ScrollBar	Szám	Must be within the predefined bounds
SpinButton	Szám	Must be within the predefined bounds
TextField	String	The text appearing in the field
TimeField	Date

Esemény tulajdonságai

The properties below return or set URI strings that define the script triggered by the event.

Név	Írásvédett	Description as labeled in the Basic IDE
OnActionPerformed	Nem	Művelet végrehajtása
OnAdjustmentValueChanged	Nem	Beállítás során
OnApproveAction	Nem	Művelet jóváhagyása
OnApproveReset	Nem	Alaphelyzetbe állítás előtt
OnApproveUpdate	Nem	Frissítés előtt
OnChanged	Nem	Változott
OnErrorOccurred	Nem	Hiba történt
OnFocusGained	Nem	Amikor a fókuszt megkapja
OnFocusLost	Nem	Amikor a fókuszt elveszti
OnItemStateChanged	Nem	Elem állapota változott
OnKeyPressed	Nem	Billentyű lenyomva
OnKeyReleased	Nem	Billentyű felengedve
OnMouseDragged	Nem	Mouse moved while key presses
OnMouseEntered	Nem	Egér belül
OnMouseExited	Nem	Egér kívül
OnMouseMoved	Nem	Egér mozdult
OnMousePressed	Nem	Egérgomb lenyomása
OnMouseReleased	Nem	Egérgomb elengedése
OnResetted	Nem	Alaphelyzetbe állítás után
OnTextChanged	Nem	Szöveg módosítva
OnUpdated	Nem	Frissítés után

To learn more about URI strings, refer to the Scripting Framework URI Specification.

List of Methods in the FormControl Service
Controls	SetFocus

Controls

This method is applicable only to controls of the TableControl type. The returned value depends on the arguments provided.

If the optional argument controlname is absent, then a zero-based Array containing the names of all controls is returned.

On the other hand, if a controlname is provided, the method returns a FormControl class instance corresponding to the specified control.

Szintaxis:

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

svc.Controls(controlname: str): svc

Paraméterek:

controlname: A valid control name as a case-sensitive string. If absent, the list of control names is returned as a zero-based array.

Példa:


      Dim myGrid As Object, myList As Variant, myControl As Object
      Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
      ' Returns an Array with the names of all controls in "myTableControl"
      myList = myGrid.Controls()
      ' Returns a FormControl class instance corresponding to "myCheckBox"
      Set myControl = myGrid.Controls("myCheckBox")

Python használatával:


      grid = form.Controls('myTableControl')  # SFDocuments.FormControl
      control_names = form.Controls()
      control = grid.Controls('myCheckBox')  # SFDocuments.FormControl

SetFocus

Sets the focus on the control. Returns True if focusing was successful.

This method is often called from a form or control event.

Szintaxis:

svc.SetFocus(): bool

Példa:


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

A Python nyelvben


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

További példák

Below are two examples that illustrate the use of the FormControl service.

The first example reads the current value in a ComboBox containing city names and writes it to a FixedTest control in a Form:


     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

A Python nyelvben


     bas = CreateScriptService('ScriptForge.Basic')  # Basic-like methods
     doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
     form = doc.Forms('formDocumentName', 'formName')
     lbl_city = form.Controls('labelCity')
     combo_city = form.Controls('comboboxCity')
     lbl_city.Caption = "Selected city: " + combo_city.Value

A következő kódrészletet az azonos csoportnévvel rendelkező RadioButton vezérlők feldolgozására használhatjuk. Ebben a példában tegyük fel, hogy három rádiógomb van optA, optB és optC névvel, és a kiválasztott vezérlő feliratát szeretnénk megjeleníteni.


     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 "Selected option: " & optControl.Caption
             Exit For
         End If
     Next opt

A Python nyelvben


     bas = CreateScriptService('ScriptForge.Basic')  # Basic-like methods
     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('Selected option: ' + control.Caption)
           break

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.

ScriptForge.Basic service

SFDocuments.Form service

SFDocuments.Document service