Kapitel 6 Textdokumente

Neben reinen Zeichenfolgen enthalten Textdokumente ebenfalls Formatierungsinformationen. Diese können an jeder beliebigen Stelle des Texts auftreten. Weiter verkompliziert wird der Aufbau durch Tabellen. Hierzu gehören nicht nur eindimensionale Zeichenfolgen, sondern auch zweidimensionale Felder. Schließlich bieten moderne Textverarbeitungsprogramme die Möglichkeit, Zeichnungsobjekte, Textrahmen und andere Objekte in einem Text zu platzieren. Diese können außerhalb des Textflusses stehen und frei auf einer Seite positioniert werden.

Dieses Kapitel stellt die zentralen Schnittstellen und Dienste von Textdokumenten vor. Der erste Abschnitt behandelt den Aufbau von Textdokumenten und konzentriert sich darauf, wie Sie mit einem StarOffice Basic-Programm schrittweise ein StarOffice-Dokument durchgehen können. Im Mittelpunkt stehen dabei Absätze, Absatzteile und deren Formatierung.

Im zweiten Abschnitt steht die effiziente Arbeit mit Textdokumenten im Vordergrund. Hierzu bietet StarOffice über die im ersten Abschnitt genannten Objekte hinaus einige Hilfsobjekte an (etwa das TextCursor-Objekt).

Der dritte Abschnitt führt über das Arbeiten mit Texten hinaus. Er setzt den Schwerpunkt auf Tabellen, Textrahmen, Textfelder, Lesezeichen, Inhaltsverzeichnisse und einiges mehr.

Informationen zum Erstellen, Öffnen, Speichern und Drucken von Dokumenten finden Sie in Kapitel 5, Arbeiten mit StarOffice-Dokumenten, da sie nicht nur für Textdokumente, sondern auch für andere Dokumentarten herangezogen werden können.

Der Aufbau von Textdokumenten

Ein Textdokument kann im Wesentlichen vier Arten von Informationen enthalten:

• den eigentlichen Text

• Vorlagen für die Formatierung von Zeichen, Absätzen und Seiten

• nichttextuelle Elemente wie Tabellen, Grafiken und Zeichnungsobjekte

• globale Einstellungen für das Textdokument

In diesem Abschnitt geht es insbesondere um den Text und die zugehörigen Formatierungsmöglichkeiten.

---

Hinweis –

Die API von StarOffice 8 für StarOffice Writer unterscheidet sich konzeptionell von der der Vorgängerversion. In der alten API stand die Arbeit mit dem Selection-Objekt im Vordergrund, das sich stark an der Idee der Benutzeroberfläche für Endanwender orientiert hat, bei der die mausgesteuerte Arbeit mit Markierungen im Mittelpunkt stand.

Die API von StarOffice 8 hat diese Verknüpfung zwischen Benutzeroberfläche und Programmierschnittstelle aufgehoben. Der Programmierer hat somit parallelen Zugriff auf alle Teile einer Anwendung und kann mit Objekten aus verschiedenen Teilbereichen eines Dokuments gleichzeitig arbeiten. Das alte Selection-Objekt steht nicht mehr zur Verfügung.

---

Absätze und Absatzteile

Den Kern eines Textdokuments bildet eine Abfolge von Absätzen. Diese sind weder benannt noch indiziert, so dass es keine Möglichkeit zum direkten Zugriff auf einzelne Absätze gibt. Die Absätze lassen sich jedoch mit Hilfe des in Kapitel 4, Einführung in die StarOffice API, beschriebenen Enumeration-Objekts sequenziell durchlaufen. Auf diese Weise können die Absätze bearbeitet werden.

Bei der Arbeit mit dem Enumeration-Objekt ist jedoch ein Sonderfall zu beachten: Es gibt nicht nur Absätze, sondern auch Tabellen zurück (streng genommen handelt es sich in StarOffice Writer bei einer Tabelle um einen Sonderfall eines Absatzes). Daher muss vor einem Zugriff auf das zurückgegebene Objekt geprüft werden, ob das zurückgegebene Objekt den Dienst com.sun.star.text.Paragraph für Absätze oder den Dienst com.sun.star.text.TextTable für Tabellen unterstützt.

Das folgende Beispiel durchläuft den Inhalt eines Textdokuments in einer Schleife und teilt jeweils in einer Meldung mit, ob es sich bei dem fraglichen Objekt um einen Absatz oder eine Tabelle handelt.

Dim Doc As Object
Dim Enum As Object
Dim TextElement As Object

' Dokumentobjekt erstellen
Doc = StarDesktop.CurrentComponent

' Enumeration-Objekt erstellen
Enum = Doc.Text.createEnumeration

' Schleife über alle Textelemente
While Enum.hasMoreElements 
   TextElement = Enum.nextElement

   If TextElement.supportsService("com.sun.star.text.TextTable") Then
      MsgBox "Der aktuelle Block enthält eine Tabelle."
   End If

   If TextElement.supportsService("com.sun.star.text.Paragraph") Then
      MsgBox "Der aktuelle Block enthält einen Absatz."
   End If
Wend

Das Beispiel erstellt ein Dokumentobjekt Doc, das auf das aktuelle StarOffice-Dokument verweist. Mit Hilfe von Doc erstellt das Beispiel dann ein Enumeration-Objekt, das nacheinander die einzelnen Textteile (Absätze und Tabellen) durchläuft und das jeweils aktuelle Element dem Objekt TextElement zuweist. Über die Methode supportsService prüft das Beispiel, ob es sich bei TextElement um einen Absatz oder eine Tabelle handelt.

Absätze

Der Dienst com.sun.star.text.Paragraph gestattet Zugriff auf den Inhalt eines Absatzes. Der innerhalb des Absatzes vorhandene Text kann über die Strings-Eigenschaft abgerufen und geändert werden:

Dim Doc As Object
Dim Enum As Object
Dim TextElement As Object

Doc = StarDesktop.CurrentComponent
Enum = Doc.Text.createEnumeration

While Enum.hasMoreElements
   TextElement = Enum.nextElement

   If TextElement.supportsService("com.sun.star.text.Paragraph") Then
      TextElement.String = Replace(TextElement.String, "you", "U") 
      TextElement.String = Replace(TextElement.String, "too", "2")
      TextElement.String = Replace(TextElement.String, "for", "4") 
   End If
Wend

Das Beispiel öffnet das aktuelle Textdokument und durchläuft dieses unter Zuhilfenahme des Enumeration-Objekts. In allen Absätzen greift es über die Eigenschaft TextElement.String auf die jeweiligen Absätze zu und ersetzt die Zeichenfolgen you, too und for durch die Zeichen U, 2 und 4. Die für das Ersetzen verwendete Funktion Replace gehört nicht zum Standardsprachumfang von StarOffice Basic. Es handelt sich hierbei um einen Fall der in Kapitel 3, Die Laufzeitbibliothek von StarOffice Basic, im Abschnitt Suchen und Ersetzen beschriebenen Beispielfunktion.

---

Hinweis –

Das hier beschriebene Verfahren für den Zugriff auf die Absätze eines Texts ist inhaltlich vergleichbar mit der in VBA verwendeten Paragraphs-Auflistung, die in den dort bereitgestellten Objekten Range und Document verfügbar ist. Während in VBA der Zugriff auf die Absätze über ihre Nummer erfolgt (z. B. über den Aufruf Paragraph(1)), ist in StarOffice Basic das oben beschriebene Enumeration-Objekt zu verwenden.

Für die in VBA vorhandenen Auflistungen Characters, Sentences und Words ist in StarOffice Basic kein direktes Gegenstück vorhanden. Es besteht jedoch die Möglichkeit, zu einem TextCursor zu wechseln, der eine Navigation auf der Ebene von Zeichen, Sätzen und Wörtern gestattet (siehe Abschnitt Der TextCursor).

---

Absatzteile

Das oben stehende Beispiel ist zwar in der Lage, den Text wie gewünscht zu ändern, kann dabei jedoch teilweise die Formatierung zerstören.

Dies liegt daran, dass sich ein Absatz wiederum aus einzelnen Unterobjekten zusammensetzt. Jedes dieser Unterobjekte enthält seine eigenen Formatierungsinformationen. Enthält ein Absatz beispielsweise in der Mitte ein fett gedrucktes Wort, so wird er in StarOffice durch drei Absatzteile dargestellt: den Teil vor dem Fettdruck, dann das fettgedruckte Wort und schließlich den Teil nach dem Fettdruck, der wieder normal dargestellt wird.

Wird der Text des Absatzes nun über die String-Eigenschaft des Absatzes geändert, so löscht StarOffice zunächst die alten Absatzteile und fügt dann einen neuen Absatzteil ein. Dabei gehen die Formatierungen der vorherigen Teile zwangsläufig verloren.

