Dienst ScriptForge.UI

Der Dienst UI (User Interface) vereinfacht die Identifizierung und Handhabung der verschiedenen Fenster, aus denen sich die gesamte LibreOffice-Anwendung zusammensetzt:

• Fensterauswahl

• Fenster verschieben und skalieren

• Statusleisten-Einstellungen

• Anzeige eines schwebenden Fortschrittsbalkens

• Erstellung neuer Fenster

• Zugriff auf die zugrunde liegenden "Dokumente"

Der Dienst UI ist der Ausgangspunkt zum Öffnen, Erstellen oder Zugreifen auf den Inhalt neuer oder bestehender Dokumente aus einem Benutzerskript.

Definitionen

WindowName

Ein Fenster kann auf verschiedene Arten bezeichnet werden:

• ein vollständiger Pfad und Dateiname

• der letzte Bestandteil des vollständigen Dateinamens oder auch nur der letzte Bestandteil ohne sein Suffix

• der Titel des Fensters

• für neue Dokumente so etwas wie "Unbenannt 1"

• eines der Spezialfenster "BASICIDE" und "WELCOMESCREEN"

Beim Fensternamen wird zwischen Groß- und Kleinschreibung unterschieden.

Objekt "Document"

Die unten beschriebenen Methoden CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument und OpenDocument generieren Objekte "Document". Wenn ein Fenster ein Dokument enthält, repräsentiert eine Instanz der Klasse Document dieses Dokument. Ein Gegenbeispiel: Die Basic IDE ist kein Dokument, sondern ein Fenster in unserer Terminologie. Zusätzlich hat ein Dokument einen Typ: Calc, Impress, Writer, …

Die spezifischen Eigenschaften und Methoden, die auf Dokumente anwendbar sind, werden in einer Klasse "Document" implementiert.

Die Implementierung der Dokumentobjektklasse erfolgt in der zugehörigen Bibliothek SFDocuments. Siehe Dienst "Document".

Dienstaufruf

Vor der Verwendung des Dienstes UI muss die Bibliothek ScriptForge geladen oder importiert werden:

• Grundlegende Makros erfordern das Laden der Bibliothek ScriptForge mit der folgenden Anweisung:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-Skripte erfordern einen Import aus dem Modul scriptforge:
from scriptforge import CreateScriptService

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

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

Eigenschaften

Konstanten

Die folgenden Beispiele zeigen eine MsgBox mit den Namen aller derzeit geöffneten Dokumente.

      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)
   

Beachten Sie als Ausnahme, dass die mit (*) gekennzeichneten Methoden nicht auf Base-Dokumente anwendbar sind.

Activate

Aktiviert das angegebene Fenster. Die Methode gibt True zurück, wenn das angegebene Fenster gefunden wird und aktiviert werden kann. Es gibt keine Änderung in der eigentlichen Benutzeroberfläche, wenn kein Fenster der Auswahl entspricht.

svc.Activate(windowname: str): bool

windowname: siehe obige Definitionen.

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

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

CreateBaseDocument

Erstellt und speichert ein neues LibreOffice-Base-Dokument, das eine leere Datenbank des angegebenen Typs einbettet. Die Methode gibt eine Dienstinstanz Document zurück.

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

filename: Identifiziert die zu erstellende Datei. Es muss der Notation SF_FileSystem.FileNaming folgen. Existiert die Datei bereits, wird sie ohne Warnung überschrieben

embeddeddatabase: "HSQLDB" (Standard), "FIREBIRD" oder "CALC".

registrationname: Der Name, der verwendet wird, um die neue Datenbank im Datenbankregister zu speichern. Wenn = "" (Standard), findet keine Registrierung statt. Existiert der Name bereits, wird er ohne Warnung überschrieben.

calcfilename: Nur wenn embeddeddatabase = "CALC", stellt calcfilename die Datei dar, welche die Tabellen als Tabellendokument enthält. Die Datei muss vorhanden sein oder es wird ein Fehler ausgelöst.

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

Erstellen Sie ein neues LibreOffice-Dokument eines bestimmten Typs oder basierend auf einer bestimmten Vorlage. Die Methode gibt ein Objekt "Document" zurück.

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

documenttype : "Calc", "Writer", … Wenn nicht vorhanden, muss das Argument templatefile vorhanden sein.

templatefile: Der vollständige FileName der Vorlage, auf der das neue Dokument aufgebaut werden soll. Wenn die Datei nicht existiert, wird das Argument ignoriert. Der Dienst FileSystem stellt die Eigenschaften TemplatesFolder und UserTemplatesFolder bereit, um beim Erstellen des Arguments zu helfen.

