Chapter 4 Introduction to the StarOffice API

The StarOffice API is a universal programming interface for access to StarOffice. You can use the StarOffice API to create, open, modify and print out StarOffice documents. It provides the option of extending the functional scope of StarOffice through personal macros and allows personal dialogs to be written.

The StarOffice API may not only be used with StarOffice Basic, but also with other programming languages such as Java and C++. A technique called Universal Network Objects (UNO) which provides an interface to various programming languages makes this possible.

This chapter centers on how StarOffice can be used in StarOffice Basic with the aid of UNO. It describes the main concepts of UNO from the standpoint of a StarOffice Basic programmer. Details on how to work with the various parts of the StarOffice API can be found in the following chapters.

Universal Network Objects (UNO)

StarOffice provides a programming interface in the form of the Universal Network Objects (UNO). This is an object-oriented programming interface which StarOffice sub-divides into various objects which for their part ensure program-controlled access to the Office package.

Since StarOffice Basic is a procedural programming language, several linguistic constructs have had to be added to it which enable the use of UNO.

To use a Universal Network Object in StarOffice Basic, you will need a variable declaration for the associated object. The declaration is made using the Dim instruction (see Chapter 2, The Language of StarOffice Basic). The Object type designation should be used to declare an object variable:

Dim Obj As Object

The call declares an object variable named Obj.

The object variable created must then be initialized so that it can be used. This can be done using the createUnoService function:

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

This call assigns to the Obj variable a reference to the newly created object. com.sun.star.frame.Desktop resembles an object type; however in UNO terminology it is called a “service” rather than a type. In accordance with UNO philosophy, an Obj is described as a reference to an object which supports the com.sun.star.frame.Desktop service. The ”service” term used in StarOffice Basic therefore corresponds to the type and class terms used in other programming languages.

There is, however, one main difference: a Universal Network Object may support several services at the same time. Some UNO services in turn support other services so that, through one object, you are provided with a whole range of services. For example, that the aforementioned object, which is based on the com.sun.star.frame.Desktop service, can also include other services for loading documents and for ending the program.

---

Note –

Whereas the structure of an object in VBA is defined by the class to which it belongs, in StarOffice Basic the structure is defined through the services which it supports. A VBA object is always assigned to precisely one single class. A StarOffice Basic object can, however, support several services.

---

Properties and Methods

An object in StarOffice Basic provides a range of properties and methods which can be called by means of the object.

Properties

Properties are like the properties of an object; for example, Filename and Title for a Document object.

The properties are set by means of a simple assignment:

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

A property, just like a normal variable, has a type that defines which values it can record. The preceding Filename and Title properties are of the string type.

Real Properties and Imitated Properties

Most of the properties of an object in StarOffice Basic are defined as such in the UNO description of the service. In addition to these "real" properties, there are also properties in StarOffice Basic which consist of two methods at the UNO level. One of these is used to query the value of the property and the other is issued to set it (get and set methods). The property has been virtually imitated from two methods. Character objects in UNO, for example, provide the getPosition and setPosition methods through which the associated key point can be called up and changed. The StarOffice Basic programmer can access the values through the Position property. Regardless of this, the original methods are also available (in our example, getPosition and setPosition).

Methods

Methods can be understood as functions that relate directly to an object and through which this object is called. The preceding Document object could, for example, provide a Save method, which can be called as follows:

Document.Save()

Methods, just like functions, may contain parameters and return values. The syntax of such method calls is oriented towards classic functions. The call

Ok = Document.Save(True)

also specifies the True parameter for the document object when requesting the Save method. Once the method has been completed, Save saves a return value in the Ok variable.

Modules, Services and Interfaces

StarOffice provides hundreds of services. To provide an overview of these services, they have been combined into modules. The modules are of no other functional importance for StarOffice Basic programmers. When specifying a service name, it is only the module name which is of any importance because this must be also listed in the name. The complete name of a service consists of the com.sun.star expression, which specifies that it is a StarOffice service, followed by the module name, such as frame, and finally the actual service name, such as Desktop. The complete name in the named example would be:

com.sun.star.frame.Desktop

In addition to the module and service terms, UNO introduces the term “interface”. While this term may be familiar to Java programmers, it is not used in Basic.

An interface combines several methods. In the strictest sense of the word, a service in UNO does not support methods, but rather interfaces, which in turn provide different methods. In other words, the methods are assigned (as combinations) to the service in interfaces. This detail may be of interest in particular to Java- or C++ programmers, since in these languages, the interface is needed to request a method. In StarOffice Basic, this is irrelevant. Here, the methods are called directly by means of the relevant object.

For an understanding of the API, it is, however, useful to have the assignment of methods to various interfaces handy, since many interfaces are used in the different services. If you are familiar with an interface, then you can transfer your knowledge from one service to another.

Some central interfaces are used so frequently that they are shown again at the end of this chapter, triggered by different services.

Tools for Working with UNO

The question remains as to which objects — or services if we are going to remain with UNO terminology — support which properties, methods and interfaces and how these can be determined. In addition to this guide, you can get more information about objects from the following sources: the supportsService method, the debug methods as well as the Developer's Guide, and the API reference.

The supportsService Method

A number of UNO objects support the supportsService method, with which you can establish whether an object supports a particular service. The call

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

for example, determines whether the TextElement object supports the com.sun.star.text.Paragraph service.

Debug Properties

Every UNO object in StarOffice Basic knows what properties, methods and interfaces it already contains. It provides properties that return these in the form of a list. The corresponding properties are:

DBG_properties - returns a string containing all properties of an object

DBG_methods - returns a string containing all methods of an object

DBG_supportetInterfaces - returns a string containing all interfaces which support an object.