Um diesen Effekt zu vermeiden, ist es möglich, statt auf den gesamten Absatz nur auf die zugehörigen Absatzteile zuzugreifen. Dazu bieten Absätze ein eigenes Enumeration-Objekt. Das folgende Beispiel zeigt eine doppelte Schleife, die sämtliche Absätze und die darin enthaltenen Absatzteile eines Textdokuments durchläuft und die Ersetzungsvorgänge aus dem vorstehenden Beispiel anwendet:

Dim Doc As Object
Dim Enum1 As Object
Dim Enum2 As Object
Dim TextElement As Object
Dim TextPortion As Object

Doc = StarDesktop.CurrentComponent
Enum1 = Doc.Text.createEnumeration

' Schleife über alle Absätze 
While Enum1.hasMoreElements
   TextElement = Enum1.nextElement
   If TextElement.supportsService("com.sun.star.text.Paragraph") Then
      Enum2 = TextElement.createEnumeration

      ' Schleife über alle Teilabsätze 
      While Enum2.hasMoreElements
         TextPortion = Enum2.nextElement
         MsgBox "'" & TextPortion.String & "'"
         TextPortion.String = Replace(TextPortion.String, "you", "U") 
         TextPortion.String = Replace(TextPortion.String, "too", "2")
         TextPortion.String = Replace(TextPortion.String, "for", "4") 

      Wend

   End If

Wend

Das Beispiel durchläuft ein Textdokument in einer doppelten Schleife. Die äußere Schleife bezieht sich auf die Absätze des Texts. Die innere Schleife bearbeitet die darin enthaltenen Absatzteile. In jedem dieser Absatzteile ändert der Beispielcode den Inhalt über die String-Eigenschaft der Zeichenfolge analog zu dem vorstehenden Beispiel für Absätze. Da jedoch die Absatzteile direkt bearbeitet werden, bleiben ihre Formatierungsinformationen beim Ersetzen der Zeichenfolge erhalten.

Formatieren

Es gibt verschiedene Methoden, um einen Text zu formatieren. Der einfachste Weg besteht darin, der betreffenden Textsequenz die gewünschten Formateigenschaften direkt zuzuweisen. Diese Vorgehensweise wird als direkte Formatierung bezeichnet. Direkte Formatierung wird insbesondere bei kurzen Dokumenten angewendet, weil die Formatierungen vom Anwender per Maus zugewiesen werden können. So können Sie beispielsweise ein bestimmtes Wort innerhalb eines Texts mit Fettdruck hervorheben oder eine Zeile zentrieren.

Neben der direkten Formatierung ist eine Formatierung von Text mit Hilfe von Vorlagen möglich. Diese Vorgehensweise wird als indirekte Formatierung bezeichnet. Bei der indirekten Formatierung weist der Anwender dem entsprechenden Textteil eine vordefinierte Vorlage zu. Wird das Layout des Texts dann zu einem späteren Zeitpunkt geändert, muss der Anwender nur die Vorlage ändern. StarOffice ändert dann die Darstellung sämtlicher Textstellen, die diese Vorlage verwenden.

---

Hinweis –

In VBA sind die Formatierungseigenschaften eines Objekts normalerweise auf eine Reihe von Unterobjekten verteilt (z. B. Range.Font, Range.Borders, Range.Shading, Range.ParagraphFormat). Der Zugriff auf die Eigenschaften erfolgt über geschachtelte Ausdrücke (z. B. Range.Font.AllCaps). In StarOffice Basic stehen die Formatierungseigenschaften hingegen durch Einsatz des jeweiligen Objekts (TextCursor, Paragraph usw.) direkt zur Verfügung. Einen Überblick zu den in StarOffice verfügbaren Zeichen- und Absatzeigenschaften finden Sie in den folgenden beiden Abschnitten.

---

---

Hinweis –

In der alten StarOffice API erfolgte die Formatierung eines Texts im Wesentlichen über das Selection-Objekt und dessen untergeordnete Objekte (z. B. Selection.Font, Selection.Paragraph und Selection.Border). In der neuen API stehen die Formatierungseigenschaften in jedem Objekt (Paragraph, TextCursor usw.) zur Verfügung und können direkt angewendet werden. Eine Auflistung der verfügbaren Zeichen- und Absatzeigenschaften finden Sie in den folgenden Absätzen.

---

Zeicheneigenschaften

Als Zeicheneigenschaften werden alle Formateigenschaften bezeichnet, die sich auf einzelne Zeichen beziehen. Hierzu zählen der Fettdruck und die Schriftart. Objekte, die das Setzen von Zeicheneigenschaften zulassen, müssen den Dienst com.sun.star.style.CharacterProperties unterstützen. StarOffice erkennt eine ganze Reihe von Diensten, die diesen Dienst unterstützen. Hierzu zählen unter anderem die zuvor beschriebenen Dienste com.sun.star.text.Paragraph für Absätze sowie com.sun.star.text.TextPortion für Absatzteile.

Der Dienst com.sun.star.style.CharacterProperties stellt keinerlei Schnittstellen zur Verfügung, bietet dafür allerdings eine Reihe von Eigenschaften, über die die Zeicheneigenschaften festgelegt und abgerufen werden können. Eine vollständige Liste sämtlicher Zeicheneigenschaften finden Sie in der StarOffice API-Referenz. In der folgenden Liste werden die wichtigsten Eigenschaften beschrieben:

• CharFontName (String): Name der gewählten Schriftart.

• CharColor (Long): Textfarbe.

• CharHeight (Float): Zeichenhöhe in Punkt (p).

• CharUnderline (Constant group): Art der Unterstreichung (Konstanten gemäß com.sun.star.awt.FontUnderline).

• CharWeight (Constant group): Schriftstärke (Konstanten gemäß com.sun.star.awt.FontWeight).

• CharBackColor (Long): Hintergrundfarbe.

• CharKeepTogether (Boolean): Unterdrückung des automatischen Zeilenumbruchs.

• CharStyleName (String): Name der Zeichenvorlage.

Absatzeigenschaften

Als Absatzeigenschaften gelten alle Formatierungsinformationen, die sich nicht auf einzelne Zeichen, sondern auf den gesamten Absatz beziehen, Hierzu gehören unter anderem der Abstand des Absatzes zum Seitenrand sowie der Zeilenabstand. Verfügbar sind die Absatzeigenschaften über den Dienst com.sun.star.style.ParagraphProperties.

Auch die Absatzeigenschaften stehen in verschiedenen Objekten zur Verfügung. Alle Objekte, die den Dienst com.sun.star.text.Paragraph unterstützen, bieten auch Unterstützung für die Absatzeigenschaften in com.sun.star.style.ParagraphProperties.

Eine vollständige Liste sämtlicher Absatzeigenschaften finden Sie in der StarOffice API-Referenz. Die gängigsten Absatzeigenschaften lauten:

• ParaAdjust (Enum): vertikale Textausrichtung (Konstanten gemäß com.sun.star.style.ParagraphAdjust).

• ParaLineSpacing (Struct): Zeilenabstand (Struktur gemäß com.sun.star.style.LineSpacing).

• ParaBackColor (Long): Hintergrundfarbe.

• ParaLeftMargin (Long): linker Rand in 100stel Millimeter.

• ParaRightMargin (Long): rechter Rand in 100stel Millimeter.

• ParaTopMargin (Long): oberer Rand in 100stel Millimeter.

• ParaBottomMargin (Long): unterer Rand in 100stel Millimeter.

• ParaTabStops (Array of struct): Art und Position der Tabulatoren (Array mit Strukturen des Typs com.sun.star.style.TabStop).

• ParaStyleName (String): Name der Absatzvorlage.

Beispiel: Einfacher HTML-Export

Das folgende Beispiel demonstriert den Umgang mit Formatierungsinformationen. Es iteriert durch ein Textdokument und erzeugt dabei eine einfache HTML-Datei. Jeder Absatz wird dazu in ein eigenes HTML-Element <P> geschrieben. Fett formatierte Absatzteile werden beim Export des Weiteren über ein HTML-Element <B> gekennzeichnet.

Dim FileNo As Integer, Filename As String, CurLine As String

Dim Doc As Object
Dim Enum1 As Object, Enum2 As Object
Dim TextElement As Object, TextPortion As Object

Filename = "c:\text.html"
FileNo = Freefile
Open Filename For Output As #FileNo
Print #FileNo, "<HTML><BODY>"

Doc = StarDesktop.CurrentComponent
Enum1 = Doc.Text.createEnumeration

' Schleife über alle Absätze
While Enum1.hasMoreElements
   TextElement = Enum1.nextElement
   If TextElement.supportsService("com.sun.star.text.Paragraph") Then
      Enum2 = TextElement.createEnumeration
      CurLine = "<P>"

      ' Schleife über alle Absatzteile
      While Enum2.hasMoreElements
         TextPortion = Enum2.nextElement
         If TextPortion.CharWeight = com.sun.star.awt.FontWeight.BOLD THEN
            CurLine = CurLine & "<B>" & TextPortion.String & "</B>" 
         Else
            CurLine = CurLine & TextPortion.String
         End If
      Wend

      ' Ausgabe der Zeile
      CurLine = CurLine & "</P>"
      Print #FileNo, CurLine

   End If
