Service SFDialogs.DialogControl

Contenu
Index 🔎︎

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

Alternativement, une instance de contrôle 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. DialogEvent renvoie l'instance de classe SFDialogs.DialogControl qui a déclenché l'événement.

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

         def some_event(event: uno):
             ctrl = CreateScriptService('SFDialogs.DialogEvent', event)
             # ...

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

## Types de contrôle

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

- Button

- CheckBox

- ComboBox

- CurrencyField

- DateField

- FileControl

- FixedLine

- FixedText

- FormattedField

- GroupBox

- ImageControl

- ListBox

- NumericField

- PatternField

- ProgressBar

- RadioButton

- ScrollBar

- TableControl

- TextField

- TimeField

- TreeControl

## Propriétés

Nom | Lecture seule | Type de contenu | Applicable à | Description
--- | --- | --- | --- | ---
Cancel | Non | Boolean | Button | Spécifie si un bouton de commande a ou non le comportement d'un bouton Annuler.
Caption | Non | String | Button, CheckBox, FixedLine, FixedText, GroupBox, RadioButton | Spécifie le texte associé au contrôle.
ControlType | Oui | String | Tous | L'un des types énumérés ci-dessus.
CurrentNode | Non | Objet UNO | TreeControl | Le nœud actuellement le plus haut sélectionné dans l'arborescence. Reportez-vous à XmutableTreeNode dans la documentation de l'interface de programmation d'application (API) pour des informations détaillées.
Default | Non | Boolean | Button | Spécifie si un bouton de commande est le bouton par défaut (OK).
Enabled | Non | Boolean | Tous | Spécifie si le contrôle est accessible avec le curseur.
Format | Non | String | DateField, TimeField, FormattedField (lecture seule) | Spécifie le format utilisé pour afficher les dates et les heures. Il doit s'agir de l'une de ces chaînes : 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, TableControl | Spécifie le nombre de lignes dans un ListBox, un ComboBox ou un Table Control.
ListIndex | Non | Long | ComboBox, ListBox, TableControl | Spécifie quel élément est sélectionné dans un ListBox, un ComboBox ou un Table Control.
Locked | Non | Boolean | ComboBox, CurrencyField, DateField, FileControl, FormattedField, 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 effectuer plusieurs sélections dans une liste déroulante.
Name | Oui | String | Tous | Le nom du contrôle.
Page | Non | Integer | Tous | Une boîte de dialogue peut comporter plusieurs pages que l'utilisateur peut parcourir pas à pas. La propriété Page de l'objet Dialog définit quelle page de la boîte de dialogue est active. La propriété Page d'un contrôle définit la page de la boîte de dialogue sur laquelle le contrôle est visible.
Parent | Oui | Service Dialog | Tous | L'instance d'objet de classe parent SFDialogs.Dialog.
Picture | Non | String | Button, ImageControl | Spécifie le nom de fichier contenant un bitmap ou un autre type de graphique à afficher sur le contrôle spécifié. Le nom de fichier doit être conforme à l'attribut FileNaming du service ScriptForge.FileSystem.
RootNode | Oui | Objet UNO | TreeControl | An object representing the lowest root node (usually there is only one such root node). Refer to XmutableTreeNode in Application Programming Interface (API) documentation for detailed information.
RowSource | Non | Array of strings | ComboBox, ListBox | Spécifie les données contenues dans une zone de liste ou une zone combinée.
Text | Oui | String | ComboBox, FileControl, FormattedField, PatternField, TextField | Donne accès au texte affiché par le contrôle.
TipText | Non | String | Tous | Spécifie le texte qui apparaît sous forme d'info-bulle lorsque vous maintenez le pointeur de la souris sur le contrôle.
TripleState | Non | Boolean | CheckBox | Spécifie si le contrôle de la case à cocher peut apparaître grisé ou non.
Value | Non | Variant |  | Refer to Value property
Visible | Non | Boolean | Tous | Spécifie si le contrôle est masqué ou visible.
XControlModel | Oui | Objet UNO | Tous | The UNO object representing the control model. Refer to XControlModel and UnoControlDialogModel in Application Programming Interface (API) documentation for detailed information.
XControlView | Oui | Objet UNO | Tous | The UNO object representing the control view. Refer to XControl and UnoControlDialog in Application Programming Interface (API) documentation for detailed information.
XTreeDataModel | Oui | Objet UNO | TreeControl | The UNO object representing the tree control data model. Refer to XMutableTreeDataModel in Application Programming Interface (API) documentation for detailed information.

