Dienst ScriptForge.UI

Der Dienst UI (User Interface) vereinfacht die Identifizierung und Handhabung der verschiedenen Fenster, aus denen sich die gesamte LibreOffice-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

Yes

Integer

Returns the height of the active window in pixels.

Width

Yes

Integer

Returns the width of the active window in pixels.

X

Yes

Integer

Returns the X coordinate of the active window, which is the distance to the left edge of the screen in pixels.

Y

Yes

Integer

Returns the Y coordinate of the active window, which is the distance to the top edge of the screen in pixels. This value does not consider window decorations added by your operating system, so even when the window is maximized this value may not be zero.


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 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)
   
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 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)
   
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 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)
   
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 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: 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 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. 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!