Wend

' HTML-Fußzeile schreiben
Print #FileNo, "</BODY></HTML>"
Close #FileNo

Die Basisstruktur des Beispiels orientiert sich an den weiter oben bereits aufgeführten Beispielen zum Durchlaufen der Absatzteile eines Texts. Hinzugekommen sind die Funktionen zum Schreiben der HTML-Datei sowie ein Prüfcode, der die Schriftstärke der jeweiligen Textabschnitte prüft und fett formatierte Absatzteile mit einem entsprechenden HTML-Tag versieht.

Standardwerte für Zeichen- und Absatzeigenschaften

Direkte Formatierungen haben stets Vorrang gegenüber indirekten Formatierungen. Das heißt, durch Vorlagen erzeugte Formatierungen haben eine niedrigere Priorität als direkte Formatierungen in einem Text.

Zu ermitteln, ob ein Abschnitt eines Dokuments direkt oder indirekt formatiert ist, ist keine leichte Aufgabe. In den von StarOffice bereitgestellten Symbolleisten finden sich die allgemeinen Texteigenschaften wie Schriftart, -stärke und -größe. Ob die betreffenden Einstellungen allerdings auf einer Vorlage basieren oder eine direkte Formatierung im Text sind, bleibt dabei noch unklar.

StarOffice Basic stellt die Methode getPropertyState zur Verfügung, mit der Programmierer prüfen können, wie eine bestimmte Formatierungseigenschaft bewirkt wurde. Sie erwartet als Parameter den Namen der Eigenschaft und gibt eine Konstante zurück, die Informationen über die Herkunft der Formatierung enthält. Folgende Antworten, die in der Aufzählung com.sun.star.beans.PropertyState definiert sind, sind möglich:

• com.sun.star.beans.PropertyState.DIRECT_VALUE: die Eigenschaft wurde im Text direkt definiert (direkte Formatierung),

• com.sun.star.beans.PropertyState.DEFAULT_VALUE: die Eigenschaft wurde über eine Vorlage definiert (indirekte Formatierung)

• com.sun.star.beans.PropertyState.AMBIGUOUS_VALUE: die Herkunft der Eigenschaft ist unklar. Dieser Zustand tritt beispielsweise beim Abfragen der Eigenschaft Fettdruck eines Absatzes auf, der sowohl fett formatierte als auch normal formatierte Wörter enthält.

Das folgende Beispiel zeigt, wie Formateigenschaften in StarOffice bearbeitet werden können. Es durchsucht einen Text nach Absatzteilen, die mit Hilfe direkter Formatierung fett formatiert wurden. Stößt es auf einen entsprechenden Absatzteil, wird die direkte Formatierung mit der Methode setPropertyToDefault gelöscht und dem betreffenden Absatzteil eine Zeichenvorlage MyBold zugewiesen.

Dim Doc As Object
Dim Enum1 As Object
Dim Enum2 As Object
Dim TextElement As Object
Dim TextPortion As Object

Doc = StarDesktop.CurrentComponent
Enum1 = Doc.Text.createEnumeration

' Schleife über alle Absätze
While Enum1.hasMoreElements
   TextElement = Enum1.nextElement
   If TextElement.supportsService("com.sun.star.text.Paragraph") Then
      Enum2 = TextElement.createEnumeration

      ' Schleife über alle Absatzteile
      While Enum2.hasMoreElements
         TextPortion = Enum2.nextElement
         If TextPortion.CharWeight = _
           com.sun.star.awt.FontWeight.BOLD AND _
           TextPortion.getPropertyState("CharWeight") = _
           com.sun.star.beans.PropertyState.DIRECT_VALUE Then

            TextPortion.setPropertyToDefault("CharWeight")
            TextPortion.CharStyleName = "MyBold"

         End If

      Wend

   End If

Wend

Bearbeiten von Textdokumenten

Im vorigen Abschnitt wurde bereits eine ganze Reihe von Optionen zum Bearbeiten von Textdokumenten besprochen. Dabei lag der Schwerpunkt auf den Diensten com.sun.star.text.TextPortion und com.sun.star.text.Paragraph, die Zugriff auf Absatzteile und ganze Absätze gewähren. Diese Dienste eignen sich für Anwendungen, in denen der Inhalt eines Texts vom Anfang bis zum Ende in einem einzigen Schleifendurchlauf bearbeitet werden soll. Für viele Probleme reicht diese Vorgehensweise jedoch nicht aus. StarOffice stellt für kompliziertere Aufgaben, einschließlich dem Rückwärtsnavigieren innerhalb eines Dokuments oder dem satz- bzw. wortweisen Navigieren statt mit TextPortions, den Dienst com.sun.star.text.TextCursor zur Verfügung.

Der TextCursor

Ein TextCursor in der StarOffice API ist vergleichbar mit dem sichtbaren Cursor in einem StarOffice-Dokument. Er markiert eine bestimmten Stelle innerhalb eines Textdokuments und lässt sich per Befehl in verschiedene Richtungen navigieren. Dennoch sollte man die in StarOffice Basic verfügbaren TextCursor-Objekte nicht mit dem sichtbaren Cursor verwechseln. Es handelt sich dabei um zwei unterschiedliche Dinge.

---

Hinweis –

Die Terminologie weicht gegenüber der in VBA verwendeten ab: Das Range-Objekt von VBA ist vom Funktionsumfang her mit dem TextCursor-Objekt in StarOffice vergleichbar und nicht – wie der Name eventuell vermuten ließe – mit dem Range-Objekt in StarOffice.

Das TextCursor-Objekt in StarOffice stellt beispielsweise Methoden zum Navigieren und Ändern von Text bereit, die in VBA im Range-Objekt enthalten sind (z. B. MoveStart, MoveEnd, InsertBefore, InsertAfter). Die entsprechenden Gegenstücke des TextCursor-Objekts in StarOffice werden in den folgenden Abschnitten beschrieben.

---

Navigieren innerhalb eines Texts

Das TextCursor-Objekt in StarOffice Basic agiert unabhängig von dem sichtbaren Cursor in einem Textdokument. Eine programmgesteuerte Positionsänderung eines TextCursor-Objekts hat keinerlei Auswirkungen auf den sichtbaren Cursor. Es ist sogar möglich, für ein und dasselbe Dokument mehrere TextCursor-Objekte zu öffnen, die unabhängig voneinander an verschiedenen Positionen eingesetzt werden können.

Ein TextCursor-Objekt wird über den Aufruf createTextCursor erstellt:

Dim Doc As Object
Dim Cursor As Object

Doc = StarDesktop.CurrentComponent
Cursor = TextDocument.Text.createTextCursor()

Das so erzeugte Cursor-Objekt unterstützt den Dienst com.sun.star.text.TextCursor, der wiederum eine ganze Reihe von Methoden zum Navigieren in Textdokumenten zur Verfügung stellt. Das folgende Beispiel bewegt den TextCursor zuerst zehn Zeichen nach links und dann drei Zeichen nach rechts:

Cursor.goLeft(10, False)
Cursor.goRight(3, False)

Ein TextCursor kann einen vollständigen Bereich markieren. Eine solche Markierung ist vergleichbar mit der Markierung einer Textstelle mit der Maus. Der Parameter False in den oben stehenden Funktionsaufrufen gibt an, ob der mit der Cursor-Bewegung überquerte Bereich markiert werden soll. So wandert beispielsweise der TextCursor in folgendem Beispiel

Cursor.goLeft(10, False)
Cursor.goRight(3, True)

zuerst zehn Zeichen nach recht, ohne diesen Bereich zu markieren, und geht danach drei Zeichen zurück, wobei diese markiert werden. Der vom TextCursor markierte Bereich beginnt somit hinter dem siebten Zeichen im Text und endet hinter dem zehnten Zeichen.

Hier finden Sie nun die zentralen Methoden, die der Dienst com.sun.star.text.TextCursor für die Navigation zur Verfügung stellt:

• goLeft (Count, Expand): springt Count Zeichen nach links.

• goRight (Count, Expand): springt Count Zeichen nach rechts.

• gotoStart (Expand): springt an den Anfang des Textdokuments.

• gotoEnd (Expand): springt an das Ende des Textdokuments.

• gotoRange (TextRange, Expand): springt zu dem angegebenen TextRange-Objekt.

• gotoStartOfWord (Expand): springt an den Anfang des aktuellen Worts.

• gotoEndOfWord (Expand): springt an das Ende des aktuellen Worts.

