Aide LibreOffice 25.8
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 .
Avant d'utiliser le service FormControl, la bibliothèque ScriptForge doit être chargée ou importée :
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()
   
      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
   
      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.
Le service FormControl est disponible pour les types de contrôle suivants :
| Button | GroupBox | PatternField | 
| 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, 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 | 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 | 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. | 
| Type de contrôle | Type | Description | 
|---|---|---|
| Button | Boolean | Applicable aux boutons bascule uniquement. | 
| CheckBox | Booléen ou Entier | 0, False : non coché | 
| 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 | 
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 | |
|---|---|
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é.
svc.Controls(): str[0..*]
svc.Controls(controlname: str): svc
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.
      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
   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.
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()
   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
   
     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
   
     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