Contenu

# Service SFDocuments.FormControl

Le service FormControl permet d'accéder aux contrôles appartenant à un formulaire, un sous-formulaire ou un contrôle de table d'un FormDocument. Chaque instance du service FormControl fait référence à un seul contrôle dans le formulaire. Ce service permet aux utilisateurs de :

- Obtenez et définissez les propriétés du contrôle représenté par l'instance FormControl.

- Accéder à la valeur active affichée par le champ.

- Régler le focus sur le contrôle souhaité.

Pour utiliser le service FormControl dans un contrôle de formulaire, de sous-formulaire ou de table particulier, tous les contrôles doivent avoir des noms uniques.

Les boutons radio qui partagent le même nom de groupe doivent également avoir des noms de contrôle uniques.

L'objectif principal du service FormControl est de définir et d'obtenir les propriétés et les valeurs affichées par les contrôles dans un formulaire.

Tous les contrôles ont une propriété Value. Cependant, son contenu variera selon le type de contrôle. Pour plus d'informations, lisez La propriété Value ci-dessous.

Il est également possible de formater les champs via les propriétés XControlModel et XControlView.

Le service SFDocuments.FormControl est étroitement lié au service SFDocuments.Form .

## Invocation du service

Avant d'utiliser le service FormControl, la bibliothèque ScriptForge doit être chargée ou importée :

• Les macros Basic nécessitent de charger la bibliothèque ScriptForge à l'aide de l'instruction suivante :
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Les scripts Python nécessitent un import depuis le module scriptforge :
from scriptforge import CreateScriptService

Le service FormControl est invoqué à partir d'une instance de service Form existante via sa méthode Controls.

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

Pour en savoir plus sur l'ouverture de FormDocument et accéder à ses formulaires, consultez l page d'aide au service SFDocuments.Form.

Alternativement, une instance FormControl peut être récupérée via le service SFDocuments.FormEvent, qui renvoie l'instance de classe SFDocuments.FormControl qui a déclenché l'événement.

          Sub OnEvent(ByRef poEvent As Object)
              Dim oControl As Object
              Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)
              ' oControl représente maintenant l'instance de la classe FormControl qui a déclenché l'événement actif
              ' ...
          End Sub

##### En Python

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

Notez que dans les exemples précédents, le préfixe "SFDocuments." peut être omis.

Le service FormEvent est utilisé exclusivement pour créer des instances des services SFDocuments.Form et SFDocuments.FormControl lorsqu'un événement de formulaire ou de contrôle a lieu.

## Types de contrôle

Le service FormControl est disponible pour les types de contrôle suivants :

- Button

- CheckBox

- ComboBox

- CurrencyField

- DateField

- FileControl

- FixedText

- FormattedField

- GroupBox

- HiddenControl

- ImageButton

- ImageControl

- ListBox

- NavigationBar

- NumericField

- PatternField

- RadioButton

- ScrollBar

- SpinButton

- TableControl

- TextField

- TimeField

## Propriétés

