SFDialogs. Service DialogControl

Le service DialogControl gère les contrôles appartenant à un dialogue défini avec le Basic Dialog Editor. Chaque instance du service actuel représente un contrôle unique dans une boîte de dialogue.

L'accent est mis sur l'obtention et la définition des valeurs affichées par les contrôles de la boîte de dialogue. La mise en forme est accessible via les propriétés XControlModel et XControlView.

Notez que le contenu unique de la propriété DialogControl.Value varie selon le type de contrôle.

Une attention particulière est portée aux contrôles de type contrôle en arborescence. Il est facile de peupler un arbre, soit branche par branche, soit avec un ensemble de branches à la fois. Le remplissage d'un contrôle d'arborescence peut être effectué de manière statique ou dynamique.

Le service SFDialogs.DialogControl est étroitement lié au service SFDialogs.Dialog.

Invocation du service

Avant d'utiliser le service DialogControl, 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 DialogControl est appelé à partir d'une instance de service Dialog existante via sa méthode Controls(). La boîte de dialogue doit être initiée avec le service SFDialogs.Dialog.

      Dim myDialog As Object, myControl As Object
      Set myDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", myLibrary, DialogName)
      Set myControl = myDialog.Controls("myTextBox")
      myControl.Value = "Dialog started at " & Now()
      myDialog.Execute()
      ' ... traiter les valeurs actives des contrôles
      myDialog.Terminate()
   

     from time import localtime, strftime
     dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', lib_name, dlg_name)
     text = dlg.Controls('myTextBox')
     text.Value = "Dialog started at " + strftime("%a, %d %b %Y %H:%M:%S", localtime())
     dlg.Execute()
     # ... traiter les valeurs actives des contrôles
     dlg.Terminate()
   

Récupération de l'instance DialogControl qui a déclenché un événement de contrôle

Une instance du service DialogControl peut être récupérée via le service SFDialogs.DialogEvent, à condition que la boîte de dialogue ait été initiée avec le service Dialog. Dans l'exemple ci-dessous, oControl contient l'instance DialogControl qui a déclenché l'événement de contrôle.

      Sub aControlEventHandler(ByRef poEvent As Object)
          Dim oControl As Object
          Set oControl = CreateScriptService("SFDialogs.DialogEvent", poEvent)
          ' ...
      End Sub
  

Ou en utilisant Python :

     def control_event_handler(event: uno):
         oControl = CreateScriptService('SFDialogs.DialogEvent', event)
         # ...
  

Notez que dans les exemples précédents, le préfixe "SFDialogs." peut être omis lorsque cela est jugé approprié.

Gestion des exceptions dans les gestionnaires d'événements

Lors de la création d'un gestionnaire d'événements pour les événements de contrôle, il est recommandé de gérer les erreurs à l'intérieur du sous-programme lui-même. Par exemple, supposons que le gestionnaire d'événements ci-dessous est appelé lorsque le bouton est cliqué.

    Sub OnButtonClicked(ByRef oEvent As Object)
    On Local Error GoTo Catch
        Dim oControl As Object
        oControl = CreateScriptService("DialogEvent", oEvent)
        ' Traiter l'événement
        Exit Sub
    Catch:
        MsgBox SF_Exception.Description
        SF_Exception.Clear
    End Sub
  

Appelez SF_Exception.Clear si vous ne voulez pas que l'erreur se propage après la fin de l'exécution du dialogue.

En Python, utilisez les blocs natifs try/except pour la gestion des exceptions, comme indiqué ci-dessous :

    def on_button_clicked(event=None):
        try:
            oControl = CreateScriptService("DialogEvent", event)
            # Traiter l'événement
        except Exception as e:
            # L'objet "bas" ci-dessous est une instance du service Basic
            bas.MsgBox(str(e))
  

Types de contrôle

Le service DialogControl est disponible pour ces types de contrôle :

Propriétés

La propriété Value

Il n'y a pas de propriété Value pour les contrôles de boîte de dialogue GroupBox, Hyperlink, ImageControl et TreeControl.

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

L'attribution d'événements via l'EDI Basic et l'attribution d'événements via des macros s'excluent mutuellement.

Méthodes

AddSubNode

Crée et renvoie un nouveau nœud du contrôle d'arborescence en tant qu'objet UNO subordonné à un nœud parent. Reportez-vous à XMutableTreeNode dans la documentation de l'interface de programmation d'application (API) pour informations détaillées.

