SFDocuments.FormControl service

The FormControl service provides access to the controls that belong to a form, a subform or a table control of a FormDocument. Each instance of the FormControl service refers to a single control in the form. This service allows users to:

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.

Service invocation

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

In Python


      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

In Python


      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.

Control types

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

Properties

Name	Readonly	Type	Applicable to	Description
Action	No	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	No	String	Button, CheckBox, FixedText, GroupBox, RadioButton	Specifies the text displayed by the control.
ControlSource	Yes	String	CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField	Specifies the rowset field mapped onto the current control.
ControlType	Yes	String	All	One of the control types listed above.
Default	No	Boolean	Button	Specifies whether a command button is the default OK button.
DefaultValue	No	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	No	Boolean	All (except HiddenControl)	Specifies if the control is accessible with the cursor.
Format	No	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	Yes	Long	ComboBox, ListBox	Returns the number of rows in a ListBox or a ComboBox.
ListIndex	No	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	No	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	No	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	No	Boolean	ComboBox, CurrencyField, DateField, FileControl, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField	Specifies if the control is read-only.
MultiSelect	No	Boolean	ListBox	Specifies whether the user can select multiple items in a listbox.
Name	Yes	String	All	The name of the control.