Nom | Lecture seule | Type | Applicable à | Description
--- | --- | --- | --- | ---
Action | Non | String | Button | Spécifie l'action déclenchée lorsque le bouton est cliqué. Les valeurs acceptées sont : none, submitForm, resetForm, refreshForm, moveToFirst, moveToLast, moveToNext, moveToPrev, saveRecord, moveToNew, deleteRecord, undoRecord.
Caption | Non | String | Button, CheckBox, FixedText, GroupBox, RadioButton | Spécifie le texte affiché par le contrôle.
ControlSource | Oui | String | CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField | Spécifie le champ d'ensemble de lignes mappé sur le contrôle actuel.
ControlType | Oui | String | Tous | L'un des types de contrôle énumérés ci-dessus.
Default | Non | Boolean | Button | Spécifie si un bouton de commande est le bouton par défaut OK.
DefaultValue | Non | Variant | CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Spécifie la valeur par défaut utilisée pour initialiser un contrôle dans un nouvel enregistrement.
Enabled | Non | Boolean | Tous (sauf HiddenControl) | Spécifie si le contrôle est accessible avec le curseur.
Format | Non | String | DateField, TimeField, FormattedField (read-only) | Spécifie le format utilisé pour afficher les dates et les heures. Il doit s'agir de l'une des chaînes suivantes : Pour les 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". Pour les heures : "24h short", "24h long", "12h short", "12h long".
ListCount | Oui | Long | ComboBox, ListBox | Renvoie le nombre de lignes dans une ListBox ou une ComboBox.
ListIndex | Non | Long | ComboBox, ListBox | Spécifie quel élément est sélectionné dans une ListBox ou une ComboBox. En cas de sélection multiple, l'index du premier élément est renvoyé ou un seul élément est défini.
ListSource | Non | Variant | ComboBox, ListBox | Spécifie les données contenues dans une ComboBox ou une ListBox sous la forme d'une matrice de base zéro de valeurs de chaîne. Combiné avec ListSourceType, peut également contenir le nom d'une table, une requête ou une instruction SQL complète.
ListSourceType | Non | Integer | ComboBox, ListBox | Spécifie le type de données contenues dans une zone de liste ou une zone combinée. Cela doit être une des constantes com.sun.star.form.ListSourceType.*.
Locked | Non | Boolean | ComboBox, CurrencyField, DateField, FileControl, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField | Spécifie si le contrôle est en lecture seule.
MultiSelect | Non | Boolean | ListBox | Spécifie si un utilisateur peut sélectionner plusieurs éléments dans une liste déroulante.
Name | Oui | String | Tous | Le nom du contrôle.
Parent | Oui | Object | Tous | Selon le type de parent, un formulaire, un sous-formulaire ou un contrôle de table, renvoie le parent SFDocuments.Form ou l'instance d'objet de classe SFDocuments.FormControl.
Picture | Non | String | Button, ImageButton, ImageControl | Spécifie le nom du fichier contenant un bitmap ou un autre type de graphique à afficher sur le contrôle. Le nom de fichier doit être conforme à l'attribut FileNaming du service ScriptForge.FileSystem.
Required | Non | Boolean | CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Un contrôle est dit requis lorsque les données sous-jacentes ne doivent pas contenir de valeur null.
Text | Oui | String | ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField | Donne accès au texte affiché par le contrôle.
TipText | Non | String | Tous (sauf HiddenControl) | Spécifie le texte qui apparaît sous forme d'info-bulle lorsque le contrôle est survolé par le pointeur de la souris.
TripleState | Non | Boolean | CheckBox | Spécifie si le contrôle de la case à cocher peut apparaître grisé ou non.
Value | Non | Variant |  | Cette propriété dépend du type de champ actif. Reportez-vous à La propriété Value pour plus d'informations.
Visible | Non | Boolean | Tous (sauf HiddenControl) | Spécifie si le contrôle est masqué ou visible.
XControlModel | Oui | Objet UNO | Tous | L'objet UNO représentant le modèle de contrôle. Reportez-vous à XControlModel et UnoControlModel dans la documentation de l'interface de programmation d'application (API) pour des informations détaillées.
XControlView | Oui | Objet UNO | Tous | L'objet UNO représentant la vue du contrôle. Reportez-vous à XControl et UnoControl dans la documentation de l'API pour plus d'informations.

## La propriété Value

Type de contrôle | Type | Description
--- | --- | ---
Button | Boolean | Applicable aux boutons bascule uniquement.
CheckBox | Booléen ou Entier | 0, False : non coché 1, True : coché 2 : grisé, ne sait pas (applicable si TripleState est True)
ComboBox | String | La valeur sélectionnée, sous forme de chaîne. La propriété ListIndex est une option alternative pour accéder à l'index de la valeur sélectionnée.
CurrencyField | Numérique |
DateField | Date |
FileControl | String | Un nom de fichier formaté conformément à la propriété FileNaming du service ScriptForge.FileSystem
FormattedField | Chaîne ou numérique |
HiddenControl | String |
ListBox | Chaîne ou matrice de chaînes | La ou les lignes sélectionnées sous la forme d'une chaîne unique ou d'une matrice de chaînes. Une seule valeur peut être définie. Si la boîte est liée à une base de données, cette propriété obtient ou définit les données sous-jacentes. Sinon, elle obtient ou définit les données affichées.
NumericField | Numérique |
PatternField | String |
RadioButton | Boolean | Chaque bouton a son propre nom. Plusieurs contrôles RadioButton sont liés lorsqu'ils partagent le même nom de groupe. Si un RadioButton est défini sur True, les autres boutons associés sont automatiquement définis sur False
ScrollBar | Numérique | Doit être dans les limites prédéfinies
SpinButton | Numérique | Doit être dans les limites prédéfinies
TextField | String | Le texte apparaissant dans le champ
TimeField | Date |

