Kapitel 5 Arbeiten mit StarOffice-Dokumenten

Die StarOffice API ist so aufgebaut, dass möglichst viele ihrer Teile universell für verschiedene Aufgaben einsetzbar sind. Hierzu zählen beispielsweise die Schnittstellen und Dienste zum Erstellen, Öffnen, Speichern, Konvertieren und Drucken von Dokumenten und für die Vorlagenverwaltung. Da diese Funktionsbereiche in allen Dokumentarten zur Verfügung stehen, werden sie in diesem Kapitel zuerst erklärt.

Der StarDesktop

Beim Umgang mit Dokumenten werden zwei Dienste am häufigsten verwendet:

• Der Dienst com.sun.star.frame.Desktop, der als Kerndienst von StarOffice bezeichnet werden kann. Er stellt die Funktionen für das Rahmenobjekt von StarOffice zur Verfügung, unter dem alle Dokumentfenster klassifiziert sind. Auch das Erstellen, Öffnen und Importieren von Dokumenten erfolgt mit diesem Dienst.

• Die Basisfunktionalität für die einzelnen Dokumentobjekte wird von dem Dienst com.sun.star.document.OfficeDocument bereitgestellt. Er stellt die Methoden zum Speichern, Exportieren und Drucken von Dokumenten zur Verfügung.

Der Dienst com.sun.star.frame.Desktop wird mit dem Start von StarOffice automatisch geöffnet. Hierzu erstellt StarOffice ein Objekt, auf das über den globalen Namen StarDesktop zugegriffen werden kann.

Die wichtigste Schnittstelle des StarDesktop ist com.sun.star.frame.XComponentLoader. Diese erfasst im Wesentlichen die Methode loadComponentFromURL, die für das Erstellen, Importieren und Öffnen von Dokumenten zuständig ist.

Der Name des Objekts StarDesktop geht auf StarOffice 5 zurück, bei dem alle Dokumentfenster in eine gemeinsame Anwendung eingebettet waren, die StarDesktop hieß. In der aktuellen Version von StarOffice gibt es keinen sichtbaren StarDesktop mehr. Der Name StarDesktop wurde jedoch für das Rahmenobjekt von StarOffice beibehalten, da er deutlich anzeigt, dass es sich um ein Basisobjekt der gesamten Anwendung handelt.

Das Objekt StarDesktop tritt die Nachfolge des Application-Objekts aus StarOffice 5 an, das bisher als Stammobjekt verwendet wurde. Im Gegensatz zu dem alten Application-Objekt ist dieses jedoch primär für das Öffnen neuer Dokumente verantwortlich. Die im alten Application-Objekt angesiedelten Funktionen zur Steuerung der Bildschirmdarstellung von StarOffice (z. B. FullScreen, FunctionBarVisible, Height, Width, Top, Visible) werden nicht mehr verwendet.

---

Hinweis –

Während der Zugriff auf das aktive Dokument in Word über Application.ActiveDocument und in Excel über Application.ActiveWorkbook erfolgt, ist in StarOffice der StarDesktop für diese Aufgabe verantwortlich. Der Zugriff auf das aktive Dokumentobjekt erfolgt in StarOffice 7 über die Eigenschaft StarDesktop.CurrentComponent.

---

Grundlegendes zu Dokumenten in StarOffice

Bei der Arbeit mit StarOffice-Dokumenten ist es hilfreich, sich mit einigen grundlegenden Dingen der Dokumentenverwaltung in StarOffice zu beschäftigen. Hierzu zählen auch die Art und Weise, wie Dateinamen für StarOffice-Dokumente aufgebaut sind sowie das Format, in dem die Dateien gespeichert werden.

Dateinamen in URL-Notation

Da StarOffice als plattformunabhängige Anwendung konzipiert wurde, verwendet es für Dateinamen die betriebssystemunabhängige URL-Notation gemäß dem Internet-Standard RFC 1738. Standarddateinamen beginnen gemäß diesem System mit dem Präfix

file:///

