Kapitel 4 Einführung in die StarOffice API

Die StarOffice API ist eine universelle Programmierschnittstelle für den Zugriff auf StarOffice. Mit der StarOffice API können Sie StarOffice-Dokumente erstellen, öffnen, bearbeiten und ausdrucken. Sie bietet die Möglichkeit, den Funktionsumfang von StarOffice durch eigene Makros zu erweitern, und gestattet die Erstellung eigener Dialogfelder.

Die StarOffice API kann nicht nur mit StarOffice verwendet werden, sondern auch mit anderen Programmiersprachen wie Java und C++. Möglich macht das eine Technik namens Universal Network Objects (UNO), die eine Schnittstelle zu verschiedenen Programmiersprachen bereitstellt.

In diesem Kapitel wird beschrieben, wie sich StarOffice mit Hilfe von UNO in StarOffice nutzen lässt. Behandelt werden die prinzipiellen Konzepte von UNO aus der Sicht eines StarOffice Basic-Programmierers. Details zum Umgang mit den verschiedenen Teilbereichen der StarOffice API finden Sie in den folgenden Kapiteln.

Universal Network Objects (UNO)

StarOffice stellt eine Programmierschnittstelle in Form von Universal Network Objects (UNO) zur Verfügung. Es handelt sich dabei um eine objektorientierte Programmierschnittstelle, die StarOffice in verschiedene Objekte unterteilt, die ihrerseits programmgesteuerten Zugriff auf die Office Suite gewähren.

Da StarOffice Basic an sich eine prozedurale Programmiersprache ist, mussten einige Sprachkonstrukte hinzugefügt werden, um die Nutzung von UNO zu ermöglichen.

Um ein Universal Network Object in StarOffice Basic zu verwenden, bedarf es einer Variablendeklaration für das verknüpfte Objekt. Die Deklaration erfolgt über die Dim-Anweisung (siehe Kapitel 2, Die Sprache StarOffice Basic). Für die Deklaration einer Objektvariable ist die Typbezeichnung Object zu verwenden:

Dim Obj As Object

Der Aufruf deklariert eine Objektvariable namens Obj.

Die erzeugte Objektvariable muss anschließend initialisiert werden, damit sie genutzt werden kann. Dies ist beispielsweise über die Funktion createUnoService möglich:

Obj = createUnoService("com.sun.star.frame.Desktop")

Dieser Aufruf ordnet der Variable Obj einen Verweis auf das neu erzeugte Objekt zu. com.sun.star.frame.Desktop ist einem Objekttyp ähnlich; in UNO-Terminologie handelt es sich eher um einen Dienst (Service) als um einen Typ. Gemäß der UNO-Philosophie bezeichnet man ein Obj als einen Verweis auf ein Objekt, das den Dienst com.sun.star.frame.Desktop unterstützt. Der in StarOffice Basic verwendete Begriff Dienst (Service) entspricht somit den in anderen Programmiersprachen verwendeten Begriffen Typ und Klasse.

Es existiert allerdings ein wesentlicher Unterschied: Ein Universal Network Object kann mehrere Dienste gleichzeitig unterstützen. Einige UNO-Dienste unterstützen wiederum andere Dienste, so dass Ihnen mit einem Objekt automatisch eine ganze Reihe von Diensten zur Verfügung stehen. So kann das vorgenannte Objekt, das auf dem Dienst com.sun.star.frame.Desktop basiert, beispielsweise weitere Dienste zum Laden von Dokumenten sowie zum Beenden des Programms enthalten.

---

Hinweis –

Während der Aufbau eines Objekts in VBA über die Klasse festgelegt wird, der es angehört, wird der Aufbau in StarOffice Basic über die Dienste definiert, die es unterstützt. Ein VBA-Objekt ist immer genau einer einzigen Klasse zugeordnet. Ein StarOffice Basic-Objekt kann hingegen mehrere Dienste unterstützen.

---

Eigenschaften und Methoden

Ein Objekt stellt in StarOffice Basic eine Reihe von Eigenschaften und Methoden zur Verfügung, die über das Objekt aufgerufen werden können.

