Service SFDialogs.Dialog

Contenu
Index 🔎︎

# SFDialogs. Service Dialog

Le service Dialog contribue à la gestion des dialogues créés avec le Dialog Editor Basic . Chaque instance de la classe actuelle représente une seule boîte de dialogue affichée à l'utilisateur.

Une boîte de dialogue peut être affichée en mode modal ou en mode non modal.

En mode modal, la boîte s'affiche et l'exécution du traitement de la macro est suspendue jusqu'à ce que l'un des boutons OK ou Annuler soit enfoncé. En attendant, les actions de l'utilisateur exécutées sur la boîte de dialogue peuvent déclencher des actions spécifiques.

En mode non modal, la boîte de dialogue est "flottante" sur le bureau de l'utilisateur et l'exécution du processus de macro se poursuit normalement. Une boîte de dialogue non modale se ferme lorsqu'elle est terminée avec la méthode Terminate() ou lorsque la session LibreOffice se termine. Le bouton de fermeture de fenêtre est inactif dans les boîtes de dialogue non modales.

Une boîte de dialogue disparaît de la mémoire après sa fermeture explicite.

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

## Invocation de service et utilisation.

Le service Dialog est appelé via la méthode CreateScriptService. Il nécessite trois arguments de position pour spécifier la boîte de dialogue à activer :

Container : "GlobalScope" pour les bibliothèques préinstallées ou un nom de la fenêtre tel que défini par le service ScriptForge.UI. La valeur par défaut de la chaîne vide "" correspond au document actuel.

Library : le nom sensible à la casse d'une bibliothèque contenue dans le conteneur. La valeur par défaut est "Standard".

DialogName : une chaîne sensible à la casse désignant la boîte de dialogue.

Ci-dessous, les exemples LibreOffice Basic et Python affichent la boîte de dialogue dlgConsole qui appartient à la bibliothèque partagée ScriptForge :

          Dim oDlg As Object, lButton As Long
          Dim Container As String, Library As String, DialogName As String
          Set oDlg = CreateScriptService("SFDialogs.Dialog", "GlobalScope", "ScriptForge", "dlgConsole")
          '... l'initialisation des contrôles va ici...
          lButton = oDlg.Execute()
          'Mode par défaut = Modal
          If lButton = oDlg.OKBUTTON Then
          '... Traiter les contrôles et faire ce qui est nécessaire ici
          End If
          oDlg.Terminate()

Ou en utilisant Python :

        dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', 'ScriptForge', 'dlgConsole')
        #... l'initialisation des contrôles va ici...
        rc = dlg.Execute()
        # Le mode par défaut est Modal
        if rc == dlg.OKBUTTON:
            #... Traiter les contrôles et faire ce qui est nécessaire ici
        dlg.Terminate()

Alternativement, une instance Dialog peut être récupérée via le service SFDialogs.DialogEvent, à condition que le dialogue ait été lancé avec le service Dialog. DialogEvent renvoie l'instance de service SFDialogs.Dialog qui a déclenché l'événement.

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

En Python :

        def some_event(event: uno):
            dlg = CreateScriptService("SFDialogs.DialogEvent", event)

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

## Propriétés

Nom | Lecture seule | Type | Description
OKBUTTON | Oui | Integer | Value=1. Un bouton OK a été pressé.
CANCELBUTTON | Oui | Integer | Value=0. Un bouton Annuler a été pressé.
Caption | Non | String | Spécifier le titre de la boîte de dialogue.
Height | Non | Long | Spécifier la hauteur de la boîte de dialogue.
Modal | Oui | Boolean | Spécifie si la boîte de dialogue est actuellement en cours d'exécution en mode modal.
Name | Oui | String | Le nom de la boîte de dialogue
Page | Non | Integer | 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.
Visible | Non | Boolean | Spécifier si la boîte de dialogue est visible sur le bureau. Par défaut, elle n'est pas visible tant que la méthode Execute() n'est pas exécutée et visible ensuite.
XDialogModel | Oui | UNO object | L'objet UNO représentant le modèle de boîte de dialogue. Reportez-vous à XControlModel et UnoControlDialogModel dans la documentation de l'interface de programmation d'application (API) pour des informations détaillées.
XDialogView | Oui | UNO object | L'objet UNO représentant la vue de la boîte de dialogue. Reportez-vous à XControl et UnoControlDialog dans la documentation de l'interface de programmation d'application (API) pour des informations détaillées.
Width | Non | Long | Spécifier la largeur de la boîte de dialogue.

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

Renvoie une chaîne URI avec la référence au script déclenché par l'événement. Lisez sa spécification dans la spécification de l'URI framework de script.

Nom | Lecture seule | Description de l'IDE Basic
OnFocusGained | Oui | À la réception du focus
OnFocusLost | Oui | À la perte du focus
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 | Souris déplacée
OnMousePressed | Oui | Bouton de la souris enfoncé
OnMouseReleased | Oui | Bouton de la souris relâché

| Méthodes |
Activate Controls | EndExecute Execute | GetTextsFromL10N Terminate

## Activate

Définir le focus sur l'instance Dialog active. Renvoie True si la mise au point a réussi.

Cette méthode est appelée à partir d'un événement de boîte de dialogue ou de contrôle, ou lorsqu'une boîte de dialogue est affichée en mode non modal.

