X-Ray tool

Die Benutzung von HasUnoInterfaces und supportsService reicht aus, um sich zur Laufzeit über ein Objekt zu informieren, aber zum Lernen eignet sich das X-Ray tool von Bernard Marcelly viel besser. Laden Sie das ZIP-File herunter, entpacken Sie es und öffnen Sie das enthaltene Dokument mit OpenOffice.org. Befolgen Sie anschließend die Installationsanweisungen.

Das X-Ray tool verlangt bei der Konfiguration eine lokale Kopie des OpenOffice.org SDK. Laden Sie es von hier herunter und entpacken Sie es.

Nun können Sie die beiden auskommentierten Zeilen des obigen Beispiels entkommentieren (den Apostroph entfernen):

'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent

Führen Sie das Makro dann erneut aus.

Ab Xray Version 5 heißt das Kommando einfach xray.

BasicLibraries ist ein OpenOffice.org-Basic-Befehl, der ein Objekt zurückgibt, mit dem man auf die OpenOffice.org Bibliotheken zugreifen kann. Die Methode loadLibrary macht die Routinen aus dieser Bibliothek verfügbar.

xray.xray spezifiziert die Subroutine xray im Modul xray in dieser Bibliothek, thisComponent ist das Objekt, das an xray zur Introspektion übergeben wird.

Um mit einem bestimmten Objekt zu arbeiten erfordert häufig, dieses Objekt zu finden oder zu erzeugen, indem man mit StarDesktop oder thisComponent beginnt.

Desktop, Dokumente, Selektionen

StarDesktop und ThisComponent sind OpenOffice.org-Basic-Befehle, die sich auf die Applikation bzw. das aktuell aktive Dokument beziehen.

Im Unterschied zu Microsoft Office ist OpenOffice.org eine Anwendung mit unterschiedlichen Komponenten. Beim Ausführen von Code möchte man häufig wissen, welche Komponente aktuell aktiv ist. Der obige Code zeigt eine Möglichkeit, dies zu überprüfen.

StarDesktop bezieht sich auf einen konzeptuellen Desktop (der historisch tatsächlich mal existiert hat) und meint de facto die Anwendung OpenOffice.org.

Neue Dokumente erzeugen

Um ein neues Text-Dokument zu erzeugen:

oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())

Um ein neues Tabellen-Dokument zu erzeugen:

oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())

Ein sinnvoller Ansatz wäre, eine einfache Funktion zu schreiben:

function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function

Dann könnte man neue Dokumente ganz einfach erzeugen:

oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")

Siehe http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

Ein bestehendes Dokument öffnen

Im folgenden Beispiel sehen Sie, wie Sie eine Datei öffnen können. OpenOffice.org URLs sind in DE/URL Grundlagen erläutert.

sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())

Auch hier könnte eine einfache Funktion das Schreiben verkürzen:

function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function

Beispiele für Aufrufe:

oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux

Die aktuelle Selektion

Häufig werden Sie eine Funktion schreiben wollen, die etwas mit dem aktuell selektierten Bereich anstellt. ThisComponent enthält die Methode getCurrentSelection. Da viele unterschiedliche Objekte selektiert sein könnten, werden Sie zuerst prüfen wollen, ob das selektierte Objekt über den Dienst verfügt, der die Methode enthält, mit der Sie das Objekt bearbeiten wollen.

Editieren Sie die Subroutine main im nachfolgenden Code und führen Sie sie mehrfach in einem Textdokument aus, wobei Sie unterschiedliche Objekte selektieren. (Um mehr als einen Textblock zu selektieren, betätigen Sie die Strg-Taste).

sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
        oCurSelection = thisComponent.getCurrentSelection()
        'xray.xray oCurSelection
        if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
                msgbox "There are " & oCurSelection.getCount() & _
                 " selections in the current text document."
        end if
end if
end sub

Wenn nichts selektiert ist, beträgt die Anzahl der Selektionen eins (nämlich der Einfügepunkt), wenn ein Textblock selektiert ist, beträgt die Anzahl ebenfalls eins, wenn zwei Textblöcke selektiert sind, beträgt sie drei: der Einfügepunkt sowie die beiden selektierten Textblöcke.

Übung 1: Modifizieren Sie den obigen Code so, dass er mit selektierten Zellbereichen in einem Tabellendokument funktioniert.

Frage 1: Wie hoch ist die Anzahl der Selektionen, wenn zwei Zellblöcke selektiert sind?

Properties

Wenn Sie die Zeile 'xray.xray oCurSelection entkommentieren, so dass xray läuft, sehen Sie, dass das Objekt, worauf oCurSelection zeigt, eine "Property" namens Count besitzt, mit einer Beschreibung "pseudo-prop, read only". In OpenOffice.org Basic könnten Sie oCurSelection.count schreiben, da dies aber in keiner anderen Sprache, mit der Sie auf die OpenOffice.org API zugreifen können, möglich ist, werde ich versuchen, in diesem Wiki nur über Methoden zuzugreifen. (Möglicherweise vergesse ich das auch das eine oder andere Mal).

Das nächste Beispiel zeigt, wie man einen Property-Wert für die aktuellen Selektionen ändert.

sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
   oCurSelection = thisComponent.getCurrentSelection()
   if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
      nCount = oCurSelection.Count
      'xray.xray oCurSelection.getByIndex(0)
      'Warnung: Am Einfügepunkt wird die selbe Aktion zwei mal angewandt -
      'das macht in diesem Fall nichts, kann aber durchaus problematisch werden.
      for i = 0 to nCount - 1
         oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
      next
   end if