Cette méthode peut être appelée avant l'affichage de la boîte de dialogue pour construire l'arbre initial. Elle peut également être appelée à partir d'un événement de dialogue ou de contrôle - en utilisant l'événement OnNodeExpanded - pour compléter dynamiquement l'arborescence.

svc.AddSubNode(parentnode: uno, displayvalue: str, opt datavalue: any): uno

parentnode : un objet UNO de nœud, de type com.sun.star.awt.tree.XMutableTreeNode.

displayvalue : le texte apparaissant dans la boîte de contrôle de l'arborescence.

datavalue : toute valeur associée au nouveau nœud. datavalue peut être une chaîne, un nombre ou une date. Omettez l'argument lorsqu'il n'est pas applicable.

Les exemples LibreOffice Basic et Python récupèrent la boîte de dialogue myDialog du document actuel à partir de la bibliothèque Standard.

      Dim oDlg As Object, myTree As Object, myNode As Object, theRoot As Object
      Set oDlg = CreateScriptService("Dialog",,, "myDialog")
      Set myTree = oDlg.Controls("myTreeControl")
      Set theRoot = myTree.CreateRoot("Tree top")
      Set myNode = myTree.AddSubNode(theRoot, "A branch ...")
   

     dlg = CreateScriptService('SFDialogs.Dialog', None, None, 'myDialog')
     tree = dlg.Controls('myTreeControl')
     root = tree.CreateRoot('Tree top')
     node = tree.AddSubNode(root, 'A branch ...')
   

AddSubTree

Renvoie True lorsqu'un sous-arbre, subordonné à un nœud parent, a pu être inséré avec succès dans un contrôle d'arbre. Si le nœud parent avait déjà des nœuds enfants avant d'appeler cette méthode, les nœuds enfants sont effacés.

svc.AddSubTree(parentnode: uno, flattree: any, opt withdatavalue: bool): bool

parentnode : un objet UNO de nœud, de type com.sun.star.awt.tree.XMutableTreeNode.

flattree : une matrice à deux dimensions triée sur les colonnes contenant les valeurs d'affichage. Une telle matrice peut être émise par la méthode GetRows appliquée sur le service SFDatabases.Database. Lorsqu'un élément de la matrice contenant le texte à afficher est Empty ou Null, aucun nouveau sous-nœud n'est créé et le reste de la ligne est ignoré.

      Flat tree    >>>>    sous arbre résultant
      A1	B1	C1             |__   A1	
      A1	B1	C2                   |__   B1
      A1	B2	C3                         |__  C1
      A2	B3	C4                         |__  C2
      A2	B3	C5                   |__   B2
      A3	B4	C6                         |__  C3
                             |__   A2
                                   |__   B3
                                         |__  C4
                                         |__  C5
                             |__   A3
                                   |__   B4
                                         |__  C6
   

withdatavalue : lorsque la valeur par défaut False est utilisée, chaque colonne de flattree contient le texte à afficher dans le contrôle d'arborescence. Lorsque True, les textes à afficher (displayvalue) sont dans les colonnes 0, 2, 4, ... tandis que les valeurs de données (datavalue ) sont dans les colonnes 1, 3, 5, ...

      Dim myTree As Object, theRoot As Object, oDb As Object, vData As Variant
      Set myTree = myDialog.Controls("myTreeControl")
      Set theRoot = myTree.CreateRoot("By product category")
      Set oDb = CreateScriptService("SFDatabases.Database", "/home/.../mydatabase.odb")
      vData = oDb.GetRows("SELECT [Category].[Name], [Category].[ID], [Product].[Name], [Product].[ID] " _
          & "FROM [Category], [Product] WHERE [Product].[CategoryID] = [Category].[ID] " _
          & "ORDER BY [Category].[Name], [Product].[Name]")
      myTree.AddSubTree(theRoot, vData, WithDataValue := True)
   

     SQL_STMT = "SELECT [Category].[Name], [Category].[ID], [Product].[Name], [Product].[ID] \
         FROM [Category], [Product] WHERE [Product].[CategoryID] = [Category].[ID] \
         ORDER BY [Category].[Name], [Product].[Name]"
     tree = dlg.Controls('myTreeControl')
     root = tree.CreateRoot('By Product category')
     db = CreateScriptService('SFDatabases.Database', '/home/.../mydatabase.odb')
     sub_tree = db.GetRows(SQL_STMT)
     tree.AddSubTree(root, sub_tree, withdatavalue=True)
   