• gotoNextWord (Expand): springt an den Anfang des nächsten Worts.

• gotoPreviousWord (Expand): springt an den Anfang des vorangehenden Worts.

• isStartOfWord (): gibt True zurück, wenn sich TextCursor am Anfang eines Worts befindet.

• isEndOfWord (): gibt True zurück, wenn sich TextCursor am Ende eines Worts befindet.

• gotoStartOfSentence (Expand): springt an den Anfang des aktuellen Satzes.

• gotoEndOfSentence (Expand): springt an das Ende des aktuellen Satzes.

• gotoNextSentence (Expand): springt an den Anfang des nächsten Satzes.

• gotoPreviousSentence (Expand): springt an den Anfang des vorangehenden Satzes.

• isStartOfSentence (): gibt True zurück, wenn sich TextCursor am Anfang eines Satzes befindet.

• isEndOfSentence (): gibt True zurück, wenn sich TextCursor am Ende eines Satzes befindet.

• gotoStartOfParagraph (Expand): springt an den Anfang des aktuellen Absatzes.

• gotoEndOfParagraph (Expand): springt an das Ende des aktuellen Absatzes.

• gotoNextParagraph (Expand): springt an den Anfang des nächsten Absatzes.

• gotoPreviousParagraph (Expand): springt an den Anfang des vorangehenden Absatzes.

• isStartOfParagraph (): gibt True zurück, wenn sich TextCursor am Anfang eines Absatzes befindet.

• isEndOfParagraph (): gibt True zurück, wenn sich TextCursor am Ende eines Absatzes befindet.

Die Unterteilung des Texts in Sätze erfolgt auf der Grundlage von Satzzeichen. Punkte werden also beispielsweise Satzendezeichen interpretiert.

Bei dem Parameter Expand handelt es sich um einen Boolean-Wert, der angibt, ob der beim Navigieren überquerte Bereich markiert werden soll. Alle Navigationsmethoden geben darüber hinaus einen Parameter zurück, der angibt, ob die Navigation erfolgreich war oder ob die Aktion mangels Text abgebrochen wurde.

Im Folgenden finden Sie eine Liste einiger Methoden zum Bearbeiten der mit einem TextCursor markierten Bereiche, die ebenfalls den Dienst com.sun.star.text.TextCursor unterstützen:

• collapseToStart (): setzt die Markierung zurück und positioniert den TextCursor am Anfang des vorher markierten Bereichs.

• collapseToEnd (): setzt die Markierung zurück und positioniert den TextCursor am Ende des vorher markierten Bereichs.

• isCollapsed (): gibt True zurück, wenn der TextCursor zurzeit keine Markierung enthält.

Formatieren von Text mit dem TextCursor

Der Dienst com.sun.star.text.TextCursor unterstützt sämtliche Zeichen- und Absatzeigenschaften, die zu Beginn dieses Kapitels bereits vorgestellt wurden.

Das folgende Beispiel verdeutlicht, wie diese zusammen mit einem TextCursor verwendet werden können. Es durchläuft ein vollständiges Dokument und formatiert das erste Wort eines jeden Satzes in Fettdruck.

Dim Doc As Object
Dim Cursor As Object
Dim Proceed As Boolean

Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor

Do

   Cursor.gotoEndOfWord(True)
   Cursor.CharWeight = com.sun.star.awt.FontWeight.BOLD
   Proceed = Cursor.gotoNextSentence(False)
   Cursor.gotoNextWord(False)

Loop While Proceed

Das Beispiel erzeugt zuerst ein Dokumentobjekt für den gerade geöffneten Text. Danach iteriert es Satz für Satz durch den gesamten Text, markiert jeweils das erste Wort und formatiert dieses fett.

Abrufen und Ändern von Textinhalten

Enthält ein TextCursor einen markierten Bereich, so steht dieser Text über die Eigenschaft String des TextCursor-Objekts zur Verfügung. Das folgende Beispiel verwendet die Eigenschaft String dazu, um jeweils das erste Wort eines Satzes in einem Meldungsfenster anzuzeigen:

Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean

Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor

Do 

   Cursor.gotoEndOfWord(True)
   MsgBox Cursor.String
   Proceed = Cursor.gotoNextSentence(False)
   Cursor.gotoNextWord(False)
Loop While Proceed 

Analog kann das erste Wort eines jeden Satzes über die Eigenschaft String geändert werden:

Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean

Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor

Do 

   Cursor.gotoEndOfWord(True)
   Cursor.String = "Ups"
   Proceed = Cursor.gotoNextSentence(False)
   Cursor.gotoNextWord(False)

Loop While Proceed 

Enthält der TextCursor einen markierten Bereich, ersetzt eine Zuweisung zur Eigenschaft String diesen durch den neuen Text. Ist kein markierter Bereich vorhanden, wird der Text an der aktuellen TextCursor-Position eingefügt.

Einfügen von Steuerzeichen

In einigen Situationen ist es notwendig, nicht den eigentlichen Text eines Dokuments zu modifizieren, sondern seine Struktur. Hierfür bietet StarOffice Steuerzeichen an, die in den Text eingefügt werden und seinen Aufbau beeinflussen. Die Steuerzeichen sind in der Konstantengruppe com.sun.star.text.ControlCharacter definiert. Folgende Steuerzeichen sind in StarOffice verfügbar:

• PARAGRAPH_BREAK: Absatzumbruch.

• LINE_BREAK: Zeilenumbruch innerhalb eines Absatzes.

• SOFT_HYPHEN: mögliche Position für Silbentrennung.

• HARD_HYPHEN: obligatorische Position für Silbentrennung.

• HARD_SPACE: geschütztes Leerzeichen, das auch im Blocksatz nicht ausgeschlossen (gespreizt oder gestaucht) wird.

Zum Einfügen der Steuerzeichen bedarf es neben dem Cursor auch des verknüpften Textdokument-Objekts. Das folgende Beispiel fügt hinter dem 20. Zeichen eines Texts einen Absatz ein:

Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor
Cursor.goRight(20, False)

Doc.Text.insertControlCharacter(Cursor, _
   com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False)

Der im Aufruf der Methode insertControlCharacter verwendete Parameter False gewährleistet, dass der aktuell vom TextCursor markierte Bereich auch nach der Einfügeoperation bestehen bleibt. Wird hier der Parameter True übergeben, so ersetzt insertControlCharacter den aktuellen Text.

Suchen von Textteilen

In vielen Fällen gilt es, einen Text nach einen bestimmten Begriff zu durchsuchen und die entsprechende Trefferstelle zu bearbeiten. Hierzu bieten alle StarOffice-Dokumente eine spezielle Schnittstelle, die stets nach dem gleichen Prinzip arbeitet: Vor einem Suchvorgang muss zunächst ein so genannter SearchDescriptor erstellt werden, der definiert, was StarOffice in einem Dokument suchen soll. Ein SearchDescriptor ist ein Objekt, das den Dienst com.sun.star.util.SearchDescriptor unterstützt und über die Methode createSearchDescriptor eines Dokuments erzeugt werden kann:

Dim SearchDesc As Object
SearchDesc = Doc.createSearchDescriptor

Nachdem der SearchDescriptor erzeugt wurde, übernimmt er den zu suchenden Text:

SearchDesc.searchString="any text"

Von seiner Funktion lässt sich der SearchDescriptor am ehesten mit dem Such-Dialog von StarOffice vergleichen. Ähnlich wie das Suchfenster lassen sich auch im SearchDescriptor-Objekt die für eine Suche notwendigen Einstellungen vornehmen.

Folgende Eigenschaften werden von dem Dienst com.sun.star.util.SearchDescriptor zur Verfügung gestellt:

• SearchBackwards (Boolean): durchsucht den Text rückwärts statt vorwärts.

• SearchCaseSensitive (Boolean): unterscheidet bei der Suche Groß- und Kleinschreibung.

• SearchRegularExpression (Boolean): verarbeitet den Suchausdruck wie einen regulären Ausdruck.

• SearchStyles (Boolean): durchsucht den Text nach der angegebenen Absatzvorlage.

• SearchWords (Boolean): sucht nur ganze Wörter.

Auch die StarOffice SearchSimilarity (auch "Fuzzy Matching", unscharfe Suche oder Ähnlichkeitssuche) ist in StarOffice Basic verfügbar. Mit dieser Funktion sucht StarOffice nach einem Ausdruck, der dem Suchbegriff zwar ähnlich, aber nicht exakt mit ihm identisch sein muss. Die Anzahl der hinzugekommenen, gelöschten und geänderten Zeichen können für diesen Ausdruck individuell definiert werden. Im Folgenden nun die verknüpften Eigenschaften des Dienstes com.sun.star.util.SearchDescriptor:

• SearchSimilarity (Boolean): führt eine Ähnlichkeitssuche durch.

