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 Collabora Office :

• 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

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

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

Propriétés

Constantes

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)

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.

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

CreateBaseDocument

Crée et stocke un nouveau document Collabora Office 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")

CreateDocument (*)

Créez un nouveau document Collabora Office d'un type donné ou basé sur un modèle donné. La méthode renvoie un objet document.

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

GetDocument

Renvoie un objet document ouvert faisant référence soit à la fenêtre active, 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.

Maximize

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

Minimize

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

OpenBaseDocument

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

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.

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

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 Collabora Office 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.

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)

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.

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

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 Collabora Office, 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'EDI Basic.

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 Collabora Office 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.

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

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.

svc.ShowProgressBar(title: str = '', text: str = '', percentage: str = -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()

WindowExists

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