hidden: wenn True, öffnet das neue Dokument im Hintergrund (Standard = False). Mit Vorsicht zu verwenden: Die Aktivierung oder Schließung kann danach nur programmgesteuert erfolgen.

In den beiden folgenden Beispielen erstellt der erste Aufruf der Methode CreateDocument ein leeres Calc-Dokument, während der zweite ein Dokument aus einer Vorlagendatei erstellt.

      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

Gibt ein offenes Objekt "Document" zurück, das entweder auf das aktive Fenster, ein bestimmtes Fenster oder das aktive Dokument verweist.

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

svc.GetDocument(windowname: uno): svc

windowname: Siehe die Definitionen oben. Fehlt dieses Argument, wird das aktive Fenster verwendet. UNO-Objekte vom Typ com.sun.star.lang.XComponent oder com.sun.star.comp.dba.ODatabaseDocument werden ebenfalls akzeptiert. Wenn Sie also ThisComponent oder ThisDatabaseDocument als Argument übergeben, wird ein neuer Dienst SFDocuments.Document, Base oder Calc erstellt.

      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)
   

Um auf den Namen des derzeit aktiven Fensters zuzugreifen, beziehen Sie sich auf die Eigenschaft ActiveWindow.

Maximize

Maximiert das aktive Fenster oder das angegebene Fenster.

svc.Maximize(windowname: str)

windowname: siehe Definitionen oben. Fehlt dieses Argument, wird das aktive Fenster maximiert.

      ui.Maximize("Untitled 1")
   

     ui.Maximize("Untitled 1")
   

Minimize

Minimiert das aktive Fenster oder das angegebene Fenster.

svc.Minimize(windowname: str)

windowname: siehe Definitionen oben. Fehlt dieses Argument, wird das aktive Fenster minimiert.

     ui.Minimize()
   

     ui.Minimize()
   

OpenBaseDocument

Öffnen Sie ein vorhandenes LibreOffice Base-Dokument. Die Methode gibt ein Objekt "Document" zurück.

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

filename: Identifiziert die zu öffnende Datei. Es muss der Notation SF_FileSystem.FileNaming folgen.

registrationname: Der Name, der verwendet werden soll, um die Datenbank im Datenbankregister zu finden. Es wird ignoriert, wenn FileName <> "".

makroexecution: 0 = Verhalten wird durch die Benutzerkonfiguration festgelegt, 1 = Makros sind nicht ausführbar, 2 = Makros sind ausführbar.

      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)
   

Um die Lesbarkeit des Codes zu verbessern, können Sie wie in den obigen Beispielen vordefinierte Konstanten für das Argument macroexecution.

OpenDocument (*)

Öffnet ein vorhandenes LibreOffice-Dokument mit den angegebenen Optionen. Gibt ein Dokumentobjekt oder eine seiner Unterklassen zurück. Die Methode gibt Nothing (in BASIC) oder None (in Python) zurück, wenn das Öffnen fehlgeschlagen ist, selbst wenn der Fehler durch eine Benutzerentscheidung verursacht wurde.

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

filename: Identifiziert die zu öffnende Datei. Es muss der Notation FileNaming des Dienstes FileSystem folgen.

password: Zu verwenden, wenn das Dokument geschützt ist. Falls falsch oder nicht vorhanden, während das Dokument geschützt ist, wird der Benutzer aufgefordert, ein Kennwort einzugeben.

readonly: Standard = False.

hidden: wenn True, öffnet das neue Dokument im Hintergrund (Standard = False). Mit Vorsicht zu verwenden: Die Aktivierung oder Schließung kann danach nur programmgesteuert erfolgen.

macroexecution: 0 = Verhalten wird durch die Benutzerkonfiguration festgelegt, 1 = Makros sind nicht ausführbar, 2 = Makros sind ausführbar.

filtername: Der Name eines Filters, der zum Laden des Dokuments verwendet werden soll. Falls vorhanden, muss der Filter vorhanden sein.

filteroptions: Eine optionale Reihe von Optionen, die dem Filter zugeordnet sind.

      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

Ändert die Größe und/oder verschiebt das aktive Fenster. Fehlende und negative Argumente werden ignoriert. Wenn das Fenster minimiert oder maximiert ist, wird es durch Aufrufen von Resize ohne Argumente wiederhergestellt.

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

left, top: Abstände der oberen linken Ecke vom oberen und linken Rand des Bildschirms in Pixel.

