Contenu

# Service ScriptForge.UI

Le service UI (User Interface) simplifie l'identification et la manipulation des différentes fenêtres composant l'ensemble de l'application LibreOffice :

- Sélection des fenêtres

- Déplacer et redimensionner les fenêtres

- Paramètres de la barre d'état

- Affichage d'une barre de progression flottante

- Création de nouvelles fenêtres

- Accès aux "documents" sous-jacents

Le service UI est le point de départ pour ouvrir, créer ou accéder au contenu de documents nouveaux ou existants à partir d'un script utilisateur.

## Définitions

### WindowName

Une fenêtre peut être ébauchée de différentes manières :

- un chemin complet et un nom de fichier

- le dernier composant du nom complet du fichier ou même seulement le dernier composant sans son suffixe

- le titre de la fenêtre

- pour les nouveaux documents, quelque chose comme "Sans titre 1"

- une des fenêtres spéciales "BASICIDE" et "WELCOMESCREEN"

Le nom de la fenêtre est sensible à la casse.

### Objet du document

Les méthodes CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument et OpenDocument, décrites ci-dessous, génèrent des objets de document. Lorsqu'une fenêtre contient un document, une instance de la classe Document représente ce document. Un contre-exemple, l'EDI Basic n'est pas un document mais une fenêtre dans notre terminologie. De plus, un document a un type : Calc, Impress, Writer, ...

Les propriétés et méthodes spécifiques applicables aux documents sont implémentées dans une classe de document.

L'implémentation de la classe d'objets document se fait dans la bibliothèque associée SFDocuments. Voir son service "Document".

## Invocation du service

Avant d'utiliser le service UI, 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

##### En Basic :

        Dim ui As Variant
        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Set ui = CreateScriptService("UI")

##### En Python

        from scriptforge import CreateScriptService
        ui = CreateScriptService("UI")

## Propriétés

Nom | Lecture seule | Type | Description
--- | --- | --- | ---
ActiveWindow | Oui | String | un WindowName valide et unique pour la fenêtre actuellement active. Lorsque la fenêtre ne peut pas être identifiée, une chaîne de longueur nulle est renvoyée.
Height | Oui | Integer | Renvoie la hauteur de la fenêtre active en pixels.
Width | Oui | Integer | Renvoie la largeur de la fenêtre active en pixels.
X | Oui | Integer | Renvoie la coordonnée X de la fenêtre active, qui correspond à la distance jusqu'au bord gauche de l'écran en pixels.
Y | Oui | Integer | Renvoie la coordonnée Y de la fenêtre active, qui correspond à la distance jusqu'au bord supérieur de l'écran en pixels. Cette valeur ne prend pas en compte les décorations de fenêtre ajoutées par votre système d'exploitation. Ainsi, même lorsque la fenêtre est agrandie, cette valeur peut ne pas être nulle.

## Constantes

Nom | Valeur | Description
--- | --- | ---
MACROEXECALWAYS | 2 | Les macros sont toujours exécutées
MACROEXECNEVER | 1 | Les macros ne sont jamais exécutées
MACROEXECNORMAL | 0 | L'exécution des macros dépend des paramètres de l'utilisateur

### Exemple :

Les exemples ci-dessous montrent une MsgBox avec les noms de tous les documents actuellement ouverts.

##### En Basic :

         Dim openDocs As Object, strDocs As String
         Set openDocs = ui.Documents()
         strDocs = openDocs(0)
         For i = 1 To UBound(openDocs)
             strDocs = strDocs & Chr(10) & openDocs(i)
         Next i
         MsgBox strDocs

##### En Python

         ui = CreateScriptService("UI")
         bas = CreateScriptService("Basic")
         openDocs = ui.Documents()
         strDocs = "\n".join(openDocs)
         bas.MsgBox(strDocs)

Liste des méthodes dans le service UI
Activate CreateBaseDocument CreateDocument (*) Documents GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) Resize | RunCommand SetStatusBar (*) ShowProgressBar WindowExists

Notez, par exception, que les méthodes marquées (*) ne sont pas applicables aux documents Base.

## Activate

Rendez la fenêtre spécifiée active. La méthode renvoie True si la fenêtre donnée est trouvée et peut être activée. Il n'y a aucun changement dans l'interface utilisateur réelle si aucune fenêtre ne correspond à la sélection.

### Syntaxe :

svc.Activate(windowname: str): bool

### Paramètres :

windowame : voir les définitions ci-dessus.

### Exemple :

##### En Basic :

          ui.Activate("C:\Documents\My file.odt")

##### En Python

          ui.Activate(r"C:\Documents\My file.odt")