## La propriété Value

Type de contrôle | Type | Description
--- | --- | ---
Button | Boolean | Pour les boutons bascule uniquement
CheckBox | Booléen ou Entier | 0, False : non coché 1, True : coché 2 : grisé, ne sait pas
ComboBox | String | La valeur sélectionnée. La propriété ListIndex est une option alternative.
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 |
ListBox | Chaîne ou matrice de chaînes | La ou les lignes sélectionnées sous forme de scalaire ou de matrice en fonction de l'attribut MultiSelect
NumericField | Numérique |
PatternField | String |
ProgressBar | Numérique | Doit être dans les limites prédéfinies
RadioButton | Boolean | Chaque bouton a son propre nom. Ils sont liés entre eux si leurs positions TAB sont contiguës. Si un bouton radio 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
TableControl | Array | Matrice unidimensionnelle avec les données de la ligne actuellement sélectionnée.
TextField | String | Le texte apparaissant dans le champ
TimeField | Date |

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

Returns a URI string with the reference to the script triggered by the event. Read its specification in the scripting framework URI specification.

Nom | Lecture seule | Description telle qu'étiquetée dans l'IDE Basic
--- | --- | ---
OnActionPerformed | Oui | Exécuter l'action
OnAdjustmentValueChanged | Oui | À l'ajustement
OnFocusGained | Oui | À la réception du focus
OnFocusLost | Oui | À la perte du focus
OnItemStateChanged | Oui | Statut modifié de l'élément
OnKeyPressed | Oui | Touche enfoncée
OnKeyReleased | Oui | Touche relâchée
OnMouseDragged | Oui | Déplacement de la souris lors de l'appui sur une touche
OnMouseEntered | Oui | Souris à l'intérieur
OnMouseExited | Oui | Souris à l'extérieur
OnMouseMoved | Oui | Déplacement de la souris
OnMousePressed | Oui | Bouton de la souris enfoncé
OnMouseReleased | Oui | Bouton de la souris relâché
OnNodeExpanded | Non | (Pas dans l'IDE Basic) lorsque le bouton d'extension est enfoncé sur un nœud dans un contrôle d'arborescence
OnNodeSelected | Non | (Pas dans l'IDE Basic) lorsqu'un nœud dans un contrôle d'arborescence est sélectionné
OnTextChanged | Oui | Texte modifié

## Méthodes

Liste des méthodes dans le service DialogControl
AddSubNode AddSubTree CreateRoot | FindNode SetFocus | SetTableData WriteLine

## AddSubNode

Create and return a new node of the tree control as a UNO object subordinate to a parent node. Refer to XMutableTreeNode in Application Programming Interface (API) documentation for detailed information.

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.

### Syntaxe :

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

### Paramètres :

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.

### Exemple :

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

##### En Basic :

          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 ...")

##### En Python

         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.

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.

### Syntaxe :

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

### Paramètres :

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, ...

### Exemple :

##### En Basic :

          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)

##### En Python

         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. Refer to XMutableTreeNode in Application Programming Interface (API) documentation for detailed information.

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.

### Syntaxe :

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

### Paramètres :

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.

### Exemple :

##### En Basic :

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

##### En Python

         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. Refer to XMutableTreeNode in Application Programming Interface (API) documentation for detailed information.

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.

### Syntaxe :

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

### Paramètres :

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: The pattern to be matched. Refer to SF_String.IsLike() method for the list of possible wildcards. When equal to the zero-length string (default), this display value is not searched for.

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.

casesensitive : la valeur par défaut est False

### Exemple :

##### En Basic :

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

##### En Python

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

## 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.

### Syntaxe :

svc.SetFocus(): bool

### Exemple :

##### En Basic :

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

##### En Python

          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.

### Syntaxe :

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

### Paramètres :

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 = Array(1, 2) signifie que la deuxième colonne est deux fois plus large que la première. Si le nombre de valeurs dans la matrice est inférieur au nombre de colonnes dans la table, 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.

### Exemple :

##### En Basic :

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

##### En Python

         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.

### Syntaxe :

svc.WriteLine(opt line: str): bool

### Paramètres :

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

### Exemple :

##### En Basic :

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

##### En Python

         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.

Rubriques connexes

SFDialogs. Service Dialog

ScriptForge.String service

ScriptForge.UI service