StarBasic InTEAM - Das Selection-Objekt

Das Selection-Objekt

Eine zentrale Rolle bei der StarBasic-Programmierung mit StarWriter spielt das Selection-Objekt. Es verkörpert den Cursor und stellt damit alle jene Methoden zur Verfügung, welche im StarWriter für eine Auswahl auch zur Verfügung stehen würde: Formatieren, Einfügen diverser Objekte, Cursor bewegen etc. Es ist daher kaum verwunderlich, dass alleine dieses Objekt weit über hundert Methoden und Eigenschaften hat.

Viele der in diesem Abschnitt beschriebenen Methoden werden im Beispiel «HTML-Nachrichten nach Text konvertieren» angewendet: zahlreiche Cursor-Bewegungen im Text, Abfragen der Abschnittsgrenzen, Zugriff auf die Graphics-Collection und Formatierung der Absätze. Ein Blick dorthin lohnt sich also nicht nur für die Online-Anwender!

Cursor im Dokument bewegen

Wollen wir einen Text bearbeiten, so müssen wir darin herumspringen und Teile davon markieren können. Hierfür steht eine Vielzahl von Methoden zur Verfügung. Die einfachsten repräsentieren die Bewegungsmöglichkeiten, die auch über die Pfeiltasten der Tastatur möglich sind.

Selection.GoUp(3, True)
Selection.GoLeft(1, False)
Selection.GotoEndOfLine(False)

Während die ersten beiden als Parameter auch eine Anzahl der Wiederholung akzeptieren, kann mit fast allen Navigations-Methoden der Text markiert werden, indem ein weiterer logischer Parameter definiert wird. Das erste obiger Beispiele geht drei Zeilen hoch und markiert diese. Das letzte springt zum Zeilenende, ohne eine Markierung zu erstellen.

Dokumentgrenzen können gleich mit mehreren Methoden angesprungen werden (bei allen folgenden kann «Start» durch «End» ersetzt werden): JumpToStartOfDoc() und GoToStartOfDoc(). Der Unterschied ist jedoch grösser, als es der Name erahnen liesse. Während der erste einfach wirklich an den Beginn eines Dokumentes springt, gelangt der zweite immer nur an den Anfang des aktuellen Kontextes. Innerhalb einer Tabelle wäre dies etwa der Anfang der Zelle, von dort die erste Zelle der Tabelle und von da wiederum erst der Beginn des Dokuments. Dessen muss man sich also bewusst sein. Andererseits erlauben es nur die GoTo-Methoden, den Text zu markieren. Ob der Cursor sich bereits am Anfang des Dokumentes befindet, lässt sich aus der Eigenschaft IsStartOfDoc auslesen.

Eine andere Möglichkeit, bestimmte Abschnitte oder Objekte eines Textes anzuwählen, bietet sich über Collections. So können etwa alle Abbildungen eines Dokuments einer gleichen Behandlung unterzogen werden, indem diese direkt angesprungen werden:

...
For x% = 1 To ActiveWindow.Graphics.Count
   ' hier kämen die Formatier-Befehle hin;
   ' die Abbildung soll gespiegelt werden:
   ActiveWindow.Graphics(x%).GraphicMirror = 1
Next
...

Dieses Beispiel liesse sich ebenso für Tabellen, OLE-Objekte etc. verwenden.

Die dritte Möglichkeit zur Positionierung des Cursors besteht in den Suchen-Methoden: über bzw. ActiveWindow.SearchAll() lassen sich gezielt Textpassagen für die Weiterverarbeitung selektieren.

Eine Selektion kann mittels Selection.Escape() aufgehoben werden.

Sonderbereiche anspringen

So wie man von einem Zeichen/Wort/Satz/Absatz/Tabelle zum anderen springen kann, so lassen sich natürlich auch die speziellen Bereiche eines Dokumentes, wie etwas Kopf-/Fusszeilen (JumpToHeader()/JumpToFooter()), Fussnoten (JumpToFootnoteOrAnchor()) oder Textmarken (JumptToBookmark()) anspringen.

Einfügen von Texten und Objekten

Natürlich lassen sich in SW auch über Makros Inhalte einfügen. Am einfachsten ist natürlich Text:

Selection.Insert("Hello Stars!")

Doch auch Abbildungen, OLE-Objekte, Tabellen etc. lassen sich einfügen. In der Klasse BaseText stehen hierfür dutzende InsertXXX-Methoden zur Verfügung: InsertField, InsertFrame, InsertGraphic, InsertObjectStarChart und InsertTable sind nur ein paar Beispiele!