## CreateBaseDocument

Crée et stocke un nouveau document LibreOffice Base intégrant une base de données vide du type donné. La méthode renvoie une instance de service Document.

### Syntaxe :

svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc

### Paramètres :

filename : identifie le fichier à créer. Il doit suivre la notation SF_FileSystem.FileNaming. Si le fichier existe déjà, il est écrasé sans avertissement.

embeddeddatabase : soit "HSQLDB" (par défaut), "FIREBIRD" ou "CALC".

registrationname : Le nom utilisé pour stocker la nouvelle base de données dans le registre des bases de données. Lorsque = "" (par défaut), aucune inscription n'a lieu. Si le nom existe déjà, il est écrasé sans avertissement.

calcfilename : uniquement lorsque embeddeddatabase = "CALC", calcfilename représente le fichier contenant les tables sous forme de feuilles Calc. Le fichier doit exister sinon une erreur est générée.

### Exemple :

##### En Basic :

          Dim myBase As Object, myCalcBase As Object
          Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")
          Set myCalcBase = ui.CreateBaseDocument("C:\Databases\MyCalcBaseFile.odb", _
              "CALC", , "C:\Databases\MyCalcFile.ods")

##### En Python

         myBase = ui.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
         myCalcBase = ui.CreateBaseDocument(r"C:\Databases\MyCalcBaseFile.odb", \
             "CALC", calcfilename = r"C:\Databases\MyCalcFile.ods")

## CreateDocument (*)

Crée un nouveau document LibreOffice d'un type donné ou basé sur un modèle donné. La méthode renvoie une instance de la classe de document ou de l'une de ses sous-classes (Calc, Writer).

### Syntaxe :

svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc

### Paramètres :

documenttype : "Calc", "Writer", etc. S'il est absent, l'argument templatefile doit être présent.

templatefile : le FileName complet du modèle sur lequel construire le nouveau document. Si le fichier n'existe pas, l'argument est ignoré. Le service FileSystem fournit les propriétés TemplatesFolder et UserTemplatesFolder pour aider à construire l'argument.

hidden : si True, ouvre le nouveau document en arrière-plan (par défaut = False). À utiliser avec prudence : l'activation ou la fermeture ultérieure ne peut se produire que par programmation.

### Exemple :

Dans les deux exemples ci-dessous, le premier appel à la méthode CreateDocument crée un document Calc vierge, tandis que le second crée un document à partir d'un fichier modèle.

##### En Basic :

          Dim myDoc1 As Object, myDoc2 As Object, FSO As Object
          Set myDoc1 = ui.CreateDocument("Calc")
          Set FSO = CreateScriptService("FileSystem")
          Set myDoc2 = ui.CreateDocument(, FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))

##### En Python

         myDoc1 = ui.CreateDocument("Calc")
         fs = CreateScriptService("FileSystem")
         myDoc2 = ui.CreateDocument(templatefile = fs.BuildPath(fs.TemplatesFolder, "personal/CV.ott"))

## Documents

Liste des documents actuellement ouverts. Les fenêtres spéciales sont ignorées. Cette liste se compose d'une matrice unidimensionnel à base zéro contenant soit des noms de fichiers (en utilisant la notation ScriptForge.FileSystem.FileNaming), soit des titres de fenêtres pour les documents non enregistrés.

### Syntaxe :

svc.Documents(): str[1..*]

### Exemple :

Dans les deux exemples ci-dessous, la méthode peut renvoyer un tableau vide s'il n'y a aucun document ouvert.

##### En Basic :

          Dim docList As Variant
          docList = ui.Documents

##### En Python

         docList = ui.Documents()

## GetDocument

Renvoie une instance de la classe Document ou de l'une de ses sous-classes (Calc, Writer, Base, FormDocument) faisant référence soit à une fenêtre donnée, soit au document actif.

### Syntaxe :

svc.GetDocument(windowname: str = ''): svc

svc.GetDocument(windowname: uno): svc

### Paramètres :

windowame : voir les définitions ci-dessus. Si cet argument est absent, la fenêtre active est utilisée. Les objets UNO de types com.sun.star.lang.XComponent ou com.sun.star.comp.dba.ODatabaseDocument sont également acceptés. Ainsi, passer ThisComponent ou ThisDatabaseDocument comme argument crée un nouveau service SFDocuments.Document, Base ou Calc.

### Exemple :

##### En Basic :

          Dim myDoc As Object
          Set myDoc = ui.GetDocument("C:\Documents\My file.odt")
          Set myBase = ui.GetDocument(ThisDatabaseDocument)

