Inhalte

# 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

##### 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

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

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

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.

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

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.

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

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

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.

### 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. 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.

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

Verwandte Themen

Dienst ScriptForge.Basic

Dienst SFDocuments.Calc

Dienst SFDocuments.Document