Contenido

# 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.

## Invocación del servicio

Antes de utilizar el servicio FormControl, es necesario cargar o importar la biblioteca ScriptForge:

• Para cargar la biblioteca ScriptForge que necesitan las macros de Basic se debe usar la siguiente declaración:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Los scripts de Python necesitan importar el módulo scriptforge:
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()

##### En 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

##### En 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.

## Tipos de controles

El servicio FormControl está disponible para los tipos de control siguientes:

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

## Propiedades

Nombre | De solo lectura | Tipo | Se aplica a | Descripción
--- | --- | --- | --- | ---
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 | Especifica el texto que muestra el control.
ControlSource | Sí | String | CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField | Specifies the rowset field mapped onto the current control.
ControlType | Sí | String | Todo | Uno de los tipos de control mencionados anteriormente.
Default | No | Boolean | Button | Especifica si un botón de orden es el botón Aceptar predeterminado.
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 | Todo (salvo HiddenControl) | Especifica si el control es accesible mediante el cursor.
Format | No | String | DateField, TimeField, FormattedField (read-only) | Especifica el formato utilizado para mostrar las fechas y horas. Debe ser una de las siguientes cadenas: 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 | Sí | 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 | Especifica el tipo de datos contenidos en un cuadro combinado o un cuadro de lista. Debe ser una de las constantes com.sun.star.form.ListSourceType.*.
Locked | No | Boolean | ComboBox, CurrencyField, DateField, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField | Especifica si el control es de solo lectura.
MultiSelect | No | Boolean | ListBox | Specifies whether the user can select multiple items in a listbox.
Name | Sí | String | Todo | El nombre del control.
Parent | Sí | Object | Todo | 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 | Sí | String | ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField | Gives access to the text being displayed by the control.
TipText | No | String | Todo (salvo HiddenControl) | Permite especificar el texto que aparece como descripción emergente cuando se posa el puntero del ratón encima del 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 | Todo (salvo HiddenControl) | Especifica si el control está oculto o es visible.
XControlModel | Sí | Objeto de UNO | Todo | The UNO object representing the control model. Refer to XControlModel and UnoControlModel in the API documentation for more information.
XControlView | Sí | Objeto de UNO | Todo | The UNO object representing the control view. Refer to XControl and UnoControl in the API documentation for more information.

## La propiedad Value

Tipo de control | Tipo | Descripción
--- | --- | ---
Button | Boolean | Applicable to toggle buttons only.
CheckBox | Booleano o entero | 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 | Numérico |
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 | Numérico |
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 | Numérico | Must be within the predefined bounds
SpinButton | Numérico | Must be within the predefined bounds
TextField | String | The text appearing in the field
TimeField | Date |

## Propiedades del evento

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

Nombre | De solo lectura | Descripción tal como figura en el EID de BASIC
--- | --- | ---
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 | Texto modificado
OnUpdated | No | After updating

Para conocer más sobre las cadenas de URI, consulte la especificación de URI del marco de programación de secuencias de órdenes (en inglés).

Lista de métodos en el servicio FormControl
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.

### Sintaxis:

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

svc.Controls(controlname: str): svc

### Parámetros:

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

### Ejemplo:

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

Con Python:

          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.

### Sintaxis:

svc.SetFocus(): bool

### Ejemplo:

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

##### En Python

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

## Más ejemplos

Encontrará más abajo dos ejemplos que ilustran el uso del servicio FormControl.

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

##### En Python

         bas = CreateScriptService('ScriptForge.Basic')  # Métodos semejantes a BASIC
         doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
         form = doc.Forms('formDocumentName', 'formName')
         lbl_city = form.Controls('labelCity')
         combo_city = form.Controls('comboboxCity')
         lbl_city.Caption = "Ciudad seleccionada: " + 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 "Opción seleccionada: " & optControl.Caption
                 Exit For
             End If
         Next opt

##### En Python

         bas = CreateScriptService('ScriptForge.Basic')  # Métodos semejantes a BASIC
         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('Opción seleccionada: ' + control.Caption)
               break

Todas las rutinas o identificadores BASIC de ScriptForge precedidas por guion bajo «_» están reservadas para uso interno. No deben utilizarse en macros BASIC o secuencias Python.

Temas relacionados

Servicio ScriptForge.Basic

SFDocuments.Form service

Servicio SFDocuments.Document