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 :

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.

warning

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.

tip

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 :

note

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

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.

note

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 :

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


tip

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
   
warning

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.


Aidez-nous !