Eigenschaften

Eigenschaften (Properties) sind wie die Eigenschaften eines Objekts, z. B. Filename und Title für ein Document- Objekt.

Das Setzen von Eigenschaften erfolgt über eine einfache Zuweisung:

Document.Title = "StarOffice 8 Basic Programmer's Guide"
Document.Filename = "progman.sxv"

Eine Eigenschaft besitzt wie eine gewöhnliche Variable einen Typ der festlegt, welche Werte sie aufnehmen kann. Die vorgenannten Eigenschaft Filename und Title sind vom Typ String.

Echte Eigenschaften und nachgebildete Eigenschaften

Die meisten Eigenschaften eines Objekts in StarOffice Basic sind als solche in der UNO-Beschreibung des Dienstes definiert. Neben diesen "echten" Eigenschaften gibt es in StarOffice Basic auch Eigenschaften, die auf UNO-Ebene aus zwei Methoden bestehen. Die eine davon dient dazu, den Wert der Eigenschaft abzufragen, die andere, ihn zu setzen (Methoden get- und set). Die Eigenschaft wurde gewissermaßen aus zwei Methoden nachgebildet. So stellen Zeichenobjekte in UNO beispielsweise die Methoden getPosition und setPosition zur Verfügung, über die der verknüpfte Eckpunkt ausgelesen und geändert werden kann. Der StarOffice Basic-Programmierer kann auf die Werte über die Eigenschaft Position zugreifen. Unabhängig davon stehen zusätzlich die Original-Methoden zur Verfügung (im Beispiel getPosition und setPosition).

Methoden

Methoden können als Funktionen aufgefasst werden, die sich direkt auf ein Objekt beziehen, das über diese aufgerufen wird. Das vorstehende Objekt Document könnte beispielsweise eine Methode Save anbieten, die wie folgt aufgerufen werden kann:

Document.Save()

Methoden können analog zu Funktionen Parameter und Rückgabewerte enthalten. Die Syntax derartiger Methodenaufrufe orientiert sich an der klassischer Funktionen. Der Aufruf

Ok = Document.Save(True)

gibt für das Dokumentobjekt beim Aufruf der Methode Save auch den Parameter True an. Nach Abschluss der Methode speichert Save einen Rückgabewert in der Variable Ok.

Module, Dienste und Schnittstellen

StarOffice stellt hunderte von Diensten zur Verfügung. Um einen Überblick dieser Dienste zu bieten, wurden sie in Modulen zusammengefasst. Eine weitere funktionale Bedeutung haben die Module für den StarOffice Basic-Programmierer nicht. Lediglich bei der Angabe eines Dienstnamens ist der Modulname von Bedeutung, da er im Namen mit aufgeführt werden muss. Der vollständige Name eines Dienstes besteht aus dem Ausdruck com.sun.star, der angibt, dass es sich um einen StarOffice-Dienst handelt, gefolgt von dem Modulnamen, beispielsweise frame und schließlich dem eigentlichen Dienstnamen, etwa Desktop. Der vollständige Name würde in dem genannten Beispiel lauten:

com.sun.star.frame.Desktop

Neben den Begriffen Modul und Dienst (Service) führt UNO den Begriff der Schnittstelle (Interface) ein. Während dieser Begriff Java-Programmierern vertraut sein dürfte, wird er in Basic nicht verwendet.

Eine Schnittstelle fasst mehrere Methoden zusammen. Streng genommen unterstützt ein Dienst in UNO keine Methoden, sondern Schnittstellen, die wiederum verschiedene Methoden bereitstellen. Die Methoden werden also mit anderen Worten dem Dienst in Schnittstellen zusammengefasst zugeordnet. Diese Feinheit mag insbesondere den Java- oder C++-Programmierer interessieren, da die Schnittstelle in diesen Sprachen benötigt wird, um eine Methode anzufordern. In StarOffice Basic ist dies irrelevant. Hier werden die Methoden direkt über das jeweils relevante Objekt aufgerufen.