gefolgt von dem lokalen Pfad. Enthält der Dateiname Unterverzeichnisse, werden diese mit Schrägstrichen getrennt, nicht mit dem unter Windows üblichen umgekehrten Schrägstrich. Der folgende Pfad verweist auf die Datei test.sxw im Verzeichnis "doc" auf Laufwerk "C:".

file:///C:/doc/test.sxw

Zur Umwandlung von lokalen Dateinamen in einen URL bietet StarOffice die Funktion ConvertToUrl. Zur Umwandlung eines URLs in einen lokalen Dateinamen bietet StarOffice die Funktion ConvertFromUrl.

MsgBox ConvertToUrl("C:\doc\test.sxw")
      ' Liefert file:///C:/doc/test.sxw 
MsgBox ConvertFromUrl("file:///C:/doc/test.sxw")
      ' liefert (unter Windows) c:\doc\test.sxw

Das Beispiel konvertiert einen lokalen Dateinamen in einen URL und zeigt diesen in einem Meldungsfenster an. Danach konvertiert es einen URL in einen lokalen Dateinamen und zeigt diesen ebenfalls an.

Der zugrunde liegende Internet-Standard RFC 1738 gestattet die Verwendung der Zeichen 0-9, a-z und A-Z. Alle anderen Zeichen werden in einer Escape-Kodierung in die URLs eingefügt. Dazu werden sie in ihren Hexadezimalwert im Zeichensatz ISO 8859-1 (ISO-Latin) umgewandelt und erhalten ein Prozentzeichen vorangestellt. Aus einem Leerzeichen in einem lokalen Dateinamen wird so beispielsweise ein %20 in einem URL.

XML-Dateiformat

Seit Version 6.0 kommt in StarOffice ein XML-basiertes Dateiformat zum Einsatz. Durch den Einsatz von XML hat der Anwender die Möglichkeit, die Dateien auch mit anderen Programmen zu öffnen und zu bearbeiten.

Komprimierung von Dateien

Da XML auf Standardtextdateien basiert, sind die sich ergebenden Dateien normalerweise sehr groß. StarOffice komprimiert die Dateien daher und speichert sie als ZIP-Datei ab. Mit Hilfe einer Option der storeAsURL-Methode kann der Anwender die XML-Dateien direkt im Originalformat speichern. Siehe hierzu Die Optionen der Methode storeAsURL.

Erstellen, Öffnen und Importieren von Dokumenten

Das Öffnen, Importieren und Erstellen von Dokumenten erfolgt über die Methode

StarDesktop.loadComponentFromURL(URL, Frame, _
            SearchFlags, FileProperties)

Der erste Parameter von loadComponentFromURL gibt den URL der verknüpften Datei an.

Als zweiten Parameter erwartet loadComponentFromURL einen Namen für das Rahmenobjekt des Fensters, das StarOffice intern zu dessen Verwaltung erzeugt. Normalerweise wird hier der vordefinierte Name _blank angegeben, der dafür sorgt, dass StarOffice ein neues Fenster erstellt. Alternativ kann auch _hidden angegeben werden, wodurch sichergestellt wird, dass das entsprechende Dokument zwar geladen wird, aber unsichtbar bleibt.

Mit diesen Parametern ist es bereits möglich, ein StarOffice-Dokument zu öffnen, da den beiden letzten Parametern Platzhalter (Dummy-Werte) zugewiesen werden können:

Dim Doc As Object 
Dim Url As String 
Dim Dummy()

Url = "file:///C:/test.sxw"

Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())

Der genannte Aufruf öffnet die Datei text.sxw und zeigt diese in einem neuen Fenster an.

Auf diese Art lassen sich beliebig viele Dokumente in StarOffice Basic öffnen und anschließend über die jeweils zurückgegebenen Dokumentobjekte bearbeiten.

---

Hinweis –

StarDesktop.loadComponentFromURL löst die Methoden Documents.Add und Documents.Open der alten StarOffice API ab.

---

Ersetzen des Inhalts des Dokumentenfensters