## Propriétés de l'événement

Les propriétés ci-dessous renvoient ou définissent des chaînes URI qui définissent le script déclenché par l'événement.

Nom | Lecture seule | Description telle qu'étiquetée dans l'EDI Basic
--- | --- | ---
OnActionPerformed | Non | Exécuter l'action
OnAdjustmentValueChanged | Non | À l'ajustement
OnApproveAction | Non | Accepter l'action
OnApproveReset | Non | Avant la réinitialisation
OnApproveUpdate | Non | Avant l'actualisation
OnChanged | Non | Modifié
OnErrorOccurred | Non | Erreur survenue
OnFocusGained | Non | À la réception du focus
OnFocusLost | Non | À la perte du focus
OnItemStateChanged | Non | Statut de l'élément modifié
OnKeyPressed | Non | Touche enfoncée
OnKeyReleased | Non | Touche relâchée
OnMouseDragged | Non | Déplacement de la souris lors de l'appui sur une touche
OnMouseEntered | Non | Souris à l'intérieur
OnMouseExited | Non | Souris à l'extérieur
OnMouseMoved | Non | Souris déplacée
OnMousePressed | Non | Bouton de la souris enfoncé
OnMouseReleased | Non | Bouton de la souris relâché
OnResetted | Non | Après réinitialisation
OnTextChanged | Non | Texte modifié
OnUpdated | Non | Après l'actualisation

Pour en savoir plus sur les chaînes URI, reportez-vous à la Spécification de l'URI du cadre de script.

Liste des méthodes dans le service FormControl
Controls | SetFocus

## Controls

Cette méthode est applicable uniquement aux contrôles du type TableControl. La valeur renvoyée dépend des arguments fournis.

Si l'argument facultatif controlname est absent, alors une matrice de base zéro contenant les noms de tous les contrôles est renvoyée.

D'autre part, si un controlname est fourni, la méthode renvoie une instance de classe FormControl correspondant au contrôle spécifié.

### Syntaxe :

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

svc.Controls(controlname: str): svc

### Paramètres :

controlname : un nom de contrôle valide sous forme de chaîne sensible à la casse. S'il est absent, la liste des noms de contrôle est renvoyée sous la forme d'une matrice de base zéro.

### Exemple :

          Dim myGrid As Object, myList As Variant, myControl As Object
          Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
          ' Renvoie un tableau avec les noms de tous les contrôles dans "myTableControl"
          myList = myGrid.Controls()
          ' Renvoie une instance de classe FormControl correspondant à "myCheckBox"
          Set myControl = myGrid.Controls("myCheckBox")

En utilisant Python :

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

## SetFocus

Définit le focus sur le contrôle. Renvoie True si le focus a réussi.

Cette méthode est souvent appelée depuis un formulaire ou un événement de contrôle.

### Syntaxe :

svc.SetFocus(): bool

### Exemple :

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

## Exemples supplémentaires

Voici deux exemples qui illustrent l'utilisation du service FormControl.

Le premier exemple lit la valeur actuelle dans une zone combinée contenant des noms de ville et l'écrit dans un contrôle FixedTest dans un formulaire :

         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éthodes de type basique
         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

L'extrait de code suivant peut être utilisé pour traiter les contrôles RadioButton qui partagent le même nom de groupe. Dans cet exemple, supposons qu'il y ait trois boutons radio avec les noms optA, optB et optC et que nous souhaitions afficher la légende du contrôle sélectionné.

         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

##### En Python

         bas = CreateScriptService('ScriptForge.Basic') # Méthodes de type basique
         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

Toutes les routines ou identifiants de base ScriptForge qui sont préfixés par un caractère de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans des macros de base ou des scripts Python.

Rubriques connexes

ScriptForge.Service Basic

SFDocuments. Service Form

Service SFDocuments.Document