Für das Verständnis der API ist es dennoch hilfreich, sich die Zuordnung von Methoden zu verschiedenen Schnittstellen zu vergegenwärtigen, da viele Schnittstellen in den verschiedenen Diensten benutzt werden. Ist man mit einer Schnittstelle vertraut, so kann man sein Wissen von einem Dienst auf einen anderen übertragen.

Einige zentrale Schnittstellen werden so häufig verwendet, dass sie am Ende dieses Kapitels noch einmal mit den Diensten, von denen Sie ausgelöst werden, aufgeführt werden.

Hilfsmittel für den Umgang mit UNO

Bleibt die Frage, welche Objekte – oder Dienste, um bei der UNO-Terminologie zu bleiben – welche Eigenschaften, Methoden und Schnittstellen unterstützen und wie sich diese ermitteln lassen. Zusätzlich zu diesem Handbuch finden Sie weitere Informationen über Objekte in den folgenden Quellen: in der Methode supportsService, in den Debug-Methoden sowie im Developer's Guide und der API-Referenz.

Die Methode "supportsService"

Eine Reihe von UNO-Objekten unterstützt die Methode supportsService, mit der sich ermitteln lässt, ob ein Objekt einen bestimmten Dienst unterstützt. Der Aufruf

Ok = TextElement.supportsService("com.sun.star.text.Paragraph")

bestimmt beispielsweise, ob das Objekt TextElement den Dienst com.sun.star.text.Paragraph unterstützt.

Debug-Eigenschaften

Jedes UNO-Objekt in StarOffice Basic weiß, welche Eigenschaften, Methoden und Schnittstellen es bereits enthält. Es stellt Eigenschaften bereit, die diese in Form einer Liste zurückliefern. Die entsprechenden Eigenschaften lauten:

DBG_properties: gibt eine Zeichenfolge (String) mit allen Eigenschaften eines Objekts zurück.

DBG_methods: gibt eine Zeichenfolge (String) mit allen Methoden eines Objekts zurück.

DBG_supportetInterfaces: gibt eine Zeichenfolge (String) mit allen Schnittstellen zurück, die ein Objekt unterstützt.

Der folgende Programmcode zeigt, wie sich DBG_properties und DBG_methods in praktischen Anwendungen verwenden lassen. Er erzeugt zunächst den Dienst com.sun.star.frame.Desktop und gibt dann die unterstützten Eigenschaften und Methoden in Meldungsfenstern aus.

Dim Obj As Object 
Obj = createUnoService("com.sun.star.frame.Desktop")

MsgBox Obj.DBG_Propierties 
MsgBox Obj.DBG_methods

Bei der Verwendung von DBG_properties ist zu beachten, dass die Funktion alle Eigenschaften zurückgibt, die ein bestimmter Dienst theoretisch unterstützen kann. Es ist jedoch nicht sichergestellt, dass diese von dem betreffenden Objekt auch verwendet werden können. Vor dem Auslesen einer Eigenschaften muss daher mit der Funktion IsEmpty geprüft werden, ob diese tatsächlich verfügbar ist.

API-Referenz

Weitere Informationen über die verfügbaren Dienste mit ihren Schnittstellen, Methoden und Eigenschaften finden Sie in der API-Referenz für die StarOffice API. Diese steht unter www.openoffice.org zur Verfügung:

http://api.openoffice.org/docs/common/ref/com/sun/star/module-ix.html

Einige zentrale Schnittstellen im Überblick

Einige Schnittstellen von StarOffice finden sich in vielen Bereichen der StarOffice API. Sie definieren Sätze von Methoden für abstrakte Aufgaben, die sich auf verschiedene Probleme anwenden lassen. Hier finden Sie einen Überblick der gängigsten dieser Schnittstellen.

Der Ursprung der Objekte wird erst später in diesem Handbuch erklärt. An dieser Stelle werden nur einige abstrakte Aspekte der Objekte, für die die StarOffice API einige zentrale Schnittstellen zur Verfügung stellt, diskutiert.

Erzeugen kontextabhängiger Objekte

Die StarOffice API bietet zwei Möglichkeiten zum Erzeugen von Objekten. Die eine besteht in der Verwendung der bereits zu Beginn dieses Kapitels genannten Funktion createUnoService. createUnoService erzeugt ein Objekt, das universell einsetzbar ist. Solche Objekte und Dienste werden auch als kontextunabhängige Dienste bezeichnet.