Die benannten Werte _blank und _hidden für den Parameter Frame stellen sicher, dass StarOffice für jeden Aufruf von loadComponentFromURL ein neues Fenster erstellt. In einigen Situationen ist es jedoch sinnvoll, den Inhalt eines vorhandenen Fensters zu ersetzen. In diesem Fall sollte das Rahmenobjekt des Fensters einen expliziten Namen haben. Beachten Sie dabei, dass dieser Name nicht mit einem Unterstrich beginnen darf. Des Weiteren muss der Parameter SearchFlags so gesetzt sein, dass der betreffende Rahmen erzeugt wird, wenn er noch nicht vorhanden ist. Die entsprechende Konstante für SearchFlags lautet:

SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
         com.sun.star.frame.FrameSearchFlag.ALL

Das folgende Beispiel zeigt, wie sich mit Hilfe des Frame-Parameters und SearchFlags der Inhalt eines geöffneten Fensters ersetzen lässt:

Dim Doc As Object 
Dim Dummy() 
Dim Url As String 
Dim SearchFlags As Long

SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
         com.sun.star.frame.FrameSearchFlag.ALL

Url = "file:///C:/test.sxw"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)

MsgBox "Klicken Sie auf OK, um das zweite Dokument anzuzeigen."

Url = "file:///C:/test2.sxw"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)

Das Beispiel öffnet zuerst die Datei test.sxw in einem neuen Fenster mit dem Rahmennamen MyFrame. Nach dem Bestätigen des Meldungsfensters ersetzt es den Inhalt des Fensters durch die Datei test2.sxw.

Die Optionen der Methode loadComponentFromURL

Der vierte Parameter der loadComponentFromURL-Funktion ist ein PropertyValue-Datenfeld, das StarOffice verschiedene Optionen zum Öffnen und Erstellen von Dokumenten zur Verfügung stellt. Für jede Option muss das Datenfeld eine PropertyValue-Struktur bereitstellen, in der der Name der Option als Zeichenfolge mit dem zugehörigen Wert gespeichert wird.

loadComponentFromURL unterstützt folgende Optionen:

• AsTemplate (Boolean): wenn Wahr, wird ein neues Dokument ohne Titel aus dem angegebenen URL geladen. Wenn Falsch, werden Vorlagendateien zur Bearbeitung geladen.

• CharacterSet (String): definiert, auf welchem Zeichensatz ein Dokument basiert.

• FilterName (String): gibt einen speziellen Filter für die loadComponentFromURL-Funktion an. Die verfügbaren Filternamen sind in der Datei \share\config\registry\instance\org\openoffice\office\TypeDetection.xml definiert.

• FilterOptions (String): definiert zusätzliche Optionen für Filter.

• JumpMark (String): springt nach dem Öffnen eines Dokuments an die in JumpMark definierte Position.

• Password (String): übergibt ein Passwort für eine geschützte Datei.

• ReadOnly (Boolean): lädt ein schreibgeschütztes Dokument.

Das folgende Beispiel zeigt, wie sich eine kommagetrennte Textdatei in StarOffice Calc unter Verwendung der Option FilterName öffnen lässt.

Dim Doc As Object 
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue 
Dim Url As String

Url = "file:///C:/csv.doc"

FileProperties(0).Name = "FilterName"
FileProperties(0).Value ="scalc: Text - txt - csv (StarOffice Calc)"

Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, FileProperties())

Das Datenfeld FileProperties umfasst genau einen Wert, da es eine Option aufnimmt. Die Eigenschaft Filtername definiert hierbei, ob StarOffice einen StarOffice Calc-Textfilter zum Öffnen von Dateien verwendet.

Erstellen neuer Dokumente

StarOffice erstellt automatisch ein neues Dokument, wenn es sich bei dem im URL angegebenen Dokument um eine Vorlage handelt.

Wird lediglich ein leeres Dokument ohne jegliche Anpassungen benötigt, kann alternativ ein private:factory-URL angegeben werden:

Dim Dummy()
Dim Url As String
Dim Doc As Object

Url = "private:factory/swriter" 
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())

Der Aufruf erstellt ein leeres StarOffice Writer-Dokument.

Dokumentobjekte

