U4CgG‖SFDocuments.FormControl service

XFkrG‖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:

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

warning

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


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

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

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

tip

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


rUEuw‖Service invocation

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

note

gF8D8‖• 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


BeDqF‖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()
   
BenDd‖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

56bE7‖control.Value = 'Current Time = ' + strftime("%a, %d %b %Y %H:%M:%S", localtime())
tip

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


qeXCN‖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)
      HE2d6‖    ' oControl now represents the instance of the FormControl class that triggered the current event
          ' ...
      End Sub
   
BenDd‖In Python

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

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

note

7gE8Y‖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.


AppFj‖Control types

ezcW8‖The FormControl service is available for the following control types:

BESBv‖Properties

VrBfK‖Name

hDr9G‖Readonly

kWac7‖Type

dXwGN‖Applicable to

bEQWc‖Description

Action

N3ejK‖No

String

Button

PszFp‖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

fmzNT‖No

String

Button, CheckBox, FixedText, GroupBox, RadioButton

62Bud‖Specifies the text displayed by the control.

ControlSource

nFFDY‖Yes

String

CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField

8H6BR‖Specifies the rowset field mapped onto the current control.

ControlType

AJUH6‖Yes

String

Enqxp‖All

FsCJK‖One of the control types listed above.

Default

DH84k‖No

Boolean

Button

pRrwC‖Specifies whether a command button is the default OK button.

DefaultValue

2dP2A‖No

Variant

CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField

Sukx9‖Specifies the default value used to initialize a control in a new record.

Enabled

nFBUQ‖No

Boolean

fQYqd‖All (except HiddenControl)

MmDQ5‖Specifies if the control is accessible with the cursor.

Format

VDkDh‖No

String

DateField, TimeField, FormattedField (read-only)

8X3Ho‖Specifies the format used to display dates and times. It must be one of following strings:

6CqCN‖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".

f6gni‖For times: "24h short", "24h long", "12h short", "12h long".

ListCount

RqjAh‖Yes

Long

ComboBox, ListBox

E4aHX‖Returns the number of rows in a ListBox or a ComboBox.

ListIndex

ApC5v‖No

Long

ComboBox, ListBox

XQ3AV‖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

5DjjX‖No

Variant

ComboBox, ListBox

nNqW5‖Specifies the data contained in a ComboBox or a ListBox as a zero-based array of string values.

rvVZ7‖Combined with ListSourceType, may also contain the name of a table, a query or a complete SQL statement.

ListSourceType

jqgF5‖No

Integer

ComboBox, ListBox

sqr2g‖Specifies the type of data contained in a combobox or a listbox.

GzpAN‖It must be one of the com.sun.star.form.ListSourceType.* constants.

Locked

BQ7JE‖No

Boolean

ComboBox, CurrencyField, DateField, FileControl, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField

EV4jD‖Specifies if the control is read-only.

MultiSelect

CXDED‖No

Boolean

ListBox

e7HnA‖Specifies whether the user can select multiple items in a listbox.

Name

TZuvX‖Yes

String

AtLKa‖All

EuBGK‖The name of the control.

Parent

SNTgh‖Yes

Object

CTjAM‖All

z8w8o‖Depending on the parent type, a form, a subform or a tablecontrol, returns the parent SFDocuments.Form or SFDocuments.FormControl class object instance.

Picture

fyoXF‖No

String

Button, ImageButton, ImageControl

RnXeR‖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

PHBtj‖No

Boolean

CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField

oYA7V‖A control is said required when the underlying data must not contain a null value.

Text

NbTpX‖Yes

String

ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField

Rv448‖Gives access to the text being displayed by the control.

TipText

7kxit‖No

String

MNqBi‖All (except HiddenControl)

VXR9Y‖Specifies the text that appears as a tooltip when you hover the mouse pointer over the control.

TripleState

Awzep‖No

Boolean

CheckBox

6S5EL‖Specifies if the checkbox control may appear dimmed (grayed) or not.

Value

mCQFz‖No

Variant

vD3X4‖This property depends on the current control type. Refer to The Value property for more information.

Visible

ybVim‖No

Boolean

G52FE‖All (except HiddenControl)

5juZG‖Specifies if the control is hidden or visible.

XControlModel

FAYCA‖Yes

UZ7ug‖UNO
object

65CSA‖All

ceFhn‖The UNO object representing the control model. Refer to XControlModel and UnoControlModel in the API documentation for more information.

