Dienst ScriptForge.UI

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

tip

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:

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.

tip

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:

note

• 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


In Basic

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

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

Eigenschaften

Name

Schreibgeschützt

Typ

Beschreibung

ActiveWindow

Ja

String

ein gültiger und eindeutiger WindowName für das aktuell aktive Fenster. Wenn das Fenster nicht identifiziert werden kann, wird eine Zeichenfolge der Länge Null zurückgegeben.

Documents

Ja

String array

Die Liste der aktuell geöffneten Dokumente. Sonderfenster werden ignoriert. Diese Liste besteht aus einer nullbasierten eindimensionalen Matrix entweder aus Dateinamen (in der Notation SF_FileSystem.FileNaming) oder aus Fenstertiteln für nicht gespeicherte Dokumente.

Height

Ja

Integer

Gibt die Höhe des aktiven Fensters in Pixel zurück.

Width

Ja

Integer

Gibt die Breite des aktiven Fensters in Pixel zurück.

X

Ja

Integer

Gibt die X-Koordinate des aktiven Fensters zurück, also den Abstand zum linken Bildschirmrand in Pixel.

Y

Ja

Integer

Gibt die Y-Koordinate des aktiven Fensters zurück, also den Abstand zum oberen Bildschirmrand in Pixel. Dieser Wert berücksichtigt keine Fensterdekorationen, die von Ihrem Betriebssystem hinzugefügt wurden, sodass dieser Wert selbst bei maximiertem Fenster möglicherweise nicht Null ist.


Konstanten

Name

Wert

Beschreibung

MACROEXECALWAYS

2

Makros werden immer ausgeführt

MACROEXECNEVER

1

Makros werden nie ausgeführt

MACROEXECNORMAL

0

Die Makroausführung hängt von den Benutzereinstellungen ab


Beispiel:

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

In 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
   
In Python

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

Liste der Methoden im Dienst "UI"

Activate
CreateBaseDocument
CreateDocument (*)
GetDocument
Maximize

Minimize
OpenBaseDocument
OpenDocument (*)
Resize

RunCommand
SetStatusBar (*)
ShowProgressBar
WindowExists


warning

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.

Syntax:

svc.Activate(windowname: str): bool

Parameter:

windowname: siehe obige Definitionen.

Beispiel:

In Basic

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

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

CreateBaseDocument

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

Syntax:

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

Parameter:

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.

Beispiel:

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

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

Syntax:

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

Parameter:

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.

Beispiel:

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.

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

     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.

Syntax:

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

svc.GetDocument(windowname: uno): svc

Parameter:

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.

Beispiel:

In Basic

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

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

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.

Syntax:

svc.Maximize(windowname: str)

Parameter:

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

Beispiel:

In Basic

      ui.Maximize("Untitled 1")
   
In Python

     ui.Maximize("Untitled 1")
   

Minimize

Minimiert das aktive Fenster oder das angegebene Fenster.

Syntax:

svc.Minimize(windowname: str)

Parameter:

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

Beispiel:

In Basic

     ui.Minimize()
   
In Python

     ui.Minimize()
   

OpenBaseDocument

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

Syntax:

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

Parameter:

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.

Beispiel:

In Basic

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

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

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


OpenDocument (*)

Öffnet ein vorhandenes Collabora Office-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.

Syntax:

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

Parameter:

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.

Beispiel:

In Basic

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

     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.

Syntax:

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

Parameter:

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.

Beispiel:

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

In Basic

      ui.Resize(, ,500, 500)
   
In Python

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

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, …

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.

tip

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


Syntax:

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

Parameter:

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: Geben Sie für jedes Argument, das an den Befehl übergeben werden soll, ein Paar an, das den Namen und den Wert des Arguments enthält.

Beispiel:

In Basic

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.

In Python

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

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

Syntax:

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

Parameter:

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

percentage: ein optionaler Fortschrittsgrad zwischen 0 und 100.

Beispiel:

In Basic

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

     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. Geben Sie den Titel, einen erläuternden Text und einen Prozentsatz des Fortschritts an, 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.

Syntax:

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

Parameter:

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.

Beispiel:

In Basic

      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
   
In Python

     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.

Syntax:

svc.WindowExists(windowname: str): bool

Parameter:

windowname: siehe obige Definitionen.

Beispiel:

In Basic

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

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

Bitte unterstützen Sie uns!