Die im vorangehenden Absatz eingeführte Funktion loadComponentFromURL gibt ein Dokumentobjekt zurück. Dieses unterstützt den Dienst com.sun.star.document.OfficeDocument, der wiederum zwei zentrale Schnittstellen bereitstellt:

• die Schnittstelle com.sun.star.frame.XStorable, die für das Speichern von Dokumenten zuständig ist und

• die Schnittstelle com.sun.star.view.XPrintable, die Methoden zum Ausdrucken von Dokumenten enthält.

---

Hinweis –

Bei der Umstellung auf StarOffice 8 werden Sie feststellen, dass der Funktionsumfang der Dokumentobjekte weitestgehend unverändert geblieben ist. So stellen die Dokumentobjekte beispielsweise weiterhin Methoden zum Speichern und Drucken von Dokumenten zur Verfügung. Die Namen und Parameter der Methoden haben sich jedoch geändert.

---

Speichern und Exportieren von Dokumenten

Das Speichern von StarOffice-Dokumenten erfolgt direkt über das Dokumentobjekt. Hierzu steht die Methode store der Schnittstelle com.sun.star.frame.XStorable zur Verfügung:

Doc.store()

Damit dieser Aufruf funktioniert, muss dem Dokument bereits ein Speicherplatz zugewiesen worden sein. Bei neuen Dokumenten ist dies nicht der Fall. In diesem Fall wird deshalb die Methode storeAsURL verwendet. Sie ist ebenfalls in com.sun.star.frame.XStorable definiert und mit ihr kann der Speicherort des Dokuments definiert werden:

Dim URL As String
Dim Dummy()

Url = "file:///C:/test3.sxw"

Doc.storeAsURL(URL, Dummy())

Neben den vorgenannten Methoden stellt com.sun.star.frame.XStorable auch einige Hilfsmethoden zur Verfügung, die beim Speichern von Dokumenten hilfreich sein können. Hierbei handelt es sich um:

• hasLocation(): gibt an, ob dem Dokument bereits ein URL zugewiesen wurde.

• isReadonly(): gibt an, ob ein Dokument schreibgeschützt ist.

• isModified(): gibt an, ob ein Dokument seit dem letzten Speichervorgang geändert wurde.

Mit diesen Optionen lässt sich der Code zum Speichern eines Dokuments erweitern, so dass die Speicherung nur dann erfolgt, wenn das Objekt tatsächlich geändert wurde, und der Dateiname nur dann abgefragt wird, wenn er auch wirklich benötigt wird:

If (Doc.isModified) Then
   If (Doc.hasLocation And (Not Doc.isReadOnly)) Then
      Doc.store()
   Else
      Doc.storeAsURL(URL, Dummy())
   End If
End If

Das Beispiel prüft zunächst, ob das betreffende Dokument seit dem letzten Speichervorgang geändert wurde. Nur wenn dies der Fall ist, wird mit dem Speichervorgang fortgefahren. Wurde dem Dokument bereits ein URL zugeordnet und ist es nicht schreibgeschützt, wird es unter dem vorhandenen URL gespeichert. Besitzt es keinen URL oder wurde es mit Schreibschutz geöffnet, wird es unter einem neuen URL gespeichert.

Die Optionen der Methode storeAsURL

Wie bei der Methode loadComponentFromURL lassen sich auch bei der Methode storeAsURL einige Optionen in Form eines PropertyValue-Datenfelds angeben. Diese bestimmen die Prozedur, die StarOffice zur Speicherung eines Dokuments verwendet. storeAsURL bietet folgende Optionen:

• CharacterSet (String): definiert, auf welchem Zeichensatz ein Dokument basiert.

• FilterName (String): gibt einen speziellen Filter für die loadComponentFromURL-Funktion an. Die verfügbaren Filternamen sind in der Datei \share\config\registry\instance\org\openoffice\office\TypeDetection.xml definiert.

• FilterOptions (String): definiert zusätzliche Optionen für Filter.

• Overwrite (Boolean): lässt das Überschreiben einer bereits vorhandenen Datei ohne Rückfrage zu.