Neben den kontextunabhängigen Diensten gibt es auch kontextabhängige Dienste, deren Objekte nur im Zusammenhang mit einem anderen Objekt sinnvoll eingesetzt werden können. So kann ein Zeichnungsobjekt für ein Tabellendokument beispielsweise nur im Zusammenhang mit eben diesem Dokument existieren.

Schnittstelle com.sun.star.lang.XMultiServiceFactory

Die Erzeugung kontextabhängiger Objekte erfolgt in der Regel über eine Methode des Objekts, von der dieses abhängig ist. Dabei kommt insbesondere die Methode createInstance in den Dokumentobjekten zum Einsatz, die in der Schnittstelle XMultiServiceFactory definiert ist.

Besagtes Zeichnungsobjekt lässt sich beispielsweise wie folgt über ein Tabellendokument-Objekt erzeugen:

Dim RectangleShape As Object

RectangleShape = _ 
   Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")

Analog erfolgt die Erzeugung einer Absatzvorlage in einem Textdokument:

Dim Style as Object 
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")

Benannter Zugriff auf untergeordnete Objekte

Die Schnittstellen XNameAccess und XNameContainer werden in Objekten verwendet, die untergeordnete Objekte enthalten, die über einen Klartextnamen angesprochen werden können.

Während XNamedAccess den Zugriff auf die einzelnen Objekte gestattet, übernimmt XNameContainer das Einfügen, Ändern und Löschen von Elementen.

Schnittstelle com.sun.star.container.XNameAccess

Ein Beispiel für den Einsatz von XNameAccess bietet das Sheet-Objekt eines Tabellendokuments. Es fasst sämtliche Seiten innerhalb des Tabellendokuments zusammen. Der Zugriff auf einzelne Seiten erfolgt über die Methode getByName der Schnittstelle XNameAccess:

Dim Sheets As Object 
Dim Sheet As Object

Sheets = Spreadsheet.Sheets 
Sheet = Sheets.getByName("Sheet1")

Einen Überblick der Namen sämtlicher Elemente bietet die Methode getElementNames. Als Ergebnis gibt sie ein Datenfeld mit den Namen zurück. Das folgende Beispiel zeigt, wie sich damit alle Elementnamen eines Tabellendokuments ermitteln und in einer Schleife anzeigen lassen:

Dim Sheets As Object
Dim SheetNames
Dim I As Integer

Sheets = Spreadsheet.Sheets
SheetNames = Sheets.getElementNames

For I=LBound(SheetNames) To UBound(SheetNames)
   MsgBox SheetNames(I)
Next I

Die Methode hasByName der Schnittstelle XNameAccess zeigt an, ob innerhalb des Basisobjekts ein untergeordnetes Objekt mit einem bestimmten Namen vorhanden ist. Deshalb gibt das folgende Beispiel eine Meldung aus, ob das Objekt Spreadsheet eine Seite mit dem Namen Sheet1 enthält.

Dim Sheets As Object

Sheets = Spreadsheet.Sheets 
If Sheets.HasByName("Sheet1") Then 
   MsgBox " Sheet1 verfügbar"
Else 
   MsgBox "Sheet1 nicht verfügbar"
End If

Schnittstelle com.sun.star.container.XNameContainer

Die Schnittstelle XNameContainer übernimmt das Einfügen, Löschen und Ändern von untergeordneten Elementen in einem Basisobjekt. Die hierfür zuständigen Funktionen lauten insertByName, removeByName und replaceByName.

Im Folgenden finden Sie ein praktisches Beispiel hierfür. Es ruft ein Textdokument auf, das ein Objekt StyleFamilies enthält und dieses wiederum verwendet, um die Absatzvorlagen (ParagraphStyles) des Dokuments zur Verfügung zu stellen.

Dim StyleFamilies As Objects 
Dim ParagraphStyles As Objects 
Dim NewStyle As Object