• SearchSimilarityAdd (Short): Anzahl der Zeichen, die bei einer Ähnlichkeitssuche hinzugefügt werden dürfen.

• SearchSimilarityExchange (Short): Anzahl der Zeichen, die im Rahmen einer Ähnlichkeitssuche ersetzt werden dürfen.

• SearchSimilarityRemove (Short): Anzahl der Zeichen, die im Rahmen einer Ähnlichkeitssuche entfernt werden dürfen.

• SearchSimilarityRelax (Boolean): beachtet für den Suchausdruck alle Abweichungsregeln gleichzeitig.

Ist der SearchDescriptor wie gewünscht vorbereitet, kann er auf das Textdokument angewendet werden. Für diesen Zweck stellen die StarOffice-Dokumente die Methoden findFirst sowie findNext zur Verfügung:

Found = Doc.findFirst (SearchDesc)

Do While Found
   ' Suchergebnis bearbeiten
   Found = Doc.findNext( Found.End, Search)

Loop

Das Beispiel ermittelt in einer Schleife sämtliche Übereinstimmungen und gibt ein TextRange-Objekt zurück, das auf die gefundene Textstelle verweist.

Beispiel: Ähnlichkeitssuche

Dieses Beispiel zeigt, wie sich ein Text nach dem Wort "Umsatz" durchsuchen und die gefundenen Stellen fett formatieren lassen. Um neben dem Wort "Umsatz" auch die Pluralform "Umsätze" und Deklinationen wie "Umsatzes" zu finden, kommt eine Ähnlichkeitssuche zum Einsatz. Die gefundenen Ausdrücke weichen um bis zu zwei Buchstaben von dem Suchausdruck ab:

Dim SearchDesc As Object
Dim Doc As Object

Doc = StarDesktop.CurrentComponent

SearchDesc = Doc.createSearchDescriptor
SearchDesc.SearchString="Umsatz"
SearchDesc.SearchSimilarity = True
SearchDesc.SearchSimilarityAdd = 2
SearchDesc.SearchSimilarityExchange = 2 
SearchDesc.SearchSimilarityRemove = 2 
SearchDesc.SearchSimilarityRelax = False

Found = Doc.findFirst (SearchDesc)

Do While Found
Found.CharWeight = com.sun.star.awt.FontWeight.BOLD
Found = Doc.findNext( Found.End, Search)
Loop

---

Hinweis –

Die Grundidee beim Suchen und Ersetzen in StarOffice ist vergleichbar mit der in VBA. Beide Schnittstellen stellen Ihnen ein Objekt zur Verfügung, mit dem die Eigenschaften für das Suchen und Ersetzen definiert werden können. Dieses Objekt wird anschließend auf den gewünschten Textbereich angewendet, um die Aktion auszuführen. Während in VBA über die Find-Eigenschaft des Range-Objekts auf das zuständige Hilfsobjekt zugegriffen wird, wird es in StarOffice Basic über den Aufruf createSearchDescriptor oder createReplaceDescriptor des Dokumentobjekts erzeugt. Auch die verfügbaren Sucheigenschaften und -methoden unterscheiden sich.

---

Wie in der alten API von StarOffice erfolgt auch in der neuen API das Suchen und Ersetzen von Text über das Dokumentobjekt. Während es speziell zur Definition der Suchoptionen bisher ein Objekt namens SearchSettings gab, erfolgt die Suche im neuen Objekt nun über ein Objekt SearchDescriptor oder ReplaceDescriptor für das automatische Ersetzen von Text. Diese Objekte umfassen nicht nur die Optionen, sondern auch den aktuellen Suchtext und gegebenenfalls die zugehörige Textersetzung. Die Deskriptor-Objekte werden über das Dokumentobjekt erzeugt, entsprechend den jeweiligen Anforderungen ausgefüllt und im Anschluss daran als Parameter für die Suchmethoden zurück an das Dokumentobjekt übergeben.

Ersetzen von Textteilen

Analog zur Suchfunktion steht auch die Ersetzungsfunktion von StarOffice in StarOffice Basic zur Verfügung. Die Handhabung beider Funktionen ist identisch. Auch für einen Ersetzungsvorgang wird zunächst ein spezielles Objekt benötigt, das die Parameter für den Ersetzungsvorgang aufnimmt. Es wird als ReplaceDescriptor bezeichnet und unterstützt den Dienst com.sun.star.util.ReplaceDescriptor. Alle der im vorstehenden Absatz beschriebenen Eigenschaften des SearchDescriptor werden auch von ReplaceDescriptor unterstützt. So ist es beispielsweise ebenfalls möglich, bei einem Ersetzungsvorgang die Unterscheidung von Groß- und Kleinschreibung ein- und auszuschalten sowie Ähnlichkeitssuchen durchzuführen.

Das folgende Beispiel demonstriert den Einsatz eines ReplaceDescriptor für eine Suche innerhalb eines StarOffice-Dokuments.

Dim I As Long
Dim Doc As Object
Dim Replace As Object
Dim BritishWords(5) As String
Dim USWords(5) As String

BritishWords() = Array("colour", "neighbour", "centre", "behaviour", _
   "metre", "through")

USWords() = Array("color", "neighbor", "center", "behavior", _
   "meter", "thru")

Doc = StarDesktop.CurrentComponent
Replace = Doc.createReplaceDescriptor

For O = 0 To 5
   Replace.SearchString = BritishWords(I)
   Replace.ReplaceString = USWords(I)
   Doc.replaceAll(Replace)
Next n

Die Ausdrücke zum Suchen und Ersetzen werden über die Eigenschaften SearchString und ReplaceString des ReplaceDescriptor gesetzt. Schließlich folgt der eigentliche Ersetzungsvorgang über die Methode replaceAll des Dokumentobjekts, die sämtliche Vorkommen des Suchausdrucks ersetzt.

Beispiel: Suchen und Ersetzen von Text mit regulären Ausdrücken

Besonders leistungsfähig ist die Ersetzungsfunktion von StarOffice im Zusammenhang mit regulären Ausdrücken. Diese bieten die Möglichkeit, anstelle eines festen Werts einen variablen Suchausdruck mit Platzhaltern und Sonderzeichen zu definieren.

Die von StarOffice unterstützten regulären Ausdrücke sind in der Online-Hilfe von StarOffice ausführlich beschrieben. Im Folgenden seien einige Beispiele genannt:

• Ein Punkt innerhalb eines Suchausdrucks steht für ein beliebiges Zeichen. So steht der Suchausdruck "sh.rt" sowohl für shirt als auch für short.

• Das Zeichen ^ markiert den Anfang eines Absatzes. Mit dem Suchausdruck ^Peter lassen sich so alle Vorkommen des Namens Peter finden, die am Anfang eines Absatzes stehen.

• Das Zeichen $ markiert ein Absatzende. Mit dem Suchausdruck Peter$ lassen sich so alle Vorkommen des Namens Peter finden, die am Ende eines Absatzes stehen.

• Ein * bestimmt, dass das vorstehende Zeichen beliebig oft wiederholt vorkommen darf. Mit dem Punkt kann er als Platzhalter für ein beliebiges Zeichen kombiniert werden. Der Ausdruck temper.*e steht beispielsweise für die englischen Begriffe temperance und temperature.

Das folgende Beispiel zeigt, wie mit Hilfe des regulären Ausdrucks "^$" sämtliche Leerzeilen aus einem Textdokument entfernt werden können:

Dim Doc As Object
Dim Replace As Object
Dim I As Long

Doc = StarDesktop.CurrentComponent
Replace = Doc.createReplaceDescriptor

Replace.SearchRegularExpression = True
Replace.SearchString = "^$"
Replace.ReplaceString = ""

Doc.replaceAll(Replace)

Textdokumente: Mehr als nur Text

Bisher ging es in diesem Kapitel ausschließlich um Textabsätze und deren Teile. Aber Textdokumente können auch andere Objekte enthalten. Dazu zählen Tabellen, Zeichnungen, Textfelder und Verzeichnisse. Diese Objekte können alle an einem beliebigen Punkt innerhalb eines Texts verankert sein.

Aufgrund dieser Gemeinsamkeiten unterstützen alle diese Objekte in StarOffice einen gemeinsamen Basisdienst namens com.sun.star.text.TextContent. Er stellt folgende Eigenschaften zur Verfügung:

• AnchorType (Enum): bestimmt den Verankerungstyp eines TextContent-Objekts (Standardwerte gemäß Enumeration com.sun.star.text.TextContentAnchorType).

• AnchorTypes (Sequence of Enum): Enumeration aller AnchorTypes, die ein spezielles TextContent-Objekt unterstützen.

• TextWrap (Enum): bestimmt den Textumlauftyp um ein TextContent-Objekt (Standardwerte gemäß Enumeration com.sun.star.text.WrapTextMode).

Die TextContent-Objekte haben auch einige gemeinsame Methoden, insbesondere die zum Erstellen, Einfügen und Löschen von Objekten.