CreateRoot

Renvoie un nouveau nœud racine du contrôle d'arborescence, en tant qu'objet nœud UNO de type com.sun.star.awt.tree.XMutableTreeNode. La nouvelle racine de l'arborescence est insérée sous les nœuds racines préexistants. Reportez-vous à XMutableTreeNode dans la documentation de l'interface de programmation d'application (API) pour informations détaillées.

Cette méthode peut être appelée avant l'affichage de la boîte de dialogue pour construire l'arbre initial. Elle peut également être appelée depuis une boîte de dialogue ou un événement de contrôle pour compléter dynamiquement l'arborescence.

svc.CreateRoot(displayvalue: str, opt datavalue: any): uno

displayvalue : le texte apparaissant dans la boîte de contrôle de l'arborescence.

      Dim myTree As Object, myNode As Object
      Set myTree = myDialog.Controls("myTreeControl")
      Set myNode = myTree.CreateRoot("Tree starts here ...")
   

     tree = dlg.Controls('myTreeControl')
     node = tree.CreateRoot('Tree starts here ...')
   

FindNode

Parcourt l'arbre et trouve récursivement, à partir de la racine, un nœud répondant à certains critères. Soit - 1 correspondance suffit - ayant sa valeur d'affichage correspondant au modèle displayvalue ou ayant sa valeur de données égale à datavalue. Les comparaisons peuvent être ou non sensibles à la casse. La première occurrence correspondante est renvoyée en tant qu'objet UNO de nœud de type com.sun.star.awt.tree.XMutableTreeNode. Reportez-vous à XMutableTreeNode dans la documentation de l'interface de programmation d'application (API) pour informations détaillées.

Lorsqu'elle n'est pas trouvée, la méthode renvoie Nothing, à tester avec la fonction intégrée IsNull().

Cette méthode peut être appelée avant l'affichage de la boîte de dialogue pour construire l'arbre initial. Elle peut également être appelée depuis une boîte de dialogue ou un événement de contrôle.

svc.FindNode(displayvalue: str = '', opt datavalue: any, casesensitive = False): uno

Un argument parmi displayvalue ou datavalue doit être spécifié. Si les deux sont présents, une seule correspondance suffit pour sélectionner le nœud.

displayvalue : le modèle à faire correspondre. Reportez-vous à la méthode SF_String.IsLike() pour obtenir la liste des caractères génériques possibles. Lorsqu'elle est égale à la chaîne de longueur nulle (par défaut), cette valeur d'affichage n'est pas recherchée.

casesensitive : la valeur par défaut est False

      Dim myTree As Object, myNode As Object
      Set myTree = myDialog.Controls("myTreeControl")
      Set myNode = myTree.FindNode("*Sophie*", CaseSensitive := True)
   

     tree = dlg.Controls('myTreeControl')
     node = FindNode('*Sophie*', casesensitive=True)
     if node is None:
         # ...
   

Resize

Déplacez le coin supérieur gauche d’un contrôle de boîte de dialogue vers de nouvelles coordonnées et/ou modifiez ses dimensions. Renvoie True si le redimensionnement a réussi.

svc.Resize(opt Left: int, opt Top: int, opt Width: int, opt Height: int): bool

Toutes les distances sont exprimées en Unités Map AppFont et sont mesurées à partir du coin supérieur gauche de la boîte de dialogue parent. Sans arguments, la méthode redimensionne le contrôle à sa « taille préférée », une taille ajustée en fonction de son contenu réel. Les arguments manquants restent inchangés.

Left : la distance horizontale depuis le coin supérieur gauche

Top : la distance verticale à partir du coin supérieur gauche

Width : la largeur horizontale du rectangle contenant le contrôle

Height : la hauteur verticale du rectangle contenant le contrôle

      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.Resize(100, 200, Height:=6000) ' La largeur n'est pas modifiée
    

      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.Resize(300, 200, 1500)  # La hauteur n'est pas modifiée
    

SetFocus

Définir le focus sur le contrôle. Renvoie True si la mise au point a réussi.

Cette méthode est souvent appelée depuis une boîte de dialogue ou un événement de contrôle.

svc.SetFocus(): bool

      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.SetFocus()
    

      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.SetFocus()
    

SetTableData

Remplit un TableControl avec les données données. Toutes les données préexistantes sont effacées avant d'insérer les nouvelles données passées en argument.

