Inhalte
Index 🔎︎

# 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 und OpenDocument erzeugen 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

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

## 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 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")
         FSO = CreateScriptService("FileSystem")
         myDoc2 = ui.CreateDocument(templatefile = FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))

## GetDocument

Gibt ein 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

         myDoc = ui.GetDocument(r"C:\Documents\My file.odt")
         from scriptforge import CreateScriptService
         bridge = CreateScriptService("Basic")
         myDoc = ui.GetDocument(bridge.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. Existiert die Datei bereits, wird sie ohne Warnung überschrieben

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 vordefinierte Konstanten für das Argument macroexecution verwenden, wie in den obigen Beispielen.

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

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

Verwandte Themen

Dienst ScriptForge.Basic

Dienst SFDocuments.Calc

Dienst SFDocuments.Document