The following program code shows how DBG_properties and DBG_methods can be used in real-life applications. It first creates the com.sun.star.frame.Desktop service and then displays the supported properties and methods in message boxes.

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

MsgBox Obj.DBG_Propierties
MsgBox Obj.DBG_methods

When using DBG_properties, note that the function returns all properties that one particular service can theoretically support. No assurances are, however, provided for whether these can also be used by the object in question. Before calling up properties, you must therefore use the IsEmpty function to check whether this is actually available.

API Reference

More information about the available services, and their interfaces, methods and properties can be found in the API reference for the StarOffice API. This can be found at www.openoffice.org:

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

An Overview of a Few Central Interfaces

Some interfaces of StarOffice can be found in many parts of the StarOffice API. They define sets of methods for abstract tasks which can be applied to various problems. Here, you will find an overview of the most common of these interfaces.

The origin of the objects is explained at a later point in this guide. At this point, only some of the abstract aspects of objects, for which the StarOffice API provides some central interfaces, are discussed.

Creating Context-Dependent Objects

The StarOffice API provides two options for creating objects. One can be found in the createUnoService function mentioned at the start of this chapter. createUnoService creates an object which can be used universally. Such objects and services are also known as context-independent services.

In addition to context-independent services, there are also context-dependent services whose objects are only useful when used in conjunction with another object. A drawing object for a spreadsheet document, for example, can therefore only exist in conjunction with this one document.

com.sun.star.lang.XMultiServiceFactory Interface

Context-dependent objects are usually created by means of an object method, on which the object depends. The createInstance method, which is defined in the XMultiServiceFactory interface, is used in particular in the document objects.

The aforementioned drawing object can, for example, be created as follows using a spreadsheet object:

Dim RectangleShape As Object

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

A paragraph template in a text document is created in the same way:

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

Named Access to Subordinate Objects

The XNameAccess and XNameContainer interfaces are used in objects that contain subordinate objects, which can be addressed using a natural language name.

While XNamedAccess permits access to the individual objects, XNameContainer takes on the insertion, modification and deletion of elements.

com.sun.star.container.XNameAccess Interface

An example of the use of XNameAccess is provided by the sheet object of a spreadsheet. It combines all the pages within the spreadsheet. The individual pages are accessed using the getByName method from XNameAccess:

Dim Sheets As Object
Dim Sheet As Object

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

The getElementNames method provides an overview of the names of all elements. As a result, it returns a data field containing the names. The following example shows how all element names of a spreadsheet can thereby be determined and displayed in a loop:

Dim Sheets As Object
Dim SheetNames
Dim I As Integer

Sheets = Spreadsheet.Sheets
SheetNames = Sheets.getElementNames

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

The hasByName method of the XNameAccess interface reveals whether a subordinate object with a particular name exists within the basic object. The following example therefore displays a message that informs the user whether the Spreadsheet object contains a page of the name Sheet1.

Dim Sheets As Object

Sheets = Spreadsheet.Sheets
If Sheets.HasByName("Sheet1") Then
   MsgBox " Sheet1 available"
Else
   MsgBox "Sheet1 not available"
End If

com.sun.star.container.XNameContainer Interface

The XNameContainer interface takes on the insertion, deletion and modification of subordinate elements in a basic object. The functions responsible are insertByName, removeByName and replaceByName.

The following is a practical example of this. It calls a text document, which contains a StyleFamilies object and uses this to in turn make the paragraph templates (ParagraphStyles) of the document available.

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

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

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

The insertByName line inserts the NewStyle style under the name of the same name in the ParagraphStyles object. The replaceByName line changes the object behind ChangingStyle into NewStyle. Finally, the removeByName call removes the object behind OldStyle from ParagraphStyles.

Index-Based Access to Subordinate Objects

The XIndexAccess and XIndexContainer interfaces are used in objects which contain subordinate objects and which can be addressed using an index.

XIndexAccess provides the methods for accessing individual objects. XIndexContainer provides methods for inserting and removing elements.

com.sun.star.container.XIndexAccess Interface

XIndexAccess provides the getByIndex and getCount methods for calling the subordinate objects. getByIndex provides an object with a particular index. getCount returns how many objects are available.

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

Sheets = Spreadsheet.Sheets

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

The example shows a loop that runs through all sheet elements one after another and saves a reference to each in the Sheet object variable. When working with the indexes, note that getCount returns the number of elements. The elements in getByIndex however are numbered beginning with 0. The counting variable of the loop therefore runs from 0 to getCount()-1.

com.sun.star.container.XIndexContainer Interface

The XIndexContainer interface provides the insertByIndex and removeByIndex functions. The parameters are structured in the same way as the corresponding functions in XNameContainer.

Iterative Access to Subordinate Objects

In some instances, an object may contain a list of subordinate objects that cannot be addressed by either a name or an index. In these situations, the XEnumeration and XenumerationAccess interfaces are appropriate. They provide a mechanism through which all subordinate elements of an objects can be passed, step by step, without having to use direct addressing.

com.sun.star.container.XEnumeration and XenumerationAccess Interfaces

The basic object must provide the XEnumerationAccess interface, which contains only a createEnumeration method. This returns an auxiliary object, which in turn provides the XEnumeration interface with the hasMoreElements and nextElement methods. Through these, you then have access to the subordinate objects.

The following example steps through all the paragraphs of a text:

Dim ParagraphEnumeration As Object
Dim Paragraph As Object

ParagraphEnumeration = Textdoc.Text.createEnumeration

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

The example first creates a ParagraphEnumeration auxiliary object. This gradually returns the individual paragraphs of the text in a loop. The loop is terminated as soon as the hasMoreElements method returns the False value, signaling that the end of the text has been reached.