Lorsque le TableControl est ajouté à la boîte de dialogue, il est possible d'utiliser l'IDE Basic pour définir si les en-têtes de colonne et de ligne seront affichés dans le tableau. Si le TableControl a des en-têtes de colonne et/ou de ligne, la première colonne et/ou ligne de la matrice de données fournie sont utilisées comme étiquettes pour les en-têtes de table.

Cette méthode renvoie True en cas de succès.

svc.SetTableData(dataarray: any[0..*, 0..*], widths: int[0..*], alignments: str, RowHeaderWidth = 10): bool

dataarray : données à saisir dans la table représentée sous la forme d'une matrice de matrices en Basic ou d'un tuple de tuples en Python. Les données doivent inclure des en-têtes de colonne et de ligne si elles doivent être affichées par le TableControl.

widths : matrice contenant les largeurs relatives de chaque colonne. En d'autres termes, widths = (1, 2) signifie que la deuxième colonne est deux fois plus large que la première. Si le nombre de valeurs de la matrice est inférieur au nombre de colonnes du tableau, alors la dernière valeur de la matrice est utilisée pour définir la largeur des colonnes restantes.

alignements : définit l'alignement dans chaque colonne sous la forme d'une chaîne dans laquelle chaque caractère peut être "L" (gauche), "C" (centre), "R" (droite) ou " " (espace, par défaut, c'est-à-dire à gauche pour les chaînes et à droite pour les valeurs numériques). Si la longueur de la chaîne est inférieure au nombre de colonnes du tableau, le dernier caractère de la chaîne est utilisé pour définir l'alignement des colonnes restantes.

RowHeaderWidth : largeur de la colonne d'en-tête de ligne exprimée en Unités Map AppFont. Par défaut = 10. L'argument est ignoré lorsque TableControl n'a pas d'en-tête de ligne.

L'exemple suivant suppose que la boîte de dialogue myDialog a un TableControl nommé Grid1 avec les propriétés "Afficher l'en-tête de ligne" et "Afficher l'en-tête de colonne" définies sur " Oui".

     Dim myDialog As Object, oTable As Object, tableData As Variant
     myDialog = CreateScriptService("Dialog", "GlobalScope", "Standard", "myDialog")
     oTable = myDialog.Controls("Grid1")
     tableData = Array("Column A", "Column B", "Column C")
     tableData = SF_Array.AppendRow(tableData, Array("Row 1", 1, 2))
     tableData = SF_Array.AppendRow(tableData, Array("Row 2", 3, 4))
     tableData = SF_Array.AppendRow(tableData, Array("Row 3", 5, 6))
     vAlignments = "LCC"
     vWidths = Array(2, 1, 1)
     oTable.SetTableData(tableData, vWidths, vAlignments)
     myDialog.Execute()
   

La propriété Value renvoie la ligne sélectionnée dans le tableau. Si aucune ligne n'est sélectionnée, un objet Array vide est renvoyé. L'extrait de code suivant montre comment tester si une ligne est sélectionnée dans le tableau.

     rowValues = oTable.Value
     If UBound(rowValues) < 0 Then
         MsgBox "No row selected."
     Else
         MsgBox "Row " & oTable.ListIndex & " is selected."
     End If
   

     dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "myDialog")
     table_control = dlg.Controls("Grid1")
     table_data = (("Column A", "Column B", "Column C"),
                   ("Row 1", 1, 2),
                   ("Row 2", 3, 4),
                   ("Row 3", 5, 6))
     alignments = "LCC"
     widths = (100, 50, 50)
     table_control.SetTableData(table_data, widths, alignments)
     dlg.Execute()
   

     bas = CreateScriptService("Basic")
     row_values = table_control.Value
     if len(row_values) == 0:
         bas.MsgBox("No row selected.")
     else:
         bas.MsgBox(f"Row {table_control.ListIndex} is selected.")
   

WriteLine

Ajouter une nouvelle ligne à la fin d'un champ de texte multiligne. Un caractère de saut de ligne sera inséré le cas échéant. La méthode renvoie True en cas de succès.

Une erreur est retournée si le contrôle réel n'est pas du type TextField ou n'est pas multiligne.

svc.WriteLine(opt line: str): bool

Line: la chaîne à insérer. Par défaut c'est une ligne vide.

      Dim oDlg As Object, oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.WriteLine("a new line")
   

     dlg = CreateScriptService('SFDialogs.Dialog', None, None, 'myDialog')
     ctrl = dlg.Controls('thisControl')
     ctr.WriteLine("a new line")
   

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.