##### En Python

         from scriptforge import CreateScriptService
         bas = CreateScriptService("Basic")
         myDoc = ui.GetDocument(r"C:\Documents\My file.odt")
         myDoc = ui.GetDocument(bas.ThisComponent)

Pour accéder au nom de la fenêtre actuellement active, reportez-vous à la propriété ActiveWindow.

## Maximize

Maximise la fenêtre active ou la fenêtre donnée.

### Syntaxe :

svc.Maximize(windowname: str)

### Paramètres :

windowame : voir les définitions ci-dessus. Si cet argument est absent, la fenêtre active est maximisée.

### Exemple :

##### En Basic :

          ui.Maximize("Untitled 1")

##### En Python

         ui.Maximize("Untitled 1")

## Minimize

Minimise la fenêtre active ou la fenêtre donnée.

### Syntaxe :

svc.Minimize(windowname: str)

### Paramètres :

windowame : voir les définitions ci-dessus. Si cet argument est absent, la fenêtre active est réduite.

### Exemple :

##### En Basic :

         ui.Minimize()

##### En Python

         ui.Minimize()

## OpenBaseDocument

Ouvrez un document LibreOffice Base existant. La méthode renvoie un objet Base.

### Syntaxe :

svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc

### Paramètres :

filename : identifie le fichier à ouvrir. Il doit suivre la notation SF_FileSystem.FileNaming.

registrationname : le nom à utiliser pour rechercher la base de données dans le registre des bases de données. Il est ignoré si FileName <> "".

macroexecution : 0 = le comportement est défini par la configuration utilisateur, 1 = les macros ne sont pas exécutables, 2 = les macros sont exécutables. La valeur par défaut est 0.

### Exemple :

##### En Basic :

          Dim myBase As Object
          Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)

##### En Python

         myBase = ui.OpenBaseDocument(r"C:\Documents\myDB.odb", macroexecution = ui.MACROEXECALWAYS)

Pour améliorer la lisibilité du code, vous pouvez utiliser des constantes prédéfinies pour l'argument macroexecution, comme dans les exemples ci-dessus.

## OpenDocument (*)

Ouvre un document LibreOffice existant avec les options données. Renvoie un objet document ou l'une de ses sous-classes. La méthode renvoie Nothing (en BASIC) ou None (en Python) si l'ouverture a échoué, même lorsque l'échec est provoqué par une décision de l'utilisateur.

### Syntaxe :

svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc

### Paramètres :

filename : identifie le fichier à ouvrir. Il doit suivre la notation FileNaming du service FileSystem.

password : à utiliser lorsque le document est protégé. En cas d'erreur ou d'absence alors que le document est protégé, l'utilisateur sera invité à saisir un mot de passe.

readonly: par défaut = False.

hidden : si True, ouvre le nouveau document en arrière-plan (par défaut = False). À utiliser avec prudence : l'activation ou la fermeture ultérieure ne peut se produire que par programmation.

macroexecution : 0 = le comportement est défini par la configuration utilisateur, 1 = les macros ne sont pas exécutables, 2 = les macros sont exécutables. La valeur par défaut est 0.

filtername : le nom d'un filtre qui doit être utilisé pour charger le document. Si cet argument est passé, le filtre doit exister.

filteroptions : une chaîne facultative d'options associées au filtre.

### Exemple :

##### En Basic :

          Dim myDoc As Object, FSO As Object
          Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)

##### En Python

         myDoc = ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)

## Resize

Redimensionne et/ou déplace la fenêtre active. Les arguments absents et négatifs sont ignorés. Si la fenêtre est réduite ou agrandie, l'appel de Resize sans arguments la restaure.

### Syntaxe :

svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)

### Paramètres :

left, top : distances du coin supérieur gauche aux bords supérieur et gauche de l'écran, en pixels.

width, height : nouvelles dimensions de la fenêtre, en pixels.

### Exemple :

Dans les exemples suivants, la largeur et la hauteur de la fenêtre sont modifiées tandis que les valeurs top et gauche restent inchangées.

##### En Basic :

          ui.Resize(Width := 500, Height := 500)

##### En Python

         ui.Resize(width = 500, height = 500)

Pour redimensionner une fenêtre qui n'est pas active, activez-la d'abord à l'aide de la méthode Activate.

## RunCommand

Exécute une commande UNO sur la fenêtre actuelle. Quelques commandes typiques sont : Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.

Les commandes peuvent être exécutées avec ou sans arguments. Les arguments ne sont pas validés avant l'exécution de la commande. Si la commande ou ses arguments ne sont pas valides, rien ne se passera.