width, height: Neue Abmessungen des Fensters in Pixel.

In den folgenden Beispielen werden width und height des Fensters geändert, während top und left unverändert bleiben.

      ui.Resize(, ,500, 500)
   

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

Um die Größe eines nicht aktiven Fensters zu ändern, aktivieren Sie es zunächst mit der Methode Activate.

RunCommand

Führt einen UNO-Befehl im aktuellen Fenster aus. Einige typische Befehle sind: "Save", "SaveAs", "ExportToPDF", "Undo", "Copy", "Paste" und so weiter.

Befehle können mit oder ohne Argumente ausgeführt werden. Argumente werden nicht validiert, bevor der Befehl ausgeführt wird. Wenn der Befehl oder seine Argumente ungültig sind, wird nichts passieren.

Eine vollständige Liste der UNO-Befehle, die in LibreOffice ausgeführt werden können, finden Sie auf der Wiki-Seite Development/DispatchCommands.

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

command: Groß-/Kleinschreibung beachtende Zeichenfolge, die den UNO-Befehlsnamen enthält. Die Aufnahme des Präfixes ".uno:" in den Befehl ist optional. Der Befehl selbst wird nicht auf Korrektheit überprüft. Wenn nach dem Befehlsaufruf nichts passiert, dann ist der Befehl wahrscheinlich falsch.

args: Legen Sie für jedes Argument, das an den Befehl übergeben werden soll, ein Paar fest, das den Namen und den Wert des Arguments enthält.

Das folgende Beispiel führt den Befehl .uno:About im aktuellen Fenster aus.

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

Unten sehen Sie ein Beispiel, das den UNO-Befehl .uno:BasicIDEAppear ausführt und die zum Öffnen der Basic-IDE erforderlichen Argumente an einer bestimmten Zeile eines Moduls übergibt.

    ' An den Befehl übergebene Argumente:
    ' 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)
  

Beachten Sie, dass das Aufrufen des Befehls BasicIDEAppear ohne Argumente einfach die Basic IDE öffnet.

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

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

In Python ist es auch möglich, RunCommand mit Schlüsselwortargumenten aufzurufen:

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

Jede LibreOffice-Komponente verfügt über einen eigenen Befehlssatz. Eine einfache Möglichkeit, Befehle zu lernen, ist der Aufruf von Extras – Anpassen… – Register: Tastatur. Wenn Sie Ihre Maus über eine Funktion in der Liste Funktion bewegen, erscheint ein Tooltipp mit dem entsprechenden UNO-Befehl.

SetStatusbar (*)

Zeigt einen Text und einen Fortschrittsbalken in der Statusleiste des aktiven Fensters an. Alle nachfolgenden Aufrufe im gleichen Makrolauf beziehen sich auf die gleiche Statuszeile des gleichen Fensters, auch wenn das Fenster nicht mehr sichtbar ist. Ein Aufruf ohne Argumente setzt die Statusleiste in ihren Normalzustand zurück.

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

text: Ein optionaler Text, der vor dem Fortschrittsbalken angezeigt werden soll.

percentage: ein optionaler Fortschrittsgrad zwischen 0 und 100.

      Dim i As Integer
      For i = 0 To 100
          ui.SetStatusbar("Progress ...", i)
          Wait 50
      Next i
      ' Setzt die Statusleiste zurück
      ui.SetStatusbar
   

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

ShowProgressBar

Zeigt einen nicht modalen Dialog an. Legen Sie den Titel, einen erläuternden Text und einen Prozentsatz des Fortschritts fest, der auf einem Fortschrittsbalken dargestellt werden soll. Der Dialog bleibt sichtbar, bis die Methode ohne Argumente aufgerufen wird oder der Benutzer den Dialog manuell schließt.

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

title: Der Titel, der oben im Dialog erscheint. Standard = "ScriptForge".

text: Ein optionaler Text, der über dem Fortschrittsbalken angezeigt wird.

percentage: ein optionaler Fortschrittsgrad zwischen 0 und 100.

      Dim i As Integer
      For i = 0 To 100
          ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
          Wait 50
      Next i
      ' Schließt das Fenster mit dem Fortschrittsbalken
      ui.ShowProgressBar
   

     from time import sleep
     for i in range(101):
         ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
         sleep(0.05)
     # Schließt das Fenster mit dem Fortschrittsbalken
     ui.ShowProgressBar()
   

WindowExists

Gibt True zurück, wenn das angegebene Fenster identifiziert werden konnte.

svc.WindowExists(windowname: str): bool

windowname: siehe obige Definitionen.

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

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