Aide LibreOffice 25.8
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.
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.
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".
Avant d'utiliser le service UI, la bibliothèque ScriptForge doit être chargée ou importée :
    Dim ui As Variant
    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Set ui = CreateScriptService("UI")
  
    from scriptforge import CreateScriptService
    ui = CreateScriptService("UI")
  | 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. | 
| 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 | 
Les exemples ci-dessous montrent une MsgBox avec les noms de tous les documents actuellement ouverts.
     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
   
     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 | ||
Notez, par exception, que les méthodes marquées (*) ne sont pas applicables aux documents Base.
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.
svc.Activate(windowname: str): bool
windowame : voir les définitions ci-dessus.
      ui.Activate("C:\Documents\My file.odt")
    
      ui.Activate(r"C:\Documents\My file.odt")
    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.
svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc
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.
      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")
   
     myBase = ui.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
     myCalcBase = ui.CreateBaseDocument(r"C:\Databases\MyCalcBaseFile.odb", \
         "CALC", calcfilename = r"C:\Databases\MyCalcFile.ods")
   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).
svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc
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.
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.
      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"))
   
     myDoc1 = ui.CreateDocument("Calc")
     fs = CreateScriptService("FileSystem")
     myDoc2 = ui.CreateDocument(templatefile = fs.BuildPath(fs.TemplatesFolder, "personal/CV.ott"))
   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.
svc.Documents(): str[1..*]
Dans les deux exemples ci-dessous, la méthode peut renvoyer un tableau vide s'il n'y a aucun document ouvert.
      Dim docList As Variant
      docList = ui.Documents
   
     docList = ui.Documents()
   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.
svc.GetDocument(windowname: str = ''): svc
svc.GetDocument(windowname: uno): svc
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.
      Dim myDoc As Object
      Set myDoc = ui.GetDocument("C:\Documents\My file.odt")
      Set myBase = ui.GetDocument(ThisDatabaseDocument)
   
     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.
Maximise la fenêtre active ou la fenêtre donnée.
svc.Maximize(windowname: str)
windowame : voir les définitions ci-dessus. Si cet argument est absent, la fenêtre active est maximisée.
      ui.Maximize("Untitled 1")
   
     ui.Maximize("Untitled 1")
   Minimise la fenêtre active ou la fenêtre donnée.
svc.Minimize(windowname: str)
windowame : voir les définitions ci-dessus. Si cet argument est absent, la fenêtre active est réduite.
     ui.Minimize()
   
     ui.Minimize()
   Ouvrez un document LibreOffice Base existant. La méthode renvoie un objet Base.
svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc
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.
      Dim myBase As Object
      Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)
   
     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.
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.
svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc
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.
      Dim myDoc As Object, FSO As Object
      Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)
   
     myDoc = ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)
   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.
svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)
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.
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.
      ui.Resize(Width := 500, Height := 500)
   
     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.
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.
svc.RunCommand(command: str, [args: any])
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.
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'.
    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.
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.
svc.SetStatusbar(text: str = '', percentage: int = -1)
text : un texte facultatif à afficher devant la barre de progression.
percentage : un degré de progression facultatif compris entre 0 et 100.
      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
   
     from time import sleep
     for i in range(101):
         ui.SetStatusbar("Test:", i)
         sleep(0.05)
     ui.SetStatusbar()
   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.
svc.ShowProgressBar(title: str = '', text: str = '', percentage: int = -1)
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.
      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
   
     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()
   Renvoie True si la fenêtre donnée peut être identifiée.
svc.WindowExists(windowname: str): bool
windowame : voir les définitions ci-dessus.
      If ui.WindowExists("C:\Document\My file.odt") Then
          ' ...
   
     if ui.WindowExists(r"C:\Document\My file.odt"):
         # ...