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. API;awt.XControl API;awt.XControlModel

Service invocation

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

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

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

def onEvent(event: uno): control = CreateScriptService('SfDocuments.FormEvent', event) Note that in previous examples, the prefix "SFDocuments." may be omitted. FormEvent service

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. Parent Yes Object All Depending on the parent type, a form, a subform or a tablecontrol, returns the parent SFDocuments.Form or SFDocuments.FormControl class object instance. Picture No 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 No 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 Yes String ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField Gives access to the text being displayed by the control. TipText No String All (except HiddenControl) Specifies the text that appears as a tooltip when you hover the mouse pointer over the control. TripleState No Boolean CheckBox Specifies if the checkbox control may appear dimmed (grayed) or not. Value No Variant This property depends on the current control type. Refer to The Value property for more information. Visible No Boolean All (except HiddenControl) Specifies if the control is hidden or visible. XControlModel Yes UNO
object All The UNO object representing the control model. Refer to XControlModel and UnoControlModel in the API documentation for more information. XControlView Yes UNO
object All The UNO object representing the control view. Refer to XControl and UnoControl in the API documentation for more information.

The Value property

Control type Type Description Button Boolean Applicable to toggle buttons only. CheckBox Boolean or Integer 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 Numeric DateField Date FileControl String A file name formatted in accordance with the FileNaming property of the ScriptForge.FileSystem service FormattedField String or Numeric HiddenControl String ListBox String or array of strings The selected row(s) as a single string or an array of strings. Only a single value can be set. If the box is linked to a database, this property gets or sets the underlying data. Otherwise it gets or sets the data being displayed. NumericField Numeric PatternField String RadioButton Boolean Each button has its own name. Multiple RadioButton controls are linked together when they share the same group name. If a RadioButton is set to True, the other related buttons are automatically set to False ScrollBar Numeric Must be within the predefined bounds SpinButton Numeric Must be within the predefined bounds TextField String The text appearing in the field TimeField Date

Event properties

The properties below return or set URI strings that define the script triggered by the event. Name ReadOnly Description as labeled in the Basic IDE OnActionPerformed No Execute action OnAdjustmentValueChanged No While adjusting OnApproveAction No Approve action OnApproveReset No Prior to reset OnApproveUpdate No Before updating OnChanged No Changed OnErrorOccurred No Error occurred OnFocusGained No When receiving focus OnFocusLost No When losing focus OnItemStateChanged No Item status changed OnKeyPressed No Key pressed OnKeyReleased No Key released OnMouseDragged No Mouse moved while key presses OnMouseEntered No Mouse inside OnMouseExited No Mouse outside OnMouseMoved No Mouse moved OnMousePressed No Mouse button pressed OnMouseReleased No Mouse button released OnResetted No After resetting OnTextChanged No Text modified OnUpdated No After updating

To learn more about URI strings, refer to the Scripting Framework URI Specification. List of Methods in the FormControl Service Controls
SetFocus

Controls -------------------------------------------------------------------------------------------------------------------------- FormControl service;Controls

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.

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

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

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") Using Python: grid = form.Controls('myTableControl') # SFDocuments.FormControl control_names = form.Controls() control = grid.Controls('myCheckBox') # SFDocuments.FormControl

SetFocus -------------------------------------------------------------------------------------------------------------------------- FormControl service;SetFocus

SetFocus

Sets the focus on the control. Returns True if focusing was successful. This method is often called from a form or control event.

svc.SetFocus(): bool

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

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

Additional examples --------------------------------------------------------------------------------------------------------------------------

Additional examples

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

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 The following code snippet can be used to process RadioButton controls that share the same group name. In this example, suppose there are three radio buttons with names optA, optB and optC and we wish to display the caption of the selected control. 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

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