### Syntaxe :

svc.Activate(): bool

### Exemple :

          Dim oDlg As Object
          Set oDlg = CreateScriptService(,, "myDialog")
          oDlg.Execute()
          ' ...
          oDlg.Activate()

Les exemples Python et LibreOffice Basic supposent tous deux que la boîte de dialogue est stockée dans la bibliothèque Standard du document actif.

         dlg = CreateScriptService(,,'myDialog')
         dlg.Execute()
         # ...
         dlg.Activate()

## Controls

Renvoyer soit :

- la liste des contrôles contenus dans la boîte de dialogue

- une instance de classe DialogControl basée sur son nom

### 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 myDialog As Object, myList As Variant, myControl As Object
          Set myDialog = CreateScriptService("SFDialogs.Dialog", , "Standard", "Dialog1")
          myList = myDialog.Controls()
          Set myControl = myDialog.Controls("myTextBox")

         dlg = CreateScriptService('SFDialogs.Dialog','', 'Standard', 'Dialog1')
         ctrls = dlg.Controls()
         ctrl = dlg.Controls('myTextBox')

## EndExecute

Termine l'affichage d'une boîte de dialogue modale et renvoie l'argument comme valeur de retour pour l'action en cours d'exécution Execute().

EndExecute() is usually contained in the processing of a macro triggered by a dialog or control event.

### Syntaxe :

svc.EndExecute(returnvalue: int)

### Paramètres :

returnvalue: The value passed to the running Execute() method.

### Exemple :

Using LibreOffice Basic:

          Sub OnEvent(poEvent As com.sun.star.lang.EventObject)
              Dim oDlg As Object
              Set oDlg = CreateScriptService("SFDialogs.DialogEvent", poEvent)
              oDlg.EndExecute(ReturnValue := 25)
          End Sub

Using Python:

         from com.sun.star.lang import EventObject
         def on_event(event: EventObject):
             dlg = CreateScriptService("SFDialogs.DialogEvent", event)
             dlg.EndExecute(25)

Above com.sun.star.lang.EventObject mentions are optional. Such annotations help identify LibreOffice Application Programming Interface (API).

## Execute

Display the dialog box and, when modal, wait for its termination by the user. The returned value is either:

- 0 : Cancel button pressed

- 1 : OK button pressed

- Otherwise the dialog stopped with an EndExecute() statement issued by a dialog or control event

For non-modal dialog boxes the method always returns 0 and the execution of the macro continues.

### Syntaxe :

svc.Execute(modal: bool = True): int

### Paramètres :

modal: False when non-modal dialog. Default = True.

### Exemple :

In this Basic example myDialog dialog is stored in current document's Standard library.

          Dim oDlg As Object, lReturn As Long
          Set oDlg = CreateScriptService("SFDialogs.Dialog", , , "myDialog")
          lReturn = oDlg.Execute(Modal := False)
          Select Case lReturn
              ' ...
          End Select

This Python code displays DlgConvert modal dialog from Euro shared Basic library.

         dlg = CreateScriptService("SFDialogs.Dialog", 'GlobalScope', 'Euro', "DlgConvert")
         rc = dlg.Execute()
         if rc == dlg.CANCELBUTTON:
             # ...

## GetTextsFromL10N

Replaces all fixed text strings in a dialog by their translated versions based on a L10N service instance. This method translates the following strings:

- The title of the dialog.

- The caption of the following control types: Button, CheckBox, FixedLine, FixedText, GroupBox and RadioButton.

- Static strings in ListBoxes and ComboBoxes.

- The tooltip or help text displayed when the mouse hovers over the control.

The method returns True if successful.

To create a list of translatable strings in a dialog use the AddTextsFromDialog method from the L10N service.

### Syntaxe :

svc.GetTextsFromL10N(l10n: svc): bool

### Paramètres :

l10n: A L10N service instance from which translated strings will be retrieved.

### Exemple :

The following example loads translated strings and applies them to the dialog "MyDialog".

##### En Basic :

         oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
         myPO = CreateScriptService("L10N", "/home/user/po_files/")
         oDlg.GetTextsFromL10N(myPO)
         oDlg.Execute()

##### En Python

         dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
         myPO = CreateScriptService("L10N", "/home/user/po_files/")
         dlg.GetTextsFromL10N(myPO)
         dlg.Execute()

Read the L10N service help page to learn more about how PO and POT files are handled.

## Terminate

Terminate the Dialog service for the current instance. Return True if the termination was successful.

### Syntaxe :

svc.Terminate(): bool

### Exemple :

Below Basic and Python examples open DlgConsole and dlgTrace non-modal dialogs. They are respectively stored in ScriptForge and Access2Base shared libraries. Dialog close buttons are disabled and explicit termination is performed at the end of a running process.

In this example a button in DlgConsole is substituting inhibited window closing:

         oDlg = CreateScriptService("SFDialogs.Dialog","GlobalScope","ScriptForge","DlgConsole")
         oDlg.Execute(modal:=False)
         Wait 5000
         oDlg.Terminate()

With Python:

         from time import sleep
         dlg = CreateScriptService('SFDialogs.Dialog',"GlobalScope",'Access2Base',"dlgTrace")
         dlg.Execute(modal=False)
         sleep 5
         dlg.Terminate()

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.DialogControl service

ScriptForge.UI service