Ein schönes Beispiel zu diesem Thema hat mir Klaus Schäfer zukommen lassen: es fügt in einem SW-Dokument eine Fusszeile mit Datum, Kürzel des Autoren und Dateinamen ein. Damit fällt die Suche nach einem Dokument, von dem nur ein Ausdruck auf Papier vorliegt, wesentlich einfacher. Falls das Dokument noch nicht gespeichert ist, holt das Makro dies nach.

Sub DateiInfoInFusszeile
   ' Makro funktioniert nur im StarWriter
   If ActiveModule.Name = "StarWriter" then

      ' Dokument speichern, falls noch nicht geschehen
      If Activedocument.Save = False Then 
         Activedocument.SaveAs
      End If

      ' Fusszeile aktiviere, einige Voreinstellungen vornehmen
      Selection.SetPageStyleFooter(True, "0.2cm", "0.5cm", True, True)

      ' Zur Fusszeile springen
      Selection.JumpToFooter()

      ' Fusszeile rechts ausrichten, kleinere Schrift
      Selection.Paragraph.Alignment = 1
      Selection.Font.Size = "8pt"

      ' aktuelles Datum (variabel)
      Selection.InsertField(0, 1,  "", "", 0)
      Selection.Insert ", "

      ' Autor des Dokuments, Kurzform
      Selection.InsertField(7, 0, "", "", 1)
      Selection.Insert ",  "

      ' Dokumentnamen ohne ....
      Selection.InsertField(2, 0, "", "", 0)

      ' ... oder mit Pfad (unerwünschtes auskommentieren)
      ' Selection.InsertField(2, 0, "", "", 1)
   Else 
      MsgBox("Dieses Makro funktioniert nur in Textdokumenten!", _
             16, "Fehler")
   End If
End Sub

Formatieren von Texten und Objekten

Im vorherigen Abschnitt wurde bereits einmal kurz dargestellt, wie eine Selektion bearbeitet werden kann. Ist im Text eine Markierung vorhanden oder ein Objekt markiert, so bezieht sich Selection also auf diese Markierung. Der Inhalt der Markierung lässt sich etwa mit Selection.Value abfragen oder mit Selection.Font auch formatieren:

' Selektion in Messagebox anzeigen
MsgBox(Selection.Value)

' Schrift auf 14 Punkt Grösse
Selection.Font.Size = 14

Ohne Markierung ist es noch immer möglich, Eigenschaften des Absatzes zu bestimmen:

' Linken Rand 1 cm einziehen
Selection.Paragraph.LeftMargin = «1cm»

Eine Ausführlichere Behandlung der Font-Eigenschaft findet ebenso in einem eigenen Abschnitt statt wie das Zuweisen von Formatvorlagen.

Auswahl auswerten

Natürlich kann auch ganz einfach auf den Inhalt einer Auswahl zugegriffen werden. Selection.Value enthält den ausgewählten Text. Diese Eigenschaft hat noch ein paar Verwandte, die ebenfalls die Auswahl liefern, dabei aber noch etwas mehr Möglichkeiten offerieren:

Selection.Value	Enthält die Auswahl als Zeichenkette. Umbrüche werden durch Leerzeichen ersetzt.
Selection.ValueAndBreaks	Enthält die Auswahl als Zeichenkette mit den Umbrüchen.
Selection.ValueAtCursor	Wie `Value`. Geht die Auswahl aber über einen Absatz hinaus, wird ein leerer String generiert. Ist nichts gewählt (`Value = ""`), dann enthält `ValueAtCursor` das Wort rechts vom Cursor oder bei Feldern deren Inhalt.

Mittels ValueAndBreaks lässt sich somit ein schneller Export des Textes in eine ASCII-Datei realisieren:

Sub ExportTextToFile
   Dim ExportFile$, FileHandle%

   If ActiveModule.Name = "StarWriter" then
      ' Zieldatei bestimmen
      ExportFile$ = Application.FileDialog("S", _
                     "Datei exportieren als", "")
      
      ' wenn keine Datei bestimmt, abbrechen
      If ExportFile$ <> "" Then
         Selection.ActionStart()
         Selection.InsertBookmark("_mhtmp_")
         
         ' alles markieren
         Selection.SelectAll()

         ' File-Handle für Export bestimmen
         FileHandle% = FreeFile

         ' Datei öffnen bzw. erstellen
         Open ExportFile$ For Output As #FileHandle%

         ' Selektion mit Umbrüchen in Datei schreiben
         Print #FileHandle%, Selection.ValueAndBreaks

         ' exportierte Datei schliessen
         Close #FileHandle%

         Selection.JumpToBookmark("_mhtmp_")
         Selection.DeleteBookmark("_mhtmp_")
         Selection.ActionEnd()
      End If
   Else 
      MsgBox("Dieses Makro funktioniert nur in einem Textdokument!", _
             16, "Fehler")
   End If
End Sub