StyleFamilies = Textdoc.StyleFamilies 
ParagraphStyles = StyleFamilies.getByName("ParagraphStyles")

ParagraphStyles.insertByName("NewStyle", NewStyle)
ParagraphStyles.replaceByName("ChangingStyle", NewStyle)
ParagraphStyles.removeByName("OldStyle")           

Die Zeile insertByName fügt die Vorlage NewStyle unter dem gleichnamigen Namen in das Objekt ParagraphStyles ein. Die Zeile replaceByName ändert das hinter ChangingStyle liegende Objekt in NewStyle. Der Aufruf removeByName entfernt schließlich das hinter OldStyle stehende Objekt aus ParagraphStyles.

Indexbasierter Zugriff auf untergeordnete Objekte

Die Schnittstellen XIndexAccess und XIndexContainer werden in Objekten verwendet, die untergeordnete Objekte enthalten und die über einen Index adressiert werden können.

XIndexAccess bietet die Methoden für den Zugriff auf einzelne Objekte an. XIndexContainer stellt Methoden zum Einfügen und Entfernen von Elementen bereit.

Schnittstelle com.sun.star.container.XIndexAccess

XIndexAccess stellt die Methoden für das Auslesen der untergeordneten Objekte getByIndex und getCount bereit. getByIndex stellt ein Objekt mit einem bestimmten Index zur Verfügung. getCount gibt die Anzahl der verfügbaren Objekte zurück.

Dim Sheets As Object 
Dim Sheet As Object 
Dim I As Integer

Sheets = Spreadsheet.Sheets

For I = 0 to Sheets.getCount() - 1
   Sheet = Sheets.getByIndex(I)
   ' Sheet bearbeiten 
Next I

Das Beispiel zeigt eine Schleife, die sämtliche Tabellenelemente (Sheets) nacheinander durchläuft und in der Objektvariable Sheet jeweils einen Verweis darauf ablegt. Beim Umgang mit den Indizes ist darauf zu achten, dass getCount die Anzahl der Elemente zurückgibt. Die Elemente in getByIndex werden jedoch beginnend mit 0 nummeriert. Die Zählvariable der Schleife läuft daher von 0 bis getCount()-1.

Schnittstelle com.sun.star.container.XIndexContainer

Die Schnittstelle XIndexContainer stellt die Funktionen insertByIndex und removeByIndex zur Verfügung. Der Aufbau der Parameter erfolgt analog zu den entsprechenden Funktionen in XNameContainer.

Iterativer Zugriff auf untergeordnete Objekte

In einigen Fällen kann ein Objekt eine Liste von untergeordneten Objekten enthalten, die weder über einen Namen noch über einen Index adressiert werden können. In diesen Situationen ist die Verwendung der Schnittstellen XEnumeration sowie XEnumerationAccess angebracht. Sie stellen einen Mechanismus zur Verfügung, über den sämtliche untergeordneten Elemente eines Objekts Schritt für Schritt durchlaufen werden können, ohne dass eine direkte Adressierung erfolgen muss.

Schnittstellen com.sun.star.container.XEnumeration und XEnumerationAccess

Das Basisobjekt muss die Schnittstelle XEnumerationAccess bereitstellen, die nur eine Methode createEnumeration enthält. Diese gibt ein Hilfsobjekt zurück, das wiederum die Schnittstelle XEnumeration mit den Methoden hasMoreElements und nextElement bereitstellt. Über diese haben Sie Zugriff auf die untergeordneten Objekte.

Das folgende Beispiel geht schrittweise alle Textabsätze durch:

Dim ParagraphEnumeration As Object 
Dim Paragraph As Object

ParagraphEnumeration = Textdoc.Text.createEnumeration

While ParagraphEnumeration.hasMoreElements()
   Paragraph = ParagraphElements.nextElement()
Wend

Das Beispiel erzeugt zuerst ein Hilfsobjekt ParagraphEnumeration. Dieses gibt in einer Schleife nach und nach die einzelnen Absätze des Texts zurück. Die Schleife bricht ab, sobald die Methode hasMoreElements den Wert False zurückgibt und damit signalisiert, dass das Ende des Texts erreicht ist.