end if
end sub

In OpenOffice.org Basic kann man die Zuweisung auch abkürzen:

oCurSelection(i).CharStyleName = "Strong Emphasis"

Hier in diesem Wiki versuche ich, sowohl zur Indexierung als auch zur Zuweisung von Properties die vollständigen Methoden zu verwenden. Dadurch kann der Code leichter in andere Sprachen portiert werden und es hilft Ihnen auch, zu verstehen, was vor sich geht (nochmal: Bitte um Entschuldigung, wenn ich mal von dieser Regel abweiche, weil ich es eigentlich nicht gewohnt bin)

Übung 2: Schreiben Sie den obigen Code so um, dass die Warnung entfernt werden kann.

Siehe DE/Aktuelle Selektion ( Current selection).

Iterativer Zugriff auf untergeordnete Objekte
( berechtigungsgesteuerte Auflistung )

Manchmal ist zum Zugriff auf ein gewünschtes Objekt eine Enumeration (Auflistung) nötig. Beispielsweise ein Absatz innerhalb eines Dokumentes oder innerhalb einer Auswahl.

Wenn ein OpenOffice-Writer Dokument aktiviert ist und Text ausgewählt wird, können beide Methoden thisDocument.getText() und thisComponent.getCurrentSelection().getByIndex(i) verwand werden. com.sun.star.text.TextRange ist die Schnittstelle (Interface): com.sun.star.container.XContentEnumerationAccess, wodurch es möglich ist, eine Auflistung aller Absätze des aktuellen Dokuments oder für eine einzelne Auswahl zu erhalten.

' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()
 
' loop over all text elements
while oTextElementEnum.hasMoreElements()
        oTextElement = oTextElementEnum.nextElement
        if oTextElement.supportsService("com.sun.star.text.TextTable") then
                MsgBox "The current block contains a table."
        end if
        if oTextElement.supportsService("com.sun.star.text.Paragraph") then
                MsgBox "The current block contains a paragraph."
        end if
wend

Aufgabe 3: Erweitere das obige Beispiel so, das eine MessageBox aller Worte des Schrifttyps "bold" zeigt .

Benannte Zugriffe

Einige Objekte bieten benannte Zugriffe auf einzelne Typen von untergeordneten Objekten an, einige andere indizierten Zugriff, und manche benannten und indizierten Zugriff.

Wenn zum Beispiel das aktuelle Dokument in OpenOffice.org ein Arbeitsblatt ist, dann kann der Zugriff auf ein einzelnes Blatt durch einen indizierten Zugriff erfolgen:

oSheet = thisComponent.getSheets.getByIndex(0)

oder mit benanntem Zugriff:

oSheet = thisComponent.getSheets.getByName("Sheet1")

Um zu überprüfen, ob ein Objekt mit einem einzelnen Namen schon existiert, benutzt man hasByName, zum Beispiel:

if thisComponent.getSheets.hasByName("Sheet1") then

Eine Schleife durch alle verfügbaren Objektnamen kann in der Art erfolgen:

mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
        msgbox mNames(i)
next

Einige untergeordnete Objekte bieten ebenfalls eine Schnittstelle an: com.sun.star.container.XNameContainer. Diese Schnittstelle definiert, dass auf solche Objekte die folgenden Methoden angewendet werden können: insertByName, replaceByname and removeByName.

Z.B.

thisComponent.getSheets.insertByName("NewSheet")

Neue Objekte erstellen

Einige Objekte bieten Dienste, die Schnittstellen beinhalten, die spezielle Methoden für die Erstellung von einzelnen Objekt-Typen anbieten.

Wenn z.B. das aktuelle Dokument ein Writer Dokument ist, dann thisComponent.getText is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods createTextCursor and createTextCursorByRange. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString

Some objects are context dependent and get created using the method createInstance which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size
 
aPoint.x = 1000
aPoint.y = 1000
 
aSize.Width = 10000
aSize.Height = 10000
 
oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint
 
thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

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

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like thisComponent.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide createInstance. If the object doesn't provide createInstance are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

UNO structs

UNO structures can be declared using the OpenOffice.org Basic command dim:

dim aPoint as new com.sun.star.awt.Point

Or by using the OpenOffice.org Basic command createUnoStruct:

aPoint = createUnoStruct("com.sun.star.awt.Point")

Creating Listeners and Handlers

Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: Tools > Configure… > Events.

OpenOffice.org versions 1.9.x and above: Tools > Customize… > Events.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

global IannzExampleKeyHandler
 
sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub
 
 
sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub
 
 
sub KeyHandler_disposing
end sub
 
 
function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
        KeyHandler_keyReleased = False    
end function
 
 
function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false   'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
        if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
                msgbox "Alt + Q was pressed"
                KeyHandler_keyPressed = true    'Don't let other listeners process this event
        end if
end if
end function

A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

sub SetupKeyHandler sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example ."KeyHandler_".

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example "KeyHandler_".

Thus in the example there is KeyHandler_disposing and KeyHandler_keyReleased which don't actually do anything but are required, and KeyHandler_keyPressed which actually does the job.

sub RemoveKeyHandler demonstrates how to remove the handler.

OpenOffice.org constants

The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

Using the recorder