• Ein neues TextContent-Objekt wird über die Methode createInstance des Dokumentobjekts erstellt.

• Eingefügt wird ein Objekt mit der insertTextContent-Methode des Textobjekts.

• Gelöscht werden TextContent-Objekte mit der removeTextContent-Methode.

In den folgenden Abschnitten finden Sie eine Reihe von Beispielen, die diese Methoden verwenden.

Tabellen

Das folgende Beispiel erstellt eine Tabelle unter Zuhilfenahme der weiter oben beschriebenen Methode createInstance.

Dim Doc As Object
Dim Table As Object
Dim Cursor As Object

Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()

Table = Doc.createInstance("com.sun.star.text.TextTable")
Table.initialize(5, 4)

Doc.Text.insertTextContent(Cursor, Table, False)

Nach der Erstellung wird die Tabelle über einen initialize-Aufruf auf die erforderliche Anzahl von Zeilen und Spalten festgelegt und dann mit insertTextContent in das Textdokument eingefügt.

Wie im Beispiel zu sehen, erwartet die Methode insertTextContent neben dem einzufügenden Content-Objekt noch zwei weitere Parameter:

• ein Cursor-Objekt, das die Einfügeposition bestimmt

• eine Boolean-Variable, die angibt, ob das Content-Objekt die aktuelle Auswahl des Cursors ersetzen (Wert True) oder vor der aktuellen Auswahl in den Text eingefügt werden soll (False).

---

Hinweis –

Beim Erstellen und Einfügen von Tabellen in ein Textdokument werden in StarOffice Basic ähnliche Objekte verwendet wie in VBA: das Dokumentobjekt und ein TextCursor-Objekt in StarOffice Basic bzw. das Range-Objekt als VBA-Gegenstück. Während das Erstellen und Einfügen der Tabelle in VBA die Methode Document.Tables.Add übernimmt, wird diese in StarOffice Basic gemäß dem vorstehenden Beispiel über createInstance erstellt und initialisiert und mit Hilfe von insertTextContent in das Dokument eingefügt.

---

Die in ein Textdokument eingefügten Tabellen können über eine einfache Schleife ermittelt werden. Zu diesem Zweck dient die Methode des getTextTables() des Textdokument-Objekts:

Dim Doc As Object
Dim TextTables As Object
Dim Table As Object
Dim I As Integer
Doc = StarDesktop.CurrentComponent
TextTables = Doc.getTextTables()
For I = 0 to TextTables.count - 1

   Table = TextTables(I)
   ' Table bearbeiten
Next I

---

Hinweis –

Texttabellen stehen in StarOffice 8 über die Liste TextTables des Dokumentobjekts zur Verfügung. Sie löst damit die bisherige Tables-Auflistung im Selection-Objekt ab. Das vorstehende Beispiel zeigt, wie eine Texttabelle erstellt werden kann. Im folgenden Abschnitt werden die Zugriffsmöglichkeiten auf Texttabellen beschrieben.

---

Bearbeiten von Tabellen

Eine Tabelle besteht aus einzelnen Zeilen. Diese wiederum enthalten die verschiedenen Zellen. Streng genommen gibt es in StarOffice keine Tabellenspalten. Diese ergeben sich implizit durch die gleiche Anordnung der untereinander stehenden Zeilen. Um den Zugriff auf die Tabellen zu vereinfachen, bietet StarOffice jedoch einige Methoden an, die spaltenweise arbeiten. Sie sind besonders nützlich, wenn in der Tabelle keine Zellen zusammengeführt wurden.

Wenden wir uns zunächst den Eigenschaften der Tabelle selbst zu. Diese sind im Dienst com.sun.star.text.TextTable definiert. Im Folgenden finden Sie eine Liste der wichtigsten Eigenschaften des Tabellenobjekts:

• BackColor (Long): Hintergrundfarbe der Tabelle.

• BottomMargin (Long): unterer Rand in 100stel Millimeter.

• LeftMargin (Long): linker Rand in 100stel Millimeter.

• RightMargin (Long): rechter Rand in 100stel Millimeter.

• TopMargin (Long): oberer Rand in 100stel Millimeter.

• RepeatHeadline (Boolean): Tabellenüberschrift wird auf jeder Seite wiederholt.

• Width (Long): absolute Breite der Tabelle in 100stel Millimeter.

Zeilen

Eine Tabelle besteht aus einer Liste mit Zeilen. Das folgende Beispiel zeigt, wie die Zeilen einer Tabelle abgerufen und formatiert werden können.

Dim Doc As Object
Dim Table As Object
Dim Cursor As Object
Dim Rows As Object
Dim Row As Object
Dim I As Integer
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()

Table = Doc.createInstance("com.sun.star.text.TextTable")
Table.initialize(5, 4)

Doc.Text.insertTextContent(Cursor, Table, False)
Rows = Table.getRows
For I = 0 To Rows.getCount() - 1
   Row = Rows.getByIndex(I)
   Row.BackColor = &HFF00FF
Next

Das Beispiel erstellt zuerst über einen Table.getRows-Aufruf eine Liste mit allen Zeilen. Die Methoden getCount und getByIndex ermöglichen eine Weiterverarbeitung der Liste und gehören zur Schnittstelle com.sun.star.table.XTableRows. Die Methode getByIndex gibt ein Zeilenobjekt zurück, das den Dienst com.sun.star.text.TextTableRow unterstützt.

Im Folgenden finden Sie die zentralen Methoden der Schnittstelle com.sun.star.table.XTableRows:

• getByIndex(Integer): gibt ein Zeilenobjekt für den angegebenen Index zurück.

• getCount(): gibt die Anzahl der Zeilenobjekte zurück.

• insertByIndex(Index, Count): fügt Count Zeilen ab der Position Index in die Tabelle ein.

• removeByIndex(Index, Count): löscht Count Zeilen ab der Position Index aus der Tabelle.

Während die Methoden getByIndex und getCount in allen Tabellen zur Verfügung stehen, können die Methoden insertByIndex und removeByIndex nur in Tabellen verwendet werden, die keine zusammengeführten Zellen enthalten.

Der Dienst com.sun.star.text.TextTableRow bietet folgende Eigenschaften:

• BackColor (Long): Hintergrundfarbe der Zeile.

• Height (Long): Höhe der Zeile in 100stel Millimeter.

• IsAutoHeight (Boolean): Tabellenhöhe wird dynamisch an den Inhalt angepasst.

• VertOrient (Const): vertikale Ausrichtung des Textrahmens – Angaben zur Vertikalen Ausrichtung des Texts innerhalb der Tabelle (Werte gemäß com.sun.star.text.VertOrientation).?

Spalten

Der Zugriff auf Spalten erfolgt genauso wie der Zugriff auf Zeilen über die Methoden getByIndex, getCount, insertByIndex und removeByIndex am Column-Objekt, auf das über getColumns zugegriffen wird. Sie können jedoch nur in Tabellen angewendet werden, die keine zusammengeführten Tabellenzellen enthalten. Eine spaltenweise Formatierung von Zellen ist in StarOffice Basic nicht möglich. Um dies zu erreichen, müssen Sie einzelne Tabellenzellen formatieren.

Zellen

Jede Zelle eines StarOffice-Dokuments verfügt über einen eindeutigen Namen. Befindet sich der Cursor von StarOffice in einer Zelle, wird der Name der jeweiligen Zellen in der Statusleiste angezeigt. Die Zelle oben links hat in der Regel den Namen A1, die Zeile unten rechts den Namen Xn, wobei X für den Buchstaben der höchsten Spalte und n für die Nummer der letzten Zeile steht. Die Zellenobjekte sind über die Methode getCellByName() des Tabellenobjekts verfügbar. Das folgende Beispiel zeigt eine Schleife, die nacheinander alle Zellen einer Tabelle durchläuft und die jeweilige Zeilen- und Spaltennummer in diese einträgt.

Dim Doc As Object
Dim Table As Object
Dim Cursor As Object
Dim Rows As Object
Dim RowIndex As Integer
Dim Cols As Object
Dim ColIndex As Integer
Dim CellName As String
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()

Table = Doc.createInstance("com.sun.star.text.TextTable")
Table.initialize(5, 4)

Doc.Text.insertTextContent(Cursor, Table, False)

Rows = Table.getRows
Cols = Table.getColumns

For RowIndex = 1 To Rows.getCount()
   For ColIndex = 1 To Cols.getCount()
      CellName = Chr(64 + ColIndex) & RowIndex
      Cell = Table.getCellByName(CellName)
      Cell.String = "Zeile: " & CStr(RowIndex) + ", Spalte: " & CStr(ColIndex)
   Next
Next

Eine Tabellenzelle ist mit einem Standardtext vergleichbar. Sie unterstützt die Schnittstelle createTextCursor zur Erstellung eines verknüpften TextCursor-Objekts.