XControlView

FzDR6‖Yes

Bdvyd‖UNO
object

DFQ5P‖All

fPcGS‖The UNO object representing the control view. Refer to XControl and UnoControl in the API documentation for more information.


pqsod‖The Value property

PbEBw‖Control type

bsmCC‖Type

MWgHB‖Description

Button

Boolean

FLUGH‖Applicable to toggle buttons only.

CheckBox

jpLCR‖Boolean or Integer

ErAZY‖0, False: not checked
1, True: checked
2: grayed out, don't know (applicable if TripleState is True)

ComboBox

String

3frrW‖The selected value, as a String. The ListIndex property is an alternate option to access the index of the selected value.

CurrencyField

faEEm‖Numeric

DateField

Date

FileControl

String

VyagB‖A file name formatted in accordance with the FileNaming property of the ScriptForge.FileSystem service

FormattedField

CaGtr‖String or Numeric

HiddenControl

String

ListBox

gtxJY‖String or array of strings

kBH32‖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

f7EZX‖Numeric

PatternField

String

RadioButton

Boolean

DrhU9‖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

WEsqT‖Numeric

LxeLY‖Must be within the predefined bounds

SpinButton

mpoa7‖Numeric

x6ZLt‖Must be within the predefined bounds

TextField

String

UZLYC‖The text appearing in the field

TimeField

Date


WBHoJ‖Event properties

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

7Azyz‖Name

N4btE‖ReadOnly

RXoDM‖Description as labeled in the Basic IDE

OnActionPerformed

yhjPA‖No

HVTKN‖Execute action

OnAdjustmentValueChanged

T5CTw‖No

qs3LA‖While adjusting

OnApproveAction

vUbN6‖No

PopWN‖Approve action

OnApproveReset

PmE7k‖No

rjQCJ‖Prior to reset

OnApproveUpdate

octLi‖No

D7yir‖Before updating

OnChanged

YM7Nt‖No

pHG54‖Changed

OnErrorOccurred

UaRoN‖No

tfW7M‖Error occurred

OnFocusGained

vDFhJ‖No

NN9FK‖When receiving focus

OnFocusLost

tLp7Y‖No

DDcCF‖When losing focus

OnItemStateChanged

EBVQM‖No

PLPUr‖Item status changed

OnKeyPressed

zBci2‖No

vPrAA‖Key pressed

OnKeyReleased

8cFqR‖No

6rrBt‖Key released

OnMouseDragged

7Pzmy‖No

2pMWG‖Mouse moved while key presses

OnMouseEntered

SGYBr‖No

AJGQd‖Mouse inside

OnMouseExited

6cFkB‖No

tfmtf‖Mouse outside

OnMouseMoved

6E7WA‖No

CeNku‖Mouse moved

OnMousePressed

iSxsS‖No

9yirD‖Mouse button pressed

OnMouseReleased

b6pFV‖No

D5vXU‖Mouse button released

OnResetted

9Ui2H‖No

mdLSp‖After resetting

OnTextChanged

jb4at‖No

m3Rb7‖Text modified

OnUpdated

bfgkG‖No

imn6B‖After updating


tip

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


RpNkd‖List of Methods in the FormControl Service

Controls

SetFocus


Controls

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

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

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

FVEx2‖Syntax:

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

svc.Controls(controlname: str): svc

WADQ4‖Parameters:

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

EFSA4‖Example:


      Dim myGrid As Object, myList As Variant, myControl As Object
      Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
      F4Sdy‖' Returns an Array with the names of all controls in "myTableControl"
      myList = myGrid.Controls()
      

YoHSo‖' Returns a FormControl class instance corresponding to "myCheckBox"

Set myControl = myGrid.Controls("myCheckBox")

AGA7Z‖Using Python:


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

SetFocus

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

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

FVEx2‖Syntax:

svc.SetFocus(): bool

EFSA4‖Example:


      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()
   
BenDd‖In Python

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

haAXC‖Additional examples

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

5iGmg‖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
   
BenDd‖In Python

     3eh6E‖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')
     8jneo‖lbl_city.Caption = "Selected city: " + combo_city.Value
   

kz9SK‖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
     gdq6C‖        MsgBox "Selected option: " & optControl.Caption
             Exit For
         End If
     Next opt
   
BenDd‖In Python

     YnBgM‖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:
     AgMTu‖      bas.MsgBox('Selected option: ' + control.Caption)
           break
   
warning

uzETY‖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.