• Password (String): übergibt das Passwort für eine geschützte Datei.

• Unpacked (Boolean): speichert ein Dokument (nicht komprimiert) in Unterverzeichnissen.

Das folgende Beispiel zeigt, wie die Option Overwrite zusammen mit storeAsURL verwendet werden kann:

Dim Doc As Object 
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue 
Dim Url As String

' ... Doc initialisieren

Url = "file:///c:/test3.sxw"

FileProperties(0).Name = "Overwrite"
FileProperties(0).Value = True

Doc.storeAsURL(sUrl, mFileProperties())

Das Beispiel speichert Doc auch dann unter dem angegebenen Dateinamen, wenn bereits eine Datei mit diesem Namen vorhanden ist.

Drucken von Dokumenten

Ähnlich wie das Speichern, erfolgt auch das Ausdrucken von Dokumenten direkt über das Dokumentobjekt. Zu diesem Zweck wird die Methode Print der Schnittstelle com.sun.star.view.XPrintable bereitgestellt. In seiner einfachsten Form lautet der Print-Aufruf:

Dim Dummy()

Doc.print(Dummy())

Wie bei der Methode loadComponentFromURL handelt es sich bei dem Dummy-Parameter um ein PropertyValue-Datenfeld, über das StarOffice einige Optionen zum Drucken festlegen kann.

Die Optionen der Methode "print"

Die Methode print erwartet ein PropertyValue-Datenfeld als Parameter, das die Einstellungen des Druck-Dialogs von StarOffice widerspiegelt:

• CopyCount (Integer): gibt die Anzahl der zu druckenden Kopien an.

• FileName (String): druckt das in der angegebenen Datei enthaltene Dokument.

• Collate (Boolean): weist den Drucker an, die Seiten der Kopien zusammenzutragen.

• Sort (Boolean): sortiert die Seiten beim Drucken mehrerer Kopien (CopyCount > 1).

• Pages (String): enthält die Liste der zu druckenden Seiten (Syntax wie im Druck-Dialog angegeben).

Das folgende Beispiel zeigt, wie sich über die Option Pages mehrere Seiten eines Dokuments ausdrucken lassen:

Dim Doc As Object 
Dim PrintProperties(0) As New com.sun.star.beans.PropertyValue

PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"

Doc.print(PrintProperties())

Druckerauswahl- und -einstellungen

Die Schnittstelle com.sun.star.view.XPrintable stellt die Eigenschaft Printer zur Verfügung, mit der der Drucker ausgewählt wird. Diese Eigenschaft nimmt ein PropertyValue-Datenfeld mit folgenden Einstellungen entgegen:

• Name (String): gibt den Namen des Druckers an.

• PaperOrientation (Enum): gibt die Seitenausrichtung an (Wert com.sun.star.view.PaperOrientation.PORTRAIT für Hochformat, com.sun.star.view.PaperOrientation.LANDSCAPE für Querformat).

• PaperFormat (Enum): gibt das Papierformat an (z. B. com.sun.star.view.PaperFormat.A4 für DIN A4 oder com.sun.star.view.PaperFormat.Letter für US-Letter).

• PaperSize (Size): Papierformat in 100stel Millimeter.

Das folgende Beispiel zeigt, wie mit Hilfe der Printer-Eigenschaft der Drucker gewechselt und das Papierformat eingestellt werden können.

Dim Doc As Object 
Dim PrinterProperties(1) As New com.sun.star.beans.PropertyValue 
Dim PaperSize As New com.sun.star.awt.Size

PaperSize.Width = 20000      ' Entspricht 20 cm
PaperSize.Height = 20000     ' Entspricht 20 cm

PrinterProperties (0).Name="Name"
PrinterProperties (0).Value="My HP Laserjet"

PrinterProperties (1).Name="PaperSize"
PrinterProperties (1).Value=PaperSize

Doc.Printer = PrinterProperties()