CellCursor = Cell.createTextCursor()

Deshalb stehen automatisch alle Formatierungsmöglichkeiten für einzelne Zeichen und Absätze zur Verfügung.

Das folgende Beispiel durchsucht alle Tabellen eines Textdokuments und formatiert alle Zellen mit numerischen Werten über die entsprechende Absatzeigenschaft rechtsbündig.

Dim Doc As Object
Dim TextTables As Object
Dim Table As Object
Dim CellNames
Dim Cell As Object
Dim CellCursor As Object
Dim I As Integer
Dim J As Integer

Doc = StarDesktop.CurrentComponent
TextTables = Doc.getTextTables()

For I = 0 to TextTables.count - 1
   Table = TextTables(I)
   CellNames = Table.getCellNames()

   For J = 0 to UBound(CellNames)
      Cell = Table.getCellByName(CellNames(J))
      If IsNumeric(Cell.String) Then
         CellCursor = Cell.createTextCursor()
         CellCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.RIGHT
      End If
   Next
Next

Das Beispiel erstellt eine TextTables-Liste mit allen Tabellen eines Texts, die in einer Schleife durchlaufen werden. Für jede dieser Tabellen erstellt StarOffice dann wiederum eine Liste der zugehörigen Zellnamen. Auch diese werden in einer Schleife durchlaufen. Enthält eine Zelle einen numerischen Wert, passt das Beispiel die Formatierung entsprechend an. Hierzu erzeugt es zunächst ein TextCursor-Objekt, das auf den Inhalt der Tabellenzelle verweist, und passt daraufhin die Absatzeigenschaften der Tabellenzelle an.

Textrahmen

Textrahmen gelten wie Tabellen und Grafiken als TextContent-Objekte. Sie bestehen zwar im Wesentlichen aus Standardtext, sind jedoch frei auf einer Seite positionierbar und befinden sich außerhalb des Textflusses.

Wie bei allen TextContent-Objekten wird auch bei einem Textrahmen zwischen der eigentlichen Erstellung und dem Einfügen in das Dokument unterschieden.

Dim Doc As Object
Dim TextTables As Object
Dim Cursor As Object
Dim Frame As Object

Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
Frame = Doc.createInstance("com.sun.star.text.TextFrame")
Doc.Text.insertTextContent(Cursor, Frame, False)

Das Erstellen eines Textrahmens erfolgt über die Methode createInstance des Dokumentobjekts. Der so erstellte Textrahmen kann dann mit der Methode insertTextContent des Text-Objekts in das Dokument eingefügt werden. Hierbei ist der Name des richtigen Dienstes com.sun.star.text.TextFrame anzugeben.

Die Einfügeposition des Textrahmens wird durch ein Cursor-Objekt bestimmt, das beim Einfügen mit ausgeführt wird.

---

Hinweis –

Textrahmen bilden das StarOffice-Gegenstück zu den in Word verwendeten Positionsrahmen. Während hierzu in VBA die Methode Document.Frames.Add verwendet wird, erfolgt die Erstellung in VBA über oben angeführtes Verfahren unter Zuhilfenahme eines TextCursor sowie der Methode createInstance des Dokumentobjekts.

---

Textrahmen-Objekte stellen eine ganze Reihe von Eigenschaften zur Verfügung, mit denen Position und Verhalten des Rahmens beeinflusst werden können. Der Großteil dieser Eigenschaften ist in dem Dienst com.sun.star.text.BaseFrameProperties definiert, der auch von jedem TextFrame-Dienst unterstützt wird. Die zentralen Eigenschaften sind:

• BackColor (Long): Hintergrundfarbe des Textrahmens.

• BottomMargin (Long): unterer Rand in 100stel Millimeter.

• LeftMargin (Long): linker Rand in 100stel Millimeter.

• RightMargin (Long): rechter Rand in 100stel Millimeter.

• TopMargin (Long): oberer Rand in 100stel Millimeter.

• Height (Long): Höhe des Textrahmens in 100stel Millimeter.

• Width (Long): Breite des Textrahmens in 100stel Millimeter.

• HoriOrient (Const): horizontale Ausrichtung des Textrahmens (gemäß com.sun.star.text.HoriOrientation).

• VertOrient (Const): vertikale Ausrichtung des Textrahmens (gemäß com.sun.star.text.VertOrientation).

Das folgende Beispiel erstellt einen Textrahmen unter Verwendung der zuvor beschriebenen Eigenschaften.

Dim Doc As Object
Dim TextTables As Object
Dim Cursor As Object
Dim Frame As Object

Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
Cursor.gotoNextWord(False)
Frame = Doc.createInstance("com.sun.star.text.TextFrame")

Frame.Width = 3000
Frame.Height = 1000
Frame.AnchorType = com.sun.star.text.TextContentAnchorType.AS_CHARACTER
Frame.TopMargin = 0
Frame.BottomMargin = 0
Frame.LeftMargin = 0
Frame.RightMargin = 0
Frame.BorderDistance = 0
Frame.HoriOrient = com.sun.star.text.HoriOrientation.NONE
Frame.VertOrient = com.sun.star.text.VertOrientation.LINE_TOP

Doc.Text.insertTextContent(Cursor, Frame, False)

Das Beispiel erstellt einen TextCursor als Einfügemarke für den Textrahmen. Dieser wird zwischen dem ersten und dem zweiten Wort des Texts positioniert. Der Textrahmen wird über Doc.createInstance erstellt. Die Eigenschaften des Textrahmen-Objekts werden auf die erforderlichen Ausgangswerte gesetzt.

Zu beachten ist hierbei das Zusammenspiel der Eigenschaften AnchorType (aus dem Dienst TextContent) und VertOrient (aus dem Dienst BaseFrameProperties). AnchorType erhält den Wert AS_CHARACTER. Der Textrahmen wird somit direkt in den Textfluss eingefügt und verhält sich wie ein Zeichen. So kann er beispielsweise bei einem Zeilenumbruch in die nächste Zeile verschoben werden. Der Wert LINE_TOP der Eigenschaft VertOrient stellt sicher, dass sich die Oberkante des Textrahmens auf gleicher Höhe mit der Oberkante der Zeichen befindet.

Nach abgeschlossener Initialisierung wird der Textrahmen schließlich über einen Aufruf von insertTextContent in das Textdokument eingefügt.

Zum Bearbeiten des Inhalts eines Textrahmens wird der bereits mehrfach erwähnte TextCursor verwendet, der auch für Textrahmen verfügbar ist.

Dim Doc As Object
Dim TextTables As Object
Dim Cursor As Object
Dim Frame As Object
Dim FrameCursor As Object

Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
Frame = Doc.createInstance("com.sun.star.text.TextFrame")

Frame.Width = 3000
Frame.Height = 1000

Doc.Text.insertTextContent(Cursor, Frame, False)

FrameCursor = Frame.createTextCursor()
FrameCursor.charWeight = com.sun.star.awt.FontWeight.BOLD
FrameCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.CENTER
FrameCursor.String = "Dies ist ein kleiner Test!"

Das Beispiel erstellt einen Textrahmen, fügt diesen in das aktuelle Dokument ein und öffnet einen TextCursor für den Textrahmen. Über diesen Cursor wird die Schrift des Rahmens auf Fettdruck und die Absatzausrichtung auf zentriert eingestellt. Schließlich wird dem Textrahmen die Zeichenfolge (String) "Dies ist ein kleiner Test!" zugewiesen.

Textfelder

Textfelder zählen zu den TextContent-Objekten, da sie über den reinen Text hinaus eine zusätzliche Logik zur Verfügung stellen. Textfelder lassen sich über die gleichen Methoden in ein Textdokument einfügen wie andere TextContent-Objekte:

Dim Doc As Object
Dim DateTimeField As Object
Dim Cursor As Object
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()

DateTimeField = Doc.createInstance("com.sun.star.text.TextField.DateTime")
DateTimeField.IsFixed = False
DateTimeField.IsDate = True
Doc.Text.insertTextContent(Cursor, DateTimeField, False)

Das Beispiel fügt am Anfang des aktuellen Textdokuments ein Textfeld mit dem aktuellen Datum ein. Der Wert True der Eigenschaft IsDate führt dazu, dass nur das Datum ohne Uhrzeit angezeigt wird. Der Wert False für IsFixed stellt sicher, dass das Datum beim Öffnen des Dokuments automatisch aktualisiert wird.

---

Hinweis –

Während der Typ eines Felds in VBA durch einen Parameter der Methode Document.Fields.Add angegeben wird, erfolgt die Definition in StarOffice Basic durch den Namen des Dienstes, der für den betreffenden Feldtyp verantwortlich ist.

---

Der Zugriff auf Textfelder erfolgte bisher über eine ganze Reihe von Methoden, die StarOffice im alten Selection-Objekt zur Verfügung gestellt hat (z. B. InsertField, DeleteUserField, SetCurField).

