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.

ScriptForge.Service Basic

SFDocuments. Service Form

Service SFDocuments.Document