Pour une liste complète des commandes UNO pouvant être exécutées dans LibreOffice, reportez-vous à la page Wiki Development/DispatchCommands.

### Syntaxe :

svc.RunCommand(command: str, [args: any])

### Paramètres :

command : chaîne sensible à la casse contenant le nom de la commande UNO. L'inclusion du préfixe ".uno :" dans la commande est facultative. L'exactitude de la commande elle-même n'est pas vérifiée. Si rien ne se passe après l'appel de la commande, la commande est probablement erronée.

args : pour chaque argument à transmettre à la commande, spécifiez une paire contenant le nom et la valeur de l'argument.

### Exemple :

##### En Basic :

L'exemple suivant exécute la commande .uno:About dans la fenêtre actuelle.

        Set ui = CreateScriptService("UI")
        ui.RunCommand("About")

Vous trouverez ci-dessous un exemple qui exécute la commande UNO .uno:BasicIDEAppear et transmet les arguments requis pour ouvrir l'EDI Basic sur une ligne spécifique d'un module.

        ' Arguments passés à la commande :
        ' Document  = "LibreOffice Macros & Dialogs"
        ' LibName = "ScriptForge"
        ' Name = "SF_Session"
        ' Line = 600
        ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", _
                      "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)

Notez qu'appeler la commande BasicIDEAppear sans arguments ouvrira simplement l'EDI Basic.

##### En Python

        ui = CreateScriptService("UI")
        ui.RunCommand("About")

        ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", \
                      "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)

En Python, il est également possible d'appeler RunCommand en utilisant des arguments de mots-clés :

        ui.RunCommand(".uno:BasicIDEAppear", Document = "LibreOffice Macros & Dialogs", \
                      LibName = "ScriptForge", Name = "SF_Session", Line = 600)

Chaque composant LibreOffice dispose de son propre jeu de commandes. Un moyen simple d'apprendre les commandes est d'aller dans Outils - Personnaliser - Clavier. Lorsque le curseur de la souris est positionné sur une fonction dans la liste Fonction, une info-bulle apparaît avec la commande UNO correspondante.

## SetStatusbar (*)

Afficher un texte et une barre de progression dans la barre d'état de la fenêtre active. Tous les appels ultérieurs dans la même exécution de macro font référence à la même barre d'état de la même fenêtre, même si la fenêtre n'est plus visible. Un appel sans arguments réinitialise la barre d'état à son état normal.

### Syntaxe :

svc.SetStatusbar(text: str = '', percentage: int = -1)

### Paramètres :

text : un texte facultatif à afficher devant la barre de progression.

percentage : un degré de progression facultatif compris entre 0 et 100.

### Exemple :

##### En Basic :

          Dim i As Integer
          For i = 0 To 100
              ui.SetStatusbar("Progress ...", i)
              Wait 50
          Next i
          ' Réinitialise la barre d'état
          ui.SetStatusbar

##### En Python

         from time import sleep
         for i in range(101):
             ui.SetStatusbar("Test:", i)
             sleep(0.05)
         ui.SetStatusbar()

## ShowProgressBar

Affiche une boîte de dialogue non modale. Précisez son titre, un texte explicatif et un pourcentage de progression à représenter sur une barre de progression. La boîte de dialogue restera visible jusqu'à un appel à la méthode sans arguments ou jusqu'à ce que l'utilisateur ferme manuellement la boîte de dialogue.

### Syntaxe :

svc.ShowProgressBar(title: str = '', text: str = '', percentage: int = -1)

### Paramètres :

title : le titre apparaissant en haut de la boîte de dialogue. Par défaut = "ScriptForge".

text : un texte facultatif à afficher au-dessus de la barre de progression.

percentage : un degré de progression facultatif compris entre 0 et 100.

### Exemple :

##### En Basic :

          Dim i As Integer
          For i = 0 To 100
              ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
              Wait 50
          Next i
          'Ferme la fenêtre de la barre de progression
          ui.ShowProgressBar

##### En Python

         from time import sleep
         for i in range(101):
             ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
             sleep(0.05)
         # Ferme la fenêtre de la barre de progression
         ui.ShowProgressBar()

## WindowExists

Renvoie True si la fenêtre donnée peut être identifiée.

### Syntaxe :

svc.WindowExists(windowname: str): bool

### Paramètres :

windowame : voir les définitions ci-dessus.

### Exemple :

##### En Basic :

          If ui.WindowExists("C:\Document\My file.odt") Then
              ' ...

##### En Python

         if ui.WindowExists(r"C:\Document\My file.odt"):
             # ...

Rubriques connexes

ScriptForge.Service Basic

SFDocuments. Service Calc

Service SFDocuments.Document