In StarOffice 8 werden die Felder gemäß einem objektorientierten Konzept verwaltet. Für die Erstellung eines Textfelds muss zunächst ein Textfeld des erforderlichen Typs erstellt und über die notwendigen Eigenschaften initialisiert werden. Anschließend wird das Textfeld über die Methode insertTextContent in das Dokument eingefügt. Ein entsprechender Quelltext wird im vorstehenden Beispiel gezeigt. Die wichtigsten Feldtypen und ihre Eigenschaften werden in den folgenden Abschnitten beschrieben.

Neben dem Einfügen von Textfeldern kann auch das Durchsuchen eines Dokuments nach Feldern eine wichtige Aufgabe sein. Das folgende Beispiel zeigt, wie alle Textfelder eines Textdokuments in einer Schleife durchlaufen und auf ihren jeweiligen Typ hin überprüft werden können.

Dim Doc As Object
Dim TextFieldEnum As Object
Dim TextField As Object
Dim I As Integer

Doc = StarDesktop.CurrentComponent

TextFieldEnum = Doc.getTextFields.createEnumeration

While TextFieldEnum.hasMoreElements()

   TextField = TextFieldEnum.nextElement()

   If TextField.supportsService("com.sun.star.text.TextField.DateTime") Then
      MsgBox "Datum/Uhrzeit"
   ElseIf TextField.supportsService("com.sun.star.text.TextField.Annotation") Then
      MsgBox "Anmerkung"
   Else
      MsgBox "unbekannt"
   End If

Wend

Ausgangspunkt für die Ermittlung der vorhandenen Textfelder bildet die Liste TextFields des Dokumentobjekts. Auf dieser Grundlage erstellt das Beispiel ein Enumeration-Objekt, über das wiederum alle Textfelder in einer Schleife abgefragt werden können. Die gefundenen Textfelder werden über die Methode supportsService auf den unterstützten Service hin überprüft. Handelt es sich bei dem Feld um ein Datums-/Uhrzeitfeld oder eine Anmerkung, wird die betreffende Feldart in einem Hinweisfenster angezeigt. Stößt das Beispiel hingegen auf ein anderes Feld, so zeigt es den Hinweis "unbekannt" an.

Im Folgenden finden Sie eine Aufstellung der wichtigsten Textfelder sowie der zugehörigen Eigenschaften. Eine vollständige Liste aller Textfelder finden Sie in der API-Referenz im Modul com.sun.star.text.TextField. (Beim Aufführen der Dienstnamen eines Textfelds ist in StarOffice Basic die Groß- und Kleinschreibung wie im vorstehenden Beispiel zu verwenden.)

Anzahl der Seiten, Wörter und Zeichen

Die Textfelder

• com.sun.star.text.TextField.PageCount

• com.sun.star.text.TextField.WordCount

• com.sun.star.text.TextField.CharacterCount

geben die Anzahl der Seiten, Wörter und Zeichen eines Texts zurück. Sie unterstützen die folgende Eigenschaft:

• NumberingType (Const): Nummerierungsformat (Richtlinien gemäß der Konstanten aus com.sun.star.style.NumberingType).

Aktuelle Seite

Die Nummer der aktuellen Seite lässt sich über das Textfeld com.sun.star.text.TextField.PageNumber in ein Dokument einfügen. Folgende Eigenschaften können angegeben werden:

• NumberingType (Const): Zahlenformat (Richtlinien gemäß der Konstanten aus com.sun.star.style.NumberingType).

• Offset (Short) : Versatz, der der Seitenzahl hinzugefügt wird (negative Angaben sind ebenfalls möglich).

Das folgende Beispiel zeigt, wie die Seitenzahl in die Fußzeile eines Dokuments eingefügt werden kann.

Dim Doc As Object
Dim DateTimeField As Object
Dim PageStyles As Object
Dim StdPage As Object
Dim FooterCursor As Object
Dim PageNumber As Object

Doc = StarDesktop.CurrentComponent

PageNumber = Doc.createInstance("com.sun.star.text.TextField.PageNumber")
PageNumber.NumberingType = com.sun.star.style.NumberingType.ARABIC

PageStyles = Doc.StyleFamilies.getByName("PageStyles")

StdPage = PageStyles("Default")
StdPage.FooterIsOn = True

FooterCursor = StdPage.FooterTextLeft.Text.createTextCursor()
StdPage.FooterTextLeft.Text.insertTextContent(FooterCursor, PageNumber, False)

Das Beispiel erstellt zuerst ein Textfeld, das den Dienst com.sun.star.text.TextField.PageNumber unterstützt. Da die Kopf- und Fußzeilen als Teil der Seitenvorlagen von StarOffice definiert sind, wird dieses zunächst über die Liste aller PageStyles ermittelt.

Um sicherzustellen, dass die Fußzeile tatsächlich angezeigt wird, wird die Eigenschaft FooterIsOn auf True gesetzt. Anschließend wird das Textfeld über das verknüpfte Textobjekt der linken Fußzeile in das Dokument eingefügt.

Anmerkungen

Anmerkungsfelder (com.sun.star.text.TextField.Annotation) sind durch ein kleines gelbes Symbol im Text gekennzeichnet. Durch Klicken auf das Symbol wird ein Textfeld geöffnet, in dem eine Anmerkung zur aktuellen Textstelle erfasst werden kann. Ein Anmerkungsfeld verfügt über folgende Eigenschaften.

• Author (String): Name des Autors.

• Content (String): Anmerkungstext.

• Date (Date): Erstellungsdatum der Anmerkung.

Datum/Uhrzeit

Ein Datums-/Uhrzeit-Feld (com.sun.star.text.TextField.DateTime) stellt das aktuelle Datum beziehungsweise die aktuelle Uhrzeit dar. Es unterstützt die folgenden Eigenschaften:

• IsFixed (Boolean): wenn True, bleiben die Zeitangaben der Einfügung unverändert, wenn False, werden diese bei jedem Öffnen des Dokuments aktualisiert.

• IsDate (Boolean): wenn True, zeigt das Feld das aktuelle Datum an, andernfalls die aktuelle Uhrzeit.

• DateTimeValue (Struct): aktueller Inhalt des Felds (Struktur com.sun.star.util.DateTime).

• NumberFormat (Const): Format, in dem Uhrzeit und Datum angezeigt werden.

Kapitelname/-nummer

Der Name des aktuellen Kapitels steht über ein Textfeld des Typs com.sun.star.text.TextField.Chapter zur Verfügung. Die Form kann über zwei Eigenschaften definiert werden.

• ChapterFormat (Const): bestimmt, ob der Kapitelname oder die Kapitelnummer angezeigt wird (gemäß com.sun.star.text.ChapterFormat).

• Level (Integer): bestimmt die Kapitelebene, deren Name und/oder Kapitelnummer angezeigt werden soll. Der Wert 0 steht für die oberste verfügbare Ebene.

Lesezeichen (Bookmarks)

Lesezeichen (Dienst com.sun.star.text.Bookmark) gehören zu den TextContent-Objekten. Lesezeichen werden gemäß dem bereits zuvor beschriebenen Konzept erstellt und eingefügt:

Dim Doc As Object
Dim Bookmark As Object
Dim Cursor As Object

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor()

Bookmark = Doc.createInstance("com.sun.star.text.Bookmark")
Bookmark.Name = "My bookmarks"
Doc.Text.insertTextContent(Cursor, Bookmark, True)

Das Beispiel erzeugt einen Cursor, der die Einfügeposition des Lesezeichens markiert, und dann das eigentliche Lesezeichen-Objekt (Bookmark). Dem Lesezeichen wird anschließend ein Name zugewiesen und es wird über insertTextContent an der Cursor-Position in das Dokument eingefügt.

Der Zugriff auf die Lesezeichen eines Texts erfolgt über eine Liste namens Bookmarks. Auf die Lesezeichen kann entweder über ihre Nummer oder über ihren Namen zugegriffen werden.

Das folgende Beispiel zeigt, wie sich ein Lesezeichen innerhalb eines Texts auffinden und ein Text an seiner Position einfügen lässt.

Dim Doc As Object
Dim Bookmark As Object
Dim Cursor As Object

Doc = StarDesktop.CurrentComponent

Bookmark = Doc.Bookmarks.getByName("My bookmarks")

Cursor = Doc.Text.createTextCursorByRange(Bookmark.Anchor)
Cursor.String = "Hier ist das Lesezeichen."

In diesem Beispiel dient die Methode getByName dazu, das gewünschte Lesezeichen anhand seines Namens aufzufinden. Danach erzeugt der Aufruf createTextCursorByRange dann einen Cursor, der an der Anker-Position des Lesezeichens positioniert ist. Dort fügt der Cursor dann den gewünschten Text ein.