Das Beispiel definiert ein Objekt namens PaperSize vom Typ com.sun.star.awt.Size. Dieses wird zur Angabe des Papierformats benötigt. Des Weiteren erstellt es ein Datenfeld für zwei PropertyValue-Einträge namens PrinterProperties. Dieses Datenfeld wird dann mit den Werten für die Eigenschaft Printer initialisiert. Im Rahmen von UNO ist der Drucker keine echte Eigenschaft, sondern eine nachgebildete.

Vorlagen

Vorlagen sind benannte Listen mit Formatierungsattributen. Sie finden sie in allen Anwendungen von StarOffice, wo sie zu einer deutlichen Vereinfachung des Formatierungsvorgangs beitragen. Ändert der Anwender eins der Attribute einer Vorlage, so passt StarOffice automatisch alle von diesem Attribut abhängigen Dokumentabschnitte an. Dadurch ist es beispielsweise möglich, die Schriftart sämtlicher Überschriften der Ebene eins durch eine zentrale Änderung im Dokument anzupassen. In Abhängigkeit von den jeweiligen Dokumenttypen erkennt StarOffice eine ganze Reihe verschiedener Vorlagenarten.

StarOffice Writer unterstützt

• Zeichenvorlagen,

• Absatzvorlagen,

• Rahmenvorlagen,

• Seitenvorlagen

• Nummerierungsvorlagen

StarOffice Calc unterstützt

• Zellvorlagen

• Seitenvorlagen

StarOffice Impress unterstützt

• Zeichenelement-Vorlagen

• Präsentationsvorlagen

Die verschiedenen Vorlagenarten werden in der StarOffice-Terminologie gemäß dem zugrunde liegenden Dienst com.sun.star.style.StyleFamily auch als StyleFamilies bezeichnet. Der Zugriff auf die StyleFamilies erfolgt über das Dokumentobjekt:

Dim Doc As Object 
Dim Sheet As Object 
Dim StyleFamilies As Object 
Dim CellStyles As Object

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies 
CellStyles = StyleFamilies.getByName("CellStyles")

Das Beispiel ermittelt über die Eigenschaft StyleFamilies eines Tabellendokuments eine Liste mit sämtlichen verfügbaren Zellvorlagen.

Der Zugriff auf die einzelnen Vorlagen ist direkt über einen Index möglich:

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object
Dim CellStyles As Object
Dim CellStyle As Object 
Dim I As Integer

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
CellStyles = StyleFamilies.getByName("CellStyles")

For I = 0 To CellStyles.Count - 1 
   CellStyle = CellStyles(I) 
   MsgBox CellStyle.Name 
Next I

Die gegenüber dem vorigen Beispiel hinzugefügte Schleife zeigt die Namen aller Zellvorlagen nacheinander in einem Meldungsfenster an.

Details zu den verschiedenen Formatierungsmöglichkeiten

Jede Vorlagenart stellt eine ganze Reihe individueller Formatierungseigenschaften zur Verfügung. Hier nun ein Überblick zu den wichtigsten Formatierungseigenschaften und den Stellen, an denen diese erklärt werden:

• Zeicheneigenschaften, Kapitel 6, Textdokumente, Dienst com.sun.star.style.CharacterProperties

• Absatzeigenschaften, Kapitel 6, Textdokumente, Dienst com.sun.star.text.Paragraph

• Zelleigenschaften, Kapitel 7, Tabellendokumente, Dienst com.sun.star.table.CellProperties

• Seiteneigenschaften, Kapitel 7, Tabellendokumente, Dienst com.sun.star.style.PageStyle

• Zeichenelement-Eigenschaften, Kapitel 7, Tabellendokumente, verschiedene Dienste

Die Formateigenschaften sind normalerweise keineswegs auf die Anwendungen beschränkt, in denen sie erklärt werden, sondern können vielmehr universell eingesetzt werden. So lassen sich die meisten der in Kapitel 7, Tabellendokumente, beschriebenen Seiteneigenschaften beispielsweise nicht nur in StarOffice Calc einsetzen, sondern auch in StarOffice Writer.

Weitere Informationen zum Arbeiten mit Vorlagen finden Sie im Abschnitt Standardwerte für Zeichen- und Absatzeigenschaften, in Kapitel 6, Textdokumente.